feat(knowledge): load signer snapshot from exact anchor commit

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

@@ -0,0 +1,155 @@
+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*)$/;
+
+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 {
+  return Object.freeze({ registry, receipt: snapshotReceipt });
+}
+
+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));
+    }
+  }
+}