hololake-system-architecture/product-source/guanghu-knowledge-base/server/trusted-signer-snapshot.ts

import {
  parseTrustedManifestSignerRegistry,
  type TrustedManifestSignerRegistry,
} from './trusted-signer-registry.js';

const ANCHOR_URL = 'https://guanghulab.com/api/ai/v1/anchor';
const CODE_URL = 'https://guanghulab.com/code/bingshuo/guanghu-ice-heart';
const REGISTRY_ID = 'GH-AIOS-TRUSTED-DOMAIN-MANIFEST-SIGNERS-001';
const REGISTRY_PATH = 'routing/trusted-domain-manifest-signers.json';
const COMMIT_PATTERN = /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/;
const VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
const registeredLoadedSnapshots = new WeakSet<object>();

export interface TrustedSignerSnapshotTransport {
  fetchJson(url: string): Promise<unknown>;
}

export type TrustedSignerSnapshotReason =
  | 'ANCHOR_INVALID'
  | 'REGISTRY_INVALID'
  | 'SOURCE_UNAVAILABLE';

export interface TrustedSignerSnapshotReceipt {
  status: 'CURRENT' | 'DEGRADED_LAST_KNOWN_GOOD' | 'UNAVAILABLE';
  reason?: TrustedSignerSnapshotReason;
  sourceCommit: string | null;
  registryVersion: string | null;
  signerCount: number;
}

export interface TrustedSignerSnapshotResult {
  registry: TrustedManifestSignerRegistry | null;
  receipt: Readonly<TrustedSignerSnapshotReceipt>;
}

interface ParsedAnchor {
  registryVersion: string;
  sourceCommit: string;
}

class SnapshotLoadError extends Error {
  constructor(readonly reason: TrustedSignerSnapshotReason) {
    super(reason);
  }
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function parseAnchor(input: unknown): ParsedAnchor {
  if (!isRecord(input)
    || input.schema !== 'guanghu.public-navigation-anchor/v1'
    || input.anchor_id !== 'GLW-PUBLIC-NAV-ANCHOR-001'
    || input.state !== 'CURRENT_CANONICAL'
    || input.repository_id !== 'REPO-012'
    || input.branch !== 'main'
    || input.public_entry !== ANCHOR_URL
    || input.code_entry !== CODE_URL
    || !isRecord(input.maps)
    || !isRecord(input.maps.trusted_domain_manifest_signers)
    || input.maps.trusted_domain_manifest_signers.path !== REGISTRY_PATH
    || input.maps.trusted_domain_manifest_signers.id !== REGISTRY_ID
    || typeof input.maps.trusted_domain_manifest_signers.version !== 'string'
    || !VERSION_PATTERN.test(input.maps.trusted_domain_manifest_signers.version)
    || !isRecord(input.navigation_source)
    || input.navigation_source.anchor_id !== 'GLW-PUBLIC-NAV-ANCHOR-001'
    || input.navigation_source.source_mode !== 'REPO-012_MAIN_GIT_SNAPSHOT'
    || input.navigation_source.source_degraded !== false
    || typeof input.navigation_source.source_commit !== 'string'
    || !COMMIT_PATTERN.test(input.navigation_source.source_commit)) {
    throw new SnapshotLoadError('ANCHOR_INVALID');
  }
  return Object.freeze({
    registryVersion: input.maps.trusted_domain_manifest_signers.version,
    sourceCommit: input.navigation_source.source_commit,
  });
}

function registryUrl(sourceCommit: string): string {
  return `${CODE_URL}/raw/commit/${sourceCommit}/${REGISTRY_PATH}`;
}

function receipt(
  status: TrustedSignerSnapshotReceipt['status'],
  registry: TrustedManifestSignerRegistry | null,
  reason?: TrustedSignerSnapshotReason,
): Readonly<TrustedSignerSnapshotReceipt> {
  return Object.freeze({
    status,
    ...(reason ? { reason } : {}),
    sourceCommit: registry?.source.sourceCommit ?? null,
    registryVersion: registry?.version ?? null,
    signerCount: registry?.signers.length ?? 0,
  });
}

function result(
  registry: TrustedManifestSignerRegistry | null,
  snapshotReceipt: Readonly<TrustedSignerSnapshotReceipt>,
): TrustedSignerSnapshotResult {
  const loaded = Object.freeze({ registry, receipt: snapshotReceipt });
  registeredLoadedSnapshots.add(loaded);
  return loaded;
}

export function assertLoadedTrustedSignerSnapshot(
  snapshot: TrustedSignerSnapshotResult,
): TrustedSignerSnapshotResult {
  if (!registeredLoadedSnapshots.has(snapshot)) throw new Error('trusted_signer_snapshot_unregistered');
  return snapshot;
}

export class TrustedSignerSnapshotLoader {
  #inFlight: Promise<TrustedSignerSnapshotResult> | null = null;
  #lastKnownGood: TrustedManifestSignerRegistry | null = null;

  constructor(private readonly transport: TrustedSignerSnapshotTransport) {}

  refresh(): Promise<TrustedSignerSnapshotResult> {
    if (this.#inFlight) return this.#inFlight;
    this.#inFlight = this.#load().finally(() => {
      this.#inFlight = null;
    });
    return this.#inFlight;
  }

  async #load(): Promise<TrustedSignerSnapshotResult> {
    try {
      let rawAnchor: unknown;
      try {
        rawAnchor = await this.transport.fetchJson(ANCHOR_URL);
      } catch {
        throw new SnapshotLoadError('SOURCE_UNAVAILABLE');
      }
      const anchor = parseAnchor(rawAnchor);
      let rawRegistry: unknown;
      try {
        rawRegistry = await this.transport.fetchJson(registryUrl(anchor.sourceCommit));
      } catch {
        throw new SnapshotLoadError('SOURCE_UNAVAILABLE');
      }
      let registry: TrustedManifestSignerRegistry;
      try {
        registry = parseTrustedManifestSignerRegistry(rawRegistry, {
          repositoryId: 'REPO-012',
          sourceCommit: anchor.sourceCommit,
          sourceUrl: registryUrl(anchor.sourceCommit),
        });
      } catch {
        throw new SnapshotLoadError('REGISTRY_INVALID');
      }
      if (registry.version !== anchor.registryVersion) {
        throw new SnapshotLoadError('REGISTRY_INVALID');
      }
      this.#lastKnownGood = registry;
      return result(registry, receipt('CURRENT', registry));
    } catch (error) {
      const reason = error instanceof SnapshotLoadError ? error.reason : 'SOURCE_UNAVAILABLE';
      return this.#lastKnownGood
        ? result(this.#lastKnownGood, receipt('DEGRADED_LAST_KNOWN_GOOD', this.#lastKnownGood, reason))
        : result(null, receipt('UNAVAILABLE', null, reason));
    }
  }
}