From b68a6bfe140974b69136c859b1f9c442c544a7fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=86=B0=E6=9C=94?= <565183519@qq.com> Date: Mon, 10 Aug 2026 01:52:42 +0800 Subject: [PATCH] feat(domain-access): validate signed handoff evidence --- .../server/domain-access.test.ts | 76 +++++++++- .../server/domain-access.ts | 130 +++++++++++++++++- 2 files changed, 195 insertions(+), 11 deletions(-) diff --git a/product-source/guanghu-knowledge-base/server/domain-access.test.ts b/product-source/guanghu-knowledge-base/server/domain-access.test.ts index 33b50fd..3570455 100644 --- a/product-source/guanghu-knowledge-base/server/domain-access.test.ts +++ b/product-source/guanghu-knowledge-base/server/domain-access.test.ts @@ -1,9 +1,42 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { evaluateDomainAccess } from './domain-access.js'; +import { evaluateDomainAccess, parseDomainAccessHandoff } from './domain-access.js'; const NOW = 1_786_291_200_000; const DIGEST = 'a'.repeat(64); +const COMMIT = 'b'.repeat(40); + +const validHandoff = { + connectionReceipt: { + connectionId: 'CONN-001', + domainId: 'DOM-FIFTH-0001', + manifestDigest: DIGEST, + nodeId: 'LOCAL-001', + receiptId: 'RECEIPT-001', + state: 'online', + }, + manifest: { + digest: DIGEST, + domainId: 'DOM-FIFTH-0001', + schema: 'gh-aios.domain-manifest/v1', + signerId: 'GH-LIGHTHOUSE-001', + sourceCommit: COMMIT, + verifierReceipt: { + manifestDigest: DIGEST, + signerId: 'GH-LIGHTHOUSE-001', + state: 'verified', + verifiedAt: NOW - 1_000, + verifierId: 'GH-MANIFEST-VERIFIER-001', + }, + }, + sessionCapability: { + capabilityId: 'CAP-001', + domainId: 'DOM-FIFTH-0001', + expiresAt: NOW + 60_000, + nodeId: 'LOCAL-001', + scopes: ['domain:enter'], + }, +} as const; test('a local workspace remains available without claiming domain runtime access', () => { const status = evaluateDomainAccess({ accountVerified: false, domainId: 'DOM-FIFTH-0001', nodeId: '' }, NOW); @@ -23,13 +56,12 @@ test('a verified Forgejo account is not a domain runtime session', () => { }); test('runtime access requires matching manifest, scoped capability and online receipt', () => { + const handoff = parseDomainAccessHandoff(validHandoff, 'DOM-FIFTH-0001', 'LOCAL-001', NOW); const status = evaluateDomainAccess({ accountVerified: true, - connectionReceipt: { domainId: 'DOM-FIFTH-0001', manifestDigest: DIGEST, nodeId: 'LOCAL-001', state: 'online' }, domainId: 'DOM-FIFTH-0001', - manifest: { digest: DIGEST, domainId: 'DOM-FIFTH-0001', verified: true }, nodeId: 'LOCAL-001', - sessionCapability: { domainId: 'DOM-FIFTH-0001', expiresAt: NOW + 60_000, nodeId: 'LOCAL-001', scopes: ['domain:enter'] }, + ...handoff, }, NOW); assert.equal(status.runtimeReady, true); assert.equal(status.stage, 'runtime-ready'); @@ -39,13 +71,43 @@ test('runtime access requires matching manifest, scoped capability and online re test('mismatched or expired evidence fails closed', () => { const status = evaluateDomainAccess({ accountVerified: true, - connectionReceipt: { domainId: 'DOMAIN-OTHER', manifestDigest: DIGEST, nodeId: 'LOCAL-001', state: 'online' }, + connectionReceipt: { connectionId: 'CONN-001', domainId: 'DOMAIN-OTHER', manifestDigest: DIGEST, nodeId: 'LOCAL-001', receiptId: 'RECEIPT-001', state: 'online' }, domainId: 'DOM-FIFTH-0001', - manifest: { digest: DIGEST, domainId: 'DOM-FIFTH-0001', verified: true }, + manifest: validHandoff.manifest, nodeId: 'LOCAL-001', - sessionCapability: { domainId: 'DOM-FIFTH-0001', expiresAt: NOW, nodeId: 'LOCAL-001', scopes: ['domain:enter'] }, + sessionCapability: { capabilityId: 'CAP-001', domainId: 'DOM-FIFTH-0001', expiresAt: NOW, nodeId: 'LOCAL-001', scopes: ['domain:enter'] }, }, NOW); assert.equal(status.runtimeReady, false); assert.ok(status.blockers.includes('scoped_session_capability_missing')); assert.ok(status.blockers.includes('matching_connection_receipt_missing')); }); + +test('a verified boolean cannot substitute for an external verifier receipt', () => { + assert.throws(() => parseDomainAccessHandoff({ + ...validHandoff, + manifest: { + digest: DIGEST, + domainId: 'DOM-FIFTH-0001', + schema: 'gh-aios.domain-manifest/v1', + signerId: 'GH-LIGHTHOUSE-001', + sourceCommit: COMMIT, + verified: true, + }, + }, 'DOM-FIFTH-0001', 'LOCAL-001', NOW), /domain_access_handoff_invalid/); +}); + +test('unknown fields and malformed digests fail closed', () => { + assert.throws(() => parseDomainAccessHandoff({ + ...validHandoff, + manifest: { ...validHandoff.manifest, digest: 'not-a-digest' }, + trusted: true, + }, 'DOM-FIFTH-0001', 'LOCAL-001', NOW), /domain_access_handoff_invalid/); +}); + +test('the handoff is bound to the requested domain, node and manifest digest', () => { + assert.throws(() => parseDomainAccessHandoff({ + ...validHandoff, + connectionReceipt: { ...validHandoff.connectionReceipt, manifestDigest: 'c'.repeat(64) }, + }, 'DOM-FIFTH-0001', 'LOCAL-001', NOW), /domain_access_handoff_invalid/); + assert.throws(() => parseDomainAccessHandoff(validHandoff, 'DOM-FIFTH-0001', 'OTHER-NODE', NOW), /domain_access_handoff_invalid/); +}); diff --git a/product-source/guanghu-knowledge-base/server/domain-access.ts b/product-source/guanghu-knowledge-base/server/domain-access.ts index 7bf9efe..ccb5c63 100644 --- a/product-source/guanghu-knowledge-base/server/domain-access.ts +++ b/product-source/guanghu-knowledge-base/server/domain-access.ts @@ -1,10 +1,52 @@ +const MANIFEST_SCHEMA = 'gh-aios.domain-manifest/v1' as const; +const SHA256_PATTERN = /^[a-f0-9]{64}$/; +const COMMIT_PATTERN = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/; + +export interface DomainManifestEvidence { + digest: string; + domainId: string; + schema: typeof MANIFEST_SCHEMA; + signerId: string; + sourceCommit: string; + verifierReceipt: { + manifestDigest: string; + signerId: string; + state: 'verified'; + verifiedAt: number; + verifierId: string; + }; +} + +export interface DomainSessionCapability { + capabilityId: string; + domainId: string; + expiresAt: number; + nodeId: string; + scopes: string[]; +} + +export interface DomainConnectionReceipt { + connectionId: string; + domainId: string; + manifestDigest: string; + nodeId: string; + receiptId: string; + state: 'online'; +} + +export interface DomainAccessHandoff { + connectionReceipt: DomainConnectionReceipt; + manifest: DomainManifestEvidence; + sessionCapability: DomainSessionCapability; +} + export interface DomainAccessEvidence { accountVerified: boolean; - connectionReceipt?: { domainId: string; manifestDigest: string; nodeId: string; state: 'online' }; + connectionReceipt?: DomainConnectionReceipt; domainId: string; - manifest?: { digest: string; domainId: string; verified: boolean }; + manifest?: DomainManifestEvidence; nodeId: string; - sessionCapability?: { domainId: string; expiresAt: number; nodeId: string; scopes: string[] }; + sessionCapability?: DomainSessionCapability; } export interface DomainAccessStatus { @@ -16,14 +58,92 @@ export interface DomainAccessStatus { stage: 'login-required' | 'identity-verified' | 'runtime-ready'; } +function isRecord(value: unknown): value is Record { + return typeof value === 'object' && value !== null && !Array.isArray(value); +} + +function hasExactKeys(record: Record, keys: string[]): boolean { + const actual = Object.keys(record).sort(); + return actual.length === keys.length && actual.every((key, index) => key === [...keys].sort()[index]); +} + +function isIdentifier(value: unknown): value is string { + return typeof value === 'string' && value.length > 0 && value.length <= 160; +} + +function invalidHandoff(): never { + throw new Error('domain_access_handoff_invalid'); +} + +/** + * Validates the structure and binding of evidence returned by a trusted route. + * Cryptographic signature verification is deliberately external: this boundary + * only accepts a signer-bound verifier receipt and never treats a boolean as proof. + */ +export function parseDomainAccessHandoff( + input: unknown, + expectedDomainId: string, + expectedNodeId: string, + now = Date.now(), +): DomainAccessHandoff { + if (!isRecord(input) || !hasExactKeys(input, ['connectionReceipt', 'manifest', 'sessionCapability'])) invalidHandoff(); + const manifest = input.manifest; + const capability = input.sessionCapability; + const connection = input.connectionReceipt; + if (!isRecord(manifest) || !hasExactKeys(manifest, ['digest', 'domainId', 'schema', 'signerId', 'sourceCommit', 'verifierReceipt'])) invalidHandoff(); + if (!isRecord(capability) || !hasExactKeys(capability, ['capabilityId', 'domainId', 'expiresAt', 'nodeId', 'scopes'])) invalidHandoff(); + if (!isRecord(connection) || !hasExactKeys(connection, ['connectionId', 'domainId', 'manifestDigest', 'nodeId', 'receiptId', 'state'])) invalidHandoff(); + + const verifier = manifest.verifierReceipt; + if (!isRecord(verifier) || !hasExactKeys(verifier, ['manifestDigest', 'signerId', 'state', 'verifiedAt', 'verifierId'])) invalidHandoff(); + + const digest = manifest.digest; + if (manifest.schema !== MANIFEST_SCHEMA + || typeof digest !== 'string' || !SHA256_PATTERN.test(digest) + || manifest.domainId !== expectedDomainId + || !isIdentifier(manifest.signerId) + || typeof manifest.sourceCommit !== 'string' || !COMMIT_PATTERN.test(manifest.sourceCommit) + || verifier.state !== 'verified' + || verifier.manifestDigest !== digest + || verifier.signerId !== manifest.signerId + || !isIdentifier(verifier.verifierId) + || typeof verifier.verifiedAt !== 'number' || !Number.isSafeInteger(verifier.verifiedAt) || verifier.verifiedAt > now) invalidHandoff(); + + if (!isIdentifier(capability.capabilityId) + || capability.domainId !== expectedDomainId + || capability.nodeId !== expectedNodeId + || typeof capability.expiresAt !== 'number' || !Number.isSafeInteger(capability.expiresAt) || capability.expiresAt <= now + || !Array.isArray(capability.scopes) + || capability.scopes.some((scope) => !isIdentifier(scope)) + || !capability.scopes.includes('domain:enter')) invalidHandoff(); + + if (!isIdentifier(connection.connectionId) + || !isIdentifier(connection.receiptId) + || connection.domainId !== expectedDomainId + || connection.nodeId !== expectedNodeId + || connection.manifestDigest !== digest + || connection.state !== 'online') invalidHandoff(); + + return input as unknown as DomainAccessHandoff; +} + export function evaluateDomainAccess(evidence: DomainAccessEvidence, now = Date.now()): DomainAccessStatus { const blockers: string[] = []; if (!evidence.accountVerified || !evidence.nodeId) blockers.push('account_node_identity_missing'); - if (!evidence.manifest?.verified || evidence.manifest.domainId !== evidence.domainId || !evidence.manifest.digest) { + const manifest = evidence.manifest; + const verifier = manifest?.verifierReceipt; + if (!manifest + || manifest.schema !== MANIFEST_SCHEMA + || manifest.domainId !== evidence.domainId + || !SHA256_PATTERN.test(manifest.digest) + || verifier?.state !== 'verified' + || verifier.manifestDigest !== manifest.digest + || verifier.signerId !== manifest.signerId) { blockers.push('verified_domain_manifest_missing'); } const capability = evidence.sessionCapability; if (!capability + || !capability.capabilityId || capability.domainId !== evidence.domainId || capability.nodeId !== evidence.nodeId || capability.expiresAt <= now @@ -32,6 +152,8 @@ export function evaluateDomainAccess(evidence: DomainAccessEvidence, now = Date. } const receipt = evidence.connectionReceipt; if (!receipt + || !receipt.connectionId + || !receipt.receiptId || receipt.state !== 'online' || receipt.domainId !== evidence.domainId || receipt.nodeId !== evidence.nodeId