@crewhaus/template-registry 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { CrewhausError } from "@crewhaus/errors";
+/**
+ * Catalog F4 `template-registry` — Section 40 backend-agnostic
+ * spec-template registry.
+ *
+ * `RegistrySource` interface (`list`, `fetch`, `metadata`) so the
+ * registry can be backed by git releases, HuggingFace datasets, npm
+ * packages, a local directory, etc. Built-in `LocalRegistrySource`
+ * is the file-backed default and the test fixture for the others.
+ *
+ * Manifest schema: `{ name, version, description, author, target,
+ * yaml, exampleEnv?, screenshots?, signature?, publicKey? }`.
+ * `signature` is base64-encoded Ed25519 over a canonical JSON of the
+ * non-signature fields; `publicKey` is the corresponding raw public
+ * key (PKCS#8 PEM or raw 32-byte). The registry verifies signatures
+ * against a configured trust root; unverified manifests are refused
+ * (T8 supply-chain check).
+ *
+ * TTL cache: `cachedRegistry({source, ttlMs})` wraps any source with
+ * a 60-minute (default) TTL. `refresh()` clears the cache so callers
+ * (and the `crewhaus templates refresh` CLI subcommand) can force a
+ * re-fetch on demand.
+ *
+ * Layer F4. Pairs with `scaffold-templates` (§26 — built-in
+ * templates), `template-marketplace-client` (§40 — Studio UI integration).
+ */
+export declare class TemplateRegistryError extends CrewhausError {
+    readonly name = "TemplateRegistryError";
+    constructor(message: string, cause?: unknown);
+}
+export type TemplateManifest = {
+    readonly name: string;
+    readonly version: string;
+    readonly description: string;
+    readonly author: string;
+    readonly target: string;
+    readonly yaml: string;
+    readonly exampleEnv?: Record<string, string>;
+    readonly screenshots?: ReadonlyArray<string>;
+    /** Base64-encoded Ed25519 signature over canonical JSON of the rest. */
+    readonly signature?: string;
+    /** PKCS#8 PEM-encoded Ed25519 public key, OR raw 32-byte hex. */
+    readonly publicKey?: string;
+};
+export type SignableManifest = Omit<TemplateManifest, "signature">;
+export type TemplateMetadata = Omit<TemplateManifest, "yaml">;
+export interface RegistrySource {
+    readonly id: string;
+    list(): Promise<ReadonlyArray<TemplateMetadata>>;
+    fetch(name: string): Promise<TemplateManifest>;
+    metadata(name: string): Promise<TemplateMetadata>;
+}
+export type TrustRoot = {
+    /** PKCS#8 PEM-encoded Ed25519 public keys trusted to sign manifests. */
+    readonly publicKeys: ReadonlyArray<string>;
+};
+declare function canonicalManifestJson(m: SignableManifest): string;
+export declare function signManifest(manifest: SignableManifest, privateKeyPem: string): string;
+export declare function verifyManifest(manifest: TemplateManifest, trustRoot: TrustRoot): {
+    ok: boolean;
+    reason?: string;
+};
+export declare function generateSigningKeypair(): {
+    privateKey: string;
+    publicKey: string;
+};
+export type LocalRegistrySourceOptions = {
+    readonly rootDir: string;
+};
+export declare class LocalRegistrySource implements RegistrySource {
+    private readonly opts;
+    readonly id = "local";
+    constructor(opts: LocalRegistrySourceOptions);
+    private manifestPath;
+    list(): Promise<ReadonlyArray<TemplateMetadata>>;
+    fetch(name: string): Promise<TemplateManifest>;
+    metadata(name: string): Promise<TemplateMetadata>;
+    /** Test/admin helper: write a manifest into the file-backed registry. */
+    put(manifest: TemplateManifest): void;
+}
+export type HttpRegistrySourceOptions = {
+    readonly id: "git" | "huggingface" | "npm";
+    readonly listUrl: string;
+    readonly fetchUrl: (name: string) => string;
+    readonly fetchImpl?: typeof fetch;
+};
+export declare class HttpRegistrySource implements RegistrySource {
+    private readonly opts;
+    readonly id: HttpRegistrySourceOptions["id"];
+    private readonly fetchImpl;
+    constructor(opts: HttpRegistrySourceOptions);
+    list(): Promise<ReadonlyArray<TemplateMetadata>>;
+    fetch(name: string): Promise<TemplateManifest>;
+    metadata(name: string): Promise<TemplateMetadata>;
+}
+export type CachedRegistryOptions = {
+    readonly source: RegistrySource;
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+};
+export interface CachedRegistry extends RegistrySource {
+    refresh(): void;
+}
+declare const DEFAULT_TTL_MS: number;
+export declare function cachedRegistry(opts: CachedRegistryOptions): CachedRegistry;
+export type VerifyingRegistryOptions = {
+    readonly source: RegistrySource;
+    readonly trustRoot: TrustRoot;
+};
+export declare function verifyingRegistry(opts: VerifyingRegistryOptions): RegistrySource;
+export { canonicalManifestJson as _canonicalManifestJsonForTest, DEFAULT_TTL_MS as _defaultTtlMsForTest, };

package/dist/index.js

@@ -0,0 +1,242 @@
+import { createPrivateKey, createPublicKey, sign as cryptoSign, verify as cryptoVerify, generateKeyPairSync, } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CrewhausError } from "@crewhaus/errors";
+/**
+ * Catalog F4 `template-registry` — Section 40 backend-agnostic
+ * spec-template registry.
+ *
+ * `RegistrySource` interface (`list`, `fetch`, `metadata`) so the
+ * registry can be backed by git releases, HuggingFace datasets, npm
+ * packages, a local directory, etc. Built-in `LocalRegistrySource`
+ * is the file-backed default and the test fixture for the others.
+ *
+ * Manifest schema: `{ name, version, description, author, target,
+ * yaml, exampleEnv?, screenshots?, signature?, publicKey? }`.
+ * `signature` is base64-encoded Ed25519 over a canonical JSON of the
+ * non-signature fields; `publicKey` is the corresponding raw public
+ * key (PKCS#8 PEM or raw 32-byte). The registry verifies signatures
+ * against a configured trust root; unverified manifests are refused
+ * (T8 supply-chain check).
+ *
+ * TTL cache: `cachedRegistry({source, ttlMs})` wraps any source with
+ * a 60-minute (default) TTL. `refresh()` clears the cache so callers
+ * (and the `crewhaus templates refresh` CLI subcommand) can force a
+ * re-fetch on demand.
+ *
+ * Layer F4. Pairs with `scaffold-templates` (§26 — built-in
+ * templates), `template-marketplace-client` (§40 — Studio UI integration).
+ */
+export class TemplateRegistryError extends CrewhausError {
+    name = "TemplateRegistryError";
+    constructor(message, cause) {
+        super("config", message, cause);
+    }
+}
+// --------------------------------------------------------------------
+// Canonical JSON for signing
+// --------------------------------------------------------------------
+function canonicalManifestJson(m) {
+    // Stable key order; omit undefined optional fields.
+    const ordered = {
+        name: m.name,
+        version: m.version,
+        description: m.description,
+        author: m.author,
+        target: m.target,
+        yaml: m.yaml,
+    };
+    if (m.exampleEnv !== undefined)
+        ordered["exampleEnv"] = m.exampleEnv;
+    if (m.screenshots !== undefined)
+        ordered["screenshots"] = m.screenshots;
+    if (m.publicKey !== undefined)
+        ordered["publicKey"] = m.publicKey;
+    return JSON.stringify(ordered);
+}
+export function signManifest(manifest, privateKeyPem) {
+    const key = createPrivateKey(privateKeyPem);
+    const sig = cryptoSign(null, Buffer.from(canonicalManifestJson(manifest), "utf8"), key);
+    return sig.toString("base64");
+}
+export function verifyManifest(manifest, trustRoot) {
+    if (manifest.signature === undefined || manifest.signature === "") {
+        return { ok: false, reason: "manifest is unsigned" };
+    }
+    if (manifest.publicKey === undefined || manifest.publicKey === "") {
+        return { ok: false, reason: "manifest is missing publicKey" };
+    }
+    if (!trustRoot.publicKeys.some((pk) => pk === manifest.publicKey)) {
+        return { ok: false, reason: "publicKey is not in trust root" };
+    }
+    let key;
+    try {
+        key = createPublicKey(manifest.publicKey);
+    }
+    catch (err) {
+        return { ok: false, reason: `invalid publicKey: ${err.message}` };
+    }
+    const { signature: _sig, ...rest } = manifest;
+    const sigBuf = Buffer.from(manifest.signature, "base64");
+    const ok = cryptoVerify(null, Buffer.from(canonicalManifestJson(rest), "utf8"), key, sigBuf);
+    return ok ? { ok: true } : { ok: false, reason: "signature does not verify" };
+}
+export function generateSigningKeypair() {
+    const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+    return {
+        privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+        publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
+    };
+}
+export class LocalRegistrySource {
+    opts;
+    id = "local";
+    constructor(opts) {
+        this.opts = opts;
+        if (typeof opts.rootDir !== "string" || opts.rootDir === "") {
+            throw new TemplateRegistryError("LocalRegistrySource: rootDir is required");
+        }
+        if (!existsSync(opts.rootDir)) {
+            mkdirSync(opts.rootDir, { recursive: true, mode: 0o700 });
+        }
+    }
+    manifestPath(name) {
+        if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
+            throw new TemplateRegistryError(`invalid template name "${name}"`);
+        }
+        return join(this.opts.rootDir, `${name}.json`);
+    }
+    async list() {
+        const out = [];
+        if (!existsSync(this.opts.rootDir))
+            return out;
+        for (const f of readdirSync(this.opts.rootDir)) {
+            if (!f.endsWith(".json"))
+                continue;
+            const path = join(this.opts.rootDir, f);
+            if (!statSync(path).isFile())
+                continue;
+            try {
+                const m = JSON.parse(readFileSync(path, "utf8"));
+                const { yaml: _yaml, ...meta } = m;
+                out.push(meta);
+            }
+            catch {
+                // skip malformed files
+            }
+        }
+        return out.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async fetch(name) {
+        const path = this.manifestPath(name);
+        if (!existsSync(path)) {
+            throw new TemplateRegistryError(`template "${name}" not found`);
+        }
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    async metadata(name) {
+        const m = await this.fetch(name);
+        const { yaml: _yaml, ...meta } = m;
+        return meta;
+    }
+    /** Test/admin helper: write a manifest into the file-backed registry. */
+    put(manifest) {
+        const path = this.manifestPath(manifest.name);
+        writeFileSync(path, JSON.stringify(manifest, null, 2), { mode: 0o600 });
+    }
+}
+export class HttpRegistrySource {
+    opts;
+    id;
+    fetchImpl;
+    constructor(opts) {
+        this.opts = opts;
+        this.id = opts.id;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+    }
+    async list() {
+        const res = await this.fetchImpl(this.opts.listUrl);
+        if (!res.ok) {
+            throw new TemplateRegistryError(`${this.id} list ${res.status}: ${(await res.text()).slice(0, 256)}`);
+        }
+        const data = (await res.json());
+        if (!Array.isArray(data?.templates)) {
+            throw new TemplateRegistryError(`${this.id} list payload missing templates[]`);
+        }
+        return data.templates;
+    }
+    async fetch(name) {
+        const res = await this.fetchImpl(this.opts.fetchUrl(name));
+        if (!res.ok) {
+            throw new TemplateRegistryError(`${this.id} fetch "${name}" ${res.status}: ${(await res.text()).slice(0, 256)}`);
+        }
+        return (await res.json());
+    }
+    async metadata(name) {
+        const m = await this.fetch(name);
+        const { yaml: _yaml, ...meta } = m;
+        return meta;
+    }
+}
+const DEFAULT_TTL_MS = 60 * 60 * 1000; // 60 minutes
+export function cachedRegistry(opts) {
+    const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
+    const now = opts.now ?? (() => Date.now());
+    let listCache;
+    const fetchCache = new Map();
+    const metadataCache = new Map();
+    return {
+        id: `${opts.source.id}+cache`,
+        async list() {
+            if (listCache && listCache.expiresAt > now())
+                return listCache.value;
+            const value = await opts.source.list();
+            listCache = { value, expiresAt: now() + ttl };
+            return value;
+        },
+        async fetch(name) {
+            const hit = fetchCache.get(name);
+            if (hit && hit.expiresAt > now())
+                return hit.value;
+            const value = await opts.source.fetch(name);
+            fetchCache.set(name, { value, expiresAt: now() + ttl });
+            return value;
+        },
+        async metadata(name) {
+            const hit = metadataCache.get(name);
+            if (hit && hit.expiresAt > now())
+                return hit.value;
+            const value = await opts.source.metadata(name);
+            metadataCache.set(name, { value, expiresAt: now() + ttl });
+            return value;
+        },
+        refresh() {
+            listCache = undefined;
+            fetchCache.clear();
+            metadataCache.clear();
+        },
+    };
+}
+export function verifyingRegistry(opts) {
+    return {
+        id: `${opts.source.id}+verifying`,
+        async list() {
+            // metadata-only listings can't verify (no yaml + signature is on the
+            // full manifest); list returns metadata as-is and callers must call
+            // fetch() to get a verified manifest.
+            return opts.source.list();
+        },
+        async fetch(name) {
+            const manifest = await opts.source.fetch(name);
+            const result = verifyManifest(manifest, opts.trustRoot);
+            if (!result.ok) {
+                throw new TemplateRegistryError(`template "${name}" failed signature verification: ${result.reason ?? "unknown reason"}`);
+            }
+            return manifest;
+        },
+        async metadata(name) {
+            return opts.source.metadata(name);
+        },
+    };
+}
+export { canonicalManifestJson as _canonicalManifestJsonForTest, DEFAULT_TTL_MS as _defaultTtlMsForTest, };

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@crewhaus/template-registry",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "description": "Backend-agnostic spec-template registry: git/huggingface/npm/local backends + TTL cache + sigstore-style signature verification (Section 40)",
-  "main": "src/index.ts",
-  "types": "src/index.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "test": "bun test src"
   },
   "dependencies": {
-    "@crewhaus/errors": "0.1.4"
+    "@crewhaus/errors": "0.1.5"
   },
   "license": "Apache-2.0",
   "author": {
@@ -32,5 +35,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "files": ["src", "README.md", "LICENSE", "NOTICE"]
+  "files": ["dist", "README.md", "LICENSE", "NOTICE"]
 }

package/src/index.test.ts

@@ -1,455 +0,0 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import {
-  HttpRegistrySource,
-  LocalRegistrySource,
-  type RegistrySource,
-  type TemplateManifest,
-  TemplateRegistryError,
-  _canonicalManifestJsonForTest,
-  _defaultTtlMsForTest,
-  cachedRegistry,
-  generateSigningKeypair,
-  signManifest,
-  verifyManifest,
-  verifyingRegistry,
-} from "./index";
-
-const baseManifest = {
-  name: "hello-cli-template",
-  version: "1.0.0",
-  description: "A CLI hello-world template",
-  author: "test",
-  target: "cli",
-  yaml: "name: hello\ntarget: cli\nagent:\n  model: claude-sonnet-4-6\n",
-};
-
-describe("Canonical JSON + signing (T1)", () => {
-  test("canonicalManifestJson is stable", () => {
-    const a = _canonicalManifestJsonForTest({ ...baseManifest });
-    const b = _canonicalManifestJsonForTest({ ...baseManifest });
-    expect(a).toBe(b);
-  });
-
-  test("signManifest + verifyManifest round-trip", () => {
-    const { privateKey, publicKey } = generateSigningKeypair();
-    const sig = signManifest({ ...baseManifest, publicKey }, privateKey);
-    const manifest: TemplateManifest = { ...baseManifest, publicKey, signature: sig };
-    const result = verifyManifest(manifest, { publicKeys: [publicKey] });
-    expect(result.ok).toBe(true);
-  });
-
-  test("verifyManifest rejects tampered yaml", () => {
-    const { privateKey, publicKey } = generateSigningKeypair();
-    const sig = signManifest({ ...baseManifest, publicKey }, privateKey);
-    const manifest: TemplateManifest = {
-      ...baseManifest,
-      yaml: "tampered: true\n",
-      publicKey,
-      signature: sig,
-    };
-    const result = verifyManifest(manifest, { publicKeys: [publicKey] });
-    expect(result.ok).toBe(false);
-    expect(result.reason).toContain("signature does not verify");
-  });
-
-  test("verifyManifest rejects unsigned manifest", () => {
-    const manifest: TemplateManifest = { ...baseManifest };
-    const result = verifyManifest(manifest, { publicKeys: ["x"] });
-    expect(result.ok).toBe(false);
-    expect(result.reason).toMatch(/unsigned/);
-  });
-
-  test("verifyManifest rejects missing publicKey", () => {
-    const manifest: TemplateManifest = { ...baseManifest, signature: "abc" };
-    const result = verifyManifest(manifest, { publicKeys: [] });
-    expect(result.ok).toBe(false);
-    expect(result.reason).toMatch(/missing publicKey/);
-  });
-
-  test("verifyManifest rejects publicKey not in trust root", () => {
-    const { privateKey, publicKey } = generateSigningKeypair();
-    const sig = signManifest({ ...baseManifest, publicKey }, privateKey);
-    const manifest: TemplateManifest = { ...baseManifest, publicKey, signature: sig };
-    // Trust a DIFFERENT key.
-    const other = generateSigningKeypair();
-    const result = verifyManifest(manifest, { publicKeys: [other.publicKey] });
-    expect(result.ok).toBe(false);
-    expect(result.reason).toMatch(/not in trust root/);
-  });
-});
-
-describe("LocalRegistrySource (T1)", () => {
-  let tmp: string;
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "template-registry-test-"));
-  });
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  test("put + fetch round-trip", async () => {
-    const src = new LocalRegistrySource({ rootDir: tmp });
-    const manifest: TemplateManifest = { ...baseManifest };
-    src.put(manifest);
-    const fetched = await src.fetch("hello-cli-template");
-    expect(fetched.name).toBe("hello-cli-template");
-    expect(fetched.yaml).toBe(baseManifest.yaml);
-  });
-
-  test("metadata strips yaml field", async () => {
-    const src = new LocalRegistrySource({ rootDir: tmp });
-    src.put({ ...baseManifest });
-    const meta = await src.metadata("hello-cli-template");
-    expect("yaml" in meta).toBe(false);
-    expect(meta.target).toBe("cli");
-  });
-
-  test("list returns metadata for all manifests, sorted", async () => {
-    const src = new LocalRegistrySource({ rootDir: tmp });
-    src.put({ ...baseManifest, name: "zebra" });
-    src.put({ ...baseManifest, name: "alpha" });
-    const list = await src.list();
-    expect(list.map((m) => m.name)).toEqual(["alpha", "zebra"]);
-  });
-
-  test("fetch unknown template throws", async () => {
-    const src = new LocalRegistrySource({ rootDir: tmp });
-    await expect(src.fetch("ghost")).rejects.toThrow(TemplateRegistryError);
-  });
-
-  test("rejects malformed template names (path traversal)", () => {
-    const src = new LocalRegistrySource({ rootDir: tmp });
-    expect(() => src.put({ ...baseManifest, name: "../escape" })).toThrow(/invalid template name/);
-    expect(() => src.put({ ...baseManifest, name: "evil/template" })).toThrow(
-      /invalid template name/,
-    );
-  });
-
-  test("requires rootDir", () => {
-    expect(() => new LocalRegistrySource({ rootDir: "" })).toThrow(TemplateRegistryError);
-  });
-});
-
-describe("HttpRegistrySource (T1)", () => {
-  test("list parses templates[] from JSON", async () => {
-    const fetchImpl = (async () =>
-      new Response(
-        JSON.stringify({
-          templates: [
-            { ...baseManifest, name: "remote-a" },
-            { ...baseManifest, name: "remote-b" },
-          ].map(({ yaml: _y, ...rest }) => rest),
-        }),
-        { status: 200 },
-      )) as unknown as typeof fetch;
-    const src = new HttpRegistrySource({
-      id: "git",
-      listUrl: "https://example.test/list",
-      fetchUrl: (n) => `https://example.test/fetch/${n}`,
-      fetchImpl,
-    });
-    const list = await src.list();
-    expect(list.map((m) => m.name).sort()).toEqual(["remote-a", "remote-b"]);
-  });
-
-  test("list throws on non-2xx", async () => {
-    const fetchImpl = (async () =>
-      new Response("not found", { status: 404 })) as unknown as typeof fetch;
-    const src = new HttpRegistrySource({
-      id: "git",
-      listUrl: "https://example.test/list",
-      fetchUrl: (n) => `https://example.test/fetch/${n}`,
-      fetchImpl,
-    });
-    await expect(src.list()).rejects.toThrow(/git list 404/);
-  });
-
-  test("list throws when payload missing templates[]", async () => {
-    const fetchImpl = (async () =>
-      new Response(JSON.stringify({ wrong: true }), { status: 200 })) as unknown as typeof fetch;
-    const src = new HttpRegistrySource({
-      id: "huggingface",
-      listUrl: "https://hf.test/list",
-      fetchUrl: (n) => `https://hf.test/${n}`,
-      fetchImpl,
-    });
-    await expect(src.list()).rejects.toThrow(/missing templates\[\]/);
-  });
-
-  test("fetch returns the full manifest from the per-name URL", async () => {
-    const seenUrls: string[] = [];
-    const fetchImpl = (async (url: string) => {
-      seenUrls.push(url);
-      return new Response(JSON.stringify({ ...baseManifest, name: "remote-c" }), { status: 200 });
-    }) as unknown as typeof fetch;
-    const src = new HttpRegistrySource({
-      id: "npm",
-      listUrl: "https://npm.test/list",
-      fetchUrl: (n) => `https://npm.test/pkg/${n}`,
-      fetchImpl,
-    });
-    const m = await src.fetch("remote-c");
-    expect(m.name).toBe("remote-c");
-    expect(m.yaml).toBe(baseManifest.yaml);
-    expect(seenUrls).toEqual(["https://npm.test/pkg/remote-c"]);
-  });
-
-  test("fetch throws on non-2xx with id, name, status and body tail", async () => {
-    const fetchImpl = (async () =>
-      new Response("nope", { status: 503 })) as unknown as typeof fetch;
-    const src = new HttpRegistrySource({
-      id: "git",
-      listUrl: "https://example.test/list",
-      fetchUrl: (n) => `https://example.test/fetch/${n}`,
-      fetchImpl,
-    });
-    await expect(src.fetch("ghost")).rejects.toThrow(/git fetch "ghost" 503: nope/);
-  });
-
-  test("metadata strips yaml from the fetched manifest", async () => {
-    const fetchImpl = (async () =>
-      new Response(JSON.stringify({ ...baseManifest, name: "remote-d" }), {
-        status: 200,
-      })) as unknown as typeof fetch;
-    const src = new HttpRegistrySource({
-      id: "git",
-      listUrl: "https://example.test/list",
-      fetchUrl: (n) => `https://example.test/fetch/${n}`,
-      fetchImpl,
-    });
-    const meta = await src.metadata("remote-d");
-    expect(meta.name).toBe("remote-d");
-    expect("yaml" in meta).toBe(false);
-  });
-});
-
-describe("cachedRegistry — TTL caching (T9)", () => {
-  test("repeated list calls within TTL hit the cache", async () => {
-    let listCalls = 0;
-    const upstream: RegistrySource = {
-      id: "upstream",
-      async list() {
-        listCalls += 1;
-        return [];
-      },
-      async fetch() {
-        throw new Error("not used");
-      },
-      async metadata() {
-        throw new Error("not used");
-      },
-    };
-    let now = 1_000;
-    const cached = cachedRegistry({ source: upstream, now: () => now, ttlMs: 1_000 });
-    await cached.list();
-    await cached.list();
-    expect(listCalls).toBe(1);
-    now += 1_500; // past TTL
-    await cached.list();
-    expect(listCalls).toBe(2);
-  });
-
-  test("refresh() clears the cache", async () => {
-    let calls = 0;
-    const upstream: RegistrySource = {
-      id: "u",
-      async list() {
-        calls += 1;
-        return [];
-      },
-      async fetch() {
-        throw new Error("nope");
-      },
-      async metadata() {
-        throw new Error("nope");
-      },
-    };
-    const cached = cachedRegistry({ source: upstream, ttlMs: 60_000 });
-    await cached.list();
-    await cached.list();
-    expect(calls).toBe(1);
-    cached.refresh();
-    await cached.list();
-    expect(calls).toBe(2);
-  });
-
-  test("default TTL is 60 minutes", () => {
-    expect(_defaultTtlMsForTest).toBe(60 * 60 * 1000);
-  });
-
-  test("fetch caches per-name within TTL, re-fetches after expiry and refresh", async () => {
-    let fetchCalls = 0;
-    const upstream: RegistrySource = {
-      id: "u",
-      async list() {
-        return [];
-      },
-      async fetch(name) {
-        fetchCalls += 1;
-        return { ...baseManifest, name };
-      },
-      async metadata() {
-        throw new Error("not used");
-      },
-    };
-    let now = 1_000;
-    const cached = cachedRegistry({ source: upstream, now: () => now, ttlMs: 1_000 });
-    await cached.fetch("a");
-    await cached.fetch("a"); // cache hit
-    expect(fetchCalls).toBe(1);
-    await cached.fetch("b"); // different key → miss
-    expect(fetchCalls).toBe(2);
-    now += 1_500; // past TTL for "a"
-    await cached.fetch("a");
-    expect(fetchCalls).toBe(3);
-    cached.refresh();
-    await cached.fetch("a");
-    expect(fetchCalls).toBe(4);
-  });
-
-  test("metadata caches per-name within TTL, re-fetches after expiry and refresh", async () => {
-    let metaCalls = 0;
-    const upstream: RegistrySource = {
-      id: "u",
-      async list() {
-        return [];
-      },
-      async fetch() {
-        throw new Error("not used");
-      },
-      async metadata(name) {
-        metaCalls += 1;
-        const { yaml: _y, ...meta } = { ...baseManifest, name };
-        return meta;
-      },
-    };
-    let now = 5_000;
-    const cached = cachedRegistry({ source: upstream, now: () => now, ttlMs: 2_000 });
-    const first = await cached.metadata("a");
-    expect(first.name).toBe("a");
-    await cached.metadata("a"); // cache hit
-    expect(metaCalls).toBe(1);
-    now += 2_500; // past TTL
-    await cached.metadata("a");
-    expect(metaCalls).toBe(2);
-    cached.refresh();
-    await cached.metadata("a");
-    expect(metaCalls).toBe(3);
-  });
-
-  test("cached id annotates the wrapped source id", () => {
-    const upstream: RegistrySource = {
-      id: "git",
-      async list() {
-        return [];
-      },
-      async fetch() {
-        throw new Error("not used");
-      },
-      async metadata() {
-        throw new Error("not used");
-      },
-    };
-    const cached = cachedRegistry({ source: upstream });
-    expect(cached.id).toBe("git+cache");
-  });
-});
-
-describe("verifyingRegistry — T8 supply-chain check", () => {
-  let tmp: string;
-  beforeEach(() => {
-    tmp = mkdtempSync(join(tmpdir(), "template-registry-verify-"));
-  });
-  afterEach(() => {
-    rmSync(tmp, { recursive: true, force: true });
-  });
-
-  test("fetch verifies signature against trust root", async () => {
-    const { privateKey, publicKey } = generateSigningKeypair();
-    const sig = signManifest({ ...baseManifest, publicKey }, privateKey);
-    const local = new LocalRegistrySource({ rootDir: tmp });
-    local.put({ ...baseManifest, publicKey, signature: sig });
-    const verifying = verifyingRegistry({
-      source: local,
-      trustRoot: { publicKeys: [publicKey] },
-    });
-    const fetched = await verifying.fetch("hello-cli-template");
-    expect(fetched.name).toBe("hello-cli-template");
-  });
-
-  test("fetch refuses unverified manifest", async () => {
-    const local = new LocalRegistrySource({ rootDir: tmp });
-    local.put({ ...baseManifest }); // no signature
-    const { publicKey } = generateSigningKeypair();
-    const verifying = verifyingRegistry({
-      source: local,
-      trustRoot: { publicKeys: [publicKey] },
-    });
-    await expect(verifying.fetch("hello-cli-template")).rejects.toThrow(
-      /failed signature verification/,
-    );
-  });
-
-  test("fetch refuses tampered manifest", async () => {
-    const { privateKey, publicKey } = generateSigningKeypair();
-    const sig = signManifest({ ...baseManifest, publicKey }, privateKey);
-    const local = new LocalRegistrySource({ rootDir: tmp });
-    local.put({ ...baseManifest, publicKey, signature: sig, yaml: "evil: true" });
-    const verifying = verifyingRegistry({
-      source: local,
-      trustRoot: { publicKeys: [publicKey] },
-    });
-    await expect(verifying.fetch("hello-cli-template")).rejects.toThrow(
-      /signature does not verify/,
-    );
-  });
-
-  test("fetch refuses signature from untrusted key", async () => {
-    const a = generateSigningKeypair();
-    const b = generateSigningKeypair();
-    const sig = signManifest({ ...baseManifest, publicKey: a.publicKey }, a.privateKey);
-    const local = new LocalRegistrySource({ rootDir: tmp });
-    local.put({ ...baseManifest, publicKey: a.publicKey, signature: sig });
-    const verifying = verifyingRegistry({
-      source: local,
-      trustRoot: { publicKeys: [b.publicKey] }, // trust a different key only
-    });
-    await expect(verifying.fetch("hello-cli-template")).rejects.toThrow(/not in trust root/);
-  });
-
-  test("id annotates the wrapped source", async () => {
-    const local = new LocalRegistrySource({ rootDir: tmp });
-    const verifying = verifyingRegistry({ source: local, trustRoot: { publicKeys: [] } });
-    expect(verifying.id).toBe("local+verifying");
-  });
-
-  test("list passes metadata through unverified (verification is fetch-only)", async () => {
-    const { privateKey, publicKey } = generateSigningKeypair();
-    const sig = signManifest({ ...baseManifest, publicKey }, privateKey);
-    const local = new LocalRegistrySource({ rootDir: tmp });
-    local.put({ ...baseManifest, name: "signed-one", publicKey, signature: sig });
-    local.put({ ...baseManifest, name: "unsigned-two" }); // no signature
-    const verifying = verifyingRegistry({
-      source: local,
-      trustRoot: { publicKeys: [publicKey] },
-    });
-    // list does NOT verify — it returns metadata for every manifest as-is.
-    const list = await verifying.list();
-    expect(list.map((m) => m.name)).toEqual(["signed-one", "unsigned-two"]);
-  });
-
-  test("metadata passes through without signature verification", async () => {
-    const local = new LocalRegistrySource({ rootDir: tmp });
-    local.put({ ...baseManifest, name: "meta-only" }); // unsigned
-    const verifying = verifyingRegistry({
-      source: local,
-      trustRoot: { publicKeys: [] },
-    });
-    const meta = await verifying.metadata("meta-only");
-    expect(meta.name).toBe("meta-only");
-    expect("yaml" in meta).toBe(false);
-  });
-});

package/src/index.ts

@@ -1,345 +0,0 @@
-import {
-  createPrivateKey,
-  createPublicKey,
-  sign as cryptoSign,
-  verify as cryptoVerify,
-  generateKeyPairSync,
-} from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { CrewhausError } from "@crewhaus/errors";
-
-/**
- * Catalog F4 `template-registry` — Section 40 backend-agnostic
- * spec-template registry.
- *
- * `RegistrySource` interface (`list`, `fetch`, `metadata`) so the
- * registry can be backed by git releases, HuggingFace datasets, npm
- * packages, a local directory, etc. Built-in `LocalRegistrySource`
- * is the file-backed default and the test fixture for the others.
- *
- * Manifest schema: `{ name, version, description, author, target,
- * yaml, exampleEnv?, screenshots?, signature?, publicKey? }`.
- * `signature` is base64-encoded Ed25519 over a canonical JSON of the
- * non-signature fields; `publicKey` is the corresponding raw public
- * key (PKCS#8 PEM or raw 32-byte). The registry verifies signatures
- * against a configured trust root; unverified manifests are refused
- * (T8 supply-chain check).
- *
- * TTL cache: `cachedRegistry({source, ttlMs})` wraps any source with
- * a 60-minute (default) TTL. `refresh()` clears the cache so callers
- * (and the `crewhaus templates refresh` CLI subcommand) can force a
- * re-fetch on demand.
- *
- * Layer F4. Pairs with `scaffold-templates` (§26 — built-in
- * templates), `template-marketplace-client` (§40 — Studio UI integration).
- */
-
-export class TemplateRegistryError extends CrewhausError {
-  override readonly name = "TemplateRegistryError";
-  constructor(message: string, cause?: unknown) {
-    super("config", message, cause);
-  }
-}
-
-export type TemplateManifest = {
-  readonly name: string;
-  readonly version: string;
-  readonly description: string;
-  readonly author: string;
-  readonly target: string;
-  readonly yaml: string;
-  readonly exampleEnv?: Record<string, string>;
-  readonly screenshots?: ReadonlyArray<string>;
-  /** Base64-encoded Ed25519 signature over canonical JSON of the rest. */
-  readonly signature?: string;
-  /** PKCS#8 PEM-encoded Ed25519 public key, OR raw 32-byte hex. */
-  readonly publicKey?: string;
-};
-
-export type SignableManifest = Omit<TemplateManifest, "signature">;
-
-export type TemplateMetadata = Omit<TemplateManifest, "yaml">;
-
-export interface RegistrySource {
-  readonly id: string;
-  list(): Promise<ReadonlyArray<TemplateMetadata>>;
-  fetch(name: string): Promise<TemplateManifest>;
-  metadata(name: string): Promise<TemplateMetadata>;
-}
-
-export type TrustRoot = {
-  /** PKCS#8 PEM-encoded Ed25519 public keys trusted to sign manifests. */
-  readonly publicKeys: ReadonlyArray<string>;
-};
-
-// --------------------------------------------------------------------
-// Canonical JSON for signing
-// --------------------------------------------------------------------
-
-function canonicalManifestJson(m: SignableManifest): string {
-  // Stable key order; omit undefined optional fields.
-  const ordered: Record<string, unknown> = {
-    name: m.name,
-    version: m.version,
-    description: m.description,
-    author: m.author,
-    target: m.target,
-    yaml: m.yaml,
-  };
-  if (m.exampleEnv !== undefined) ordered["exampleEnv"] = m.exampleEnv;
-  if (m.screenshots !== undefined) ordered["screenshots"] = m.screenshots;
-  if (m.publicKey !== undefined) ordered["publicKey"] = m.publicKey;
-  return JSON.stringify(ordered);
-}
-
-export function signManifest(manifest: SignableManifest, privateKeyPem: string): string {
-  const key = createPrivateKey(privateKeyPem);
-  const sig = cryptoSign(null, Buffer.from(canonicalManifestJson(manifest), "utf8"), key);
-  return sig.toString("base64");
-}
-
-export function verifyManifest(
-  manifest: TemplateManifest,
-  trustRoot: TrustRoot,
-): { ok: boolean; reason?: string } {
-  if (manifest.signature === undefined || manifest.signature === "") {
-    return { ok: false, reason: "manifest is unsigned" };
-  }
-  if (manifest.publicKey === undefined || manifest.publicKey === "") {
-    return { ok: false, reason: "manifest is missing publicKey" };
-  }
-  if (!trustRoot.publicKeys.some((pk) => pk === manifest.publicKey)) {
-    return { ok: false, reason: "publicKey is not in trust root" };
-  }
-  let key: ReturnType<typeof createPublicKey>;
-  try {
-    key = createPublicKey(manifest.publicKey);
-  } catch (err) {
-    return { ok: false, reason: `invalid publicKey: ${(err as Error).message}` };
-  }
-  const { signature: _sig, ...rest } = manifest;
-  const sigBuf = Buffer.from(manifest.signature, "base64");
-  const ok = cryptoVerify(null, Buffer.from(canonicalManifestJson(rest), "utf8"), key, sigBuf);
-  return ok ? { ok: true } : { ok: false, reason: "signature does not verify" };
-}
-
-export function generateSigningKeypair(): { privateKey: string; publicKey: string } {
-  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
-  return {
-    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
-    publicKey: publicKey.export({ type: "spki", format: "pem" }).toString(),
-  };
-}
-
-// --------------------------------------------------------------------
-// Local file-backed source (default)
-// --------------------------------------------------------------------
-
-export type LocalRegistrySourceOptions = {
-  readonly rootDir: string;
-};
-
-export class LocalRegistrySource implements RegistrySource {
-  readonly id = "local";
-  constructor(private readonly opts: LocalRegistrySourceOptions) {
-    if (typeof opts.rootDir !== "string" || opts.rootDir === "") {
-      throw new TemplateRegistryError("LocalRegistrySource: rootDir is required");
-    }
-    if (!existsSync(opts.rootDir)) {
-      mkdirSync(opts.rootDir, { recursive: true, mode: 0o700 });
-    }
-  }
-
-  private manifestPath(name: string): string {
-    if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) {
-      throw new TemplateRegistryError(`invalid template name "${name}"`);
-    }
-    return join(this.opts.rootDir, `${name}.json`);
-  }
-
-  async list(): Promise<ReadonlyArray<TemplateMetadata>> {
-    const out: TemplateMetadata[] = [];
-    if (!existsSync(this.opts.rootDir)) return out;
-    for (const f of readdirSync(this.opts.rootDir)) {
-      if (!f.endsWith(".json")) continue;
-      const path = join(this.opts.rootDir, f);
-      if (!statSync(path).isFile()) continue;
-      try {
-        const m = JSON.parse(readFileSync(path, "utf8")) as TemplateManifest;
-        const { yaml: _yaml, ...meta } = m;
-        out.push(meta);
-      } catch {
-        // skip malformed files
-      }
-    }
-    return out.sort((a, b) => a.name.localeCompare(b.name));
-  }
-
-  async fetch(name: string): Promise<TemplateManifest> {
-    const path = this.manifestPath(name);
-    if (!existsSync(path)) {
-      throw new TemplateRegistryError(`template "${name}" not found`);
-    }
-    return JSON.parse(readFileSync(path, "utf8")) as TemplateManifest;
-  }
-
-  async metadata(name: string): Promise<TemplateMetadata> {
-    const m = await this.fetch(name);
-    const { yaml: _yaml, ...meta } = m;
-    return meta;
-  }
-
-  /** Test/admin helper: write a manifest into the file-backed registry. */
-  put(manifest: TemplateManifest): void {
-    const path = this.manifestPath(manifest.name);
-    writeFileSync(path, JSON.stringify(manifest, null, 2), { mode: 0o600 });
-  }
-}
-
-// --------------------------------------------------------------------
-// Generic HTTP-backed source (covers git releases / HuggingFace / npm
-// — all of which serve manifest blobs over HTTP). Caller supplies the
-// list URL + per-manifest URL builder.
-// --------------------------------------------------------------------
-
-export type HttpRegistrySourceOptions = {
-  readonly id: "git" | "huggingface" | "npm";
-  readonly listUrl: string;
-  readonly fetchUrl: (name: string) => string;
-  readonly fetchImpl?: typeof fetch;
-};
-
-export class HttpRegistrySource implements RegistrySource {
-  readonly id: HttpRegistrySourceOptions["id"];
-  private readonly fetchImpl: typeof fetch;
-  constructor(private readonly opts: HttpRegistrySourceOptions) {
-    this.id = opts.id;
-    this.fetchImpl = opts.fetchImpl ?? fetch;
-  }
-
-  async list(): Promise<ReadonlyArray<TemplateMetadata>> {
-    const res = await this.fetchImpl(this.opts.listUrl);
-    if (!res.ok) {
-      throw new TemplateRegistryError(
-        `${this.id} list ${res.status}: ${(await res.text()).slice(0, 256)}`,
-      );
-    }
-    const data = (await res.json()) as { templates?: ReadonlyArray<TemplateMetadata> };
-    if (!Array.isArray(data?.templates)) {
-      throw new TemplateRegistryError(`${this.id} list payload missing templates[]`);
-    }
-    return data.templates;
-  }
-
-  async fetch(name: string): Promise<TemplateManifest> {
-    const res = await this.fetchImpl(this.opts.fetchUrl(name));
-    if (!res.ok) {
-      throw new TemplateRegistryError(
-        `${this.id} fetch "${name}" ${res.status}: ${(await res.text()).slice(0, 256)}`,
-      );
-    }
-    return (await res.json()) as TemplateManifest;
-  }
-
-  async metadata(name: string): Promise<TemplateMetadata> {
-    const m = await this.fetch(name);
-    const { yaml: _yaml, ...meta } = m;
-    return meta;
-  }
-}
-
-// --------------------------------------------------------------------
-// TTL cache wrapper
-// --------------------------------------------------------------------
-
-export type CachedRegistryOptions = {
-  readonly source: RegistrySource;
-  readonly ttlMs?: number;
-  readonly now?: () => number;
-};
-
-export interface CachedRegistry extends RegistrySource {
-  refresh(): void;
-}
-
-const DEFAULT_TTL_MS = 60 * 60 * 1000; // 60 minutes
-
-export function cachedRegistry(opts: CachedRegistryOptions): CachedRegistry {
-  const ttl = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const now = opts.now ?? ((): number => Date.now());
-  type Cache<T> = { value: T; expiresAt: number };
-  let listCache: Cache<ReadonlyArray<TemplateMetadata>> | undefined;
-  const fetchCache = new Map<string, Cache<TemplateManifest>>();
-  const metadataCache = new Map<string, Cache<TemplateMetadata>>();
-
-  return {
-    id: `${opts.source.id}+cache`,
-    async list(): Promise<ReadonlyArray<TemplateMetadata>> {
-      if (listCache && listCache.expiresAt > now()) return listCache.value;
-      const value = await opts.source.list();
-      listCache = { value, expiresAt: now() + ttl };
-      return value;
-    },
-    async fetch(name): Promise<TemplateManifest> {
-      const hit = fetchCache.get(name);
-      if (hit && hit.expiresAt > now()) return hit.value;
-      const value = await opts.source.fetch(name);
-      fetchCache.set(name, { value, expiresAt: now() + ttl });
-      return value;
-    },
-    async metadata(name): Promise<TemplateMetadata> {
-      const hit = metadataCache.get(name);
-      if (hit && hit.expiresAt > now()) return hit.value;
-      const value = await opts.source.metadata(name);
-      metadataCache.set(name, { value, expiresAt: now() + ttl });
-      return value;
-    },
-    refresh(): void {
-      listCache = undefined;
-      fetchCache.clear();
-      metadataCache.clear();
-    },
-  };
-}
-
-// --------------------------------------------------------------------
-// Verifying registry — wraps any source with mandatory signature
-// verification. Throws if the manifest's signature does not verify
-// against the configured trust root.
-// --------------------------------------------------------------------
-
-export type VerifyingRegistryOptions = {
-  readonly source: RegistrySource;
-  readonly trustRoot: TrustRoot;
-};
-
-export function verifyingRegistry(opts: VerifyingRegistryOptions): RegistrySource {
-  return {
-    id: `${opts.source.id}+verifying`,
-    async list(): Promise<ReadonlyArray<TemplateMetadata>> {
-      // metadata-only listings can't verify (no yaml + signature is on the
-      // full manifest); list returns metadata as-is and callers must call
-      // fetch() to get a verified manifest.
-      return opts.source.list();
-    },
-    async fetch(name: string): Promise<TemplateManifest> {
-      const manifest = await opts.source.fetch(name);
-      const result = verifyManifest(manifest, opts.trustRoot);
-      if (!result.ok) {
-        throw new TemplateRegistryError(
-          `template "${name}" failed signature verification: ${result.reason ?? "unknown reason"}`,
-        );
-      }
-      return manifest;
-    },
-    async metadata(name: string): Promise<TemplateMetadata> {
-      return opts.source.metadata(name);
-    },
-  };
-}
-
-export {
-  canonicalManifestJson as _canonicalManifestJsonForTest,
-  DEFAULT_TTL_MS as _defaultTtlMsForTest,
-};