hololake-system-architecture/product-source/guanghu-knowledge-base/server/domain-access.ts

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?: DomainConnectionReceipt;
  domainId: string;
  manifest?: DomainManifestEvidence;
  nodeId: string;
  sessionCapability?: DomainSessionCapability;
}

export interface DomainAccessStatus {
  blockers: string[];
  domainId: string;
  localWorkspaceAllowed: true;
  nodeId: string;
  runtimeReady: boolean;
  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');
  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
    || !capability.scopes.includes('domain:enter')) {
    blockers.push('scoped_session_capability_missing');
  }
  const receipt = evidence.connectionReceipt;
  if (!receipt
    || !receipt.connectionId
    || !receipt.receiptId
    || receipt.state !== 'online'
    || receipt.domainId !== evidence.domainId
    || receipt.nodeId !== evidence.nodeId
    || receipt.manifestDigest !== evidence.manifest?.digest) {
    blockers.push('matching_connection_receipt_missing');
  }
  const runtimeReady = blockers.length === 0;
  return {
    blockers,
    domainId: evidence.domainId,
    localWorkspaceAllowed: true,
    nodeId: evidence.nodeId,
    runtimeReady,
    stage: runtimeReady ? 'runtime-ready' : evidence.accountVerified && Boolean(evidence.nodeId) ? 'identity-verified' : 'login-required',
  };
}