bingshuo/hololake-system-architecture
Watch
1
0
Fork
You've already forked hololake-system-architecture
 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity

feat(domain-access): validate signed handoff evidence

Browse source
This commit is contained in:
冰朔 2026-08-10 01:52:42 +08:00
commit b68a6bfe14
2 changed files with 195 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

76
product-source/guanghu-knowledge-base/server/domain-access.test.ts
View file

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

130
product-source/guanghu-knowledge-base/server/domain-access.ts
View file

@ -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