feat: 建立三项目机器身份与安全传输 v1 (#151)

This commit is contained in:
QiuSW
2026-08-31 10:53:51 +08:00
parent 573113eb3b
commit 009dc3cca0
22 changed files with 2188 additions and 1 deletions
+62
View File
@@ -0,0 +1,62 @@
# Machine identity contract v1
`yovision.machine-identity/v1` defines service-to-service identity for YoVision connectors. It is deliberately separate from Sense and Bell users, GoAdmin JWT/Cookie state, database roles and operating-system accounts.
## Authentication mechanism
Every request uses HTTPS and one compact Ed25519 JWS in `Authorization: Bearer <token>`. The protected header is closed and contains `alg=EdDSA`, `typ=YOVISION-MACHINE+JWT`, `kid` and `ver=yovision.machine-identity/v1`. The closed claims object contains:
mTLS is not the primary v1 identity mechanism. A customer PKI may add mTLS later as transport hardening, but it cannot replace or weaken the v1 principal, audience, scope, request binding, replay and revocation checks.
- one instance-specific `iss`/`sub` principal;
- one exact service `aud`;
- the minimum required `scope` values;
- `iat`, `nbf`, `exp` and a single-use random `jti`;
- uppercase HTTP method `htm`, normalized absolute-path reference `htu`, and lowercase SHA-256 `body_sha256`.
Tokens live for at most 300 seconds. Consumers allow at most 30 seconds of clock skew, verify the signature and active key/principal before authorization, then atomically consume `jti` until `exp + skew`. Retrying transport creates a new token and `jti`; business idempotency keys remain unchanged.
Production consumers persist the replay key `(principal, jti)` in their own durable store so a process restart cannot reopen the replay window. The checked-in process-local replay stores are adapter test/default primitives only; connector tasks must inject an atomic durable implementation and test restart behavior without sharing a database across products.
The v1 scopes are:
| Caller | Audience | Scope |
|---|---|---|
| Sense | `yovision-brain` | `source-config:write` |
| Brain | `yovision-sense` | `runtime-status:write` |
| Brain or Sense | `yovision-bell` | `events:ingest` |
| Bell | `yovision-sense` | `evidence:read` |
No wildcard audience or scope exists. A relay authenticates as its own transport principal and never replaces the original event producer identity.
## Key lifecycle
Private Ed25519 keys are generated per product instance and stored outside the repository in an OS-protected file or secret store. Runtime configuration contains only the private-key path. Public registries are local consumer configuration, not a shared database.
Rotation first registers a new `kid`, switches the caller, and removes the old key after an overlap no longer than 24 hours. A disabled principal or revoked `kid` is rejected on every request, including tokens that have not expired. Emergency rollback disables the connector; it never enables a shared password, browser token, query token, plaintext transport or signature bypass.
## Threat boundary
v1 protects against token modification, wrong audience/scope, expired or premature tokens, captured-token replay, key/principal revocation and accidental credential mixing. It does not protect a host after administrator/root compromise, a stolen usable private key before revocation, compromised TLS trust roots, endpoint implementation flaws or denial of service. Rate and body-size limits remain consumer responsibilities.
See `../transport/v1/README.md` for HTTPS and request policy. Stable failures are defined in `errors.md`; callers and logs must expose only the stable code, principal/kid when already authenticated, and correlation ID—never the token, signature, private/public key material or complete Authorization header.
## Compatibility
v1 is closed. New optional claims require all consumers to accept them before producers emit them. Any change to signing input, algorithm, claim meaning, replay semantics, maximum lifetime, audience or scope meaning publishes a new major version. Consumers keep the last accepted major during a controlled migration; rollback disables the new producer version without weakening verification.
## Reproducible verification
From the repository root:
```powershell
pwsh -NoProfile -File contracts/tests/machine-identity-v1/run.ps1
cd Sense/server
go test -race ./app/sense/integration/machine_identity
cd ../../Bell/server
go test -race ./app/bell/integration/machine_identity
```
The isolated contract test validates both JSON Schemas, the fixed Go/Python Ed25519 vector, request binding, exact audience/scope, expiry, replay, rotation overlap, revocation, bearer-only extraction and verified TLS policy. Product connector tasks remain responsible for injecting a durable replay store and testing restart recovery.
+14
View File
@@ -0,0 +1,14 @@
# Machine identity v1 stable errors
| Code | Meaning | Retry |
|---|---|---|
| `machine_token_missing` | Authorization bearer token is absent or malformed | No, fix request |
| `machine_token_invalid` | Header, claims, signature, request binding or key is invalid | No |
| `machine_token_expired` | Token is outside its accepted time window | Mint a new token |
| `machine_audience_denied` | Exact audience does not match | No |
| `machine_scope_denied` | Required scope is absent or not granted to the key | No |
| `machine_identity_revoked` | Principal or key is disabled/revoked | No; operator action |
| `machine_token_replayed` | The same principal/jti was already accepted | Retry with a new token and the same business idempotency key |
| `machine_transport_required` | HTTPS policy is not satisfied | No; fix deployment |
Responses and audit facts never include the token, signature, key material or Authorization header.
@@ -0,0 +1,28 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://yovision.local/contracts/machine-identity/v1/machine-token.schema.json",
"title": "YoVision machine token claims v1",
"type": "object",
"additionalProperties": false,
"required": ["ver", "iss", "sub", "aud", "scope", "iat", "nbf", "exp", "jti", "htm", "htu", "body_sha256"],
"properties": {
"ver": {"const": "yovision.machine-identity/v1"},
"iss": {"type": "string", "pattern": "^yv:(sense|brain|bell):[a-z0-9][a-z0-9.-]{0,62}$"},
"sub": {"type": "string", "pattern": "^yv:(sense|brain|bell):[a-z0-9][a-z0-9.-]{0,62}$"},
"aud": {"enum": ["yovision-sense", "yovision-brain", "yovision-bell"]},
"scope": {
"type": "array",
"minItems": 1,
"maxItems": 4,
"uniqueItems": true,
"items": {"enum": ["source-config:write", "runtime-status:write", "events:ingest", "evidence:read"]}
},
"iat": {"type": "integer", "minimum": 0},
"nbf": {"type": "integer", "minimum": 0},
"exp": {"type": "integer", "minimum": 0},
"jti": {"type": "string", "pattern": "^[A-Za-z0-9_-]{22,64}$"},
"htm": {"type": "string", "pattern": "^(GET|POST|PUT|PATCH|DELETE)$"},
"htu": {"type": "string", "pattern": "^/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$"},
"body_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"}
}
}
@@ -0,0 +1,38 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://yovision.local/contracts/machine-identity/v1/principal-registry.schema.json",
"title": "YoVision machine principal registry v1",
"type": "object",
"additionalProperties": false,
"required": ["version", "audience", "principals"],
"properties": {
"version": {"const": "yovision.machine-principal-registry/v1"},
"audience": {"enum": ["yovision-sense", "yovision-brain", "yovision-bell"]},
"principals": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["principal_id", "enabled", "keys"],
"properties": {
"principal_id": {"type": "string", "pattern": "^yv:(sense|brain|bell):[a-z0-9][a-z0-9.-]{0,62}$"},
"enabled": {"type": "boolean"},
"keys": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["kid", "public_key_base64url", "status", "scopes"],
"properties": {
"kid": {"type": "string", "pattern": "^[A-Za-z0-9._-]{8,64}$"},
"public_key_base64url": {"type": "string", "pattern": "^[A-Za-z0-9_-]{43}$"},
"status": {"enum": ["active", "revoked"]},
"scopes": {"type": "array", "minItems": 1, "maxItems": 4, "uniqueItems": true, "items": {"enum": ["source-config:write", "runtime-status:write", "events:ingest", "evidence:read"]}}
}
}
}
}
}
}
}
}
@@ -0,0 +1,11 @@
{
"version": "yovision.machine-token-vector/v1",
"public_key_base64url": "ebVWLo_mVPlAeLES6KmLp5AfhTrmlb7X4OORC60ElmQ",
"token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImJyYWluLXZlY3Rvci0wMDAxIiwidHlwIjoiWU9WSVNJT04tTUFDSElORStKV1QiLCJ2ZXIiOiJ5b3Zpc2lvbi5tYWNoaW5lLWlkZW50aXR5L3YxIn0.eyJhdWQiOiJ5b3Zpc2lvbi1zZW5zZSIsImJvZHlfc2hhMjU2IjoiNDA5NDQzYTZlZTVhYTI5NmRjY2Q2YzBkMTkzZTIxNDU2OGRhYTAwNTNiNjYxNTVmYmE4YWRjYTk5NWI3ODIzZCIsImV4cCI6MTgwMDAwMDMwMCwiaHRtIjoiUE9TVCIsImh0dSI6Ii9tYWNoaW5lL3YxL3J1bnRpbWUtc3RhdHVzIiwiaWF0IjoxODAwMDAwMDAwLCJpc3MiOiJ5djpicmFpbjp2ZWN0b3IiLCJqdGkiOiJBUUlEQkFVR0J3Z0pDZ3NNRFE0UEVBIiwibmJmIjoxODAwMDAwMDAwLCJzY29wZSI6WyJydW50aW1lLXN0YXR1czp3cml0ZSJdLCJzdWIiOiJ5djpicmFpbjp2ZWN0b3IiLCJ2ZXIiOiJ5b3Zpc2lvbi5tYWNoaW5lLWlkZW50aXR5L3YxIn0.zrvo_7lRiDX1D6po6OlfQg4hDg6XXlyUEmNMYgpuRl3ArXSjvGuOLivDousIyLtRO4bYJu9xMAWX1cea7MdVBQ",
"now": 1800000000,
"audience": "yovision-sense",
"required_scope": "runtime-status:write",
"method": "POST",
"path": "/machine/v1/runtime-status",
"body_base64": "eyJzdGF0dXMiOiJydW5uaW5nIn0="
}
@@ -0,0 +1,2 @@
cryptography==50.0.1
jsonschema==4.25.1
@@ -0,0 +1,33 @@
[CmdletBinding()]
param()
$ErrorActionPreference = 'Stop'
$testDirectory = $PSScriptRoot
$requirements = Join-Path $testDirectory 'requirements.txt'
$tempRoot = [IO.Path]::GetFullPath([IO.Path]::GetTempPath())
$workDirectory = Join-Path $tempRoot ("yovision-machine-identity-v1-{0}" -f [Guid]::NewGuid().ToString('N'))
try {
New-Item -ItemType Directory -Path $workDirectory | Out-Null
$virtualEnvironment = Join-Path $workDirectory '.venv'
python -m venv $virtualEnvironment
if ($LASTEXITCODE -ne 0) { throw 'Failed to create the isolated Python environment.' }
$python = Join-Path $virtualEnvironment 'Scripts\python.exe'
$env:PIP_DISABLE_PIP_VERSION_CHECK = '1'
$env:PYTHONDONTWRITEBYTECODE = '1'
& $python -m pip install --quiet --requirement $requirements
if ($LASTEXITCODE -ne 0) { throw 'Failed to install pinned machine-identity test dependencies.' }
& $python $testDirectory\test_contract.py
if ($LASTEXITCODE -ne 0) { throw 'Machine-identity v1 contract tests failed.' }
}
finally {
$resolvedWorkDirectory = [IO.Path]::GetFullPath($workDirectory)
if (-not $resolvedWorkDirectory.StartsWith($tempRoot, [StringComparison]::OrdinalIgnoreCase)) {
throw "Refusing to remove a temporary directory outside $tempRoot"
}
if (Test-Path -LiteralPath $resolvedWorkDirectory) {
Remove-Item -LiteralPath $resolvedWorkDirectory -Recurse -Force
}
}
@@ -0,0 +1,181 @@
from __future__ import annotations
import json
import base64
import ssl
import sys
import tempfile
import unittest
from pathlib import Path
ROOT = Path(__file__).resolve().parents[3]
sys.path.insert(0, str(ROOT / "Brain" / "src"))
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
from jsonschema import Draft202012Validator
from yovision_brain.integration.machine_identity import (
KeyRecord,
MachineIdentityError,
Registry,
ReplayStore,
Signer,
TransportPolicy,
Verifier,
load_registry,
bearer_token,
)
class ContractFilesTest(unittest.TestCase):
def test_closed_claim_and_registry_schemas(self) -> None:
claims = json.loads((ROOT / "contracts/machine-identity/v1/machine-token.schema.json").read_text(encoding="utf-8"))
registry = json.loads((ROOT / "contracts/machine-identity/v1/principal-registry.schema.json").read_text(encoding="utf-8"))
transport = json.loads((ROOT / "contracts/transport/v1/transport-policy.schema.json").read_text(encoding="utf-8"))
Draft202012Validator.check_schema(claims)
Draft202012Validator.check_schema(registry)
Draft202012Validator.check_schema(transport)
self.assertFalse(claims["additionalProperties"])
self.assertEqual(claims["properties"]["ver"]["const"], "yovision.machine-identity/v1")
self.assertEqual(claims["properties"]["scope"]["items"]["enum"], [
"source-config:write", "runtime-status:write", "events:ingest", "evidence:read"
])
self.assertFalse(registry["additionalProperties"])
self.assertEqual(transport["properties"]["verify_certificate"]["const"], True)
self.assertEqual(transport["properties"]["verify_hostname"]["const"], True)
vector = json.loads((ROOT / "contracts/tests/machine-identity-v1/cross-language-vector.json").read_text(encoding="utf-8"))
claims_object = json.loads(base64.urlsafe_b64decode(vector["token"].split(".")[1] + "=="))
Draft202012Validator(claims).validate(claims_object)
Draft202012Validator(transport).validate({
"version": "yovision.transport/v1", "tls_min_version": "1.2", "verify_certificate": True,
"verify_hostname": True, "connect_timeout_ms": 1000, "response_header_timeout_ms": 1000,
"request_timeout_ms": 5000, "max_request_bytes": 1048576,
})
def test_brain_dependency_is_frozen(self) -> None:
pyproject = (ROOT / "Brain/pyproject.toml").read_text(encoding="utf-8")
self.assertIn('dependencies = ["cryptography==50.0.1"]', pyproject)
def test_contract_documents_fail_closed(self) -> None:
identity = (ROOT / "contracts/machine-identity/v1/README.md").read_text(encoding="utf-8")
transport = (ROOT / "contracts/transport/v1/README.md").read_text(encoding="utf-8")
for required in ("300 seconds", "30 seconds", "24 hours", "jti", "revoked", "browser token"):
self.assertIn(required, identity)
for required in ("TLS 1.2", "hostname verification", "query-string credentials", "disables the connector"):
self.assertIn(required, transport)
def test_python_verifies_cross_language_vector(self) -> None:
vector = json.loads((ROOT / "contracts/tests/machine-identity-v1/cross-language-vector.json").read_text(encoding="utf-8"))
raw_key = base64.urlsafe_b64decode(vector["public_key_base64url"] + "=")
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
registry = Registry([KeyRecord("yv:brain:vector", "brain-vector-0001", Ed25519PublicKey.from_public_bytes(raw_key), vector["audience"], frozenset({vector["required_scope"]}))])
verifier = Verifier(registry, ReplayStore(), clock=lambda: vector["now"])
claims = verifier.verify(vector["token"], vector["audience"], vector["required_scope"], vector["method"], vector["path"], base64.b64decode(vector["body_base64"]))
self.assertEqual(claims.iss, "yv:brain:vector")
class BrainAdapterTest(unittest.TestCase):
def setUp(self) -> None:
self.now = 1_800_000_000
self.private = Ed25519PrivateKey.generate()
self.record = KeyRecord(
principal="yv:brain:node-a",
key_id="brain-key-0001",
public_key=self.private.public_key(),
audience="yovision-sense",
scopes=frozenset({"runtime-status:write"}),
)
self.registry = Registry([self.record])
self.signer = Signer("yv:brain:node-a", "brain-key-0001", self.private, clock=lambda: self.now)
def mint(self, body: bytes = b"{}") -> str:
return self.signer.mint("yovision-sense", ["runtime-status:write"], "POST", "/machine/v1/runtime-status", body)
def verify(self, token: str, body: bytes = b"{}", **changes: str):
verifier = Verifier(self.registry, changes.pop("replay", ReplayStore()), clock=lambda: int(changes.pop("now", self.now)))
return verifier.verify(
token,
changes.pop("audience", "yovision-sense"),
changes.pop("scope", "runtime-status:write"),
changes.pop("method", "POST"),
changes.pop("path", "/machine/v1/runtime-status"),
body,
)
def assert_code(self, code: str, callback) -> None:
with self.assertRaises(MachineIdentityError) as caught:
callback()
self.assertEqual(caught.exception.code, code)
self.assertEqual(str(caught.exception), code)
def test_valid_token_and_replay_rejection(self) -> None:
token = self.mint()
replay = ReplayStore()
first = Verifier(self.registry, replay, clock=lambda: self.now)
claims = first.verify(token, "yovision-sense", "runtime-status:write", "POST", "/machine/v1/runtime-status", b"{}")
self.assertEqual(claims.iss, "yv:brain:node-a")
self.assert_code("machine_token_replayed", lambda: first.verify(token, "yovision-sense", "runtime-status:write", "POST", "/machine/v1/runtime-status", b"{}"))
def test_bearer_token_has_no_cookie_or_query_fallback(self) -> None:
self.assertEqual(bearer_token("Bearer compact.token.value"), "compact.token.value")
for value in ("", "compact.token.value", "Bearer", "Bearer one two", "Cookie compact.token.value"):
self.assert_code("machine_token_missing", lambda value=value: bearer_token(value))
def test_wrong_audience_scope_body_and_expiry(self) -> None:
self.assert_code("machine_audience_denied", lambda: self.verify(self.mint(), audience="yovision-bell"))
self.assert_code("machine_scope_denied", lambda: self.verify(self.mint(), scope="events:ingest"))
self.assert_code("machine_token_invalid", lambda: self.verify(self.mint(), body=b"changed"))
self.assert_code("machine_token_expired", lambda: self.verify(self.mint(), now=str(self.now + 361)))
def test_tampering_revocation_and_rotation(self) -> None:
token = self.mint()
parts = token.split(".")
tampered = f"{parts[0]}.{parts[1][:-1]}A.{parts[2]}"
self.assert_code("machine_token_invalid", lambda: self.verify(tampered))
self.assertTrue(self.registry.revoke("brain-key-0001"))
self.assert_code("machine_identity_revoked", lambda: self.verify(self.mint()))
new_private = Ed25519PrivateKey.generate()
overlap = Registry([
self.record,
KeyRecord("yv:brain:node-a", "brain-key-0002", new_private.public_key(), "yovision-sense", frozenset({"runtime-status:write"})),
])
new_signer = Signer("yv:brain:node-a", "brain-key-0002", new_private, clock=lambda: self.now)
verifier = Verifier(overlap, ReplayStore(), clock=lambda: self.now)
verifier.verify(self.mint(), "yovision-sense", "runtime-status:write", "POST", "/machine/v1/runtime-status", b"{}")
verifier.verify(new_signer.mint("yovision-sense", ["runtime-status:write"], "POST", "/machine/v1/runtime-status", b"{}"), "yovision-sense", "runtime-status:write", "POST", "/machine/v1/runtime-status", b"{}")
def test_transport_policy_requires_verified_tls(self) -> None:
policy = TransportPolicy("1.2", True, True, 1000, 1000, 2000, 1024)
context = policy.ssl_context()
self.assertGreaterEqual(context.minimum_version, ssl.TLSVersion.TLSv1_2)
self.assertTrue(context.check_hostname)
self.assertEqual(context.verify_mode, ssl.CERT_REQUIRED)
with self.assertRaises(ValueError):
TransportPolicy("1.1", True, True, 1000, 1000, 2000, 1024).validate()
with self.assertRaises(ValueError):
TransportPolicy("1.2", True, False, 1000, 1000, 2000, 1024).validate()
def test_loads_external_public_registry_and_rejects_wrong_audience(self) -> None:
from cryptography.hazmat.primitives import serialization
raw_public = self.private.public_key().public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
document = {
"version": "yovision.machine-principal-registry/v1",
"audience": "yovision-sense",
"principals": [{
"principal_id": "yv:brain:node-a", "enabled": True,
"keys": [{"kid": "brain-key-0001", "public_key_base64url": base64.urlsafe_b64encode(raw_public).rstrip(b"=").decode(), "status": "active", "scopes": ["runtime-status:write"]}],
}],
}
with tempfile.TemporaryDirectory() as directory:
path = Path(directory) / "principals.json"
path.write_text(json.dumps(document), encoding="utf-8")
registry = load_registry(path, "yovision-sense")
self.assertIsNotNone(registry.lookup("brain-key-0001"))
with self.assertRaises(ValueError):
load_registry(path, "yovision-bell")
if __name__ == "__main__":
unittest.main(verbosity=2)
+12
View File
@@ -0,0 +1,12 @@
# Machine transport policy v1
`yovision.transport/v1` applies to every connector protected by machine identity v1.
- HTTPS is mandatory. TLS 1.2 is the minimum and TLS 1.3 is preferred.
- Certificate-chain and hostname verification are mandatory. `InsecureSkipVerify`, plaintext fallback and query-string credentials are forbidden.
- Connection, response-header and total request timeouts are explicit and bounded; consumers enforce a route-specific body limit before decoding.
- `X-Request-ID` is an opaque 16–128 character correlation value. It may be generated by the caller or first trusted hop, is never an authentication factor, and must not contain credentials or personal data.
- Retry only timeout, connection loss, `429` and `5xx` according to the connector policy. Authentication/authorization failures and contract `4xx` responses are terminal until configuration changes.
- Each retry signs a new machine token and `jti`. The business idempotency key and payload remain unchanged.
Transport failures must not start Sense, Brain or Bell with weakened authentication. Rollback disables the connector and preserves local facts, Outbox/Receipt state and last-known-good configuration.
@@ -0,0 +1,18 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://yovision.local/contracts/transport/v1/transport-policy.schema.json",
"title": "YoVision machine transport policy v1",
"type": "object",
"additionalProperties": false,
"required": ["version", "tls_min_version", "verify_certificate", "verify_hostname", "connect_timeout_ms", "response_header_timeout_ms", "request_timeout_ms", "max_request_bytes"],
"properties": {
"version": {"const": "yovision.transport/v1"},
"tls_min_version": {"enum": ["1.2", "1.3"]},
"verify_certificate": {"const": true},
"verify_hostname": {"const": true},
"connect_timeout_ms": {"type": "integer", "minimum": 100, "maximum": 30000},
"response_header_timeout_ms": {"type": "integer", "minimum": 100, "maximum": 30000},
"request_timeout_ms": {"type": "integer", "minimum": 100, "maximum": 60000},
"max_request_bytes": {"type": "integer", "minimum": 1, "maximum": 10485760}
}
}