open-museum-mcp 0.6.0 → 0.7.0

package/dist/clearanceTool.d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+import type { Federation } from './core/index.js';
+/**
+ * Input schema for the `clearance_record` MCP tool.
+ *
+ * Deliberately does NOT regex-validate the id against ID_REGEX, unlike
+ * `get_artwork` and `cite`. The clearance tool's contract is that a non-cleared
+ * work — including a malformed id — returns a definitive DENY manifest, not an
+ * error. `federation.clearanceManifest` emits that deny for an invalid id, so
+ * gating the id here would wrongly convert a contractual deny into a ZodError.
+ */
+export declare const ClearanceInput: z.ZodObject<{
+    id: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Handle a `clearance_record` call. Returns a normal (non-error) tool result
+ * for every id: a cleared work yields a permitted manifest, a non-cleared or
+ * malformed id yields a deny manifest. Both are valid answers.
+ */
+export declare function handleClearanceRecord(federation: Federation, args: unknown): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;

package/dist/clearanceTool.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/**
+ * Input schema for the `clearance_record` MCP tool.
+ *
+ * Deliberately does NOT regex-validate the id against ID_REGEX, unlike
+ * `get_artwork` and `cite`. The clearance tool's contract is that a non-cleared
+ * work — including a malformed id — returns a definitive DENY manifest, not an
+ * error. `federation.clearanceManifest` emits that deny for an invalid id, so
+ * gating the id here would wrongly convert a contractual deny into a ZodError.
+ */
+export const ClearanceInput = z.object({
+    id: z.string(),
+});
+/**
+ * Handle a `clearance_record` call. Returns a normal (non-error) tool result
+ * for every id: a cleared work yields a permitted manifest, a non-cleared or
+ * malformed id yields a deny manifest. Both are valid answers.
+ */
+export async function handleClearanceRecord(federation, args) {
+    const input = ClearanceInput.parse(args);
+    const env = await federation.clearanceManifest(input.id);
+    return { content: [{ type: 'text', text: JSON.stringify(env, null, 2) }] };
+}
+//# sourceMappingURL=clearanceTool.js.map

package/dist/clearanceTool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clearanceTool.js","sourceRoot":"","sources":["../src/clearanceTool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE;CACf,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,UAAsB,EAAE,IAAa;IAC/E,MAAM,KAAK,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,GAAG,GAAG,MAAM,UAAU,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACzD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACtF,CAAC"}

package/dist/core/clearance/envelope.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tier-0 envelope: integrity, not authenticity. It wraps a pure Clearance
+ * Manifest payload with a hash computed over the payload's RFC 8785 (JCS)
+ * canonical bytes. The hash lives HERE, never inside the payload — payload
+ * purity is a design invariant (the payload never carries its own hash, its
+ * signature, or any commercial data).
+ *
+ * This is what the distributed OSS MCP emits by default; it ships no key.
+ * Tiers 1/2 (C2PA signing) wrap the same payload with a signature — the payload
+ * shape is unchanged across tiers.
+ */
+export interface Tier0Envelope<T = unknown> {
+    tier: 0;
+    payload: T;
+    integrity: {
+        alg: 'sha-256';
+        jcs: true;
+        hash: string;
+    };
+}
+/**
+ * Wrap a payload in a Tier-0 envelope. Canonicalizes FIRST (RFC 8785), then
+ * hashes the canonical bytes with Web Crypto (`crypto.subtle`, Workers-safe).
+ * Throws if the payload is not canonicalizable JSON.
+ */
+export declare function wrapTier0<T>(payload: T): Promise<Tier0Envelope<T>>;

package/dist/core/clearance/envelope.js

@@ -0,0 +1,15 @@
+import { canonicalizeToBytes } from './jcs.js';
+/**
+ * Wrap a payload in a Tier-0 envelope. Canonicalizes FIRST (RFC 8785), then
+ * hashes the canonical bytes with Web Crypto (`crypto.subtle`, Workers-safe).
+ * Throws if the payload is not canonicalizable JSON.
+ */
+export async function wrapTier0(payload) {
+    const bytes = canonicalizeToBytes(payload);
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    const hash = Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+    return { tier: 0, payload, integrity: { alg: 'sha-256', jcs: true, hash } };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/core/clearance/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../../../src/core/clearance/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAmB/C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,OAAU;IAC3C,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;SAC5C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;AAC9E,CAAC"}

package/dist/core/clearance/jcs.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Canonicalize a JSON-compatible value to its RFC 8785 string form.
+ * Throws on values JSON cannot represent (functions, symbols, undefined,
+ * non-finite numbers) — a Clearance Manifest payload must be canonicalizable.
+ */
+export declare function canonicalize(value: unknown): string;
+/** Canonicalize and encode to UTF-8 bytes (ArrayBuffer-backed, for Web Crypto). */
+export declare function canonicalizeToBytes(value: unknown): Uint8Array<ArrayBuffer>;

package/dist/core/clearance/jcs.js

@@ -0,0 +1,65 @@
+// RFC 8785 JSON Canonicalization Scheme (JCS).
+//
+// Produces the canonical UTF-8 serialization of a JSON value: object keys sorted
+// by UTF-16 code unit, ECMAScript number serialization, minimal string escaping,
+// no insignificant whitespace. This is the byte sequence a Clearance Manifest's
+// Tier-0 envelope hashes over.
+//
+// Lifted verbatim (ported to TypeScript) from the PIF sibling standard's vetted
+// dependency-free verifier (pif-spec/verifier/jcs.mjs). Runs unchanged in Node,
+// the browser, and Cloudflare Workers — no dependencies, no `node:` imports.
+//
+// IMPORTANT (the contract the spec must warn implementers about): canonicalize
+// FIRST, then hash the canonical bytes. Never hash the raw serialized string —
+// JSON.stringify on the same object can produce different bytes (key order,
+// whitespace) and therefore a different, non-interoperable hash.
+/**
+ * Canonicalize a JSON-compatible value to its RFC 8785 string form.
+ * Throws on values JSON cannot represent (functions, symbols, undefined,
+ * non-finite numbers) — a Clearance Manifest payload must be canonicalizable.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return 'null';
+    const t = typeof value;
+    if (t === 'boolean')
+        return value ? 'true' : 'false';
+    if (t === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error('JCS: non-finite numbers are not permitted in JSON');
+        }
+        // JSON.stringify uses ECMAScript Number-to-string, which is what JCS mandates.
+        return JSON.stringify(value);
+    }
+    if (t === 'string') {
+        // ECMAScript JSON string escaping (control chars as \u00XX, correct surrogate
+        // handling) is exactly the escaping RFC 8785 specifies.
+        //
+        // PORTABILITY NOTE for non-JS implementers (RFC 8785 §3.2.2.2): escape ONLY the
+        // two mandatory characters (" -> \", \ -> \\) and the C0 control range U+0000..U+001F,
+        // using the short forms \b \t \n \f \r where they exist and \u00XX (lowercase hex)
+        // otherwise. Do NOT escape the forward solidus "/", and do NOT escape any non-ASCII
+        // character; codepoints >= U+0080 are emitted as raw UTF-8. Over-escaping (e.g.
+        // \uXXXX for every non-ASCII char, as some language JSON encoders do by default) is
+        // the most common interop bug and will produce a different byte string, hence a
+        // different hash. V8's JSON.stringify already implements exactly this.
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalize).join(',') + ']';
+    }
+    if (t === 'object') {
+        // Object.keys() then default Array sort: lexicographic by UTF-16 code unit,
+        // which is the ordering RFC 8785 requires.
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const members = keys.map((k) => JSON.stringify(k) + ':' + canonicalize(obj[k]));
+        return '{' + members.join(',') + '}';
+    }
+    throw new Error(`JCS: unsupported value of type ${t}`);
+}
+/** Canonicalize and encode to UTF-8 bytes (ArrayBuffer-backed, for Web Crypto). */
+export function canonicalizeToBytes(value) {
+    return new TextEncoder().encode(canonicalize(value));
+}
+//# sourceMappingURL=jcs.js.map

package/dist/core/clearance/jcs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jcs.js","sourceRoot":"","sources":["../../../src/core/clearance/jcs.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,EAAE;AACF,iFAAiF;AACjF,iFAAiF;AACjF,gFAAgF;AAChF,+BAA+B;AAC/B,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,iEAAiE;AAEjE;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAElC,MAAM,CAAC,GAAG,OAAO,KAAK,CAAC;IAEvB,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAErD,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,+EAA+E;QAC/E,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,8EAA8E;QAC9E,wDAAwD;QACxD,EAAE;QACF,gFAAgF;QAChF,uFAAuF;QACvF,mFAAmF;QACnF,oFAAoF;QACpF,gFAAgF;QAChF,oFAAoF;QACpF,gFAAgF;QAChF,uEAAuE;QACvE,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACvD,CAAC;IAED,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnB,4EAA4E;QAC5E,2CAA2C;QAC3C,MAAM,GAAG,GAAG,KAAgC,CAAC;QAC7C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;QACrC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,GAAG,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAChF,OAAO,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACvC,CAAC;IAED,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,EAAE,CAAC,CAAC;AACzD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/core/clearance/licenseMap.d.ts

@@ -0,0 +1,38 @@
+import type { LicenseType, RightsConfidence } from '../../types.js';
+/**
+ * The structured `basis` for a single clearance determination. Shape is normative
+ * (schema-enforced): `rule`, `inputs`, and `summary` are all required —
+ * honesty-by-architecture. A determination that cannot name its rule, cite its
+ * inputs, and state its reasoning is not a valid determination.
+ *
+ * `rule` is a stable id that resolves as a fragment under the rule registry:
+ * `https://openclearance.org/v0.1/rules#<rule>`. The set of ids is OPEN, not a
+ * closed enum — an unrecognised id yields a non-fatal `unrecognised_rule`
+ * advisory at verification time, never a schema rejection. See
+ * `spec/clearance/v0.1/rules.md`.
+ */
+export interface ClearanceBasis {
+    rule: string;
+    inputs: {
+        field: string;
+        value: unknown;
+    }[];
+    summary: string;
+}
+export interface ClearanceDecision {
+    statement: string | null;
+    commercialReproduction: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    derivatives: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    attributionRequired: {
+        required: boolean;
+        basis: ClearanceBasis;
+    };
+    confidence: RightsConfidence;
+}
+export declare function clearanceForLicense(type: LicenseType): ClearanceDecision;

package/dist/core/clearance/licenseMap.js

@@ -0,0 +1,68 @@
+// The ONLY place clearance determinations live. Fail-closed: a license type not
+// listed here resolves to all-false / default-deny. Adding a recognised
+// permissive license later is a single entry here + a rule-registry row + a test.
+const PERMISSIVE = {
+    CC0: {
+        statement: 'https://creativecommons.org/publicdomain/zero/1.0/',
+        rulePrefix: 'cc0',
+        summaryNoun: 'CC0 public-domain dedication',
+    },
+    // The gate only emits type=PD for the worldwide Creative Commons Public
+    // Domain Mark (Europeana `rights` = .../publicdomain/mark/1.0/) and the
+    // Wikimedia PD/PDM templates — never a jurisdiction-scoped rightsstatements.org
+    // value. The Public Domain Mark URI is therefore the accurate, gate-aligned
+    // statement; the old US-scoped NoC-US URI claimed a narrower (and incorrect)
+    // scope the gate never asserts.
+    PD: {
+        statement: 'https://creativecommons.org/publicdomain/mark/1.0/',
+        rulePrefix: 'pd',
+        summaryNoun: 'Public Domain Mark status',
+    },
+};
+export function clearanceForLicense(type) {
+    const ok = PERMISSIVE[type];
+    const inputs = [{ field: 'license.type', value: type }];
+    if (ok) {
+        return {
+            statement: ok.statement,
+            commercialReproduction: {
+                permitted: true,
+                basis: {
+                    rule: `${ok.rulePrefix}-grants-commercial`,
+                    inputs,
+                    summary: `${ok.summaryNoun} permits all uses, including commercial.`,
+                },
+            },
+            derivatives: {
+                permitted: true,
+                basis: {
+                    rule: `${ok.rulePrefix}-grants-derivatives`,
+                    inputs,
+                    summary: `${ok.summaryNoun} permits modification and derivative works.`,
+                },
+            },
+            attributionRequired: {
+                required: false,
+                basis: {
+                    rule: `${ok.rulePrefix}-waives-attribution`,
+                    inputs,
+                    summary: `${ok.summaryNoun} requires no attribution as a condition of reuse.`,
+                },
+            },
+            confidence: 'high',
+        };
+    }
+    const denyBasis = {
+        rule: 'default-deny',
+        inputs,
+        summary: `unrecognized or non-permissive license type '${type}' ⇒ default deny`,
+    };
+    return {
+        statement: null,
+        commercialReproduction: { permitted: false, basis: denyBasis },
+        derivatives: { permitted: false, basis: denyBasis },
+        attributionRequired: { required: false, basis: denyBasis },
+        confidence: 'low',
+    };
+}
+//# sourceMappingURL=licenseMap.js.map

package/dist/core/clearance/licenseMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"licenseMap.js","sourceRoot":"","sources":["../../../src/core/clearance/licenseMap.ts"],"names":[],"mappings":"AA4BA,gFAAgF;AAChF,wEAAwE;AACxE,kFAAkF;AAClF,MAAM,UAAU,GAEZ;IACF,GAAG,EAAE;QACH,SAAS,EAAE,oDAAoD;QAC/D,UAAU,EAAE,KAAK;QACjB,WAAW,EAAE,8BAA8B;KAC5C;IACD,wEAAwE;IACxE,wEAAwE;IACxE,gFAAgF;IAChF,4EAA4E;IAC5E,6EAA6E;IAC7E,gCAAgC;IAChC,EAAE,EAAE;QACF,SAAS,EAAE,oDAAoD;QAC/D,UAAU,EAAE,IAAI;QAChB,WAAW,EAAE,2BAA2B;KACzC;CACF,CAAC;AAEF,MAAM,UAAU,mBAAmB,CAAC,IAAiB;IACnD,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAExD,IAAI,EAAE,EAAE,CAAC;QACP,OAAO;YACL,SAAS,EAAE,EAAE,CAAC,SAAS;YACvB,sBAAsB,EAAE;gBACtB,SAAS,EAAE,IAAI;gBACf,KAAK,EAAE;oBACL,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,oBAAoB;oBAC1C,MAAM;oBACN,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,0CAA0C;iBACrE;aACF;YACD,WAAW,EAAE;gBACX,SAAS,EAAE,IAAI;gBACf,KAAK,EAAE;oBACL,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,qBAAqB;oBAC3C,MAAM;oBACN,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,6CAA6C;iBACxE;aACF;YACD,mBAAmB,EAAE;gBACnB,QAAQ,EAAE,KAAK;gBACf,KAAK,EAAE;oBACL,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,qBAAqB;oBAC3C,MAAM;oBACN,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,mDAAmD;iBAC9E;aACF;YACD,UAAU,EAAE,MAAM;SACnB,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAmB;QAChC,IAAI,EAAE,cAAc;QACpB,MAAM;QACN,OAAO,EAAE,gDAAgD,IAAI,kBAAkB;KAChF,CAAC;IACF,OAAO;QACL,SAAS,EAAE,IAAI;QACf,sBAAsB,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE;QAC9D,WAAW,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE;QACnD,mBAAmB,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE;QAC1D,UAAU,EAAE,KAAK;KAClB,CAAC;AACJ,CAAC"}

package/dist/core/clearance/manifest.d.ts

@@ -0,0 +1,104 @@
+import type { Artist, ArtworkImages, RightsConfidence, ValidationResult } from '../../types.js';
+import { type ClearanceBasis } from './licenseMap.js';
+/**
+ * The pure Clearance Manifest payload (JSON-LD). It never contains its own hash,
+ * its signature, or any commercial data — integrity lives in the Tier-0 envelope
+ * (see envelope.ts), commerce in a sibling vendor assertion that references this
+ * payload by content hash. The payload is byte-identical to what the engine
+ * emits and independently verifiable.
+ *
+ * Field names mirror the engine's canonical Artwork vocabulary wherever they map
+ * (`artist`, `displayDate`, `imageUrls`, `imageOpenAccess`, `metadataOpenAccess`,
+ * `museum`) so the open-museum.art data-model reconciliation is a thin mapping,
+ * not a translation. JSON-LD semantics are supplied by aliasing these terms to
+ * schema.org / Dublin Core IRIs in context.jsonld — the `@context` is the sole
+ * normative authority; `specVersion` is human-readable convenience only.
+ */
+export interface ClearanceManifestPayload {
+    '@context': string[];
+    type: 'ClearanceManifest';
+    specVersion: string;
+    work: ClearanceWork;
+    source: ClearanceSource;
+    rights: ClearanceRights;
+    clearance: ClearanceBlock;
+    verification: ClearanceVerification;
+    /** Omitted for rejected records, which carry no identified Artwork to cite. */
+    citation?: ClearanceCitation;
+}
+export interface ClearanceWork {
+    id: string;
+    title?: string;
+    artist?: Artist;
+    displayDate?: string;
+    yearStart?: number | null;
+    yearEnd?: number | null;
+    medium?: string;
+}
+export interface ClearanceMuseum {
+    code: string;
+    name?: string;
+    url?: string;
+}
+export interface ClearanceSource {
+    museum: ClearanceMuseum;
+    apiUrl?: string;
+    pageUrl?: string;
+    originalUrl?: string;
+    imageUrls?: ArtworkImages;
+}
+export interface ClearanceRights {
+    statement: string | null;
+    sourceApiValue: {
+        field: string;
+        value: unknown;
+    } | null;
+    imageOpenAccess: boolean;
+    metadataOpenAccess: boolean;
+    confidence: RightsConfidence;
+}
+export interface ClearanceBlock {
+    commercialReproduction: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    derivatives: {
+        permitted: boolean;
+        basis: ClearanceBasis;
+    };
+    attributionRequired: {
+        required: boolean;
+        basis: ClearanceBasis;
+    };
+}
+export interface ClearanceVerification {
+    determinedBy: {
+        actor: string;
+        role: string;
+    };
+    tool: string;
+    determinedAt: string;
+    ruleContext: string;
+    determinationSource: {
+        type: string;
+        field?: string;
+        url?: string;
+        retrievedAt: string;
+    };
+}
+export interface ClearanceCitation {
+    full: string;
+    caption: string;
+    short: string;
+}
+export interface BuildOptions {
+    /** Engine version string for the `verification.tool` provenance field. */
+    engineVersion: string;
+    /**
+     * Generation timestamp, used only where no determination timestamp exists in
+     * the data (the deny path has no `license.verifiedAt`). Injected so manifests
+     * are deterministic and reproducible as conformance fixtures.
+     */
+    now: string;
+}
+export declare function buildClearancePayload(result: ValidationResult, opts: BuildOptions): ClearanceManifestPayload;

package/dist/core/clearance/manifest.js

@@ -0,0 +1,112 @@
+import { cite } from '../../cite.js';
+import { clearanceForLicense } from './licenseMap.js';
+const CONTEXT = [
+    'https://schema.org/',
+    'http://purl.org/dc/terms/',
+    'https://openclearance.org/v0.1/context.jsonld',
+];
+const TYPE = 'ClearanceManifest';
+const SPEC_VERSION = '0.1';
+const TOOL_NAME = 'open-museum-mcp';
+/** Split `<museum>.<field path>` on the first dot. `met.isPublicDomain` → field `isPublicDomain`. */
+function apiFieldOf(verificationSource) {
+    const i = verificationSource.indexOf('.');
+    return i < 0 ? verificationSource : verificationSource.slice(i + 1);
+}
+export function buildClearancePayload(result, opts) {
+    return result.status === 'accepted'
+        ? buildAccepted(result.artwork, opts)
+        : buildRejected(result.rejection, opts);
+}
+function buildAccepted(art, opts) {
+    const decision = clearanceForLicense(art.license.type);
+    const field = apiFieldOf(art.license.verificationSource);
+    return {
+        '@context': CONTEXT,
+        type: TYPE,
+        specVersion: SPEC_VERSION,
+        work: {
+            id: art.id,
+            title: art.title,
+            artist: art.artist,
+            displayDate: art.displayDate,
+            yearStart: art.yearStart,
+            yearEnd: art.yearEnd,
+            medium: art.medium,
+        },
+        source: {
+            museum: { code: art.museum.code, name: art.museum.name, url: art.museum.url },
+            apiUrl: art.source.apiUrl,
+            pageUrl: art.source.pageUrl,
+            ...(art.source.originalUrl ? { originalUrl: art.source.originalUrl } : {}),
+            imageUrls: art.imageUrls,
+        },
+        rights: {
+            statement: decision.statement,
+            sourceApiValue: { field, value: art.license.rawValue },
+            imageOpenAccess: art.imageOpenAccess,
+            metadataOpenAccess: art.metadataOpenAccess,
+            confidence: decision.confidence,
+        },
+        clearance: {
+            commercialReproduction: decision.commercialReproduction,
+            derivatives: decision.derivatives,
+            attributionRequired: decision.attributionRequired,
+        },
+        verification: {
+            determinedBy: { actor: `museum:${art.museum.code}`, role: 'rights-source' },
+            tool: `${TOOL_NAME}@${opts.engineVersion} · ${art.license.verificationSource}`,
+            determinedAt: art.license.verifiedAt,
+            ruleContext: `${art.license.verificationSource}='${art.license.rawValue}' ⇒ ${art.license.type}`,
+            determinationSource: {
+                type: 'api-field',
+                field,
+                url: art.source.apiUrl,
+                retrievedAt: art.license.verifiedAt,
+            },
+        },
+        citation: {
+            full: cite(art, 'full'),
+            caption: cite(art, 'caption'),
+            short: cite(art, 'short'),
+        },
+    };
+}
+function buildRejected(rej, opts) {
+    // The deny determination (all-false booleans, default-deny rule, low
+    // confidence) comes from the single source of truth; the rejection supplies
+    // the case-specific evidence (the gate's verbatim reason) into each basis.
+    const decision = clearanceForLicense('UNKNOWN');
+    const basis = {
+        rule: 'default-deny',
+        inputs: [{ field: 'rejection.reason', value: rej.reason }],
+        summary: `rights gate rejected '${rej.id}': ${rej.reason} ⇒ default deny`,
+    };
+    return {
+        '@context': CONTEXT,
+        type: TYPE,
+        specVersion: SPEC_VERSION,
+        work: { id: rej.id },
+        source: { museum: { code: rej.museumCode } },
+        rights: {
+            statement: decision.statement,
+            sourceApiValue: null,
+            imageOpenAccess: false,
+            metadataOpenAccess: false,
+            confidence: decision.confidence,
+        },
+        clearance: {
+            commercialReproduction: { permitted: false, basis },
+            derivatives: { permitted: false, basis },
+            attributionRequired: { required: false, basis },
+        },
+        verification: {
+            determinedBy: { actor: 'engine:open-museum-mcp', role: 'rights-gate' },
+            tool: `${TOOL_NAME}@${opts.engineVersion} · rights-gate`,
+            determinedAt: opts.now,
+            ruleContext: `strict default deny: ${rej.reason}`,
+            determinationSource: { type: 'rights-gate-default', retrievedAt: opts.now },
+        },
+    };
+}
+//# sourceMappingURL=manifest.js.map

package/dist/core/clearance/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../../src/core/clearance/manifest.ts"],"names":[],"mappings":"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"}

package/dist/core/federation.d.ts

@@ -3,6 +3,8 @@ import { type CiteStyle } from '../cite.js';
 import type { Fetcher } from '../fetchers/types.js';
 import type { Artwork } from '../types.js';
 import type { CacheStore } from './cache.js';
+import { type Tier0Envelope } from './clearance/envelope.js';
+import { type ClearanceManifestPayload } from './clearance/manifest.js';
 export declare const ID_REGEX: RegExp;
 /**
  * Parsed parameters for a federation search. Shared by every front door (MCP
@@ -58,12 +60,33 @@ export interface FederationOptions {
      * diagnostic hook, not an error path. The MCP server logs to stderr here.
      */
     onReject?: (id: string, reason: string) => void;
+    /**
+     * Engine version string stamped into a Clearance Manifest's
+     * `verification.tool` provenance field. The host (MCP server) supplies its
+     * real package version; defaults to a placeholder so the core stays usable
+     * without one.
+     */
+    engineVersion?: string;
+    /**
+     * Clock for the generation timestamp used where no determination timestamp
+     * exists in the data (the clearance deny path has no `license.verifiedAt`).
+     * Injectable so emitted manifests are deterministic in tests and fixtures.
+     */
+    clock?: () => string;
 }
 export interface Federation {
     readonly fetchers: Record<string, Fetcher>;
     search(params: SearchParams): Promise<SearchResult>;
     getArtwork(id: string): Promise<FetchOutcome>;
     cite(id: string, style: CiteStyle): Promise<CiteOutcome>;
+    /**
+     * Emit a portable, fail-closed Clearance Manifest (rights-clearance +
+     * provenance + citation) for an artwork id, wrapped in a Tier-0 integrity
+     * envelope. A non-cleared work — rejected by the rights gate, an unknown
+     * museum, or an invalid id — returns a definitive *deny* manifest, never an
+     * error: a deny is a valid answer.
+     */
+    clearanceManifest(id: string): Promise<Tier0Envelope<ClearanceManifestPayload>>;
 }
 /**
  * Build a federation over a set of museum fetchers and a cache. This is the

package/dist/core/federation.js

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import { cite as citeArtwork } from '../cite.js';
 import { dedupeWikimediaUploads } from '../dedupe.js';
 import { filterByYearRange } from '../yearFilter.js';
+import { wrapTier0 } from './clearance/envelope.js';
+import { buildClearancePayload } from './clearance/manifest.js';
 // Museum IDs follow `<code>:<segment>(/<segment>)*`. Each segment is
 // alphanumeric, underscore, or hyphen. The four numeric-ID museums (Met,
 // Cleveland, AIC, Wikimedia) match a single all-digit segment; Europeana's
@@ -14,6 +16,13 @@ export const ID_REGEX = /^[a-z]+:(?!.*\.\.)[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/
 // cap, we'd hammer the upstream and risk rate-limit errors. 8 is empirically
 // gentle and keeps wall-clock time within the same order of magnitude.
 const DEFAULT_FETCH_CONCURRENCY = 8;
+// Overfetch buffer: how many candidate IDs to pull per requested result before
+// the rights gate and image filter thin them down. Bumped from 2x to 3x after
+// the Met search stopped pre-filtering to public-domain upstream — more fetched
+// records are now rejected by the gate post-fetch, so a larger candidate pool is
+// needed to still fill a page. Applied only when has_image is set (the common
+// path); the cache key carries the resolved overfetch count.
+const OVERFETCH_FACTOR = 3;
 /**
  * Parsed parameters for a federation search. Shared by every front door (MCP
  * tool, HTTP endpoint) so validation lives in one place. The date bounds gate
@@ -57,8 +66,8 @@ async function withConcurrency(items, limit, fn) {
     return results;
 }
 // The cache key includes the overfetch count, not the user-facing `limit`.
-// That means limit:5 and limit:6 produce different keys (since 5*2=10 vs
-// 6*2=12). The trade-off: more cache rows, but each row is guaranteed to
+// That means limit:5 and limit:6 produce different keys (since 5*3=15 vs
+// 6*3=18). The trade-off: more cache rows, but each row is guaranteed to
 // hold enough IDs to satisfy a request at its overfetch tier even after
 // rights-gate rejections. Bucketing would need explicit refill logic.
 function searchCacheKey(query, museum, hasImage, overFetch) {
@@ -75,6 +84,8 @@ export function createFederation(opts) {
     const { fetchers, cache } = opts;
     const concurrency = opts.concurrency ?? DEFAULT_FETCH_CONCURRENCY;
     const onReject = opts.onReject;
+    const engineVersion = opts.engineVersion ?? '0.0.0';
+    const clock = opts.clock ?? (() => new Date().toISOString());
     async function getArtwork(id) {
         if (!ID_REGEX.test(id)) {
             return { ok: false, reason: `invalid artwork id: ${id}` };
@@ -105,7 +116,7 @@ export function createFederation(opts) {
         if (fetcherList.length === 0) {
             throw new UnknownMuseumError(params.museum ?? '');
         }
-        const overFetch = params.has_image ? params.limit * 2 : params.limit;
+        const overFetch = params.has_image ? params.limit * OVERFETCH_FACTOR : params.limit;
         const cacheKey = searchCacheKey(params.query, params.museum, params.has_image, overFetch);
         let allIds = await cache.getQuery(cacheKey);
         if (!allIds) {
@@ -132,6 +143,23 @@ export function createFederation(opts) {
             return { ok: false, reason: out.reason };
         return { ok: true, citation: citeArtwork(out.artwork, style) };
     }
-    return { fetchers, search, getArtwork, cite };
+    async function clearanceManifest(id) {
+        const buildOpts = { engineVersion, now: clock() };
+        const code = id.includes(':') ? id.slice(0, id.indexOf(':')) : '';
+        const deny = (reason) => wrapTier0(buildClearancePayload({ status: 'rejected', rejection: { id, museumCode: code, reason, rawSnapshot: null } }, buildOpts));
+        if (!ID_REGEX.test(id))
+            return deny(`invalid artwork id: ${id}`);
+        const fetcher = fetchers[code];
+        if (!fetcher)
+            return deny(`unknown museum code: ${code}`);
+        // Determinations are cheap and version-bound, so the manifest path does not
+        // touch the object cache — it always reflects the current rights gate.
+        const raw = await fetcher.getRaw(id);
+        const result = fetcher.normalize(raw);
+        if (result.status === 'rejected')
+            onReject?.(id, result.rejection.reason);
+        return wrapTier0(buildClearancePayload(result, buildOpts));
+    }
+    return { fetchers, search, getArtwork, cite, clearanceManifest };
 }
 //# sourceMappingURL=federation.js.map