@frockbot/catalog-core 0.0.0 → 0.1.1

package/package.json

@@ -1,14 +1,28 @@
 {
   "name": "@frockbot/catalog-core",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-composition": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.6",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/catalog-core"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/index.test.ts

@@ -0,0 +1,341 @@
+import { describe, expect, test } from "bun:test";
+import {
+  MAX_CATALOG_SKILL_BODY_BYTES_V1,
+  assertCatalogEntryMatchesIndexV1,
+  catalogContentHashV1,
+  catalogEntryKeyV1,
+  catalogSetupFieldKeyV1,
+  catalogIndexKeyV1,
+  CATALOG_POINTER_KEY_V1,
+  decodeCatalogEntryDocumentV1,
+  decodeCatalogEntryV1,
+  decodeCatalogIndexDocumentV1,
+  decodeCatalogIndexV1,
+  decodeCatalogPointerV1,
+  MAX_CATALOG_ENTRIES_V1,
+  parseCatalogIndexDocumentV1,
+  type CatalogEntryV1,
+  type CatalogIndexEntryV1,
+} from "./index.ts";
+
+const MANIFEST_HASH = "a".repeat(64);
+
+function indexEntry(
+  overrides: Partial<CatalogIndexEntryV1> = {},
+): CatalogIndexEntryV1 {
+  return {
+    catalogId: "mcp-weather",
+    packageId: "mcp-weather",
+    displayName: "Weather",
+    description: "Forecasts from a public MCP server.",
+    version: "0.0.1",
+    manifestHash: MANIFEST_HASH,
+    kind: "mcp-connector",
+    ...overrides,
+  };
+}
+
+function entryDetail(overrides: Partial<CatalogEntryV1> = {}): CatalogEntryV1 {
+  return {
+    schemaVersion: 1,
+    catalogId: "mcp-weather",
+    packageId: "mcp-weather",
+    displayName: "Weather",
+    description: "Forecasts from a public MCP server.",
+    version: "0.0.1",
+    kind: "mcp-connector",
+    manifestHash: MANIFEST_HASH,
+    servers: [],
+    setupFields: [],
+    skills: [],
+    ...overrides,
+  };
+}
+
+describe("catalog index decoding", () => {
+  test("accepts an index and keeps only declared fields", () => {
+    const index = decodeCatalogIndexV1({
+      schemaVersion: 1,
+      generation: "gen-0001",
+      entries: [indexEntry()],
+    });
+    expect(index.entries[0]?.catalogId).toBe("mcp-weather");
+    expect(Object.hasOwn(index.entries[0]!, "logo")).toBe(false);
+  });
+
+  test("rejects an unknown field on the index", () => {
+    expect(() =>
+      decodeCatalogIndexV1({
+        schemaVersion: 1,
+        generation: "gen-0001",
+        entries: [],
+        cursor: "next",
+      }),
+    ).toThrow('unknown field "cursor"');
+  });
+
+  test("rejects an unknown field on an entry", () => {
+    expect(() =>
+      decodeCatalogIndexV1({
+        schemaVersion: 1,
+        generation: "gen-0001",
+        entries: [{ ...indexEntry(), price: 10 }],
+      }),
+    ).toThrow('unknown field "price"');
+  });
+
+  test("rejects an unsupported schema version", () => {
+    expect(() =>
+      decodeCatalogIndexV1({
+        schemaVersion: 2,
+        generation: "gen-0001",
+        entries: [],
+      }),
+    ).toThrow("schema version is unsupported");
+  });
+
+  test("rejects a manifest hash that is not a SHA-256 digest", () => {
+    expect(() =>
+      decodeCatalogIndexV1({
+        schemaVersion: 1,
+        generation: "gen-0001",
+        entries: [indexEntry({ manifestHash: "not-a-hash" })],
+      }),
+    ).toThrow("manifestHash is invalid");
+  });
+
+  test("rejects a repeated catalogId", () => {
+    expect(() =>
+      decodeCatalogIndexV1({
+        schemaVersion: 1,
+        generation: "gen-0001",
+        entries: [indexEntry(), indexEntry()],
+      }),
+    ).toThrow("repeats a catalogId");
+  });
+
+  test("rejects more entries than the bound", () => {
+    expect(() =>
+      decodeCatalogIndexV1({
+        schemaVersion: 1,
+        generation: "gen-0001",
+        entries: Array.from({ length: MAX_CATALOG_ENTRIES_V1 + 1 }, (_, i) =>
+          indexEntry({ catalogId: `mcp-${i}`, packageId: `mcp-${i}` }),
+        ),
+      }),
+    ).toThrow("bounded array");
+  });
+
+  test("rejects a non-https logo or homepage", () => {
+    for (const field of ["logo", "homepage"] as const) {
+      expect(() =>
+        decodeCatalogIndexV1({
+          schemaVersion: 1,
+          generation: "gen-0001",
+          entries: [
+            indexEntry({
+              [field]: "javascript:alert(1)",
+            } as Partial<CatalogIndexEntryV1>),
+          ],
+        }),
+      ).toThrow("must be an https URL");
+    }
+  });
+});
+
+describe("catalog entry decoding", () => {
+  test("accepts servers, setup fields and skills", () => {
+    const entry = decodeCatalogEntryV1(
+      entryDetail({
+        servers: [
+          {
+            name: "weather",
+            transport: "streamable-http",
+            url: "https://mcp.example.com/weather",
+            auth: "api-key",
+          },
+        ],
+        setupFields: [
+          { type: "string", title: "Region", minLength: 2, maxLength: 8 },
+        ],
+        skills: [
+          {
+            name: "forecast",
+            description: "Ask for a forecast.",
+            body: "1. Ask the region.",
+          },
+        ],
+      }),
+    );
+    expect(entry.servers[0]?.transport).toBe("streamable-http");
+    expect(entry.setupFields[0]?.title).toBe("Region");
+    expect(entry.skills[0]?.name).toBe("forecast");
+    // The body lives in the entry document, at the pinned generation: a
+    // plugin-borne Skill is indexed there and copied nowhere.
+    expect(entry.skills[0]?.body).toBe("1. Ask the region.");
+  });
+
+  test("bounds a Skill body and refuses an unknown Skill field", () => {
+    expect(() =>
+      decodeCatalogEntryV1(
+        entryDetail({
+          skills: [
+            {
+              name: "forecast",
+              body: "x".repeat(MAX_CATALOG_SKILL_BODY_BYTES_V1 + 1),
+            },
+          ],
+        }),
+      ),
+    ).toThrow(/catalog skill body is invalid/u);
+    // A field GrokBot's own plugin index carries and a Catalog entry must not:
+    // a body is data, a file path is a claim about some host's disk.
+    const withFilePath = entryDetail();
+    (withFilePath.skills as unknown[]).push({
+      name: "forecast",
+      filePath: "plugins/cache/forecast/SKILL.md",
+    });
+    expect(() => decodeCatalogEntryV1(withFilePath)).toThrow(/unknown field/u);
+  });
+
+  test("rejects an unknown transport", () => {
+    expect(() =>
+      decodeCatalogEntryV1(
+        entryDetail({
+          servers: [
+            {
+              name: "weather",
+              transport: "stdio" as never,
+              url: "https://mcp.example.com/weather",
+              auth: "none",
+            },
+          ],
+        }),
+      ),
+    ).toThrow("transport is invalid");
+  });
+
+  test("rejects a setup field the Package manifest dialect would refuse", () => {
+    expect(() =>
+      decodeCatalogEntryV1(
+        entryDetail({ setupFields: [{ $ref: "#/x" } as never] }),
+      ),
+    ).toThrow();
+  });
+
+  test("rejects an unknown field on the detail document", () => {
+    expect(() =>
+      decodeCatalogEntryV1({ ...entryDetail(), installs: 12 }),
+    ).toThrow('unknown field "installs"');
+  });
+});
+
+describe("content addressing", () => {
+  test("verifies a document against its hash before decoding", async () => {
+    const document = JSON.stringify({
+      schemaVersion: 1,
+      generation: "gen-0001",
+      entries: [indexEntry()],
+    });
+    const hash = await catalogContentHashV1(document);
+    const index = await decodeCatalogIndexDocumentV1(document, hash);
+    expect(index.generation).toBe("gen-0001");
+  });
+
+  test("refuses a document whose bytes changed under a pinned hash", async () => {
+    const document = JSON.stringify({
+      schemaVersion: 1,
+      generation: "gen-0001",
+      entries: [indexEntry()],
+    });
+    const hash = await catalogContentHashV1(document);
+    const tampered = JSON.stringify({
+      schemaVersion: 1,
+      generation: "gen-0001",
+      entries: [indexEntry({ displayName: "Weather Pro" })],
+    });
+    await expect(decodeCatalogIndexDocumentV1(tampered, hash)).rejects.toThrow(
+      "failed content hash verification",
+    );
+  });
+
+  test("refuses an entry document under a mismatched hash", async () => {
+    const document = JSON.stringify(entryDetail());
+    await expect(
+      decodeCatalogEntryDocumentV1(document, "b".repeat(64)),
+    ).rejects.toThrow("failed content hash verification");
+  });
+
+  test("refuses a document that is not JSON", () => {
+    expect(() => parseCatalogIndexDocumentV1("<html>")).toThrow("is not JSON");
+  });
+});
+
+describe("object layout", () => {
+  test("keys name a generation-scoped, immutable object", () => {
+    expect(catalogIndexKeyV1("gen-0001")).toBe("catalog/gen-0001/index.json");
+    expect(catalogEntryKeyV1("gen-0001", "mcp-weather")).toBe(
+      "catalog/gen-0001/entry/mcp-weather.json",
+    );
+    expect(CATALOG_POINTER_KEY_V1).toBe("catalog/current");
+  });
+
+  test("refuses a generation or catalogId that could escape its prefix", () => {
+    expect(() => catalogIndexKeyV1("../secrets")).toThrow(
+      "catalog generation is invalid",
+    );
+    expect(() => catalogEntryKeyV1("gen-0001", "../../index")).toThrow(
+      "catalogId is invalid",
+    );
+  });
+
+  test("decodes the pointer and refuses a partial one", () => {
+    expect(
+      decodeCatalogPointerV1({
+        schemaVersion: 1,
+        generation: "gen-0001",
+        indexHash: MANIFEST_HASH,
+      }).generation,
+    ).toBe("gen-0001");
+    expect(() =>
+      decodeCatalogPointerV1({ schemaVersion: 1, generation: "gen-0001" }),
+    ).toThrow('is missing "indexHash"');
+  });
+});
+
+describe("entry against index", () => {
+  test("accepts an entry that agrees with its index row", () => {
+    expect(() =>
+      assertCatalogEntryMatchesIndexV1(entryDetail(), indexEntry()),
+    ).not.toThrow();
+  });
+
+  test("refuses an entry whose version drifted from the index", () => {
+    expect(() =>
+      assertCatalogEntryMatchesIndexV1(
+        entryDetail({ version: "0.0.2" }),
+        indexEntry(),
+      ),
+    ).toThrow("does not match its index row");
+  });
+});
+
+describe("a Catalog entry's setup fields", () => {
+  test("map to the values key an install records the answer under", () => {
+    // A setup field is a bare JSON Schema with no identifier, so the key an
+    // install records the answer under is derived from the title — in one
+    // place, because the form that collects it and anything that reads the
+    // install back have to agree.
+    expect(catalogSetupFieldKeyV1({ title: "Region" }, 0)).toBe("region");
+    expect(catalogSetupFieldKeyV1({ title: "Base URL" }, 1)).toBe("base-url");
+    expect(catalogSetupFieldKeyV1({ title: "  " }, 2)).toBe("setup-2");
+    expect(catalogSetupFieldKeyV1({}, 3)).toBe("setup-3");
+  });
+
+  test("give a stable key, so an answer survives a reopened form", () => {
+    const field = { title: "Workspace ID" };
+    expect(catalogSetupFieldKeyV1(field, 0)).toBe(
+      catalogSetupFieldKeyV1(field, 5),
+    );
+  });
+});

package/src/index.ts

@@ -0,0 +1,570 @@
+/**
+ * The remote Package Catalog seam.
+ *
+ * A Catalog *generation* is an immutable, content-addressed set of objects in
+ * the `PACKAGE_CATALOG` bucket:
+ *
+ *   catalog/<generation>/index.json          the whole index
+ *   catalog/<generation>/entry/<catalogId>.json   one entry's detail
+ *   catalog/current                          the mutable pointer
+ *
+ * The pointer is the only mutable object; everything it names is immutable, so
+ * a User Durable Object can pin one generation and one index hash and refuse an
+ * install that arrives against any other. Nothing here reaches the network or
+ * object storage: this module is the DTOs, their strict decoders and the key
+ * layout, so the gateway, the User Durable Object, the publisher script and the
+ * browser all agree without any of them importing another's runtime.
+ *
+ * These are product DTOs, not kernel types, which is why they live beside
+ * `configuration-core` and `connection-core` rather than in
+ * `kernel-composition`: the kernel decodes a Package *manifest*, and contains
+ * no product policy. The one thing borrowed from the kernel is the setting
+ * schema decoder, so a Catalog entry cannot describe a setup field a Package
+ * manifest could not declare.
+ */
+import {
+  decodePackageSettingSchemaV1,
+  type PackageSettingSchema,
+} from "@frockbot/kernel-composition";
+
+export class CatalogDecodeError extends Error {
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "CatalogDecodeError";
+  }
+}
+
+export const CATALOG_POINTER_KEY_V1 = "catalog/current";
+
+/** Bounds every Catalog document, so a hostile object cannot exhaust a DO. */
+export const MAX_CATALOG_ENTRIES_V1 = 512;
+export const MAX_CATALOG_SERVERS_V1 = 16;
+export const MAX_CATALOG_SETUP_FIELDS_V1 = 32;
+export const MAX_CATALOG_SKILLS_V1 = 64;
+/**
+ * Longest Skill body one Catalog entry may carry.
+ *
+ * A plugin-borne Skill is *indexed*, never copied into an instruction root
+ * (`docs/research/grokbot-computer.md` line 285: `plugin-skills/cache.json` is
+ * only an index). The entry document at the pinned generation is therefore the
+ * one place the body lives, and it is bounded here so a hostile entry cannot
+ * fill a system prompt or exhaust the document bound above.
+ */
+export const MAX_CATALOG_SKILL_BODY_BYTES_V1 = 16_384;
+export const MAX_CATALOG_DOCUMENT_BYTES_V1 = 1_048_576;
+
+export type CatalogEntryKindV1 = "package" | "mcp-connector";
+export type CatalogServerTransportV1 = "streamable-http" | "sse";
+export type CatalogServerAuthV1 = "none" | "api-key" | "oauth";
+
+export interface CatalogIndexEntryV1 {
+  catalogId: string;
+  packageId: string;
+  displayName: string;
+  description: string;
+  version: string;
+  manifestHash: string;
+  kind: CatalogEntryKindV1;
+  logo?: string;
+  homepage?: string;
+}
+
+export interface CatalogIndexV1 {
+  schemaVersion: 1;
+  generation: string;
+  entries: CatalogIndexEntryV1[];
+}
+
+export interface CatalogServerV1 {
+  name: string;
+  transport: CatalogServerTransportV1;
+  url: string;
+  auth: CatalogServerAuthV1;
+}
+
+export interface CatalogSkillV1 {
+  name: string;
+  description?: string;
+  /**
+   * The Markdown recipe, as a `SKILL.md` body. Optional: an entry may announce
+   * a Skill it does not ship, and the Skills Package then records a refusal
+   * rather than injecting a Skill with nothing to say.
+   */
+  body?: string;
+}
+
+export interface CatalogEntryV1 {
+  schemaVersion: 1;
+  catalogId: string;
+  packageId: string;
+  displayName: string;
+  description: string;
+  version: string;
+  kind: CatalogEntryKindV1;
+  manifestHash: string;
+  logo?: string;
+  homepage?: string;
+  servers: CatalogServerV1[];
+  setupFields: PackageSettingSchema[];
+  skills: CatalogSkillV1[];
+}
+
+/**
+ * The `values` key one `setupFields` entry fills in.
+ *
+ * A Catalog entry's setup fields are bare JSON Schemas: the shape carries a
+ * `title` and a `description` but no identifier, so the key an install records
+ * the answer under is derived from the title, and from its position when the
+ * schema declares none. Derived in one place because the form that collects
+ * the answer and anything that later reads it have to agree.
+ */
+export function catalogSetupFieldKeyV1(
+  field: { title?: string },
+  index: number,
+): string {
+  const slug = (field.title ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 64);
+  return slug || `setup-${index}`;
+}
+
+/** The mutable pointer at `catalog/current`, naming the live generation. */
+export interface CatalogPointerV1 {
+  schemaVersion: 1;
+  generation: string;
+  indexHash: string;
+}
+
+/** What a reader pins: one generation and the hash of its index bytes. */
+export interface CatalogPinV1 {
+  generation: string;
+  indexHash: string;
+}
+
+const GENERATION_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const CATALOG_ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const PACKAGE_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+const HASH_PATTERN = /^[0-9a-f]{64}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function exactRecord(
+  value: unknown,
+  label: string,
+  required: readonly string[],
+  optional: readonly string[] = [],
+): Record<string, unknown> {
+  if (!isRecord(value)) {
+    throw new CatalogDecodeError(`${label} must be an object`);
+  }
+  const allowed = new Set([...required, ...optional]);
+  for (const key of Reflect.ownKeys(value)) {
+    if (typeof key !== "string" || !allowed.has(key)) {
+      throw new CatalogDecodeError(
+        `${label} has unknown field "${String(key)}"`,
+      );
+    }
+  }
+  for (const key of required) {
+    if (!Object.hasOwn(value, key)) {
+      throw new CatalogDecodeError(`${label} is missing "${key}"`);
+    }
+  }
+  return value;
+}
+
+function text(
+  value: unknown,
+  label: string,
+  maxLength: number,
+  { allowEmpty = false } = {},
+): string {
+  if (
+    typeof value !== "string" ||
+    value.length > maxLength ||
+    (!allowEmpty && value.trim().length === 0)
+  ) {
+    throw new CatalogDecodeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function optionalText(
+  value: unknown,
+  label: string,
+  maxLength: number,
+): string | undefined {
+  return value === undefined ? undefined : text(value, label, maxLength);
+}
+
+function pattern(
+  value: unknown,
+  label: string,
+  expression: RegExp,
+  maxLength = 128,
+): string {
+  const candidate = text(value, label, maxLength);
+  if (!expression.test(candidate)) {
+    throw new CatalogDecodeError(`${label} is invalid`);
+  }
+  return candidate;
+}
+
+function boundedArray(
+  value: unknown,
+  label: string,
+  maxLength: number,
+): unknown[] {
+  if (!Array.isArray(value) || value.length > maxLength) {
+    throw new CatalogDecodeError(`${label} must be a bounded array`);
+  }
+  return value;
+}
+
+function entryKind(value: unknown, label: string): CatalogEntryKindV1 {
+  if (value !== "package" && value !== "mcp-connector") {
+    throw new CatalogDecodeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+/**
+ * A Catalog logo and homepage are rendered by the browser, so only an absolute
+ * `https:` URL is admitted: a `javascript:` or `data:` value in a document the
+ * gateway serves would otherwise reach an `href` or an `img`.
+ */
+function httpsUrl(value: unknown, label: string): string {
+  const candidate = text(value, label, 2_048);
+  const url = URL.parse(candidate);
+  if (!url || url.protocol !== "https:") {
+    throw new CatalogDecodeError(`${label} must be an https URL`);
+  }
+  return candidate;
+}
+
+function optionalHttpsUrl(value: unknown, label: string): string | undefined {
+  return value === undefined ? undefined : httpsUrl(value, label);
+}
+
+function withOptional<T extends Record<string, unknown>>(
+  base: T,
+  optional: Record<string, string | undefined>,
+): T {
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(optional)) {
+    if (value !== undefined) result[key] = value;
+  }
+  return result as T;
+}
+
+function schemaVersion(value: Record<string, unknown>, label: string): void {
+  if (value.schemaVersion !== 1) {
+    throw new CatalogDecodeError(`${label} schema version is unsupported`);
+  }
+}
+
+export function decodeCatalogGenerationIdV1(value: unknown): string {
+  return pattern(value, "catalog generation", GENERATION_PATTERN, 64);
+}
+
+export function decodeCatalogIdV1(value: unknown): string {
+  return pattern(value, "catalogId", CATALOG_ID_PATTERN, 64);
+}
+
+export function decodeCatalogContentHashV1(
+  value: unknown,
+  label = "catalog content hash",
+): string {
+  return pattern(value, label, HASH_PATTERN, 64);
+}
+
+export function decodeCatalogIndexEntryV1(value: unknown): CatalogIndexEntryV1 {
+  const entry = exactRecord(
+    value,
+    "catalog entry",
+    [
+      "catalogId",
+      "packageId",
+      "displayName",
+      "description",
+      "version",
+      "manifestHash",
+      "kind",
+    ],
+    ["logo", "homepage"],
+  );
+  return withOptional(
+    {
+      catalogId: decodeCatalogIdV1(entry.catalogId),
+      packageId: pattern(entry.packageId, "packageId", PACKAGE_ID_PATTERN, 64),
+      displayName: text(entry.displayName, "displayName", 100),
+      description: text(entry.description, "description", 2_000, {
+        allowEmpty: true,
+      }),
+      version: text(entry.version, "version", 100),
+      manifestHash: decodeCatalogContentHashV1(
+        entry.manifestHash,
+        "manifestHash",
+      ),
+      kind: entryKind(entry.kind, "kind"),
+    },
+    {
+      logo: optionalHttpsUrl(entry.logo, "logo"),
+      homepage: optionalHttpsUrl(entry.homepage, "homepage"),
+    },
+  );
+}
+
+export function decodeCatalogIndexV1(input: unknown): CatalogIndexV1 {
+  const value = exactRecord(input, "catalog index", [
+    "schemaVersion",
+    "generation",
+    "entries",
+  ]);
+  schemaVersion(value, "catalog index");
+  const entries = boundedArray(
+    value.entries,
+    "catalog index entries",
+    MAX_CATALOG_ENTRIES_V1,
+  ).map(decodeCatalogIndexEntryV1);
+  const identifiers = new Set(entries.map((entry) => entry.catalogId));
+  if (identifiers.size !== entries.length) {
+    throw new CatalogDecodeError("catalog index repeats a catalogId");
+  }
+  return {
+    schemaVersion: 1,
+    generation: decodeCatalogGenerationIdV1(value.generation),
+    entries,
+  };
+}
+
+function decodeCatalogServerV1(value: unknown): CatalogServerV1 {
+  const server = exactRecord(value, "catalog server", [
+    "name",
+    "transport",
+    "url",
+    "auth",
+  ]);
+  if (server.transport !== "streamable-http" && server.transport !== "sse") {
+    throw new CatalogDecodeError("catalog server transport is invalid");
+  }
+  if (
+    server.auth !== "none" &&
+    server.auth !== "api-key" &&
+    server.auth !== "oauth"
+  ) {
+    throw new CatalogDecodeError("catalog server auth is invalid");
+  }
+  return {
+    name: text(server.name, "catalog server name", 100),
+    transport: server.transport,
+    url: httpsUrl(server.url, "catalog server url"),
+    auth: server.auth,
+  };
+}
+
+function decodeCatalogSkillV1(value: unknown): CatalogSkillV1 {
+  const skill = exactRecord(
+    value,
+    "catalog skill",
+    ["name"],
+    ["description", "body"],
+  );
+  return withOptional(
+    { name: text(skill.name, "catalog skill name", 100) },
+    {
+      description: optionalText(
+        skill.description,
+        "catalog skill description",
+        2_000,
+      ),
+      body: optionalText(
+        skill.body,
+        "catalog skill body",
+        MAX_CATALOG_SKILL_BODY_BYTES_V1,
+      ),
+    },
+  );
+}
+
+export function decodeCatalogEntryV1(input: unknown): CatalogEntryV1 {
+  const value = exactRecord(
+    input,
+    "catalog entry detail",
+    [
+      "schemaVersion",
+      "catalogId",
+      "packageId",
+      "displayName",
+      "description",
+      "version",
+      "kind",
+      "manifestHash",
+      "servers",
+      "setupFields",
+      "skills",
+    ],
+    ["logo", "homepage"],
+  );
+  schemaVersion(value, "catalog entry detail");
+  return withOptional(
+    {
+      schemaVersion: 1 as const,
+      catalogId: decodeCatalogIdV1(value.catalogId),
+      packageId: pattern(value.packageId, "packageId", PACKAGE_ID_PATTERN, 64),
+      displayName: text(value.displayName, "displayName", 100),
+      description: text(value.description, "description", 2_000, {
+        allowEmpty: true,
+      }),
+      version: text(value.version, "version", 100),
+      kind: entryKind(value.kind, "kind"),
+      manifestHash: decodeCatalogContentHashV1(
+        value.manifestHash,
+        "manifestHash",
+      ),
+      servers: boundedArray(
+        value.servers,
+        "catalog servers",
+        MAX_CATALOG_SERVERS_V1,
+      ).map(decodeCatalogServerV1),
+      setupFields: boundedArray(
+        value.setupFields,
+        "catalog setup fields",
+        MAX_CATALOG_SETUP_FIELDS_V1,
+      ).map(decodePackageSettingSchemaV1),
+      skills: boundedArray(
+        value.skills,
+        "catalog skills",
+        MAX_CATALOG_SKILLS_V1,
+      ).map(decodeCatalogSkillV1),
+    },
+    {
+      logo: optionalHttpsUrl(value.logo, "logo"),
+      homepage: optionalHttpsUrl(value.homepage, "homepage"),
+    },
+  );
+}
+
+export function decodeCatalogPointerV1(input: unknown): CatalogPointerV1 {
+  const value = exactRecord(input, "catalog pointer", [
+    "schemaVersion",
+    "generation",
+    "indexHash",
+  ]);
+  schemaVersion(value, "catalog pointer");
+  return {
+    schemaVersion: 1,
+    generation: decodeCatalogGenerationIdV1(value.generation),
+    indexHash: decodeCatalogContentHashV1(value.indexHash, "indexHash"),
+  };
+}
+
+export function catalogIndexKeyV1(generation: string): string {
+  return `catalog/${decodeCatalogGenerationIdV1(generation)}/index.json`;
+}
+
+export function catalogEntryKeyV1(
+  generation: string,
+  catalogId: string,
+): string {
+  return `catalog/${decodeCatalogGenerationIdV1(generation)}/entry/${decodeCatalogIdV1(catalogId)}.json`;
+}
+
+/**
+ * The content hash of one Catalog document: SHA-256 over the exact UTF-8 bytes
+ * the bucket holds. Hashing the bytes rather than a re-serialization is what
+ * makes a pinned `indexHash` mean "these bytes", so a reader that pins one and
+ * later reads different bytes at the same key sees a mismatch, not a silent
+ * re-canonicalization that hides it.
+ */
+export async function catalogContentHashV1(document: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(document),
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+function assertDocumentSize(document: string, label: string): void {
+  if (document.length > MAX_CATALOG_DOCUMENT_BYTES_V1) {
+    throw new CatalogDecodeError(`${label} is too large`);
+  }
+}
+
+function parseDocument(document: string, label: string): unknown {
+  assertDocumentSize(document, label);
+  try {
+    return JSON.parse(document) as unknown;
+  } catch (error) {
+    throw new CatalogDecodeError(`${label} is not JSON`, { cause: error });
+  }
+}
+
+async function assertContentHash(
+  document: string,
+  expectedHash: string,
+  label: string,
+): Promise<void> {
+  const actual = await catalogContentHashV1(document);
+  if (actual !== decodeCatalogContentHashV1(expectedHash, `${label} hash`)) {
+    throw new CatalogDecodeError(`${label} failed content hash verification`);
+  }
+}
+
+/**
+ * Read one index document: hash first, decode second. A mismatched hash is
+ * refused before the bytes are parsed, so nothing downstream ever sees a
+ * document that is not the one that was pinned.
+ */
+export async function decodeCatalogIndexDocumentV1(
+  document: string,
+  expectedHash: string,
+): Promise<CatalogIndexV1> {
+  await assertContentHash(document, expectedHash, "catalog index");
+  return decodeCatalogIndexV1(parseDocument(document, "catalog index"));
+}
+
+export async function decodeCatalogEntryDocumentV1(
+  document: string,
+  expectedHash: string,
+): Promise<CatalogEntryV1> {
+  await assertContentHash(document, expectedHash, "catalog entry");
+  return decodeCatalogEntryV1(parseDocument(document, "catalog entry"));
+}
+
+/** Parse an index document whose hash the caller has not pinned yet. */
+export function parseCatalogIndexDocumentV1(document: string): CatalogIndexV1 {
+  return decodeCatalogIndexV1(parseDocument(document, "catalog index"));
+}
+
+export function parseCatalogEntryDocumentV1(document: string): CatalogEntryV1 {
+  return decodeCatalogEntryV1(parseDocument(document, "catalog entry"));
+}
+
+/**
+ * An entry detail must agree with the index row that named it. The index is
+ * what a reader pinned, so identity, version and manifest hash are checked
+ * against it rather than trusted from the entry document.
+ */
+export function assertCatalogEntryMatchesIndexV1(
+  entry: CatalogEntryV1,
+  indexEntry: CatalogIndexEntryV1,
+): void {
+  if (
+    entry.catalogId !== indexEntry.catalogId ||
+    entry.packageId !== indexEntry.packageId ||
+    entry.version !== indexEntry.version ||
+    entry.kind !== indexEntry.kind ||
+    entry.manifestHash !== indexEntry.manifestHash
+  ) {
+    throw new CatalogDecodeError(
+      `catalog entry "${indexEntry.catalogId}" does not match its index row`,
+    );
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/catalog-core
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.