@ziffer-io/mcp 0.1.0

package/dist/anchor.js

@@ -0,0 +1,161 @@
+/**
+ * Read a {@link TrustAnchor} off disk, from the document the engine's own tool
+ * writes (ACP-197, section 6b point 3).
+ *
+ * # The format is not ours to choose
+ *
+ * `ZIFFER_TRUST_ANCHOR` names the output of `acp-bundle pubkey --key <file>`,
+ * at engine pin fed43d1, `crates/acp-bundle-cli/src/main.rs::cmd_pubkey` (the
+ * same four keys in the same order it wrote at 356ef8e, where this comment was
+ * first written; re-read at the v1.3.32 pin rather than assumed). That
+ * document exists precisely so an operator stops transcribing a key between
+ * three encodings by hand, and its doc comment says why a slip matters: **a
+ * transcription slip does not surface as a transcription slip** -- it surfaces
+ * as a signature that does not verify, wearing the face of a compromise. A
+ * second file format here would put that slip back, one layer up.
+ *
+ * The fields read are the two the engine's own `load_public_key` reads, because
+ * the top level of that document IS the `--pubkey` file:
+ *
+ * ```json
+ * {
+ *   "ed25519_pk_hex": "<64 hex chars>",
+ *   "fingerprint": "sha256:<hex>",
+ *   "identity": { "classical": "<base64>", "pq": "<base64>" },
+ *   "mldsa65_pk_hex": "<3904 hex chars>"
+ * }
+ * ```
+ *
+ * `identity` and `fingerprint` are other encodings of the same two keys and are
+ * deliberately NOT read: reading a key twice from one file is two answers to
+ * "which identity is this", and the one nobody exercises is the wrong one.
+ *
+ * # Why the suite floor is not in this file
+ *
+ * {@link TrustAnchor} needs a third value, `minSuite`, and this document does
+ * not carry it -- by construction. `cmd_pubkey` refuses to emit an `alg` field
+ * and states the rule: a suite name is a WIRE field (CR-1), never a member of
+ * an identity, and putting one beside a key would invent a shape no schema in
+ * the engine declares. So the floor is separate configuration, in
+ * `ZIFFER_SUITE_FLOOR`, with no default -- which is also the shape the Executor
+ * already ships (`ZIFFER_POLICY_SIGNING_KEY` names the key file and
+ * `ZIFFER_EXECUTOR_SUITE_FLOOR` names the floor beside it,
+ * `docs/onboarding/executor.md` section 4: "an unknown suite is refused, never
+ * defaulted").
+ */
+import { readFile } from 'node:fs/promises';
+/** Ed25519 verification key: 32 bytes, so 64 hex characters. */
+const ED25519_PK_HEX_LEN = 64;
+/** ML-DSA-65 verification key: 1,952 bytes, so 3,904 hex characters. */
+const MLDSA65_PK_HEX_LEN = 3904;
+/**
+ * The secret-half field names `acp-bundle` writes into a KEY file.
+ *
+ * Checked for by name because the mistake this catches is a plausible one: the
+ * operator has two JSON files with similar names, and points
+ * `ZIFFER_TRUST_ANCHOR` at the signing key instead of the public document. That
+ * file has no `ed25519_pk_hex`, so without this check the refusal would be
+ * `TrustAnchorMalformed: missing ed25519_pk_hex` -- true, unhelpful, and it
+ * would send the developer to inspect a file holding a live private key while
+ * wondering what field to add to it. `cmd_pubkey` guards the same confusion
+ * from the other direction with `refuse_if_secret_present`.
+ */
+const SECRET_FIELDS = ['ed25519_sk_hex', 'mldsa65_sk_hex'];
+/**
+ * A trust anchor file that is missing, unreadable, or not what it claims to be.
+ *
+ * Named like the configuration refusals in `config.ts` and for the same reason:
+ * the agent reading this needs to act, and "the file you named is a signing
+ * key" and "the file you named does not exist" are different actions.
+ *
+ * `detail` never carries file CONTENT. A malformed anchor is quoted back into
+ * an agent's context, and if the file turned out to be a secret key, echoing
+ * the bytes that made it malformed is how the key gets there.
+ */
+export class AnchorError extends Error {
+    name;
+    /** The path that was read, which is safe to name and is what identifies it. */
+    path;
+    constructor(name, path, detail) {
+        super(`${name}: ${path}: ${detail}`);
+        this.name = name;
+        this.path = path;
+    }
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Decode a lowercase-hex field of an exact length.
+ *
+ * The length is checked before the decode and is exact rather than a minimum,
+ * because a key of the wrong length is not a weak key, it is a different
+ * object: 31 bytes of an Ed25519 key is not an Ed25519 key at all, and
+ * `verifyReceipt` would refuse every signature under it with a clause that
+ * blames the receipt for a defect in the anchor.
+ */
+function hexField(doc, key, expected, path) {
+    const raw = doc[key];
+    if (typeof raw !== 'string') {
+        throw new AnchorError('TrustAnchorMalformed', path, `${key} is ${raw === undefined ? 'absent' : 'not a string'}; this is not an \`acp-bundle pubkey\` document.`);
+    }
+    if (raw.length !== expected) {
+        throw new AnchorError('TrustAnchorMalformed', path, `${key} is ${raw.length} hex characters, expected exactly ${expected}.`);
+    }
+    if (!/^[0-9a-f]+$/.test(raw)) {
+        // Lowercase only, matching what `cmd_pubkey` writes. Accepting uppercase
+        // would mean two spellings of one anchor file compare unequal while
+        // decoding to the same key, and an operator diffing a rotated key against
+        // the previous one could not tell which changed.
+        throw new AnchorError('TrustAnchorMalformed', path, `${key} is not lowercase hexadecimal.`);
+    }
+    const out = new Uint8Array(raw.length / 2);
+    for (let i = 0; i < out.length; i += 1) {
+        out[i] = Number.parseInt(raw.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+/**
+ * Read and parse the anchor document at `path`, or refuse by name.
+ *
+ * @param minSuite the CR-4 floor from `ZIFFER_SUITE_FLOOR`, passed through
+ *                 unvalidated: `verifyReceipt` is the one place that knows
+ *                 which suite names exist, and it refuses an unknown floor
+ *                 under `CLAUSE_UNKNOWN_SUITE`. A second table of suite names
+ *                 here would be a second answer to what a suite is.
+ * @throws AnchorError `TrustAnchorUnreadable`, `TrustAnchorNotJson`,
+ *         `TrustAnchorHoldsSecret` or `TrustAnchorMalformed`.
+ */
+export async function loadTrustAnchor(path, minSuite) {
+    let raw;
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        // The cause's message is included because "no such file" and "permission
+        // denied" are different developer actions and both are safe to say: it is
+        // errno text about a path, not content from inside the file.
+        throw new AnchorError('TrustAnchorUnreadable', path, error instanceof Error ? error.message : 'could not be read.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new AnchorError('TrustAnchorNotJson', path, 'the file is not JSON; expected the output of `acp-bundle pubkey --key <file>`.');
+    }
+    if (!isRecord(parsed)) {
+        throw new AnchorError('TrustAnchorNotJson', path, 'the file is JSON but not an object.');
+    }
+    for (const secret of SECRET_FIELDS) {
+        if (secret in parsed) {
+            throw new AnchorError('TrustAnchorHoldsSecret', path, `this file carries ${secret}, so it is a SIGNING KEY, not a public trust anchor. Nothing was read from it. Run \`acp-bundle pubkey --key <this file> --out <anchor file>\` and point ZIFFER_TRUST_ANCHOR at the output.`);
+        }
+    }
+    return {
+        classical: hexField(parsed, 'ed25519_pk_hex', ED25519_PK_HEX_LEN, path),
+        pq: hexField(parsed, 'mldsa65_pk_hex', MLDSA65_PK_HEX_LEN, path),
+        minSuite,
+    };
+}
+//# sourceMappingURL=anchor.js.map

package/dist/anchor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchor.js","sourceRoot":"","sources":["../src/anchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAI5C,gEAAgE;AAChE,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAC9B,wEAAwE;AACxE,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAEhC;;;;;;;;;;;GAWG;AACH,MAAM,aAAa,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAU,CAAC;AAEpE;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAClB,IAAI,CAAS;IAC/B,+EAA+E;IACtE,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,IAAY,EAAE,MAAc;QACpD,KAAK,CAAC,GAAG,IAAI,KAAK,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;QACrC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,QAAQ,CAAC,GAA4B,EAAE,GAAW,EAAE,QAAgB,EAAE,IAAY;IACzF,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACrB,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,WAAW,CACnB,sBAAsB,EACtB,IAAI,EACJ,GAAG,GAAG,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,kDAAkD,CAC7G,CAAC;IACJ,CAAC;IACD,IAAI,GAAG,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC5B,MAAM,IAAI,WAAW,CACnB,sBAAsB,EACtB,IAAI,EACJ,GAAG,GAAG,OAAO,GAAG,CAAC,MAAM,qCAAqC,QAAQ,GAAG,CACxE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,yEAAyE;QACzE,oEAAoE;QACpE,0EAA0E;QAC1E,iDAAiD;QACjD,MAAM,IAAI,WAAW,CACnB,sBAAsB,EACtB,IAAI,EACJ,GAAG,GAAG,gCAAgC,CACvC,CAAC;IACJ,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,IAAY,EAAE,QAAgB;IAClE,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,yEAAyE;QACzE,0EAA0E;QAC1E,6DAA6D;QAC7D,MAAM,IAAI,WAAW,CACnB,uBAAuB,EACvB,IAAI,EACJ,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAC9D,CAAC;IACJ,CAAC;IAED,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,WAAW,CACnB,oBAAoB,EACpB,IAAI,EACJ,gFAAgF,CACjF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,WAAW,CAAC,oBAAoB,EAAE,IAAI,EAAE,qCAAqC,CAAC,CAAC;IAC3F,CAAC;IAED,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,IAAI,MAAM,IAAI,MAAM,EAAE,CAAC;YACrB,MAAM,IAAI,WAAW,CACnB,wBAAwB,EACxB,IAAI,EACJ,qBAAqB,MAAM,6LAA6L,CACzN,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO;QACL,SAAS,EAAE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,IAAI,CAAC;QACvE,EAAE,EAAE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,IAAI,CAAC;QAChE,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/bin.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * `npx @ziffer-io/mcp` — the entry point (ACP-197, section 6b).
+ *
+ * # Everything human goes to stderr
+ *
+ * stdout is the JSON-RPC stream. A single stray `console.log` — a banner, a
+ * version line, a debug print — is not a cosmetic problem: it lands in the
+ * middle of a framed message and the client's parser fails on a protocol error
+ * that names nothing about where it came from. So this file writes to stderr,
+ * which MCP clients surface as server logs, and nothing else in this package
+ * writes to either.
+ *
+ * # It does not check its configuration before starting
+ *
+ * Deliberately, and `config.ts` carries the argument: a stdio server that exits
+ * during the handshake tells the agent only that the server failed to start,
+ * and the variable that was missing dies on a stderr nobody reads. Starting and
+ * refusing per tool puts the variable name in front of the one party that can
+ * fix it. The startup line below reports what is configured so a developer who
+ * IS reading the log gets the same information early — a report, not a gate.
+ */
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG"}

package/dist/bin.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * `npx @ziffer-io/mcp` — the entry point (ACP-197, section 6b).
+ *
+ * # Everything human goes to stderr
+ *
+ * stdout is the JSON-RPC stream. A single stray `console.log` — a banner, a
+ * version line, a debug print — is not a cosmetic problem: it lands in the
+ * middle of a framed message and the client's parser fails on a protocol error
+ * that names nothing about where it came from. So this file writes to stderr,
+ * which MCP clients surface as server logs, and nothing else in this package
+ * writes to either.
+ *
+ * # It does not check its configuration before starting
+ *
+ * Deliberately, and `config.ts` carries the argument: a stdio server that exits
+ * during the handshake tells the agent only that the server failed to start,
+ * and the variable that was missing dies on a stderr nobody reads. Starting and
+ * refusing per tool puts the variable name in front of the one party that can
+ * fix it. The startup line below reports what is configured so a developer who
+ * IS reading the log gets the same information early — a report, not a gate.
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { VARS } from './config.js';
+import { createDefaultServer } from './server.js';
+/**
+ * Which variables are set, never their values.
+ *
+ * `ZIFFER_API_KEY` is a bearer credential and this line goes to a log an agent
+ * may capture into its own context. Presence is the whole of what is useful
+ * here anyway: the question this answers is "did my environment reach the
+ * server", and a boolean answers it.
+ */
+function configurationSummary() {
+    return Object.values(VARS)
+        .map((variable) => {
+        const raw = process.env[variable];
+        return `${variable}=${raw === undefined || raw.trim() === '' ? 'unset' : 'set'}`;
+    })
+        .join(' ');
+}
+async function main() {
+    const server = createDefaultServer();
+    await server.connect(new StdioServerTransport());
+    process.stderr.write(`ziffer mcp: serving on stdio (${configurationSummary()})\n`);
+}
+main().catch((error) => {
+    // Reached only if the transport itself fails — a tool refusal never lands
+    // here, because every handler returns its refusal as a result. Exiting
+    // non-zero matters: an MCP client restarts or reports a server that died, and
+    // a process that lingers after its transport is gone is one the client waits
+    // on for ever.
+    process.stderr.write(`ziffer mcp: could not serve: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAElD;;;;;;;GAOG;AACH,SAAS,oBAAoB;IAC3B,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;SACvB,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;QAChB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClC,OAAO,GAAG,QAAQ,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;IACnF,CAAC,CAAC;SACD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,mBAAmB,EAAE,CAAC;IACrC,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,oBAAoB,EAAE,KAAK,CAAC,CAAC;AACrF,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,0EAA0E;IAC1E,uEAAuE;IACvE,8EAA8E;IAC9E,6EAA6E;IAC7E,eAAe;IACf,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gCAAgC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAC3F,CAAC;IACF,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The one file that knows the concrete `@ziffer-io/client` (ACP-197, section 6b
+ * point 1).
+ *
+ * `tools.ts` calls a {@link DecisionClient}, an interface. This module is where
+ * that interface is satisfied by the real thing, and it is deliberately the
+ * only import site: if §6's spelling of a field ever differs from §1's wire
+ * spelling, the mapping belongs here and nowhere else. Two files translating
+ * between the same two vocabularies is how they come to disagree.
+ *
+ * # What is deliberately NOT here
+ *
+ * An HTTP client. This package will not carry one even when `@ziffer-io/client` is
+ * unavailable: a second implementation of §1 is a second place that knows the
+ * auth header, the paths, the status codes and the receipt-passthrough rule,
+ * and the second one is always the one that drifts. `docs/onboarding/sdk.md`
+ * tells developers there is one client; this package would be the
+ * counterexample.
+ *
+ * There is also no retry, no backoff and no caching. `wait` is the client's own
+ * polling loop and it is the one place that decides how often to ask; a second
+ * loop here would be two answers to "how hard do we poll", and the tool would
+ * be holding a decision the developer's own code has not seen.
+ */
+import type { ClientFactory } from './tools.js';
+/**
+ * Build a client from the environment, or refuse.
+ *
+ * Configuration is resolved first and the refusal it raises reaches the agent
+ * as the tool's result, so an unset key is reported before any socket is
+ * opened. {@link ZifferClient} satisfies {@link DecisionClient} structurally —
+ * §6 fixed that surface and `tools.ts` names the two calls used — so there is
+ * no adapter here and no cast: had the two disagreed, this is the one file
+ * where the mapping would live.
+ */
+export declare const zifferClientFactory: ClientFactory;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAGjC,CAAC"}

package/dist/client.js

@@ -0,0 +1,41 @@
+/**
+ * The one file that knows the concrete `@ziffer-io/client` (ACP-197, section 6b
+ * point 1).
+ *
+ * `tools.ts` calls a {@link DecisionClient}, an interface. This module is where
+ * that interface is satisfied by the real thing, and it is deliberately the
+ * only import site: if §6's spelling of a field ever differs from §1's wire
+ * spelling, the mapping belongs here and nowhere else. Two files translating
+ * between the same two vocabularies is how they come to disagree.
+ *
+ * # What is deliberately NOT here
+ *
+ * An HTTP client. This package will not carry one even when `@ziffer-io/client` is
+ * unavailable: a second implementation of §1 is a second place that knows the
+ * auth header, the paths, the status codes and the receipt-passthrough rule,
+ * and the second one is always the one that drifts. `docs/onboarding/sdk.md`
+ * tells developers there is one client; this package would be the
+ * counterexample.
+ *
+ * There is also no retry, no backoff and no caching. `wait` is the client's own
+ * polling loop and it is the one place that decides how often to ask; a second
+ * loop here would be two answers to "how hard do we poll", and the tool would
+ * be holding a decision the developer's own code has not seen.
+ */
+import { ZifferClient } from '@ziffer-io/client';
+import { apiConfig } from './config.js';
+/**
+ * Build a client from the environment, or refuse.
+ *
+ * Configuration is resolved first and the refusal it raises reaches the agent
+ * as the tool's result, so an unset key is reported before any socket is
+ * opened. {@link ZifferClient} satisfies {@link DecisionClient} structurally —
+ * §6 fixed that surface and `tools.ts` names the two calls used — so there is
+ * no adapter here and no cast: had the two disagreed, this is the one file
+ * where the mapping would live.
+ */
+export const zifferClientFactory = async (env) => {
+    const config = apiConfig(env);
+    return new ZifferClient(config.baseUrl, config.apiKey);
+};
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,SAAS,EAAY,MAAM,aAAa,CAAC;AAGlD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAkB,KAAK,EAAE,GAAQ,EAA2B,EAAE;IAC5F,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9B,OAAO,IAAI,YAAY,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;AACzD,CAAC,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,108 @@
+/**
+ * What the developer hands `npx @ziffer-io/mcp`, and what happens when they have
+ * not handed it anything yet (ACP-197, section 6b point 3).
+ *
+ * This is the only place in this package that reads the environment, for the
+ * reason `services/approval/src/config.ts` states one service over: a second
+ * `process.env` somewhere in a tool handler would be a second statement of what
+ * this server requires, and the one that goes stale is the documented one.
+ *
+ * # This server starts unconfigured, and that inverts the house rule
+ *
+ * Every other process in this repository refuses to start without its complete
+ * environment. `docs/onboarding/executor.md` section 4 states the reason and it
+ * is a good one: a process that came up and cannot serve is worse than one that
+ * refused to come up, because a supervisor keeps the first alive.
+ *
+ * An MCP server over stdio has no supervisor and no operator watching a log. It
+ * is spawned by a coding agent, it speaks JSON-RPC on stdout, and when it exits
+ * during the initialization handshake the agent is told only that the server
+ * failed to start. The variable that was missing died with the process, on a
+ * stderr nobody is reading. So the failure would surface to the developer as
+ * "the Ziffer MCP server does not work" -- undebuggable from the only side that
+ * can fix it.
+ *
+ * So the process starts, and configuration is resolved PER CALL: each tool that
+ * needs a value asks for it, and a missing one is a named {@link ConfigError}
+ * returned to the agent as the tool's result, naming the exact variable to set.
+ * The agent can then tell its developer, or read
+ * {@link https://../../docs/onboarding/sdk.md} through `get_integration_guide`,
+ * which is the one tool that deliberately needs no configuration at all.
+ *
+ * **This is not a relaxation of failing closed.** Nothing proceeds on a missing
+ * value: an unconfigured `propose` sends no request and an unconfigured
+ * `explain_receipt` verifies nothing. The refusal moved from process exit to
+ * tool result; it did not become a default. A default `ZIFFER_API_URL` would
+ * point a developer's proposals at a host nobody chose, and a default trust
+ * anchor would verify receipts under a key nobody enrolled.
+ */
+/**
+ * The variables, named once. Every error below quotes one of these, so a rename
+ * cannot leave a message pointing at a variable that no longer exists
+ * (`services/approval/src/config.ts`'s `VARS`, and `services/kms`'s `pub mod
+ * var` one language over).
+ */
+export declare const VARS: {
+    readonly API_URL: "ZIFFER_API_URL";
+    readonly API_KEY: "ZIFFER_API_KEY";
+    readonly TRUST_ANCHOR: "ZIFFER_TRUST_ANCHOR";
+    readonly SUITE_FLOOR: "ZIFFER_SUITE_FLOOR";
+};
+/**
+ * A configuration value that is missing or is not what it claims to be.
+ *
+ * `name` is the refusal's machine-readable half, spelled in the PascalCase the
+ * ACP-197 section 1 refusals use (`ApiKeyUnknown`, `TenantMismatch`), so an
+ * agent can branch on it. `variable` is what the developer has to set, and it
+ * is a separate field rather than something to parse back out of the message.
+ *
+ * `detail` describes the SHAPE of what was wrong and never carries the value.
+ * `ZIFFER_API_KEY` is a bearer credential and this text is returned over the
+ * MCP transport into an agent's context, which is the last place a live key
+ * should be echoed -- the same reason `ApprovalConfig`'s printer redacts its
+ * private key one service over.
+ */
+export declare class ConfigError extends Error {
+    /** The refusal name an agent branches on. */
+    readonly name: string;
+    /** The environment variable the developer has to set. */
+    readonly variable: string;
+    constructor(name: string, variable: string, detail: string);
+}
+/** Where this server sends proposals, and the key that says who is sending. */
+export interface ApiConfig {
+    /** `ZIFFER_API_URL` — the gateway's base URL, no trailing slash. */
+    readonly baseUrl: string;
+    /** `ZIFFER_API_KEY` — the bearer key. It also determines the tenant: ACP-197
+     * section 1 makes the KEY the tenant, so this server never sends a tenant
+     * name of its own and could not override one if it wanted to. */
+    readonly apiKey: string;
+}
+/** Where this server reads the verifier's own trust anchor from. */
+export interface AnchorConfig {
+    /** `ZIFFER_TRUST_ANCHOR` — path to an `acp-bundle pubkey` document. */
+    readonly anchorPath: string;
+    /** `ZIFFER_SUITE_FLOOR` — the CR-4 floor, by wire suite name. */
+    readonly suiteFloor: string;
+}
+/** The environment, as a plain map, so tests never mutate `process.env`. */
+export type Env = Readonly<Record<string, string | undefined>>;
+/**
+ * Resolve the gateway leg, or refuse by name.
+ *
+ * @throws ConfigError `ApiUrlUnconfigured` or `ApiKeyUnconfigured`.
+ */
+export declare function apiConfig(env: Env): ApiConfig;
+/**
+ * Resolve the verification leg, or refuse by name.
+ *
+ * `anchorPathOverride` is `explain_receipt`'s optional argument. It wins over
+ * the variable because a developer verifying a receipt against a SECOND
+ * identity -- a staging tenant, or a key they are about to rotate to -- should
+ * not have to restart their coding agent to do it. When neither is present the
+ * refusal names the variable, because that is the durable way to set it.
+ *
+ * @throws ConfigError `TrustAnchorUnconfigured` or `SuiteFloorUnconfigured`.
+ */
+export declare function anchorConfig(env: Env, anchorPathOverride?: string): AnchorConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,IAAI;;;;;CAKP,CAAC;AAEX;;;;;;;;;;;;;GAaG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,6CAA6C;IAC7C,SAAkB,IAAI,EAAE,MAAM,CAAC;IAC/B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAK3D;AAED,+EAA+E;AAC/E,MAAM,WAAW,SAAS;IACxB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;qEAEiE;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,oEAAoE;AACpE,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,iEAAiE;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,4EAA4E;AAC5E,MAAM,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAU/D;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,SAAS,CA2C7C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,kBAAkB,CAAC,EAAE,MAAM,GAAG,YAAY,CAkBhF"}

package/dist/config.js

@@ -0,0 +1,134 @@
+/**
+ * What the developer hands `npx @ziffer-io/mcp`, and what happens when they have
+ * not handed it anything yet (ACP-197, section 6b point 3).
+ *
+ * This is the only place in this package that reads the environment, for the
+ * reason `services/approval/src/config.ts` states one service over: a second
+ * `process.env` somewhere in a tool handler would be a second statement of what
+ * this server requires, and the one that goes stale is the documented one.
+ *
+ * # This server starts unconfigured, and that inverts the house rule
+ *
+ * Every other process in this repository refuses to start without its complete
+ * environment. `docs/onboarding/executor.md` section 4 states the reason and it
+ * is a good one: a process that came up and cannot serve is worse than one that
+ * refused to come up, because a supervisor keeps the first alive.
+ *
+ * An MCP server over stdio has no supervisor and no operator watching a log. It
+ * is spawned by a coding agent, it speaks JSON-RPC on stdout, and when it exits
+ * during the initialization handshake the agent is told only that the server
+ * failed to start. The variable that was missing died with the process, on a
+ * stderr nobody is reading. So the failure would surface to the developer as
+ * "the Ziffer MCP server does not work" -- undebuggable from the only side that
+ * can fix it.
+ *
+ * So the process starts, and configuration is resolved PER CALL: each tool that
+ * needs a value asks for it, and a missing one is a named {@link ConfigError}
+ * returned to the agent as the tool's result, naming the exact variable to set.
+ * The agent can then tell its developer, or read
+ * {@link https://../../docs/onboarding/sdk.md} through `get_integration_guide`,
+ * which is the one tool that deliberately needs no configuration at all.
+ *
+ * **This is not a relaxation of failing closed.** Nothing proceeds on a missing
+ * value: an unconfigured `propose` sends no request and an unconfigured
+ * `explain_receipt` verifies nothing. The refusal moved from process exit to
+ * tool result; it did not become a default. A default `ZIFFER_API_URL` would
+ * point a developer's proposals at a host nobody chose, and a default trust
+ * anchor would verify receipts under a key nobody enrolled.
+ */
+/**
+ * The variables, named once. Every error below quotes one of these, so a rename
+ * cannot leave a message pointing at a variable that no longer exists
+ * (`services/approval/src/config.ts`'s `VARS`, and `services/kms`'s `pub mod
+ * var` one language over).
+ */
+export const VARS = {
+    API_URL: 'ZIFFER_API_URL',
+    API_KEY: 'ZIFFER_API_KEY',
+    TRUST_ANCHOR: 'ZIFFER_TRUST_ANCHOR',
+    SUITE_FLOOR: 'ZIFFER_SUITE_FLOOR',
+};
+/**
+ * A configuration value that is missing or is not what it claims to be.
+ *
+ * `name` is the refusal's machine-readable half, spelled in the PascalCase the
+ * ACP-197 section 1 refusals use (`ApiKeyUnknown`, `TenantMismatch`), so an
+ * agent can branch on it. `variable` is what the developer has to set, and it
+ * is a separate field rather than something to parse back out of the message.
+ *
+ * `detail` describes the SHAPE of what was wrong and never carries the value.
+ * `ZIFFER_API_KEY` is a bearer credential and this text is returned over the
+ * MCP transport into an agent's context, which is the last place a live key
+ * should be echoed -- the same reason `ApprovalConfig`'s printer redacts its
+ * private key one service over.
+ */
+export class ConfigError extends Error {
+    /** The refusal name an agent branches on. */
+    name;
+    /** The environment variable the developer has to set. */
+    variable;
+    constructor(name, variable, detail) {
+        super(`${name}: ${detail} Set ${variable}.`);
+        this.name = name;
+        this.variable = variable;
+    }
+}
+function required(env, variable, refusal, detail) {
+    const raw = env[variable];
+    if (raw === undefined || raw.trim() === '') {
+        throw new ConfigError(refusal, variable, detail);
+    }
+    return raw.trim();
+}
+/**
+ * Resolve the gateway leg, or refuse by name.
+ *
+ * @throws ConfigError `ApiUrlUnconfigured` or `ApiKeyUnconfigured`.
+ */
+export function apiConfig(env) {
+    const raw = required(env, VARS.API_URL, 'ApiUrlUnconfigured', 'this server does not know which Ziffer gateway to call.');
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        // Named separately from the unset case because they are different developer
+        // actions: one is "you have set nothing", the other is "what you set is not
+        // a URL". A single refusal covering both sends the reader to check a
+        // variable that is, in fact, present.
+        throw new ConfigError('ApiUrlMalformed', VARS.API_URL, 'the value is not an absolute URL (expected something like https://api.ziffer.io).');
+    }
+    if (parsed.protocol !== 'https:' && parsed.hostname !== 'localhost' && parsed.hostname !== '127.0.0.1') {
+        // The API key is a bearer credential, so plaintext to a remote host hands
+        // it to anyone on the path. Localhost is exempt because the stub server the
+        // tests run, and the local gateway a developer runs while integrating, are
+        // both http:// on the loopback -- refusing those would mean the only way to
+        // try this package is against production.
+        throw new ConfigError('ApiUrlInsecure', VARS.API_URL, `the value is ${parsed.protocol}// to a remote host, which would send the bearer key in plaintext; use https:// (http:// is allowed only for localhost).`);
+    }
+    const apiKey = required(env, VARS.API_KEY, 'ApiKeyUnconfigured', 'this server has no Ziffer API key, so it cannot say which tenant is proposing.');
+    // No trailing slash, once, here: a base URL that sometimes ends in one turns
+    // every join site into a place where `//v1/proposals` can be built, and the
+    // gateway would answer that with a 404 that names nothing.
+    return { baseUrl: raw.replace(/\/+$/, ''), apiKey };
+}
+/**
+ * Resolve the verification leg, or refuse by name.
+ *
+ * `anchorPathOverride` is `explain_receipt`'s optional argument. It wins over
+ * the variable because a developer verifying a receipt against a SECOND
+ * identity -- a staging tenant, or a key they are about to rotate to -- should
+ * not have to restart their coding agent to do it. When neither is present the
+ * refusal names the variable, because that is the durable way to set it.
+ *
+ * @throws ConfigError `TrustAnchorUnconfigured` or `SuiteFloorUnconfigured`.
+ */
+export function anchorConfig(env, anchorPathOverride) {
+    const override = anchorPathOverride?.trim();
+    const anchorPath = override !== undefined && override !== ''
+        ? override
+        : required(env, VARS.TRUST_ANCHOR, 'TrustAnchorUnconfigured', 'this server has no trust anchor, so it has no identity to verify receipts under.');
+    const suiteFloor = required(env, VARS.SUITE_FLOOR, 'SuiteFloorUnconfigured', 'this server has no CR-4 suite floor, and there is no default one: a floor chosen here would be a minimum signature strength nobody agreed to.');
+    return { anchorPath, suiteFloor };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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