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

import { createHash, verify as verifySignature } from 'node:crypto';

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})?$/;
const cryptographicallyVerifiedManifests = new WeakSet<object>();

export interface DomainManifestEvidence {
  digest: string;
  domainId: string;
  repositoryId: string;
  schema: typeof MANIFEST_SCHEMA;
  signature: string;
  signerId: string;
  sourceCommit: string;
  verifierReceipt: {
    manifestDigest: string;
    signerId: string;
    state: 'verified';
    verifiedAt: number;
    verifierId: string;
  };
}

export interface DomainManifestSignedPayload {
  domainId: string;
  repositoryId: string;
  schema: typeof MANIFEST_SCHEMA;
  signerId: string;
  sourceCommit: string;
}

export interface TrustedManifestSigner {
  algorithm: 'Ed25519';
  publicKeyPem: string;
  repositoryId: string;
  signerId: 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');
}

export function domainManifestSigningBytes(payload: DomainManifestSignedPayload): Buffer {
  return Buffer.from(JSON.stringify({
    domainId: payload.domainId,
    repositoryId: payload.repositoryId,
    schema: payload.schema,
    signerId: payload.signerId,
    sourceCommit: payload.sourceCommit,
  }), 'utf8');
}

/**
 * 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,
  trustedSigner: TrustedManifestSigner,
  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', 'repositoryId', 'schema', 'signature', 'signerId', 'sourceCommit'])) 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 digest = manifest.digest;
  if (manifest.schema !== MANIFEST_SCHEMA
    || typeof digest !== 'string' || !SHA256_PATTERN.test(digest)
    || manifest.domainId !== expectedDomainId
    || manifest.repositoryId !== trustedSigner.repositoryId
    || manifest.signerId !== trustedSigner.signerId
    || trustedSigner.algorithm !== 'Ed25519'
    || !isIdentifier(trustedSigner.publicKeyPem)
    || !isIdentifier(manifest.signerId)
    || typeof manifest.sourceCommit !== 'string' || !COMMIT_PATTERN.test(manifest.sourceCommit)
    || typeof manifest.signature !== 'string') invalidHandoff();

  const signedPayload = domainManifestSigningBytes({
    domainId: manifest.domainId,
    repositoryId: manifest.repositoryId,
    schema: manifest.schema,
    signerId: manifest.signerId,
    sourceCommit: manifest.sourceCommit,
  });
  if (createHash('sha256').update(signedPayload).digest('hex') !== digest) invalidHandoff();
  let signature: Buffer;
  try {
    signature = Buffer.from(manifest.signature, 'base64');
    if (signature.length !== 64 || signature.toString('base64') !== manifest.signature) invalidHandoff();
    if (!verifySignature(null, signedPayload, trustedSigner.publicKeyPem, signature)) invalidHandoff();
  } catch {
    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();

  const handoff: DomainAccessHandoff = {
    connectionReceipt: connection as unknown as DomainConnectionReceipt,
    manifest: {
      ...(manifest as unknown as Omit<DomainManifestEvidence, 'verifierReceipt'>),
      verifierReceipt: {
        manifestDigest: digest,
        signerId: manifest.signerId,
        state: 'verified',
        verifiedAt: now,
        verifierId: 'HOLOLAKE-DESKTOP-ED25519',
      },
    },
    sessionCapability: capability as unknown as DomainSessionCapability,
  };
  cryptographicallyVerifiedManifests.add(handoff.manifest);
  return handoff;
}

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
    || !cryptographicallyVerifiedManifests.has(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',
  };
}