@forestrie/mcp-register 0.0.0-stage → 0.1.0

package/dist/core/issue.d.ts

@@ -0,0 +1,38 @@
+import { type GrantView } from "./grant.js";
+import type { Es256Signer } from "./signer.js";
+/** canopy reads at most this much register-grant body (`auth-grant.ts`). */
+export declare const MAX_PARENT_GRANT_BYTES: number;
+/** GF_CREATE|GF_EXTEND (byte 3), GF_DATA_LOG (byte 7): a data-log creation
+ *  grant, the shape that both opens the child log and carries statements. */
+export declare function dataLogCreateExtendFlags(): Uint8Array;
+export interface IssueGrantInput {
+    /** The child data log the grant creates (UUID). */
+    logId: string;
+    /** The requester's authority log the grant is sequenced into (UUID). */
+    ownerLogId: string;
+    /** The key the grant names: 64 bytes x‖y of the performer's log key. */
+    grantData: Uint8Array;
+    /** The batch ceiling canopy prices a paid child grant by. At least 1. */
+    maxHeight: number;
+}
+export interface IssuedGrant {
+    /** The signed grant, untagged COSE Sign1. */
+    grant: Uint8Array;
+    /** The canonical grant v0 CBOR that was signed (its SHA-256 is the payload). */
+    grantPayload: Uint8Array;
+    flags: Uint8Array;
+}
+export declare function issueChildGrant(input: IssueGrantInput, authority: Es256Signer): Promise<IssuedGrant>;
+/**
+ * Why `parent` cannot authorise a child grant signed by `authorityXY`, or
+ * `[]`. The parent is the requester's own authority grant: an auth-log
+ * grant naming the authority key, whose log becomes the child's owner.
+ */
+export declare function parentGrantProblems(parent: GrantView, authorityXY: Uint8Array): string[];
+/** The register-grant request body: canonical CBOR `{parentGrant: <bytes>}`. */
+export declare function registerGrantBody(parentGrant: Uint8Array): Uint8Array;
+/** Merge the sealed receipt and the entry's idtimestamp into the grant. */
+export declare function completeGrant(grant: Uint8Array, receipt: Uint8Array, entryIdHex: string): Uint8Array;
+/** The grant v0 CBOR a grant carries at unprotected -65538: its content. */
+export declare function grantContent(grant: Uint8Array): Uint8Array;
+//# sourceMappingURL=issue.d.ts.map

package/dist/core/issue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue.d.ts","sourceRoot":"","sources":["../../src/core/issue.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAExD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAW/C,4EAA4E;AAC5E,eAAO,MAAM,sBAAsB,QAAY,CAAC;AAEhD;6EAC6E;AAC7E,wBAAgB,wBAAwB,IAAI,UAAU,CAKrD;AAED,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,SAAS,EAAE,UAAU,CAAC;IACtB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,KAAK,EAAE,UAAU,CAAC;IAClB,gFAAgF;IAChF,YAAY,EAAE,UAAU,CAAC;IACzB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,eAAe,EACtB,SAAS,EAAE,WAAW,GACrB,OAAO,CAAC,WAAW,CAAC,CAwDtB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,UAAU,GACtB,MAAM,EAAE,CAeV;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,UAAU,GAAG,UAAU,CAIrE;AAID,2EAA2E;AAC3E,wBAAgB,aAAa,CAC3B,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,UAAU,EACnB,UAAU,EAAE,MAAM,GACjB,UAAU,CAeZ;AAED,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAU1D"}

package/dist/core/issue.js

@@ -0,0 +1,135 @@
+/**
+ * Issue a child grant as the requester, and complete it once canopy has
+ * sealed it.
+ *
+ * The requester owns an authority log (ARC-0028: the requester funds, the
+ * performer writes) and is its own grant issuer: it signs a child grant
+ * with its authority key, naming the performer's log key in `grantData`.
+ * Forestrie runs no issuer.
+ *
+ * The bytes are the ES256 profile of `@forestrie/grant-builder`'s
+ * `signGrantPayloadWithEs256Pem`, which univocity verifies
+ * (`verifyCoseSign1ES256`), with the PEM replaced by the signer seam:
+ *
+ *  - untagged COSE Sign1, protected `{1: -7}` (wire `a10126`);
+ *  - payload the 32-byte SHA-256 of the canonical grant v0 CBOR;
+ *  - signature over `["Signature1", protected, h'', payload]`, r‖s;
+ *  - unprotected `{-65537: 8 zero bytes, -65538: grant v0 CBOR}`, in that
+ *    canonical order.
+ *
+ * grant-builder itself is not imported: its index pulls in its node-only
+ * PEM module, and this file is browser-safe.
+ *
+ * Completing a grant merges the receipt (396) and the entry's idtimestamp
+ * (-65537) into the unprotected header without re-signing, as forestrie-cli
+ * `register-grant-complete.ts` does. The completed grant is the
+ * `Forestrie-Grant` credential register_statement and delegate_sealing take.
+ */
+import { appendCborBstr, appendCborText, decodeCoseSign1, encodeCborDeterministic, encodeGrantPayloadV0Canonical, mergeUnprotectedIntoCoseSign1, uuidToBytes, } from "@forestrie/encoding";
+import { GrantError } from "./grant.js";
+import { bytesEqual, sha256 } from "./hex.js";
+const ES256_PROTECTED_HEADER = new Uint8Array([0xa1, 0x01, 0x26]);
+// CBOR negative-int keys (major type 1): -65537, then -65538.
+const CBOR_KEY_IDTIMESTAMP = [0x3a, 0x00, 0x01, 0x00, 0x00];
+const CBOR_KEY_FORESTRIE_GRANT_V0 = [0x3a, 0x00, 0x01, 0x00, 0x01];
+const HEADER_RECEIPT = 396;
+const HEADER_IDTIMESTAMP = -65537;
+/** canopy's register-grant body key for the parent grant evidence. */
+const PARENT_GRANT_BODY_KEY = "parentGrant";
+/** canopy reads at most this much register-grant body (`auth-grant.ts`). */
+export const MAX_PARENT_GRANT_BYTES = 16 * 1024;
+/** GF_CREATE|GF_EXTEND (byte 3), GF_DATA_LOG (byte 7): a data-log creation
+ *  grant, the shape that both opens the child log and carries statements. */
+export function dataLogCreateExtendFlags() {
+    const flags = new Uint8Array(8);
+    flags[3] = 0x03;
+    flags[7] = 0x02;
+    return flags;
+}
+export async function issueChildGrant(input, authority) {
+    let logId;
+    let ownerLogId;
+    try {
+        logId = uuidToBytes(input.logId);
+        ownerLogId = uuidToBytes(input.ownerLogId);
+    }
+    catch {
+        throw new GrantError(`logId and ownerLogId must be UUIDs (got ${input.logId}, ${input.ownerLogId})`);
+    }
+    if (bytesEqual(logId, ownerLogId))
+        throw new GrantError("a child grant must name a log other than its owner (logId equals ownerLogId)");
+    if (input.grantData.length !== 64)
+        throw new GrantError(`grantData must be a 64-byte ES256 x‖y (got ${input.grantData.length} bytes): canopy forwards only ES256 child roots`);
+    if (!Number.isSafeInteger(input.maxHeight) || input.maxHeight < 1)
+        throw new GrantError(`maxHeight must be a positive integer (got ${input.maxHeight})`);
+    const flags = dataLogCreateExtendFlags();
+    const grantPayload = encodeGrantPayloadV0Canonical({
+        logId,
+        ownerLogId,
+        grant: flags,
+        maxHeight: input.maxHeight,
+        minGrowth: 0,
+        grantData: input.grantData,
+    });
+    const payload = await sha256(grantPayload);
+    const sig = [0x84];
+    appendCborText(sig, "Signature1");
+    appendCborBstr(sig, ES256_PROTECTED_HEADER);
+    appendCborBstr(sig, new Uint8Array(0));
+    appendCborBstr(sig, payload);
+    const signature = await authority.sign(new Uint8Array(sig));
+    if (signature.length !== 64)
+        throw new GrantError(`the authority signer returned ${signature.length} bytes; ES256 needs a 64-byte r‖s`);
+    const out = [0x84];
+    appendCborBstr(out, ES256_PROTECTED_HEADER);
+    out.push(0xa2);
+    out.push(...CBOR_KEY_IDTIMESTAMP);
+    appendCborBstr(out, new Uint8Array(8));
+    out.push(...CBOR_KEY_FORESTRIE_GRANT_V0);
+    appendCborBstr(out, grantPayload);
+    appendCborBstr(out, payload);
+    appendCborBstr(out, signature);
+    return { grant: new Uint8Array(out), grantPayload, flags };
+}
+/**
+ * Why `parent` cannot authorise a child grant signed by `authorityXY`, or
+ * `[]`. The parent is the requester's own authority grant: an auth-log
+ * grant naming the authority key, whose log becomes the child's owner.
+ */
+export function parentGrantProblems(parent, authorityXY) {
+    const problems = [];
+    if (!parent.authLog)
+        problems.push(`the parent grant's flags ${parent.flagsHex} are not an authority-log grant (GF_AUTH_LOG); only an authority log can own a child log`);
+    if (parent.grantData.length !== 64)
+        problems.push(`the parent grant names a ${parent.grantData.length}-byte key; canopy's prepare refuses non-ES256 parents, so the authority key must be ES256`);
+    else if (!bytesEqual(parent.grantData, authorityXY))
+        problems.push("the parent grant names a different key than this server's authority key, so this key does not own that authority log and cannot issue under it");
+    return problems;
+}
+/** The register-grant request body: canonical CBOR `{parentGrant: <bytes>}`. */
+export function registerGrantBody(parentGrant) {
+    return encodeCborDeterministic(new Map([[PARENT_GRANT_BODY_KEY, parentGrant]]));
+}
+const ENTRY_ID = /^[0-9a-f]{32}$/;
+/** Merge the sealed receipt and the entry's idtimestamp into the grant. */
+export function completeGrant(grant, receipt, entryIdHex) {
+    if (!ENTRY_ID.test(entryIdHex))
+        throw new GrantError(`entryId must be 32 lowercase hex (got ${entryIdHex})`);
+    const idtimestamp = new Uint8Array(8);
+    for (let i = 0; i < 8; i++)
+        idtimestamp[i] = parseInt(entryIdHex.slice(i * 2, i * 2 + 2), 16);
+    return mergeUnprotectedIntoCoseSign1(grant, new Map([
+        [HEADER_RECEIPT, receipt],
+        [HEADER_IDTIMESTAMP, idtimestamp],
+    ]));
+}
+/** The grant v0 CBOR a grant carries at unprotected -65538: its content. */
+export function grantContent(grant) {
+    const sign1 = decodeCoseSign1(grant);
+    const unprotected = sign1?.unprotected;
+    const content = unprotected instanceof Map ? unprotected.get(-65538) : undefined;
+    if (!(content instanceof Uint8Array) || content.length === 0)
+        throw new GrantError("not a Forestrie-Grant: no grant v0 CBOR at unprotected label -65538");
+    return content;
+}
+//# sourceMappingURL=issue.js.map

package/dist/core/issue.js.map

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

package/dist/core/limits.d.ts

@@ -0,0 +1,9 @@
+/**
+ * canopy's statement size limit, `maxStatementSize` in its SCITT
+ * configuration (canopy `scrapi/transparency-configuration.ts`): 4 MiB,
+ * checked against the signed statement's Content-Length. The limit is on
+ * the COSE Sign1 as sent, so the payload must leave room for the headers
+ * and the signature.
+ */
+export declare const MAX_STATEMENT_BYTES: number;
+//# sourceMappingURL=limits.d.ts.map

package/dist/core/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/core/limits.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAkB,CAAC"}

package/dist/core/limits.js

@@ -0,0 +1,9 @@
+/**
+ * canopy's statement size limit, `maxStatementSize` in its SCITT
+ * configuration (canopy `scrapi/transparency-configuration.ts`): 4 MiB,
+ * checked against the signed statement's Content-Length. The limit is on
+ * the COSE Sign1 as sent, so the payload must leave room for the headers
+ * and the signature.
+ */
+export const MAX_STATEMENT_BYTES = 4 * 1024 * 1024;
+//# sourceMappingURL=limits.js.map

package/dist/core/limits.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.js","sourceRoot":"","sources":["../../src/core/limits.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/core/scrapi.d.ts

@@ -0,0 +1,66 @@
+/** The parts of a response these readers look at. Headers keyed lowercase. */
+export interface ResponseView {
+    url: string;
+    status: number;
+    headers: Record<string, string>;
+    body: Uint8Array;
+}
+export interface Problem {
+    status: number;
+    title: string;
+    detail?: string;
+    reason?: string;
+    /** From the response's Retry-After, e.g. canopy's queue-full 503. */
+    retryAfterSeconds?: number;
+}
+export declare function readProblem(res: ResponseView): Problem;
+/** The origin of a base URL, or `undefined` when it does not parse. */
+export declare function originOf(baseUrl: string): string | undefined;
+export type RegisterOutcome = {
+    kind: "accepted";
+    statusUrl: string;
+    retryAfterSeconds?: number;
+} | {
+    kind: "problem";
+    problem: Problem;
+};
+export declare function readRegisterResponse(res: ResponseView, origin?: string): RegisterOutcome;
+export type RegisterGrantOutcome = RegisterOutcome | {
+    kind: "payment_required";
+    /** The raw `X-PAYMENT-REQUIRED` header (base64 JSON), undecoded. */
+    paymentRequiredHeader: string;
+    problem: Problem;
+};
+/**
+ * canopy's answer to `POST /register/{R}/grants`: 303 to the grant's status
+ * URL, or 402 with an `X-PAYMENT-REQUIRED` challenge when the parent grant
+ * makes this child payment-gated (and again, with canopy's reason, when a
+ * presented `X-PAYMENT` is refused). A 402 without the header is a problem.
+ */
+export declare function readRegisterGrantResponse(res: ResponseView, origin?: string): RegisterGrantOutcome;
+export type StatusOutcome = {
+    kind: "pending";
+    retryAfterSeconds: number;
+} | {
+    kind: "sequenced";
+    receiptUrl: string;
+    massifHeight: number;
+    entryId: string;
+} | {
+    kind: "problem";
+    problem: Problem;
+};
+export declare function readStatusResponse(res: ResponseView, origin?: string): StatusOutcome;
+export type ReceiptOutcome = {
+    kind: "sealed";
+    receipt: Uint8Array;
+    contentType?: string;
+} | {
+    kind: "awaiting_seal";
+    reason: string;
+} | {
+    kind: "problem";
+    problem: Problem;
+};
+export declare function readReceiptResponse(res: ResponseView): ReceiptOutcome;
+//# sourceMappingURL=scrapi.d.ts.map

package/dist/core/scrapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scrapi.d.ts","sourceRoot":"","sources":["../../src/core/scrapi.ts"],"names":[],"mappings":"AAmBA,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAkCtD;AAqCD,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAM5D;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,YAAY,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,CAYjB;AAED,MAAM,MAAM,oBAAoB,GAC5B,eAAe,GACf;IACE,IAAI,EAAE,kBAAkB,CAAC;IACzB,oEAAoE;IACpE,qBAAqB,EAAE,MAAM,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEN;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,YAAY,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,oBAAoB,CAStB;AAID,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,GAC9C;IACE,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB,GACD;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1C,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,YAAY,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,aAAa,CAcf;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC;AAY1C,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,GAAG,cAAc,CAgBrE"}

package/dist/core/scrapi.js

@@ -0,0 +1,174 @@
+/**
+ * Read canopy's answers to the write path, over already-fetched responses.
+ *
+ * The registration contract (canopy `scrapi/register-signed-statement.ts`,
+ * `scrapi/query-registration-status.ts`, `scrapi/resolve-receipt.ts`):
+ *
+ *  - `POST /register/{R}/entries` answers 303 with `Location` = the
+ *    transient status URL `…/logs/{R}/{T}/entries/{sha256(statement)}`.
+ *  - The status URL answers 303 to itself (`Retry-After`) until the entry is
+ *    sequenced, then 303 to the permanent receipt URL
+ *    `…/logs/{R}/{T}/{massifHeight}/entries/{entryId}/receipt`.
+ *  - The receipt URL answers 404 "checkpoint missing" (or "checkpoint does
+ *    not cover entry") until a checkpoint covering the entry is sealed,
+ *    then 200 with the receipt. Other 404s are faults.
+ *  - Failures are `application/problem+cbor` maps `{title, status, detail?,
+ *    reason?}`.
+ */
+import { decodeCborDeterministic } from "@forestrie/encoding";
+export function readProblem(res) {
+    const retry = retryAfter(res);
+    const base = {
+        status: res.status,
+        title: `HTTP ${res.status}`,
+        ...(retry !== undefined ? { retryAfterSeconds: retry } : {}),
+    };
+    if (res.body.length === 0)
+        return base;
+    try {
+        const decoded = decodeCborDeterministic(res.body);
+        const get = (k) => decoded instanceof Map
+            ? decoded.get(k)
+            : typeof decoded === "object" && decoded !== null
+                ? decoded[k]
+                : undefined;
+        const title = get("title");
+        const detail = get("detail");
+        const reason = get("reason");
+        if (typeof title === "string")
+            return {
+                ...base,
+                title,
+                ...(typeof detail === "string" ? { detail } : {}),
+                ...(typeof reason === "string" ? { reason } : {}),
+            };
+    }
+    catch {
+        // Not CBOR: fall through to printable text.
+    }
+    const text = new TextDecoder()
+        .decode(res.body)
+        .replace(/[^\x20-\x7e]+/g, " ")
+        .trim();
+    return text ? { ...base, detail: text.slice(0, 200) } : base;
+}
+/**
+ * Resolve a Location against the URL that answered, and keep it on the
+ * expected origin: a status or receipt URL that points elsewhere is not
+ * followed (the caller would otherwise fetch wherever a server says).
+ */
+function follow(location, res, origin) {
+    let url;
+    try {
+        url = new URL(location, res.url);
+    }
+    catch {
+        return {
+            ok: false,
+            problem: {
+                status: res.status,
+                title: "Invalid Location",
+                detail: `the Location header is not a URL: ${location.slice(0, 200)}`,
+            },
+        };
+    }
+    if (origin !== undefined && url.origin !== origin)
+        return {
+            ok: false,
+            problem: {
+                status: res.status,
+                title: "Unexpected Location",
+                detail: `the Location header points to ${url.origin}, not ${origin}; not following it`,
+            },
+        };
+    return { ok: true, url: url.toString() };
+}
+/** The origin of a base URL, or `undefined` when it does not parse. */
+export function originOf(baseUrl) {
+    try {
+        return new URL(baseUrl).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readRegisterResponse(res, origin) {
+    if (res.status === 303 && res.headers["location"]) {
+        const next = follow(res.headers["location"], res, origin);
+        if (!next.ok)
+            return { kind: "problem", problem: next.problem };
+        const retry = retryAfter(res);
+        return {
+            kind: "accepted",
+            statusUrl: next.url,
+            ...(retry !== undefined ? { retryAfterSeconds: retry } : {}),
+        };
+    }
+    return { kind: "problem", problem: readProblem(res) };
+}
+/**
+ * canopy's answer to `POST /register/{R}/grants`: 303 to the grant's status
+ * URL, or 402 with an `X-PAYMENT-REQUIRED` challenge when the parent grant
+ * makes this child payment-gated (and again, with canopy's reason, when a
+ * presented `X-PAYMENT` is refused). A 402 without the header is a problem.
+ */
+export function readRegisterGrantResponse(res, origin) {
+    const header = res.headers["x-payment-required"];
+    if (res.status === 402 && header)
+        return {
+            kind: "payment_required",
+            paymentRequiredHeader: header,
+            problem: readProblem(res),
+        };
+    return readRegisterResponse(res, origin);
+}
+const RECEIPT_PATH = /\/(\d+)\/entries\/([0-9a-f]{32})\/receipt$/;
+export function readStatusResponse(res, origin) {
+    if (res.status !== 303)
+        return { kind: "problem", problem: readProblem(res) };
+    const next = follow(res.headers["location"] ?? res.url, res, origin);
+    if (!next.ok)
+        return { kind: "problem", problem: next.problem };
+    const match = RECEIPT_PATH.exec(new URL(next.url).pathname);
+    if (match)
+        return {
+            kind: "sequenced",
+            receiptUrl: next.url,
+            massifHeight: Number(match[1]),
+            entryId: match[2],
+        };
+    return { kind: "pending", retryAfterSeconds: retryAfter(res) ?? 1 };
+}
+/**
+ * The 404s that mean "sequenced, not yet sealed": no checkpoint yet, or one
+ * that predates the entry (canopy `scrapi/resolve-receipt.ts`). canopy
+ * answers 404 for other reasons too — a missing massif, a height or index
+ * mismatch, an unknown forest — and those will not fix themselves by
+ * waiting, so they are problems, with canopy's reason.
+ */
+const AWAITING_SEAL = /checkpoint missing\)$|checkpoint does not cover entry\)$/;
+export function readReceiptResponse(res) {
+    if (res.status === 404) {
+        const problem = readProblem(res);
+        if (AWAITING_SEAL.test(problem.title))
+            return { kind: "awaiting_seal", reason: problem.title };
+        return { kind: "problem", problem };
+    }
+    if (res.status === 200 && res.body.length > 0)
+        return {
+            kind: "sealed",
+            receipt: res.body,
+            ...(res.headers["content-type"]
+                ? { contentType: res.headers["content-type"] }
+                : {}),
+        };
+    return { kind: "problem", problem: readProblem(res) };
+}
+function retryAfter(res) {
+    const raw = res.headers["retry-after"];
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+//# sourceMappingURL=scrapi.js.map

package/dist/core/scrapi.js.map

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

package/dist/core/signer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The signer seam: every signature this package makes goes through one
+ * `Es256Signer`. Core code builds the exact bytes to be signed and hands
+ * them over; it never sees a private key, and no signature byte ever
+ * arrives from a tool argument. Where the key lives — a local key file
+ * (the default, `src/node/signer-file.ts`), a KMS, a remote signer — is the
+ * backend's business.
+ *
+ * ES256 only: canopy's child-log paths (register-grant auto-forward and
+ * `POST /api/forest/{child}/prepare`) accept 64-byte P-256 roots only, so a
+ * KS256 log key could not delegate its own sealing without an operator.
+ */
+export interface Es256Signer {
+    /** The P-256 public key as 64 bytes x‖y — what a grant's `grantData` names. */
+    publicKeyXY(): Promise<Uint8Array>;
+    /**
+     * ECDSA P-256 with SHA-256 over `message` (the signer hashes), returned as
+     * IEEE P1363 r‖s, 64 bytes. For COSE that message is the Sig_structure.
+     */
+    sign(message: Uint8Array): Promise<Uint8Array>;
+    /** Where the key lives, for humans: never key material. */
+    readonly description: string;
+}
+//# sourceMappingURL=signer.d.ts.map

package/dist/core/signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.d.ts","sourceRoot":"","sources":["../../src/core/signer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IACnC;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC/C,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B"}

package/dist/core/signer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=signer.js.map

package/dist/core/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/core/signer.ts"],"names":[],"mappings":""}

package/dist/core/statement.d.ts

@@ -0,0 +1,26 @@
+import type { Es256Signer } from "./signer.js";
+export declare class StatementError extends Error {
+    readonly code: "invalid_input" | "too_large" | "signer_failed";
+    constructor(code: "invalid_input" | "too_large" | "signer_failed", message: string);
+}
+export interface SignStatementInput {
+    payload: Uint8Array;
+    /** The payload's media type, carried in protected header 3. */
+    contentType: string;
+    /** CWT iss; defaults to the hex of the kid. */
+    issuer?: string;
+    /** CWT sub; defaults to `sha-256:<hex of payload>`, as forestrie-cli does. */
+    subject?: string;
+    /** CWT iat, seconds since the epoch; omitted when absent. */
+    issuedAt?: number;
+}
+export interface SignedStatement {
+    statement: Uint8Array;
+    /** sha256 of the statement: the id in canopy's status URL. */
+    contentHash: string;
+    kid: Uint8Array;
+    issuer: string;
+    subject: string;
+}
+export declare function signStatement(input: SignStatementInput, signer: Es256Signer): Promise<SignedStatement>;
+//# sourceMappingURL=statement.d.ts.map

package/dist/core/statement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement.d.ts","sourceRoot":"","sources":["../../src/core/statement.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,qBAAa,cAAe,SAAQ,KAAK;IAErC,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,GAAG,eAAe;gBAArD,IAAI,EAAE,eAAe,GAAG,WAAW,GAAG,eAAe,EAC9D,OAAO,EAAE,MAAM;CAIlB;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,UAAU,CAAC;IACpB,+DAA+D;IAC/D,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,UAAU,CAAC;IACtB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,kBAAkB,EACzB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,eAAe,CAAC,CA0E1B"}

package/dist/core/statement.js

@@ -0,0 +1,70 @@
+/**
+ * Build and sign the statement canopy registers: an untagged COSE Sign1,
+ * payload attached, protected header `{1: -7, 3: cty, 4: kid, 15: {1: iss,
+ * 2: sub}}`, empty unprotected header.
+ *
+ * Byte-for-byte the construction of `@forestrie/encoding`'s
+ * `signCoseSign1Statement` (the one forestrie-cli uses), with the
+ * WebCrypto call replaced by the signer seam: the same protected map, the
+ * same Sig_structure, the same envelope encoder.
+ *
+ * kid is the key's 32-byte x coordinate, the binding canopy checks first
+ * (canopy `grant/statement-signer-binding.ts`).
+ */
+import { COSE_ALG_ES256, encodeCoseProtectedMapBytes, encodeCoseSign1Statement, encodeSigStructure, verifyCoseSign1WithParsedKey, } from "@forestrie/encoding";
+import { MAX_STATEMENT_BYTES } from "./limits.js";
+import { sha256, toHex } from "./hex.js";
+export class StatementError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export async function signStatement(input, signer) {
+    if (input.payload.length === 0)
+        throw new StatementError("invalid_input", "payload is empty");
+    if (input.payload.length > MAX_STATEMENT_BYTES)
+        throw new StatementError("too_large", `payload is ${input.payload.length} bytes; canopy accepts signed statements up to ${MAX_STATEMENT_BYTES} bytes. Register a small manifest naming the artefact's digest instead`);
+    if (!input.contentType.trim())
+        throw new StatementError("invalid_input", "contentType is empty");
+    const xy = await signer.publicKeyXY();
+    if (xy.length !== 64)
+        throw new StatementError("signer_failed", `signer returned a ${xy.length}-byte public key; ES256 needs 64 bytes x‖y`);
+    const kid = xy.slice(0, 32);
+    const issuer = input.issuer ?? toHex(kid);
+    const subject = input.subject ?? `sha-256:${toHex(await sha256(input.payload))}`;
+    const options = {
+        alg: COSE_ALG_ES256,
+        cty: input.contentType,
+        cwtClaims: {
+            iss: issuer,
+            sub: subject,
+            ...(input.issuedAt !== undefined ? { iat: input.issuedAt } : {}),
+        },
+    };
+    const sigStructure = encodeSigStructure(encodeCoseProtectedMapBytes(kid, options), new Uint8Array(0), input.payload);
+    const signature = await signer.sign(sigStructure);
+    if (signature.length !== 64)
+        throw new StatementError("signer_failed", `signer returned a ${signature.length}-byte signature; ES256 is 64 bytes r‖s`);
+    const statement = encodeCoseSign1Statement(input.payload, kid, signature, options);
+    // Check our own work before canopy does: a signer that signs with a key
+    // other than the one it reports would otherwise surface as a bare 403.
+    const verified = await verifyCoseSign1WithParsedKey(statement, {
+        x: xy.slice(0, 32),
+        y: xy.slice(32),
+        curve: "P-256",
+    });
+    if (!verified)
+        throw new StatementError("signer_failed", "the signature does not verify under the signer's own public key");
+    if (statement.length > MAX_STATEMENT_BYTES)
+        throw new StatementError("too_large", `the signed statement is ${statement.length} bytes; canopy's limit is ${MAX_STATEMENT_BYTES}`);
+    return {
+        statement,
+        contentHash: toHex(await sha256(statement)),
+        kid,
+        issuer,
+        subject,
+    };
+}
+//# sourceMappingURL=statement.js.map

package/dist/core/statement.js.map

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

package/dist/core/version.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Version strings, as literals.
+ *
+ * Not read from `package.json`: `src/core` is browser-safe, so it has no
+ * `node:fs`, and a JSON import would bake a resolveJsonModule edge into the
+ * `"."` bundle for a handful of strings. The MCP smoke test asserts
+ * `PACKAGE_VERSION === package.json#version`, so a forgotten bump is a red
+ * test rather than a silent lie in `initialize`'s serverInfo.
+ *
+ * Only the versions this package reports (`--help`, `initialize`) live here.
+ * Bump each one in the same commit as the dependency it names.
+ */
+/** Keep in sync with package.json#version. Asserted by test/node/mcp-smoke. */
+export declare const PACKAGE_VERSION = "0.1.0";
+/** Keep in sync with package.json#dependencies["@forestrie/mcp-verify"] — the
+ *  verifier this package composes with. Asserted by
+ *  test/core/version.test.ts. */
+export declare const VERIFIER_VERSION = "0.5.0";
+/** Keep in sync with package.json#dependencies["@forestrie/mcp-resolve"] —
+ *  the resolver this package composes with. Asserted by
+ *  test/core/version.test.ts. */
+export declare const RESOLVE_VERSION = "0.3.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/core/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/core/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,+EAA+E;AAC/E,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;iCAEiC;AACjC,eAAO,MAAM,gBAAgB,UAAU,CAAC;AAExC;;iCAEiC;AACjC,eAAO,MAAM,eAAe,UAAU,CAAC"}