feat(domain-access): validate signed handoff evidence

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/);
+});

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<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function hasExactKeys(record: Record<string, unknown>, 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