@ziffer-io/client 0.1.0

package/LICENSE

@@ -0,0 +1,120 @@
+ZIFFER SDK LICENSE
+
+Copyright (c) 2026 code75 SASU, Paris, France. All rights reserved.
+ZIFFER is a registered trademark of code75 SASU ("code75") — code75.io · ziffer.io
+
+This licence governs the software package it accompanies (the "SDK"): the ZIFFER client
+libraries, receipt verifier, wire types and MCP server published by code75. The SDK is
+proprietary software. It is not open source.
+
+1. DEFINITIONS
+   "Agreement" means the written contract under which code75 provides the ZIFFER service to
+   you or the organisation you act for. code75's standard form of that contract is the ZIFFER
+   Customer Agreement, docs/legal/ziffer-customer-agreement.md, v0.1, provided on request.
+   "Service" means the ZIFFER service so provided. "You" means the person or organisation
+   using the SDK under an Agreement.
+
+2. LICENCE
+   Subject to the Agreement and to this licence, code75 grants you a limited, non-exclusive,
+   non-transferable, non-sublicensable, revocable licence to install and run the SDK, in
+   unmodified form, solely to interact with the Service and to verify the receipts it issues,
+   for the term of the Agreement.
+
+3. RESTRICTIONS
+   Except as expressly permitted by section 2 or by a law that cannot be excluded by
+   contract, you shall not, and shall not permit anyone else to:
+   (a) copy, distribute, publish, sublicense, sell, rent, lease or lend the SDK, or make it
+       available to any third party;
+   (b) modify, adapt, translate or create derivative works of the SDK;
+   (c) reverse engineer, decompile, disassemble or otherwise attempt to derive the source
+       code, algorithms or protocols of the SDK or the Service;
+   (d) use the SDK to build, train or benchmark a product or service that competes with the
+       Service, or to access the Service other than through the interfaces code75 documents;
+   (e) circumvent, disable or interfere with any security, verification or usage-control
+       mechanism of the SDK or the Service;
+   (f) remove, obscure or alter any copyright, trademark or other proprietary notice on or
+       in the SDK.
+
+4. OWNERSHIP AND INTELLECTUAL PROPERTY
+   The SDK is licensed, not sold. code75 and its licensors own and retain all right, title
+   and interest in and to the SDK and the Service, including all copyright, patent, trade
+   secret, trademark and other intellectual property rights, and all improvements and
+   derivative works, by whomever made. Nothing in this licence transfers any such right to
+   you. All rights not expressly granted are reserved. Any suggestion, idea or feedback you
+   provide about the SDK or the Service may be used by code75 without restriction or
+   compensation. "ZIFFER" and "code75" and the associated logos are brands and marks of
+   code75; this licence grants no right to use them.
+
+5. THIRD-PARTY COMPONENTS
+   The SDK includes third-party open-source components listed in the accompanying file
+   THIRD-PARTY-NOTICES. Those components are licensed under their own terms, which govern
+   them and prevail over this licence for those components only. This licence does not
+   apply to them.
+
+6. UPDATES
+   code75 may release updated versions of the SDK. This licence applies to each version you
+   install unless a later version is accompanied by a different licence. code75 has no
+   obligation to provide updates or support except as stated in the Agreement.
+
+7. YOUR RESPONSIBILITY FOR YOUR ACTIONS AND YOUR DATA
+   The Service issues decisions and signed receipts; it does not perform any action. You
+   alone decide what your systems do with a decision, you alone hold the credentials with
+   which any action is performed, and you alone are responsible for every action your
+   systems take or fail to take, for the policy you write and sign, for the data you submit
+   to the Service, and for your compliance with applicable law, including data protection,
+   export control and sanctions laws. A decision or receipt is not legal, regulatory,
+   financial or professional advice and is not a guarantee that any action is lawful,
+   appropriate or safe.
+
+7A. INDEMNITY
+   You shall defend, indemnify and hold harmless code75, its officers, employees and
+   contractors from and against any claim, loss, liability, damage, cost or expense
+   (including reasonable legal fees) arising out of or relating to: (a) your use of the
+   SDK or the Service; (b) any action taken or not taken by your systems; (c) the policy,
+   data or content you provide; or (d) your breach of this licence, the Agreement or
+   applicable law.
+
+7B. PRE-RELEASE SOFTWARE
+   The SDK and the Service may be provided in a pre-release, evaluation or limited form.
+   You accept that such software may contain errors and may change or be withdrawn, and
+   you use it at your own risk.
+
+8. NO WARRANTY
+   THE SDK IS PROVIDED "AS IS" AND "AS AVAILABLE", WITHOUT WARRANTY OF ANY KIND, EXPRESS,
+   IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION ANY WARRANTY OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, TITLE OR NON-INFRINGEMENT, TO THE MAXIMUM EXTENT
+   PERMITTED BY LAW.
+
+9. LIMITATION OF LIABILITY
+   TO THE MAXIMUM EXTENT PERMITTED BY LAW, CODE75 SHALL NOT BE LIABLE FOR ANY INDIRECT,
+   INCIDENTAL, SPECIAL, CONSEQUENTIAL OR PUNITIVE DAMAGES, OR FOR ANY LOSS OF PROFITS,
+   REVENUE, DATA OR GOODWILL, ARISING OUT OF OR RELATING TO THE SDK, HOWEVER CAUSED AND
+   UNDER ANY THEORY OF LIABILITY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+   CODE75'S TOTAL LIABILITY UNDER THIS LICENCE SHALL NOT EXCEED THE AMOUNT STATED IN THE
+   AGREEMENT OR, IF NONE IS STATED, ONE HUNDRED EUROS (EUR 100). Nothing in this licence
+   excludes or limits liability that cannot be excluded or limited under applicable law.
+
+10. TERMINATION
+   This licence terminates automatically, without notice, if you breach it or when the
+   Agreement ends. On termination you shall stop all use of the SDK and destroy every copy
+   in your possession or control. Sections 3, 4, 7, 7A, 8, 9, 10, 11 and 12 survive
+   termination.
+
+11. GOVERNING LAW AND JURISDICTION
+   This licence is governed by the laws of France, without regard to conflict-of-law rules.
+   Any dispute arising out of or relating to this licence is submitted to the exclusive
+   jurisdiction of the competent courts of Paris, France, unless the Agreement states
+   otherwise.
+
+12. GENERAL
+   This licence, the Agreement and THIRD-PARTY-NOTICES are the entire terms for the SDK.
+   Where this licence and the Agreement conflict, the Agreement prevails. If any provision
+   of this licence is held unenforceable, it is enforced to the maximum extent permitted
+   and the remainder stays in effect. No failure or delay by code75 in exercising a right
+   is a waiver of it. You may not assign this licence without code75's written consent;
+   code75 may assign it to a successor of the ZIFFER business. Any claim by you relating to
+   the SDK must be brought within one (1) year after it arises, to the extent the law
+   allows. This licence is written in English; a translation is for convenience only and
+   the English text prevails.
+
+Contact: code75 SASU, Paris — code75.io · ziffer.io

package/README.md

@@ -0,0 +1,69 @@
+# `@ziffer-io/client`
+
+The TypeScript SDK for the ZIFFER decision API: submit a proposal, wait for the decision, and
+verify the receipt before you act on it.
+
+```bash
+npm install @ziffer-io/client
+```
+
+That one line brings the wire types (`@ziffer-io/types`) and the verifier (`@ziffer-io/verify`)
+with it. `verifyReceipt` is **re-exported unchanged** from the verifier's own package, so there is
+one verifier in your dependency tree rather than two that can disagree — the tests assert it is
+the same function object, so the re-export cannot decay into a copy quietly.
+
+## The whole integration
+
+```ts
+import { ZifferClient, verifyReceipt, Refusal, type TrustAnchor } from '@ziffer-io/client';
+
+const client = new ZifferClient(process.env.ZIFFER_API_URL, process.env.ZIFFER_API_KEY);
+const anchor: TrustAnchor = await loadAnchor(process.env.ZIFFER_TRUST_ANCHOR);
+
+const submitted = await client.propose(proposal);
+const decision = await client.wait(submitted.decision_id, { timeoutMs: 30_000 });
+if (decision.outcome !== 'ALLOW') throw new Error(`ziffer refused: ${decision.clause}`);
+
+verifyReceipt(decision.receipt, new TextEncoder().encode(JSON.stringify(proposal)), anchor);
+await bank.transfer(amount, toAccount);          // your line, unchanged
+```
+
+`verifyReceipt` throws on any defect. Catch `Refusal` and read `.clause` — narrow with
+`instanceof`, never a cast: a `catch` binds `unknown` and also sees the errors you did not plan
+for, so an `as Refusal` would read a `clause` off a `TypeError` and report a protocol refusal that
+never happened.
+
+`docs/onboarding/sdk.md` section 8 is the same integration at length, with what each refusal means.
+
+## What it does not do
+
+- **It computes no security value, and that is deliberate.** The proposal goes out as you wrote it
+  and the receipt comes back as the gateway stored it. A compromised client writes the whole
+  message, so nothing a client derives about its own request is evidence (RES-8). Every check that
+  matters happens inside `verifyReceipt`, over bytes you supply.
+- **`ALLOW` is not permission to act; the verified receipt is.** The outcome field is transmitted
+  data. Nothing is gated until `verifyReceipt` has returned without throwing, and a handler that
+  calls it without branching on it is not gated at all.
+- **It does not fetch your trust anchor.** `TrustAnchor` is an argument. Obtain the
+  `acp-bundle pubkey` document out of band; an anchor the API served you proves nothing about the
+  API.
+- **It does not choose your signature-suite floor.** There is no default, deliberately.
+- **It has no `approve` and no sandbox shortcut that mints a receipt.** Approval happens inside
+  the deployment, under keys your process never holds.
+- **A pass from `verifyReceipt` is the stateless half of §9.3 only.** `@ziffer-io/verify`'s README
+  lists the six steps that need a signed bundle, a ledger and a context store, and are absent
+  rather than approximated.
+
+## Development
+
+```sh
+pnpm --filter @ziffer-io/client test   # tsc -b && node --test
+```
+
+## Licence
+
+Proprietary. Copyright (c) 2026 code75 SASU, Paris, France. ZIFFER is a registered trademark of code75
+SASU. This package is **not open source**: it is licensed for use with the ZIFFER service under
+your agreement with code75, on the terms in `LICENSE` beside this file. The third-party
+open-source components it redistributes are listed in `THIRD-PARTY-NOTICES` and are governed by
+their own licences.

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,52 @@
+THIRD-PARTY NOTICES for @ziffer-io/client
+
+GENERATED FILE -- do not edit by hand.
+Regenerate with: node tools/third-party-notices.mjs
+tools/release-npm.sh refuses to publish when this file is out of date.
+
+The LICENSE beside this file governs the ZIFFER SDK itself, which is
+proprietary software of code75 SASU. The components below are third-party
+open-source, are redistributed under their own licences, and those licences
+govern them and prevail for those components only (SDK licence, section 5).
+Each entry is read from the component as it is installed, at the version
+this release resolves.
+
+6 component(s):
+
+----------------------------------------------------------------------------
+@noble/ciphers  2.3.0
+  licence: MIT
+  Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+  full text: LICENSE, as distributed in the package
+
+----------------------------------------------------------------------------
+@noble/curves  2.3.0
+  licence: MIT
+  Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+  full text: LICENSE, as distributed in the package
+
+----------------------------------------------------------------------------
+@noble/hashes  2.3.0
+  licence: MIT
+  Copyright (c) 2022 Paul Miller (https://paulmillr.com)
+  full text: LICENSE, as distributed in the package
+
+----------------------------------------------------------------------------
+@noble/post-quantum  0.7.0
+  licence: MIT
+  Copyright (c) 2024 Paul Miller (https://paulmillr.com)
+  full text: LICENSE, as distributed in the package
+
+----------------------------------------------------------------------------
+@ziffer-io/types  link:../types
+  licence: SEE LICENSE IN LICENSE
+  Copyright (c) 2026 code75 SASU, Paris, France. All rights reserved.
+  full text: LICENSE, as distributed in the package
+
+----------------------------------------------------------------------------
+@ziffer-io/verify  link:../acp-verify
+  licence: SEE LICENSE IN LICENSE
+  Copyright (c) 2026 code75 SASU, Paris, France. All rights reserved.
+  full text: LICENSE, as distributed in the package
+
+----------------------------------------------------------------------------

package/dist/client.d.ts

@@ -0,0 +1,197 @@
+/**
+ * The TypeScript client for the public decision API (ACP-197 §1) — the
+ * sibling of the Python SDK's `Client`, speaking the same two routes:
+ *
+ *   POST /v1/proposals            submit one wire Proposal
+ *   GET  /v1/decisions/{id}       poll a decision; the ONE place receipts are served
+ *
+ * One rule, carried over from the scaffold this file replaced: this client
+ * may never compute or assert a security value on the control plane's
+ * behalf. It carries a proposal; it does not carry a risk grade, a
+ * reversibility claim, or an authorisation decision. Every one of those is
+ * recomputed by the Executor from the signed bundle (RES-8), because a
+ * compromised client writes the whole message. The same rule points the
+ * other way too: the client sends the caller's proposal EXACTLY as given —
+ * no defaulting, no rewriting, no "helpful" normalisation — because the
+ * proposal is signed material downstream and a client that edits it has
+ * become its author (the §1 gateway refuses a tenant rewrite for the same
+ * reason).
+ *
+ * # R / B / T for what this module handles
+ *
+ * - `decision_id` is a LOCATOR, classified T (§1). Nothing about it is
+ *   evidence. The binding claim — "this receipt is about my proposal" — is
+ *   verified by `verifyReceipt` recomputing `proposal_hash` from the
+ *   caller's own bytes; the id only tells the client which row to fetch.
+ * - `receipt` is served verbatim by the gateway (parse-free passthrough).
+ *   This client necessarily parses the enclosing JSON response, so what it
+ *   hands back is the parsed VALUE, unmodified — and `verifyReceipt`
+ *   canonicalises the body itself, so a parsed value loses nothing the
+ *   verifier needs. The client never inspects, normalises or re-encodes it.
+ * - Verification has ONE home: `@ziffer-io/verify`, re-exported from this
+ *   package's index. Zero verification logic lives here (ACP-197 §6).
+ *
+ * # Failure surface — named, never silent
+ *
+ * - A gateway refusal (`{"error": name}` with a non-2xx status) throws
+ *   {@link ApiRefusal} carrying the name VERBATIM. The set of names is the
+ *   gateway's and is open; this client closes nothing, because a client
+ *   that filtered names would turn a new server refusal into a silent one.
+ * - An answer that is not §1's shape throws {@link ResponseMalformed}. Fail
+ *   closed: a client guessing at a malformed answer is a client inventing a
+ *   decision status.
+ * - A poll that outlives its deadline throws {@link WaitTimeout}. A timeout
+ *   is "no answer yet", never "the answer was no" (ingress-low's rule for
+ *   its own dependency, one layer out).
+ */
+import type { wire } from '@ziffer-io/types';
+/**
+ * The header every SUCCESSFUL answer carries (ACP-256 §5): the instant the key
+ * that authenticated the call ends, RFC 3339 in UTC. Lowercase because that is
+ * how `Headers.get` and Node's server spell names; the gateway writes it as
+ * `X-Ziffer-Api-Key-Expires` and header names are case-insensitive.
+ *
+ * Never on a refusal. An expired key is refused exactly as an unknown one, so
+ * the only moment a caller can learn its key is about to die is while it still
+ * works -- which is why this client reads the header off 2xx answers only and
+ * would be looking for an oracle if it read it off anything else.
+ */
+export declare const API_KEY_EXPIRES_HEADER = "x-ziffer-api-key-expires";
+/** How close to its end a key has to be before the warning fires. */
+export declare const API_KEY_EXPIRY_WARNING_DAYS = 14;
+/** Test seam only -- not re-exported from the package index. */
+export declare function _resetApiKeyExpiryWarning(): void;
+/**
+ * The §1 POST body: one wire Proposal, snake_case on the wire as
+ * `spec/schemas/wire/proposal.schema.json` spells it.
+ *
+ * Field types are INDEXED from the generated `wire.Proposal` rather than
+ * restated — `services/approval/src/door.ts`'s `WireRenderedSummary` idiom.
+ * The generated model is camelCase; the wire keys are the schema's. Indexing
+ * keeps one definition of each field's domain, so this interface cannot
+ * drift from the schemas without `tsc` catching it (a retyped field here
+ * would be a second definition of a schema object — the encoding-split
+ * defect at the source level).
+ */
+export interface WireProposal {
+    readonly schema_id: wire.Proposal['schemaId'];
+    readonly schema_version: wire.Proposal['schemaVersion'];
+    readonly schema_hash: wire.Proposal['schemaHash'];
+    readonly fidelity: wire.Proposal['fidelity'];
+    readonly tenant_id: wire.Proposal['tenantId'];
+    readonly payload: WireProposalPayload;
+}
+/** PR-1's closed payload, snake_case as the schema spells it — same indexing
+ * rule as {@link WireProposal}. */
+export interface WireProposalPayload {
+    readonly task_type: wire.ProposalPayload['taskType'];
+    readonly operator: wire.ProposalPayload['operator'];
+    readonly targets: wire.ProposalPayload['targets'];
+    readonly params: wire.ProposalPayload['params'];
+    readonly cidrs: wire.ProposalPayload['cidrs'];
+}
+/** The two §1 states. `decided` means the relay recorded a verdict; it does
+ * NOT mean a receipt exists — `receipt` is present iff one does. */
+export type DecisionStatus = 'pending' | 'decided';
+/**
+ * What both §1 routes answer. Refusals expose exactly `{outcome, clause}` —
+ * the fields ingress-low's `relayed_response` exposes — and an absent
+ * `clause` is ABSENT, never `null`: one object, one encoding.
+ */
+export interface Decision {
+    /** The locator (T). Compare nothing against it; fetch with it. */
+    readonly decision_id: string;
+    readonly status: DecisionStatus;
+    /** The engine's outcome type — a fourth spelling of ALLOW / ATTEST / DENY
+     * would be a fourth definition of the object every component agrees on. */
+    readonly outcome?: wire.DecisionOutcome;
+    readonly clause?: string;
+    /**
+     * The signed receipt, verbatim from the one route that serves receipts
+     * (GET). Deliberately `unknown`: its ONLY consumer is `verifyReceipt`,
+     * which takes `unknown` and refuses by name — typing it here would invite
+     * reading fields out of an unverified receipt.
+     */
+    readonly receipt?: unknown;
+}
+/** §1 names, exported so callers and tests never retype the strings. The set
+ * is OPEN — the gateway may name more; {@link ApiRefusal} carries any name
+ * verbatim and this list closes nothing. */
+export declare const ERROR_API_KEY_UNKNOWN = "ApiKeyUnknown";
+export declare const ERROR_TENANT_MISMATCH = "TenantMismatch";
+export declare const ERROR_PROPOSAL_MALFORMED = "ProposalMalformed";
+export declare const ERROR_DECISION_UNKNOWN = "DecisionUnknown";
+export declare const ERROR_ADMISSION_UNAVAILABLE = "AdmissionUnavailable";
+/**
+ * The gateway answered, and the answer was a named refusal. `error` is the
+ * gateway's name, verbatim — the machine-readable half, as `Refusal.clause`
+ * is for verification. `status` is carried for the operator; the NAME is the
+ * contract.
+ */
+export declare class ApiRefusal extends Error {
+    /** The gateway's refusal name, e.g. `ApiKeyUnknown`. Verbatim. */
+    readonly error: string;
+    /** The HTTP status the name arrived under. */
+    readonly status: number;
+    constructor(status: number, error: string);
+}
+/**
+ * The answer was not §1's shape — not JSON, missing or mistyped fields, a
+ * receipt where §1 says none can be, an id that is not the one asked for.
+ * Thrown instead of guessed at: an SDK that repairs a malformed answer is
+ * an SDK that invents decision state.
+ */
+export declare class ResponseMalformed extends Error {
+    constructor(message: string);
+}
+/** The deadline passed with the decision still `pending`. Not a refusal and
+ * not an answer — the decision may still decide; the id remains fetchable. */
+export declare class WaitTimeout extends Error {
+    readonly decisionId: string;
+    constructor(decisionId: string, timeoutMs: number);
+}
+/** Options for {@link ZifferClient.wait}. */
+export interface WaitOptions {
+    /** Give up (throw {@link WaitTimeout}) after this long. Default 30 000. */
+    readonly timeoutMs?: number;
+    /** Delay between polls. Default 500. */
+    readonly intervalMs?: number;
+}
+/**
+ * The client. One instance per (gateway, key); the KEY determines the tenant
+ * server-side (§1), so there is nothing tenant-shaped to configure here —
+ * a client-side tenant setting would be a value the server must ignore.
+ */
+export declare class ZifferClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    /**
+     * POST /v1/proposals. The proposal is serialised as given — the caller's
+     * values, no edits — and the answer never carries a receipt (§1): fetch it
+     * with {@link decision} once decided.
+     */
+    propose(proposal: WireProposal): Promise<Decision>;
+    /**
+     * GET /v1/decisions/{id}. `receipt` is present iff a signed receipt
+     * exists; hand it to `verifyReceipt` with your OWN copy of the proposal
+     * bytes — the id proves nothing (T), the recomputed hash is the binding.
+     */
+    decision(id: string): Promise<Decision>;
+    /**
+     * Poll {@link decision} until `decided` or the deadline. A `WaitTimeout`
+     * is "no answer yet", never a verdict; every named refusal (404 included)
+     * propagates immediately — retrying `DecisionUnknown` would be the client
+     * deciding the server was wrong.
+     */
+    wait(id: string, opts?: WaitOptions): Promise<Decision>;
+    /**
+     * One request, one parse, one narrowing. 2xx returns the parsed body for
+     * the caller's guard; anything else must be §1's `{"error": name}` and
+     * throws {@link ApiRefusal} with the name verbatim. A non-JSON or unnamed
+     * error body throws {@link ResponseMalformed} — an intermediary's HTML 502
+     * is not the gateway's answer and is never dressed up as one.
+     */
+    private request;
+}
+//# 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":"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"}

package/dist/client.js

@@ -0,0 +1,323 @@
+/**
+ * The TypeScript client for the public decision API (ACP-197 §1) — the
+ * sibling of the Python SDK's `Client`, speaking the same two routes:
+ *
+ *   POST /v1/proposals            submit one wire Proposal
+ *   GET  /v1/decisions/{id}       poll a decision; the ONE place receipts are served
+ *
+ * One rule, carried over from the scaffold this file replaced: this client
+ * may never compute or assert a security value on the control plane's
+ * behalf. It carries a proposal; it does not carry a risk grade, a
+ * reversibility claim, or an authorisation decision. Every one of those is
+ * recomputed by the Executor from the signed bundle (RES-8), because a
+ * compromised client writes the whole message. The same rule points the
+ * other way too: the client sends the caller's proposal EXACTLY as given —
+ * no defaulting, no rewriting, no "helpful" normalisation — because the
+ * proposal is signed material downstream and a client that edits it has
+ * become its author (the §1 gateway refuses a tenant rewrite for the same
+ * reason).
+ *
+ * # R / B / T for what this module handles
+ *
+ * - `decision_id` is a LOCATOR, classified T (§1). Nothing about it is
+ *   evidence. The binding claim — "this receipt is about my proposal" — is
+ *   verified by `verifyReceipt` recomputing `proposal_hash` from the
+ *   caller's own bytes; the id only tells the client which row to fetch.
+ * - `receipt` is served verbatim by the gateway (parse-free passthrough).
+ *   This client necessarily parses the enclosing JSON response, so what it
+ *   hands back is the parsed VALUE, unmodified — and `verifyReceipt`
+ *   canonicalises the body itself, so a parsed value loses nothing the
+ *   verifier needs. The client never inspects, normalises or re-encodes it.
+ * - Verification has ONE home: `@ziffer-io/verify`, re-exported from this
+ *   package's index. Zero verification logic lives here (ACP-197 §6).
+ *
+ * # Failure surface — named, never silent
+ *
+ * - A gateway refusal (`{"error": name}` with a non-2xx status) throws
+ *   {@link ApiRefusal} carrying the name VERBATIM. The set of names is the
+ *   gateway's and is open; this client closes nothing, because a client
+ *   that filtered names would turn a new server refusal into a silent one.
+ * - An answer that is not §1's shape throws {@link ResponseMalformed}. Fail
+ *   closed: a client guessing at a malformed answer is a client inventing a
+ *   decision status.
+ * - A poll that outlives its deadline throws {@link WaitTimeout}. A timeout
+ *   is "no answer yet", never "the answer was no" (ingress-low's rule for
+ *   its own dependency, one layer out).
+ */
+// ---------------------------------------------------------------- key expiry
+/**
+ * The header every SUCCESSFUL answer carries (ACP-256 §5): the instant the key
+ * that authenticated the call ends, RFC 3339 in UTC. Lowercase because that is
+ * how `Headers.get` and Node's server spell names; the gateway writes it as
+ * `X-Ziffer-Api-Key-Expires` and header names are case-insensitive.
+ *
+ * Never on a refusal. An expired key is refused exactly as an unknown one, so
+ * the only moment a caller can learn its key is about to die is while it still
+ * works -- which is why this client reads the header off 2xx answers only and
+ * would be looking for an oracle if it read it off anything else.
+ */
+export const API_KEY_EXPIRES_HEADER = 'x-ziffer-api-key-expires';
+/** How close to its end a key has to be before the warning fires. */
+export const API_KEY_EXPIRY_WARNING_DAYS = 14;
+/**
+ * ONCE per process: a line per call is noise the operator filters out, and the
+ * one that mattered goes with it. `console.warn` and not a logger of this
+ * package's own, because that is the channel a deployment already routes.
+ */
+let expiryWarned = false;
+/** Test seam only -- not re-exported from the package index. */
+export function _resetApiKeyExpiryWarning() {
+    expiryWarned = false;
+}
+const RFC3339_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+/**
+ * `null` is an answer with no such header -- a gateway from before it existed
+ * -- and says nothing. A header that is present but not the store's rendering
+ * is reported ONCE by name rather than ignored: silence there is exactly how a
+ * customer would stop being warned without anyone noticing the drift.
+ */
+function noteKeyExpiry(value) {
+    if (value === null || expiryWarned) {
+        return;
+    }
+    const at = RFC3339_UTC.test(value) ? Date.parse(value) : Number.NaN;
+    if (Number.isNaN(at)) {
+        expiryWarned = true;
+        console.warn(`the gateway's ${API_KEY_EXPIRES_HEADER} header is not RFC 3339 UTC (${JSON.stringify(value)}); ` +
+            'this client cannot tell when the API key expires');
+        return;
+    }
+    const msLeft = at - Date.now();
+    if (msLeft < API_KEY_EXPIRY_WARNING_DAYS * 86_400_000) {
+        expiryWarned = true;
+        // Whole days ROUNDED UP: 2 days 23 hours is "3 day(s) left" to the person
+        // reading it.
+        const days = Math.max(Math.ceil(msLeft / 86_400_000), 0);
+        console.warn(`the ZIFFER API key expires on ${value} (${days} day(s) left). An expired key is ` +
+            'refused exactly like an unknown one, so rotate BEFORE then: ask for a successor ' +
+            "(tools/mint-api-key.py --rotate <this key's key_hash>), deploy it, then have this one revoked");
+    }
+}
+// ------------------------------------------------------------ error surface
+/** §1 names, exported so callers and tests never retype the strings. The set
+ * is OPEN — the gateway may name more; {@link ApiRefusal} carries any name
+ * verbatim and this list closes nothing. */
+export const ERROR_API_KEY_UNKNOWN = 'ApiKeyUnknown';
+export const ERROR_TENANT_MISMATCH = 'TenantMismatch';
+export const ERROR_PROPOSAL_MALFORMED = 'ProposalMalformed';
+export const ERROR_DECISION_UNKNOWN = 'DecisionUnknown';
+export const ERROR_ADMISSION_UNAVAILABLE = 'AdmissionUnavailable';
+/**
+ * The gateway answered, and the answer was a named refusal. `error` is the
+ * gateway's name, verbatim — the machine-readable half, as `Refusal.clause`
+ * is for verification. `status` is carried for the operator; the NAME is the
+ * contract.
+ */
+export class ApiRefusal extends Error {
+    /** The gateway's refusal name, e.g. `ApiKeyUnknown`. Verbatim. */
+    error;
+    /** The HTTP status the name arrived under. */
+    status;
+    constructor(status, error) {
+        super(`${error} (HTTP ${status})`);
+        this.name = 'ApiRefusal';
+        this.error = error;
+        this.status = status;
+    }
+}
+/**
+ * The answer was not §1's shape — not JSON, missing or mistyped fields, a
+ * receipt where §1 says none can be, an id that is not the one asked for.
+ * Thrown instead of guessed at: an SDK that repairs a malformed answer is
+ * an SDK that invents decision state.
+ */
+export class ResponseMalformed extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ResponseMalformed';
+    }
+}
+/** The deadline passed with the decision still `pending`. Not a refusal and
+ * not an answer — the decision may still decide; the id remains fetchable. */
+export class WaitTimeout extends Error {
+    decisionId;
+    constructor(decisionId, timeoutMs) {
+        super(`decision ${decisionId} still pending after ${timeoutMs}ms`);
+        this.name = 'WaitTimeout';
+        this.decisionId = decisionId;
+    }
+}
+// ------------------------------------------------------------------- guards
+/** The engine's three outcomes, typed from the generated union so a drift in
+ * the schema surfaces here as a compile error, not a runtime disagreement. */
+const OUTCOMES = ['ALLOW', 'ATTEST', 'DENY'];
+function isOutcome(v) {
+    return typeof v === 'string' && OUTCOMES.some((o) => o === v);
+}
+function isStatus(v) {
+    return v === 'pending' || v === 'decided';
+}
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Narrow one §1 response body to a {@link Decision}, refusing by name on any
+ * departure. `receiptAllowed` is false on the POST path: §1 says the receipt
+ * is NEVER in the POST response — one place serves receipts — and a client
+ * that tolerated one there would quietly stand up a second serving place.
+ */
+function decisionFromBody(body, receiptAllowed) {
+    if (!isRecord(body)) {
+        throw new ResponseMalformed('decision response is not a JSON object');
+    }
+    const id = body['decision_id'];
+    if (typeof id !== 'string' || id.length === 0) {
+        throw new ResponseMalformed('decision response carries no decision_id');
+    }
+    const status = body['status'];
+    if (!isStatus(status)) {
+        throw new ResponseMalformed('decision response status is not "pending" or "decided"');
+    }
+    let decision = { decision_id: id, status };
+    if ('outcome' in body) {
+        const outcome = body['outcome'];
+        if (!isOutcome(outcome)) {
+            // An answer this client cannot read as one of the three is not a
+            // verdict and never becomes one (ingress-low's rule for the same
+            // value, one hop earlier).
+            throw new ResponseMalformed('decision outcome is not ALLOW, ATTEST or DENY');
+        }
+        decision = { ...decision, outcome };
+    }
+    if ('clause' in body) {
+        const clause = body['clause'];
+        if (typeof clause !== 'string') {
+            // Includes null: an absent clause is spelled ABSENT (§1's parity with
+            // ingress-low) — accepting null here would admit the second encoding.
+            throw new ResponseMalformed('decision clause is not a string');
+        }
+        decision = { ...decision, clause };
+    }
+    if ('receipt' in body) {
+        if (!receiptAllowed) {
+            throw new ResponseMalformed('receipt in a POST response: one place serves receipts (GET)');
+        }
+        decision = { ...decision, receipt: body['receipt'] };
+    }
+    return decision;
+}
+/**
+ * The client. One instance per (gateway, key); the KEY determines the tenant
+ * server-side (§1), so there is nothing tenant-shaped to configure here —
+ * a client-side tenant setting would be a value the server must ignore.
+ */
+export class ZifferClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        if (baseUrl.length === 0) {
+            throw new TypeError('ZifferClient: baseUrl is empty');
+        }
+        if (apiKey.length === 0) {
+            // Refused here, not sent: an empty bearer token is a caller bug, and
+            // mailing it to the server converts a local defect into a remote 401
+            // whose log line points at the wrong component.
+            throw new TypeError('ZifferClient: apiKey is empty');
+        }
+        this.baseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl;
+        this.apiKey = apiKey;
+    }
+    /**
+     * POST /v1/proposals. The proposal is serialised as given — the caller's
+     * values, no edits — and the answer never carries a receipt (§1): fetch it
+     * with {@link decision} once decided.
+     */
+    async propose(proposal) {
+        const body = await this.request('POST', '/v1/proposals', JSON.stringify(proposal));
+        return decisionFromBody(body, false);
+    }
+    /**
+     * GET /v1/decisions/{id}. `receipt` is present iff a signed receipt
+     * exists; hand it to `verifyReceipt` with your OWN copy of the proposal
+     * bytes — the id proves nothing (T), the recomputed hash is the binding.
+     */
+    async decision(id) {
+        if (id.length === 0) {
+            throw new TypeError('ZifferClient.decision: id is empty');
+        }
+        const body = await this.request('GET', `/v1/decisions/${encodeURIComponent(id)}`, null);
+        const d = decisionFromBody(body, true);
+        if (d.decision_id !== id) {
+            // The id is a locator, but an answer ABOUT A DIFFERENT LOCATOR is not
+            // an answer to this question — surfacing it as one would let a
+            // confused (or malicious) proxy substitute decisions silently.
+            throw new ResponseMalformed(`decision response is about ${d.decision_id}, not ${id}`);
+        }
+        return d;
+    }
+    /**
+     * Poll {@link decision} until `decided` or the deadline. A `WaitTimeout`
+     * is "no answer yet", never a verdict; every named refusal (404 included)
+     * propagates immediately — retrying `DecisionUnknown` would be the client
+     * deciding the server was wrong.
+     */
+    async wait(id, opts) {
+        const timeoutMs = opts?.timeoutMs ?? 30_000;
+        const intervalMs = opts?.intervalMs ?? 500;
+        if (timeoutMs <= 0 || intervalMs <= 0) {
+            throw new TypeError('ZifferClient.wait: timeoutMs and intervalMs must be positive');
+        }
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const d = await this.decision(id);
+            if (d.status === 'decided') {
+                return d;
+            }
+            if (Date.now() + intervalMs > deadline) {
+                throw new WaitTimeout(id, timeoutMs);
+            }
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+        }
+    }
+    /**
+     * One request, one parse, one narrowing. 2xx returns the parsed body for
+     * the caller's guard; anything else must be §1's `{"error": name}` and
+     * throws {@link ApiRefusal} with the name verbatim. A non-JSON or unnamed
+     * error body throws {@link ResponseMalformed} — an intermediary's HTML 502
+     * is not the gateway's answer and is never dressed up as one.
+     */
+    async request(method, path, body) {
+        const headers = {
+            authorization: `Bearer ${this.apiKey}`,
+        };
+        if (body !== null) {
+            headers['content-type'] = 'application/json';
+        }
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method,
+            headers,
+            ...(body !== null ? { body } : {}),
+        });
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new ResponseMalformed(`HTTP ${res.status} with a non-JSON body from ${method} ${path}`);
+        }
+        if (res.ok) {
+            // Only here, on a 2xx (see API_KEY_EXPIRES_HEADER).
+            noteKeyExpiry(res.headers.get(API_KEY_EXPIRES_HEADER));
+            return parsed;
+        }
+        if (isRecord(parsed)) {
+            const name = parsed['error'];
+            if (typeof name === 'string' && name.length > 0) {
+                throw new ApiRefusal(res.status, name);
+            }
+        }
+        throw new ResponseMalformed(`HTTP ${res.status} from ${method} ${path} names no error`);
+    }
+}
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAIH,8EAA8E;AAE9E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEjE,qEAAqE;AACrE,MAAM,CAAC,MAAM,2BAA2B,GAAG,EAAE,CAAC;AAE9C;;;;GAIG;AACH,IAAI,YAAY,GAAG,KAAK,CAAC;AAEzB,gEAAgE;AAChE,MAAM,UAAU,yBAAyB;IACvC,YAAY,GAAG,KAAK,CAAC;AACvB,CAAC;AAED,MAAM,WAAW,GAAG,wCAAwC,CAAC;AAE7D;;;;;GAKG;AACH,SAAS,aAAa,CAAC,KAAoB;IACzC,IAAI,KAAK,KAAK,IAAI,IAAI,YAAY,EAAE,CAAC;QACnC,OAAO;IACT,CAAC;IACD,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;IACpE,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QACrB,YAAY,GAAG,IAAI,CAAC;QACpB,OAAO,CAAC,IAAI,CACV,iBAAiB,sBAAsB,gCAAgC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK;YAC/F,kDAAkD,CACrD,CAAC;QACF,OAAO;IACT,CAAC;IACD,MAAM,MAAM,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/B,IAAI,MAAM,GAAG,2BAA2B,GAAG,UAAU,EAAE,CAAC;QACtD,YAAY,GAAG,IAAI,CAAC;QACpB,0EAA0E;QAC1E,cAAc;QACd,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CACV,iCAAiC,KAAK,KAAK,IAAI,mCAAmC;YAChF,kFAAkF;YAClF,+FAA+F,CAClG,CAAC;IACJ,CAAC;AACH,CAAC;AA6DD,6EAA6E;AAE7E;;4CAE4C;AAC5C,MAAM,CAAC,MAAM,qBAAqB,GAAG,eAAe,CAAC;AACrD,MAAM,CAAC,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AACtD,MAAM,CAAC,MAAM,wBAAwB,GAAG,mBAAmB,CAAC;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAAG,iBAAiB,CAAC;AACxD,MAAM,CAAC,MAAM,2BAA2B,GAAG,sBAAsB,CAAC;AAElE;;;;;GAKG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,kEAAkE;IACzD,KAAK,CAAS;IACvB,8CAA8C;IACrC,MAAM,CAAS;IAExB,YAAY,MAAc,EAAE,KAAa;QACvC,KAAK,CAAC,GAAG,KAAK,UAAU,MAAM,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;8EAC8E;AAC9E,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,UAAU,CAAS;IAE5B,YAAY,UAAkB,EAAE,SAAiB;QAC/C,KAAK,CAAC,YAAY,UAAU,wBAAwB,SAAS,IAAI,CAAC,CAAC;QACnE,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;CACF;AAED,6EAA6E;AAE7E;8EAC8E;AAC9E,MAAM,QAAQ,GAAoC,CAAC,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;AAE9E,SAAS,SAAS,CAAC,CAAU;IAC3B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,SAAS,CAAC;AAC5C,CAAC;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;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,IAAa,EAAE,cAAuB;IAC9D,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,iBAAiB,CAAC,wCAAwC,CAAC,CAAC;IACxE,CAAC;IACD,MAAM,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC;IAC/B,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,iBAAiB,CAAC,0CAA0C,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,iBAAiB,CACzB,wDAAwD,CACzD,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,GAAa,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;IACrD,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;QAChC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,iEAAiE;YACjE,iEAAiE;YACjE,2BAA2B;YAC3B,MAAM,IAAI,iBAAiB,CAAC,+CAA+C,CAAC,CAAC;QAC/E,CAAC;QACD,QAAQ,GAAG,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,CAAC;IACtC,CAAC;IACD,IAAI,QAAQ,IAAI,IAAI,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,sEAAsE;YACtE,sEAAsE;YACtE,MAAM,IAAI,iBAAiB,CAAC,iCAAiC,CAAC,CAAC;QACjE,CAAC;QACD,QAAQ,GAAG,EAAE,GAAG,QAAQ,EAAE,MAAM,EAAE,CAAC;IACrC,CAAC;IACD,IAAI,SAAS,IAAI,IAAI,EAAE,CAAC;QACtB,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,MAAM,IAAI,iBAAiB,CACzB,6DAA6D,CAC9D,CAAC;QACJ,CAAC;QACD,QAAQ,GAAG,EAAE,GAAG,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAYD;;;;GAIG;AACH,MAAM,OAAO,YAAY;IACN,OAAO,CAAS;IAChB,MAAM,CAAS;IAEhC,YAAY,OAAe,EAAE,MAAc;QACzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,SAAS,CAAC,gCAAgC,CAAC,CAAC;QACxD,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,qEAAqE;YACrE,qEAAqE;YACrE,gDAAgD;YAChD,MAAM,IAAI,SAAS,CAAC,+BAA+B,CAAC,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;QACtE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,OAAO,CAAC,QAAsB;QAClC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;QACnF,OAAO,gBAAgB,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvC,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,EAAU;QACvB,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,SAAS,CAAC,oCAAoC,CAAC,CAAC;QAC5D,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,iBAAiB,kBAAkB,CAAC,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACxF,MAAM,CAAC,GAAG,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,CAAC,WAAW,KAAK,EAAE,EAAE,CAAC;YACzB,sEAAsE;YACtE,+DAA+D;YAC/D,+DAA+D;YAC/D,MAAM,IAAI,iBAAiB,CACzB,8BAA8B,CAAC,CAAC,WAAW,SAAS,EAAE,EAAE,CACzD,CAAC;QACJ,CAAC;QACD,OAAO,CAAC,CAAC;IACX,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,EAAU,EAAE,IAAkB;QACvC,MAAM,SAAS,GAAG,IAAI,EAAE,SAAS,IAAI,MAAM,CAAC;QAC5C,MAAM,UAAU,GAAG,IAAI,EAAE,UAAU,IAAI,GAAG,CAAC;QAC3C,IAAI,SAAS,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,SAAS,CAAC,8DAA8D,CAAC,CAAC;QACtF,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QACxC,SAAS,CAAC;YACR,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YAClC,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC3B,OAAO,CAAC,CAAC;YACX,CAAC;YACD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,QAAQ,EAAE,CAAC;gBACvC,MAAM,IAAI,WAAW,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;YACvC,CAAC;YACD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACK,KAAK,CAAC,OAAO,CACnB,MAAsB,EACtB,IAAY,EACZ,IAAmB;QAEnB,MAAM,OAAO,GAA2B;YACtC,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;SACvC,CAAC;QACF,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;QAC/C,CAAC;QACD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;YAChD,MAAM;YACN,OAAO;YACP,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACnC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,iBAAiB,CACzB,QAAQ,GAAG,CAAC,MAAM,8BAA8B,MAAM,IAAI,IAAI,EAAE,CACjE,CAAC;QACJ,CAAC;QACD,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC;YACX,oDAAoD;YACpD,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,CAAC,CAAC;YACvD,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;YAC7B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChD,MAAM,IAAI,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,MAAM,IAAI,iBAAiB,CACzB,QAAQ,GAAG,CAAC,MAAM,SAAS,MAAM,IAAI,IAAI,iBAAiB,CAC3D,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @ziffer-io/client — the TypeScript SDK for the public decision API (ACP-197 §6).
+ *
+ * Two halves, one boundary:
+ *
+ * - `ZifferClient` (./client.js) carries proposals out and decisions back.
+ *   It computes no security value: the proposal goes as the caller wrote it,
+ *   the receipt comes back as the gateway stored it (RES-8 — a compromised
+ *   client writes the whole message, so nothing a client derives is
+ *   evidence).
+ * - `verifyReceipt` is RE-EXPORTED from `@ziffer-io/verify`, unchanged. The runbook
+ *   rule this line implements: verification has ONE home, and the client
+ *   adds none of its own — a second verifier behind a client-shaped API
+ *   would be the two-definitions defect with a signature on it. The tests
+ *   assert the re-export is the SAME function object, so this cannot decay
+ *   into a copy silently.
+ */
+export { API_KEY_EXPIRES_HEADER, API_KEY_EXPIRY_WARNING_DAYS, ApiRefusal, ERROR_ADMISSION_UNAVAILABLE, ERROR_API_KEY_UNKNOWN, ERROR_DECISION_UNKNOWN, ERROR_PROPOSAL_MALFORMED, ERROR_TENANT_MISMATCH, ResponseMalformed, WaitTimeout, ZifferClient, type Decision, type DecisionStatus, type WaitOptions, type WireProposal, type WireProposalPayload, } from './client.js';
+export { Refusal, verifyReceipt, type TrustAnchor, type Verified, type VerifyOptions, } from '@ziffer-io/verify';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,UAAU,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AAOrB,OAAO,EACL,OAAO,EACP,aAAa,EACb,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @ziffer-io/client — the TypeScript SDK for the public decision API (ACP-197 §6).
+ *
+ * Two halves, one boundary:
+ *
+ * - `ZifferClient` (./client.js) carries proposals out and decisions back.
+ *   It computes no security value: the proposal goes as the caller wrote it,
+ *   the receipt comes back as the gateway stored it (RES-8 — a compromised
+ *   client writes the whole message, so nothing a client derives is
+ *   evidence).
+ * - `verifyReceipt` is RE-EXPORTED from `@ziffer-io/verify`, unchanged. The runbook
+ *   rule this line implements: verification has ONE home, and the client
+ *   adds none of its own — a second verifier behind a client-shaped API
+ *   would be the two-definitions defect with a signature on it. The tests
+ *   assert the re-export is the SAME function object, so this cannot decay
+ *   into a copy silently.
+ */
+export { API_KEY_EXPIRES_HEADER, API_KEY_EXPIRY_WARNING_DAYS, ApiRefusal, ERROR_ADMISSION_UNAVAILABLE, ERROR_API_KEY_UNKNOWN, ERROR_DECISION_UNKNOWN, ERROR_PROPOSAL_MALFORMED, ERROR_TENANT_MISMATCH, ResponseMalformed, WaitTimeout, ZifferClient, } from './client.js';
+// The verify surface a receipt-holding caller needs, and ONLY that: the
+// verifier itself, its refusal type, and the types its signature names.
+// The rest of @ziffer-io/verify (canon, the strict Ed25519 predicate, suite
+// algebra) stays importable from its own home — re-exporting internals here
+// would hand this package an API surface it does not implement.
+export { Refusal, verifyReceipt, } from '@ziffer-io/verify';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,sBAAsB,EACtB,2BAA2B,EAC3B,UAAU,EACV,2BAA2B,EAC3B,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,iBAAiB,EACjB,WAAW,EACX,YAAY,GAMb,MAAM,aAAa,CAAC;AAErB,wEAAwE;AACxE,wEAAwE;AACxE,4EAA4E;AAC5E,4EAA4E;AAC5E,gEAAgE;AAChE,OAAO,EACL,OAAO,EACP,aAAa,GAId,MAAM,mBAAmB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ziffer-io/client",
+  "version": "0.1.0",
+  "description": "The ZIFFER decision API client for TypeScript, with receipt verification re-exported from one home.",
+  "author": "code75 SASU",
+  "license": "SEE LICENSE IN LICENSE",
+  "comment-license": "The SDK is proprietary (code75 SASU). \"license\" is the SPDX escape hatch for exactly this case: there is no SPDX identifier for these terms, so the field points at the file that states them, and LICENSE ships in the tarball beside THIRD-PARTY-NOTICES. Do not put an OSI identifier here -- Apache-2.0 stood in these four files until ACP-214 and was wrong the whole time.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "THIRD-PARTY-NOTICES"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ziffer-hq/ziffer.git",
+    "directory": "packages/acp-client"
+  },
+  "homepage": "https://ziffer.io",
+  "publishConfig": {
+    "access": "public"
+  },
+  "comment-no-provenance": "There is deliberately no \"provenance\": true here, and it was removed rather than never added. npm generates a provenance attestation only from a recognised CI runner, and its documentation states plainly that provenance is NOT SUPPORTED for private repositories (docs.npmjs.com/trusted-publishers, read 2026-09-03) -- ziffer-hq/ziffer is private (`gh api` says so). Setting the flag does not degrade to a warning: npm attempts the attestation and the publish FAILS, so the field would have broken the operator's very first publish from a laptop and every CI publish after it. tools/release-npm.sh asserts the field stays absent, and that assertion is the thing to delete on the day this repository becomes public -- at which point trusted publishing generates provenance on its own, with no flag at all.",
+  "ziffer": {
+    "enginePin": "fed43d10b427e0a4435a8f04e474334d88a5aa6e"
+  },
+  "comment-enginePin": "The engine commit whose wire types this client speaks and whose verifier it re-exports. A COPY of the rev in Cargo.toml, which is the one authority tools/guard.sh reads; tools/release-npm.sh refuses to release when the two differ, by name. tools/bump-pin.sh does not move this field -- see packages/types/package.json for why and what closing it costs.",
+  "comment-deps": "Exactly two: @ziffer-io/types because the wire format is the one permitted shared definition (it IS the schemas, generated), and @ziffer-io/verify because verification has ONE home and this client re-exports it rather than growing a second (ACP-197 runbook section 6). No HTTP dependency: Node's own fetch carries two routes; a framework here is surface without a claim.",
+  "comment-types-was-a-git-dependency": "Until ACP-214 the first of those two was `git+https://ziffer-hq@github.com/ziffer-hq/agent-control-plane.git#<pin>&path:/packages/acp-types`. That is a private repository, so the published client would have been uninstallable rather than merely awkward; and pnpm runs `prepare` for a git dependency, so a consumer who could reach it would have compiled our wire types on their own machine. It is now a workspace dependency on packages/types, which `pnpm pack` rewrites to that package's exact published version -- measured, and asserted again by tools/release-npm.sh over every tarball.",
+  "dependencies": {
+    "@ziffer-io/verify": "0.1.0",
+    "@ziffer-io/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.2"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "pretest": "tsc -b && if ! find dist -name '*.test.js' -print -quit | grep -q .; then echo 'ACP-248: no compiled test file under dist/ -- node --test reports 0 tests and exits 0, so this package would go green having run nothing' >&2; exit 1; fi",
+    "test": "tsc -b && node --test \"dist/**/*.test.js\""
+  }
+}