@book.dev/sdk 3.8.0 → 3.10.0

package/dist/registryClient.d.ts

@@ -0,0 +1,227 @@
+/**
+ * Client for the OpenBook registry protocol (`openbook-registry/1`) — the
+ * read side a store-browsing app needs: the registry identity document, the
+ * paginated install index, per-plugin metadata, verified downloads, and the
+ * signed revocation feed.
+ *
+ * Trust model (PROTOCOL.md §6): a registry is identified by its pinned
+ * `(baseUrl, keys)`, never by anything a fetch returned. The caller supplies
+ * the pin; this client verifies everything it downloads against it —
+ * digest recomputed from the bytes, publisher signature against the index's
+ * `pinnedKeys`, notary countersignature and revocation entries against the
+ * pinned notary key. Any failed step throws: there is no partial trust.
+ */
+import { type PluginManifest, type PluginPackage } from './plugins';
+import type { FetchLike } from './client';
+export type { FetchLike };
+export declare function isSemver(v: string): boolean;
+/**
+ * Semver precedence compare (spec §11): numeric MAJOR.MINOR.PATCH, then
+ * prerelease (absent > present; numeric identifiers numerically, and lower
+ * than alphanumeric ones). Build metadata is ignored. Returns <0, 0, >0.
+ * Inputs must already satisfy {@link isSemver}. Byte-for-byte port of the
+ * store's `compareSemver` (open-book-pub `packages/store/lib/canonical.ts`).
+ */
+export declare function compareSemver(a: string, b: string): number;
+/** `GET /api/v1/registry` — the identity document a client pins. */
+export interface RegistryDocument {
+    protocol: string;
+    name: string;
+    baseUrl: string;
+    apiVersion: number;
+    algorithms: string[];
+    notaryPublicKey: string | null;
+    registryPublicKey: string | null;
+    fingerprints: {
+        notary: string | null;
+        registry: string | null;
+    };
+    endpoints: Record<string, string>;
+}
+/** One row of `GET /api/v1/index` — a plugin at its latest approved version. */
+export interface RegistryIndexEntry {
+    id: string;
+    name: string;
+    description: string;
+    icon: string | null;
+    category: string | null;
+    publisher: string | null;
+    /** Publisher keys this plugin id is pinned to (TOFU), first-seen first. */
+    pinnedKeys?: string[];
+    /** @deprecated Use `pinnedKeys`; retained as the pre-rotation fallback. */
+    pinnedKey: string;
+    latestVersion: string;
+    /** Canonical digest of the latest approved version — what both signatures cover. */
+    digest: string;
+    /** Content address of the publisher's uploaded document (pre-splice). */
+    artifactSha256: string;
+}
+export interface RegistryIndexPage {
+    plugins: RegistryIndexEntry[];
+    limit: number;
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** The notary countersignature spliced into approved downloads (§5.4.1). */
+export interface RegistryNotarization {
+    registry: string;
+    publicKey: string;
+    signature: string;
+    algorithm: string;
+    timestamp: string;
+}
+export interface RegistryPluginVersion {
+    version: string;
+    digest: string;
+    artifactSha256: string;
+    status: string;
+    createdAt: string;
+    manifest: PluginManifest;
+    notarization: RegistryNotarization | null;
+}
+/** `GET /api/v1/plugins/{id}` — a plugin's version history. */
+export interface RegistryPluginMeta {
+    id: string;
+    pinnedKeys?: string[];
+    /** @deprecated Use `pinnedKeys`; retained as the pre-rotation fallback. */
+    pinnedKey: string;
+    createdAt: string;
+    versions: RegistryPluginVersion[];
+}
+/** One signed entry of the revocation feed (§5.5). */
+export interface RegistryRevocation {
+    id: string;
+    seq: number;
+    pluginId: string;
+    /** The revoked version, or null = every version, including future ones. */
+    version: string | null;
+    reason: string;
+    signerPublicKey: string | null;
+    signature: string | null;
+    createdAt: string;
+}
+/** The signed freshness/rollback anchor accompanying a revocation feed. */
+export interface RegistryRevocationHead {
+    maxSeq: number;
+    generatedAt: string;
+    publicKey: string;
+    signature: string;
+}
+/** The trust states a verified download can earn (§6.5). */
+export interface RegistryTrust {
+    /** Package signature verifies with the pinned `registryPublicKey`. */
+    firstParty: boolean;
+    /** Notary countersignature verifies with the pinned `notaryPublicKey`. */
+    notarised: boolean;
+}
+/** A fully verified download: the package plus what the verification proved. */
+export interface VerifiedDownload {
+    pkg: PluginPackage;
+    /** The recomputed canonical digest the signatures were checked over. */
+    digest: string;
+    trust: RegistryTrust;
+    notarization: RegistryNotarization | null;
+}
+/** The pin a client persists for a registry: base URL + keys, per §6.2. */
+export interface RegistryPin {
+    baseUrl: string;
+    name?: string;
+    notaryPublicKey?: string | null;
+    registryPublicKey?: string | null;
+}
+/** A typed failure from the registry client; `code` is stable for branching. */
+export declare class RegistryError extends Error {
+    readonly code: 'unsupported_protocol' | 'insecure_base_url' | 'http_error' | 'revoked' | 'not_found' | 'digest_mismatch' | 'etag_mismatch' | 'signature_invalid' | 'notarization_invalid' | 'revocation_unavailable' | 'bad_response';
+    constructor(code: 'unsupported_protocol' | 'insecure_base_url' | 'http_error' | 'revoked' | 'not_found' | 'digest_mismatch' | 'etag_mismatch' | 'signature_invalid' | 'notarization_invalid' | 'revocation_unavailable' | 'bad_response', message: string);
+}
+/** Must exceed the endpoint's 60s max-age + 300s SWR cache floor (§6.6). */
+export declare const REVOCATION_STALENESS_MS: number;
+/** HTTPS only, except an explicit developer-local http://localhost (§3). */
+export declare function registryBaseUrlProblem(baseUrl: string): string | null;
+/**
+ * Human-comparable fingerprint of a raw Ed25519 key (§6.2): SHA-256 of the
+ * raw 32 bytes, truncated to 128 bits, as eight dash-separated hex quads.
+ */
+export declare function registryKeyFingerprint(publicKeyBase64: string): Promise<string>;
+/** Does a revocation entry cover this `(pluginId, version)`? `version: null` covers all. */
+export declare function revocationMatches(entry: Pick<RegistryRevocation, 'pluginId' | 'version'>, pluginId: string, version: string): boolean;
+/**
+ * Fetch + validate a registry's identity document WITHOUT a pin — the
+ * add-a-registry flow (§6.2): the caller must display the fingerprints for
+ * out-of-band confirmation before pinning anything from this response.
+ */
+export declare function fetchRegistryDocument(baseUrl: string, fetchImpl?: FetchLike): Promise<RegistryDocument>;
+/**
+ * The read client for one pinned registry. All verification happens against
+ * the PIN handed to the constructor — never against keys learned from the
+ * network afterwards.
+ */
+export declare class RegistryClient {
+    readonly pin: RegistryPin;
+    private readonly fetchImpl;
+    private doc;
+    constructor(pin: RegistryPin, opts?: {
+        fetch?: FetchLike;
+    });
+    private get base();
+    private endpoint;
+    private json;
+    /**
+     * The registry's identity document (fetched once, cached). Checked against
+     * the pin: a protocol this client does not speak is refused, and a document
+     * whose keys disagree with pinned keys is refused as a possible attack
+     * (§6.2 — a pin change is a NEW trust decision, never a silent update).
+     */
+    document(): Promise<RegistryDocument>;
+    /** One page of the install index (§5.2). */
+    indexPage(opts?: {
+        limit?: number;
+        cursor?: string;
+        q?: string;
+        category?: string;
+    }): Promise<RegistryIndexPage>;
+    /**
+     * Walk the whole (filtered) index, one page at a time — cursors are walked
+     * sequentially per §9, capped defensively against a cursor loop.
+     */
+    indexAll(opts?: {
+        q?: string;
+        category?: string;
+        limit?: number;
+    }): Promise<RegistryIndexEntry[]>;
+    /** Find one plugin's index row by exact id (via the substring search filter). */
+    findIndexEntry(pluginId: string): Promise<RegistryIndexEntry | null>;
+    /** A plugin's version history (§5.3). Null when the registry doesn't know the id. */
+    pluginMeta(pluginId: string): Promise<RegistryPluginMeta | null>;
+    /**
+     * Download one version and verify it offline (§6.3). Every step must pass:
+     *
+     * 1. sha256(served bytes) equals the strong `ETag` (transport integrity).
+     * 2. The canonical digest RECOMPUTED from manifest+files equals `expect.digest`
+     *    (the value the index/metadata promised) and the `X-Canonical-Digest` hint.
+     * 3. The publisher signature verifies over that digest with ANY member of
+     *    `expect.pinnedKeys` — never with the key that travelled inside the package.
+     * 4. A present notary countersignature verifies with the PINNED notary key —
+     *    present-but-invalid is a hard failure, not a downgrade to "unnotarised".
+     *
+     * Revocations are the caller's step (§6.6): check {@link revocations} before
+     * installing what this returns.
+     */
+    download(pluginId: string, version: string, expect: {
+        digest: string;
+        pinnedKeys: string[];
+    }): Promise<VerifiedDownload>;
+    /**
+     * The revocation feed (§5.5, §6.6), from `since` (exclusive). Entries are
+     * verified against the pinned notary key; on a registry that advertises a
+     * notary key, unsigned or badly-signed entries are IGNORED (an injection is
+     * not a kill switch). Only a registry with no notary key at all has its
+     * unsigned entries honoured — failing open on the kill switch is the
+     * dangerous direction.
+     */
+    revocations(since?: number): Promise<{
+        maxSeq: number;
+        entries: RegistryRevocation[];
+        generatedAt: string | null;
+    }>;
+}

package/dist/registryClient.js

@@ -0,0 +1,397 @@
+/**
+ * Client for the OpenBook registry protocol (`openbook-registry/1`) — the
+ * read side a store-browsing app needs: the registry identity document, the
+ * paginated install index, per-plugin metadata, verified downloads, and the
+ * signed revocation feed.
+ *
+ * Trust model (PROTOCOL.md §6): a registry is identified by its pinned
+ * `(baseUrl, keys)`, never by anything a fetch returned. The caller supplies
+ * the pin; this client verifies everything it downloads against it —
+ * digest recomputed from the bytes, publisher signature against the index's
+ * `pinnedKeys`, notary countersignature and revocation entries against the
+ * pinned notary key. Any failed step throws: there is no partial trust.
+ */
+import { canonicalDigest, canonicalJson, verifyEd25519Message, } from './plugins';
+// ── Semver (the protocol's version ordering) ─────────────────────────────────
+// Strict-enough semver: MAJOR.MINOR.PATCH with optional -prerelease/+build.
+const SEMVER_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-[0-9A-Za-z-.]+)?(\+[0-9A-Za-z-.]+)?$/;
+export function isSemver(v) {
+    return SEMVER_RE.test(v);
+}
+/**
+ * Semver precedence compare (spec §11): numeric MAJOR.MINOR.PATCH, then
+ * prerelease (absent > present; numeric identifiers numerically, and lower
+ * than alphanumeric ones). Build metadata is ignored. Returns <0, 0, >0.
+ * Inputs must already satisfy {@link isSemver}. Byte-for-byte port of the
+ * store's `compareSemver` (open-book-pub `packages/store/lib/canonical.ts`).
+ */
+export function compareSemver(a, b) {
+    const pa = SEMVER_RE.exec(a);
+    const pb = SEMVER_RE.exec(b);
+    if (!pa || !pb)
+        throw new TypeError(`compareSemver: not semver: ${!pa ? a : b}`);
+    for (let i = 1; i <= 3; i++) {
+        const d = Number(pa[i]) - Number(pb[i]);
+        if (d !== 0)
+            return d;
+    }
+    const prea = pa[4]?.slice(1);
+    const preb = pb[4]?.slice(1);
+    if (prea === undefined && preb === undefined)
+        return 0;
+    if (prea === undefined)
+        return 1; // a release outranks any prerelease
+    if (preb === undefined)
+        return -1;
+    const as = prea.split('.');
+    const bs = preb.split('.');
+    for (let i = 0; i < Math.max(as.length, bs.length); i++) {
+        const x = as[i];
+        const y = bs[i];
+        if (x === undefined)
+            return -1; // fewer identifiers = lower precedence
+        if (y === undefined)
+            return 1;
+        const xn = /^\d+$/.test(x);
+        const yn = /^\d+$/.test(y);
+        if (xn && yn) {
+            const d = Number(x) - Number(y);
+            if (d !== 0)
+                return d;
+        }
+        else if (xn !== yn) {
+            return xn ? -1 : 1; // numeric identifiers sort below alphanumeric
+        }
+        else if (x !== y) {
+            return x < y ? -1 : 1;
+        }
+    }
+    return 0;
+}
+/** A typed failure from the registry client; `code` is stable for branching. */
+export class RegistryError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'RegistryError';
+    }
+}
+const DEFAULT_ENDPOINTS = {
+    registry: '/api/v1/registry',
+    index: '/api/v1/index',
+    plugin: '/api/v1/plugins/{id}',
+    download: '/api/v1/plugins/{id}/versions/{version}/download',
+    revocations: '/api/v1/revocations',
+};
+const PROTOCOL_MAJOR = 1;
+/** Must exceed the endpoint's 60s max-age + 300s SWR cache floor (§6.6). */
+export const REVOCATION_STALENESS_MS = 15 * 60 * 1000;
+/** HTTPS only, except an explicit developer-local http://localhost (§3). */
+export function registryBaseUrlProblem(baseUrl) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return 'not a valid URL';
+    }
+    if (url.protocol === 'https:')
+        return null;
+    if (url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1'))
+        return null;
+    return 'a registry must be served over https:// (http is allowed only for localhost)';
+}
+const sha256Hex = async (bytes) => {
+    const hash = await crypto.subtle.digest('SHA-256', bytes);
+    return [...new Uint8Array(hash)].map((b) => b.toString(16).padStart(2, '0')).join('');
+};
+/**
+ * Human-comparable fingerprint of a raw Ed25519 key (§6.2): SHA-256 of the
+ * raw 32 bytes, truncated to 128 bits, as eight dash-separated hex quads.
+ */
+export async function registryKeyFingerprint(publicKeyBase64) {
+    const raw = Uint8Array.from(atob(publicKeyBase64), (c) => c.charCodeAt(0));
+    const hex = (await sha256Hex(raw)).slice(0, 32);
+    return hex.replace(/(.{4})(?=.)/g, '$1-');
+}
+/** Does a revocation entry cover this `(pluginId, version)`? `version: null` covers all. */
+export function revocationMatches(entry, pluginId, version) {
+    return entry.pluginId === pluginId && (entry.version === null || entry.version === version);
+}
+/**
+ * Fetch + validate a registry's identity document WITHOUT a pin — the
+ * add-a-registry flow (§6.2): the caller must display the fingerprints for
+ * out-of-band confirmation before pinning anything from this response.
+ */
+export async function fetchRegistryDocument(baseUrl, fetchImpl = fetch) {
+    const problem = registryBaseUrlProblem(baseUrl);
+    if (problem)
+        throw new RegistryError('insecure_base_url', problem);
+    const res = await fetchImpl(`${baseUrl.replace(/\/$/, '')}${DEFAULT_ENDPOINTS.registry}`);
+    if (!res.ok)
+        throw new RegistryError('http_error', `registry document fetch failed (${res.status})`);
+    const doc = (await res.json());
+    const match = /^openbook-registry\/(\d+)$/.exec(doc?.protocol ?? '');
+    if (!match || Number(match[1]) !== PROTOCOL_MAJOR) {
+        throw new RegistryError('unsupported_protocol', `unsupported registry protocol ${JSON.stringify(doc?.protocol)} — this app speaks openbook-registry/${PROTOCOL_MAJOR}`);
+    }
+    if (!Array.isArray(doc.algorithms) || !doc.algorithms.includes('ed25519')) {
+        throw new RegistryError('unsupported_protocol', 'the registry offers no signature algorithm this app supports (ed25519)');
+    }
+    return doc;
+}
+/**
+ * The read client for one pinned registry. All verification happens against
+ * the PIN handed to the constructor — never against keys learned from the
+ * network afterwards.
+ */
+export class RegistryClient {
+    constructor(pin, opts = {}) {
+        this.pin = pin;
+        this.doc = null;
+        this.fetchImpl = opts.fetch ?? ((url, init) => fetch(url, init));
+        const problem = registryBaseUrlProblem(pin.baseUrl);
+        if (problem)
+            throw new RegistryError('insecure_base_url', problem);
+    }
+    get base() {
+        return this.pin.baseUrl.replace(/\/$/, '');
+    }
+    async endpoint(name, subst = {}) {
+        // Refusal gates in document() are security decisions, not endpoint
+        // discovery hints. Propagate them instead of silently falling back.
+        const doc = await this.document();
+        let template = doc.endpoints?.[name] ?? DEFAULT_ENDPOINTS[name];
+        for (const [k, v] of Object.entries(subst))
+            template = template.replace(`{${k}}`, encodeURIComponent(v));
+        return `${this.base}${template}`;
+    }
+    async json(url) {
+        const res = await this.fetchImpl(url);
+        if (res.status === 404)
+            throw new RegistryError('not_found', `not found: ${url}`);
+        if (res.status === 410)
+            throw new RegistryError('revoked', 'this version has been revoked by the registry');
+        if (!res.ok)
+            throw new RegistryError('http_error', `registry request failed (${res.status}): ${url}`);
+        return { body: (await res.json()), res };
+    }
+    /**
+     * The registry's identity document (fetched once, cached). Checked against
+     * the pin: a protocol this client does not speak is refused, and a document
+     * whose keys disagree with pinned keys is refused as a possible attack
+     * (§6.2 — a pin change is a NEW trust decision, never a silent update).
+     */
+    async document() {
+        if (this.doc)
+            return this.doc;
+        const doc = await fetchRegistryDocument(this.base, this.fetchImpl);
+        if (this.pin.notaryPublicKey && doc.notaryPublicKey !== this.pin.notaryPublicKey) {
+            throw new RegistryError('unsupported_protocol', 'the registry\'s notary key no longer matches the pinned key — refusing (re-confirm the registry out of band)');
+        }
+        if (this.pin.registryPublicKey && doc.registryPublicKey !== this.pin.registryPublicKey) {
+            throw new RegistryError('unsupported_protocol', 'the registry\'s first-party key no longer matches the pinned key — refusing (re-confirm the registry out of band)');
+        }
+        this.doc = doc;
+        return doc;
+    }
+    /** One page of the install index (§5.2). */
+    async indexPage(opts = {}) {
+        const url = new URL(await this.endpoint('index'));
+        if (opts.limit !== undefined)
+            url.searchParams.set('limit', String(opts.limit));
+        if (opts.cursor)
+            url.searchParams.set('cursor', opts.cursor);
+        if (opts.q)
+            url.searchParams.set('q', opts.q);
+        if (opts.category)
+            url.searchParams.set('category', opts.category);
+        const { body } = await this.json(url.toString());
+        if (!Array.isArray(body?.plugins))
+            throw new RegistryError('bad_response', 'index response has no plugins array');
+        return body;
+    }
+    /**
+     * Walk the whole (filtered) index, one page at a time — cursors are walked
+     * sequentially per §9, capped defensively against a cursor loop.
+     */
+    async indexAll(opts = {}) {
+        const all = [];
+        let cursor;
+        for (let page = 0; page < 100; page++) {
+            const { plugins, nextCursor } = await this.indexPage({ ...opts, cursor });
+            all.push(...plugins);
+            if (!nextCursor)
+                return all;
+            cursor = nextCursor;
+        }
+        throw new RegistryError('bad_response', 'index walk exceeded 100 pages — refusing a possible cursor loop');
+    }
+    /** Find one plugin's index row by exact id (via the substring search filter). */
+    async findIndexEntry(pluginId) {
+        const matches = await this.indexAll({ q: pluginId });
+        return matches.find((p) => p.id === pluginId) ?? null;
+    }
+    /** A plugin's version history (§5.3). Null when the registry doesn't know the id. */
+    async pluginMeta(pluginId) {
+        try {
+            const { body } = await this.json(await this.endpoint('plugin', { id: pluginId }));
+            return body;
+        }
+        catch (err) {
+            if (err instanceof RegistryError && err.code === 'not_found')
+                return null;
+            throw err;
+        }
+    }
+    /**
+     * Download one version and verify it offline (§6.3). Every step must pass:
+     *
+     * 1. sha256(served bytes) equals the strong `ETag` (transport integrity).
+     * 2. The canonical digest RECOMPUTED from manifest+files equals `expect.digest`
+     *    (the value the index/metadata promised) and the `X-Canonical-Digest` hint.
+     * 3. The publisher signature verifies over that digest with ANY member of
+     *    `expect.pinnedKeys` — never with the key that travelled inside the package.
+     * 4. A present notary countersignature verifies with the PINNED notary key —
+     *    present-but-invalid is a hard failure, not a downgrade to "unnotarised".
+     *
+     * Revocations are the caller's step (§6.6): check {@link revocations} before
+     * installing what this returns.
+     */
+    async download(pluginId, version, expect) {
+        const res = await this.fetchImpl(await this.endpoint('download', { id: pluginId, version }));
+        if (res.status === 410)
+            throw new RegistryError('revoked', `${pluginId}@${version} has been revoked by the registry`);
+        if (res.status === 404)
+            throw new RegistryError('not_found', `${pluginId}@${version} is not downloadable from this registry`);
+        if (!res.ok)
+            throw new RegistryError('http_error', `download failed (${res.status})`);
+        const served = new Uint8Array(await res.arrayBuffer());
+        const etag = res.headers.get('etag');
+        if (etag) {
+            const tag = etag.replace(/^W\//, '').replace(/^"|"$/g, '');
+            if ((await sha256Hex(served)) !== tag) {
+                throw new RegistryError('etag_mismatch', 'the downloaded bytes do not hash to the served ETag — corrupted or tampered in transit');
+            }
+        }
+        let doc;
+        try {
+            doc = JSON.parse(new TextDecoder().decode(served));
+        }
+        catch {
+            throw new RegistryError('bad_response', 'the download is not a JSON plugin package');
+        }
+        if (!doc || typeof doc !== 'object' || !doc.manifest || !doc.files) {
+            throw new RegistryError('bad_response', 'the download is missing manifest or files');
+        }
+        const digest = await canonicalDigest(doc.manifest, doc.files);
+        if (digest !== expect.digest) {
+            throw new RegistryError('digest_mismatch', 'the recomputed canonical digest does not match what the registry index promised');
+        }
+        const digestHeader = res.headers.get('x-canonical-digest');
+        if (digestHeader && digestHeader !== digest) {
+            throw new RegistryError('digest_mismatch', 'the X-Canonical-Digest header disagrees with the recomputed digest');
+        }
+        const sig = doc.signature;
+        let publisherVerified = false;
+        if (sig?.algorithm === 'ed25519') {
+            for (const pinnedKey of expect.pinnedKeys) {
+                if (await verifyEd25519Message(pinnedKey, digest, sig.signature)) {
+                    publisherVerified = true;
+                    break;
+                }
+            }
+        }
+        if (!sig || !publisherVerified) {
+            throw new RegistryError('signature_invalid', 'the publisher signature does not verify against the key this plugin id is pinned to');
+        }
+        const notarization = doc.notarization ?? null;
+        let notarised = false;
+        if (this.pin.notaryPublicKey && !notarization) {
+            throw new RegistryError('notarization_invalid', 'the approved download is missing the notarization required by this pinned store');
+        }
+        if (notarization) {
+            // Verify with the PINNED notary key only. Without a pinned key the
+            // member is unverifiable and earns nothing (notarised stays false); a
+            // pinned key + failing signature is a hard failure.
+            if (this.pin.notaryPublicKey) {
+                if (!(await verifyEd25519Message(this.pin.notaryPublicKey, digest, notarization.signature))) {
+                    throw new RegistryError('notarization_invalid', 'the notary countersignature does not verify against the pinned notary key');
+                }
+                notarised = true;
+            }
+        }
+        const firstParty = !!this.pin.registryPublicKey && (await verifyEd25519Message(this.pin.registryPublicKey, digest, sig.signature));
+        return {
+            pkg: { manifest: doc.manifest, files: doc.files, signature: sig },
+            digest,
+            trust: { firstParty, notarised },
+            notarization,
+        };
+    }
+    /**
+     * The revocation feed (§5.5, §6.6), from `since` (exclusive). Entries are
+     * verified against the pinned notary key; on a registry that advertises a
+     * notary key, unsigned or badly-signed entries are IGNORED (an injection is
+     * not a kill switch). Only a registry with no notary key at all has its
+     * unsigned entries honoured — failing open on the kill switch is the
+     * dangerous direction.
+     */
+    async revocations(since) {
+        const url = new URL(await this.endpoint('revocations'));
+        if (since !== undefined && since > 0)
+            url.searchParams.set('since', String(since));
+        const { body } = await this.json(url.toString());
+        if (!Array.isArray(body?.revocations) || typeof body.maxSeq !== 'number') {
+            throw new RegistryError('bad_response', 'malformed revocations response');
+        }
+        const notaryKey = this.pin.notaryPublicKey ?? null;
+        let verifiedMaxSeq = body.maxSeq;
+        let generatedAt = null;
+        if (notaryKey) {
+            const head = body.head;
+            if (!head
+                || !Number.isSafeInteger(head.maxSeq)
+                || head.maxSeq < 0
+                || typeof head.generatedAt !== 'string'
+                || typeof head.signature !== 'string') {
+                throw new RegistryError('bad_response', 'a registry with a pinned notary key returned no valid signed revocation head');
+            }
+            const payload = canonicalJson({ generatedAt: head.generatedAt, maxSeq: head.maxSeq });
+            if (!(await verifyEd25519Message(notaryKey, payload, head.signature))) {
+                throw new RegistryError('bad_response', 'the revocation feed head does not verify against the pinned notary key');
+            }
+            const generatedAtMs = Date.parse(head.generatedAt);
+            if (!Number.isFinite(generatedAtMs) || Date.now() - generatedAtMs > REVOCATION_STALENESS_MS) {
+                throw new RegistryError('bad_response', 'the signed revocation feed head is stale');
+            }
+            if (since !== undefined && head.maxSeq < since) {
+                throw new RegistryError('bad_response', `the signed revocation feed rolled back from sequence ${since} to ${head.maxSeq}`);
+            }
+            verifiedMaxSeq = head.maxSeq;
+            generatedAt = head.generatedAt;
+        }
+        const entries = [];
+        for (const entry of body.revocations) {
+            if (!entry || typeof entry.pluginId !== 'string')
+                continue;
+            if (notaryKey) {
+                if (!entry.signature)
+                    continue; // unsigned on a signing registry = injection, not revocation
+                const payload = canonicalJson({
+                    id: entry.id,
+                    pluginId: entry.pluginId,
+                    reason: entry.reason,
+                    revokedAt: entry.createdAt,
+                    seq: entry.seq,
+                    version: entry.version ?? null,
+                });
+                if (!(await verifyEd25519Message(notaryKey, payload, entry.signature)))
+                    continue;
+            }
+            entries.push(entry);
+        }
+        return { maxSeq: verifiedMaxSeq, entries, generatedAt };
+    }
+}
+//# sourceMappingURL=registryClient.js.map

package/dist/registryClient.js.map

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

package/dist/routes.d.ts

@@ -257,6 +257,15 @@ export declare const API: {
      * page/row mutation (server-managed) — only these ledger routes write them.
      */
     readonly ledger: "/api/ledger";
+    /**
+     * LX-4: restore an export's embedded ledger-records section into an EMPTY
+     * ledger by replaying it through the server's ledger writer. `POST` with a
+     * {@link LedgerExportSection} body; instance-administration gated (the same
+     * gate as {@link API.importLibrary} — it writes a whole book). A target that
+     * already keeps any ledger data refuses with a typed 409 (`invalid-state`) —
+     * merging is explicitly out of scope.
+     */
+    readonly ledgerRestoreSection: "/api/ledger/restore-section";
     /** Accounts: `GET` (list) / `POST` (create — hierarchical colon-delimited name). */
     readonly ledgerAccounts: "/api/ledger/accounts";
     /** One account: `GET` / `PATCH` (rename; close — rejected at nonzero balance). */