feat: 建立三项目机器身份与安全传输 v1 (#151)
This commit is contained in:
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user