@ziffer-io/mcp 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,136 @@
+# `@ziffer-io/mcp`
+
+A local MCP server, over stdio, so a coding agent can integrate the ZIFFER SDK against our real
+documentation and drive a live decision loop while testing.
+
+```bash
+npx @ziffer-io/mcp
+```
+
+## What it is, and the boundary that matters
+
+**This server has no hands on your machine.** It serves knowledge and ZIFFER-side calls. It
+writes no files, runs no commands, and starts no processes. Your coding agent is the thing that
+edits your code; this is a source it can ask.
+
+That boundary is also the honest limit of what it does for your security posture:
+
+> **MCP alone routes the question; only the SDK's `verify` line enforces the answer.**
+
+An agent that has talked to this server has not thereby been gated by anything. It runs on a
+developer's machine at development time and is nowhere near your production path. What gates an
+action is the `verify` call that ends up in your handler — `docs/onboarding/sdk.md` section 6
+says so at length, and that document is what `get_integration_guide` serves.
+
+## The five tools
+
+| tool | what it does | needs |
+| --- | --- | --- |
+| `get_integration_guide` | returns `docs/onboarding/sdk.md` for `python` or `typescript` | nothing |
+| `propose` | submits one wire Proposal, returns the gateway response verbatim | `ZIFFER_API_URL`, `ZIFFER_API_KEY` |
+| `check_decision` | one decision by id, receipt included when present | `ZIFFER_API_URL`, `ZIFFER_API_KEY` |
+| `explain_receipt` | verifies a receipt, reports `valid: bound to <hash>` or the named clause | `ZIFFER_TRUST_ANCHOR`, `ZIFFER_SUITE_FLOOR` |
+| `sandbox_status` | whether a tenant id is a sandbox, and whether one decision still waits on its robot approver | nothing, or `ZIFFER_API_URL`+`ZIFFER_API_KEY` with a `decision_id` |
+
+`explain_receipt` takes the proposal as **base64 of the bytes your code passes to `verify`**,
+not as a JSON object, because `verify` takes bytes and this tool exists to reproduce your call.
+Accepting an object would insert an encoding step your production path does not have, and would
+hide one real failure outright: bytes that are not UTF-8 JSON at all — a truncated read, a
+double-encoded string — which the verifier refuses under `AT-8a`.
+
+**Key order and whitespace are not the issue**, and it is worth saying because the opposite reads
+so plausibly that an earlier draft of this package asserted it. The verifier parses your bytes and
+canonicalises them itself, so `JSON.stringify`, `json.dumps` and a pretty-printed copy of one
+object all verify identically. A `9.3-3` means a genuinely different proposal, and the tool's hint
+says so.
+
+There is **no approve tool and no simulated approval**, and there will not be one added quietly.
+An approval minted on a laptop is a fake receipt factory, which is the exact artifact this product
+exists to make impossible.
+
+`sandbox_status` is not an exception to that, and the reason is the design rather than a
+concession. Until ACP-213 this file said a sandbox mode was "a separate ticket with its own
+design"; that ticket landed, and the design is: **a ZIFFER sandbox is a separate tenant** with its
+own receipt signing identity, approved by a robot service inside the deployment holding keys this
+machine never sees. So a sandbox receipt is signed by a different key and fails production
+verification (`9.3-1`) by construction. There is a truthful thing for a client to report, and
+still nothing for it to approve — `sandbox_status` reads a name and asks the API about one
+decision, verifies nothing, and says so in its own output. `docs/onboarding/sandbox.md` states
+what the marker guarantees and what it does not.
+
+## Configuration
+
+| variable | what it is |
+| --- | --- |
+| `ZIFFER_API_URL` | the gateway base URL. `https://`, or `http://` on loopback only — the key is a bearer credential |
+| `ZIFFER_API_KEY` | your API key. **It determines the tenant**; nothing here sends a tenant name |
+| `ZIFFER_TRUST_ANCHOR` | path to an `acp-bundle pubkey --key <keyfile> --out anchor.json` document |
+| `ZIFFER_SUITE_FLOOR` | the CR-4 signature suite floor. No default, deliberately |
+
+**The server starts without any of them**, which inverts the rule every other process in this
+repository follows. The reason is in `src/config.ts`: a stdio server that exits during the
+handshake tells the agent only that the server failed to start, and the name of the missing
+variable dies on a stderr nobody is reading. So each tool refuses on its own, by name, telling
+the agent exactly which variable to set. `get_integration_guide` needs nothing at all, so an
+agent can read how to integrate before any credential exists.
+
+Nothing is defaulted. An unconfigured `propose` sends no request; an unconfigured
+`explain_receipt` verifies nothing. The refusal moved from process exit to tool result; it did
+not become a fallback.
+
+## What does not work yet
+
+1. **`npx @ziffer-io/mcp` does not resolve, because nothing is published yet — but the reason it
+   *could not have been* published is now fixed (ACP-214).** Until this change the blocker was
+   structural: this package depended on `@acp/client` and `@acp/verify`, which were unpublished
+   workspace packages, and `@acp/client` in turn declared the engine's `@acp/types` as a `git+`
+   dependency on a repository that is **private** — so a developer who ran `npx` would have got a
+   command that installs and then cannot start, or cannot install at all. That is closed. There
+   are four packages now (`@ziffer-io/types`, `@ziffer-io/verify`, `@ziffer-io/client` and this
+   one), each publishing compiled `dist/` with no git dependency and nothing for a consumer to
+   build, and `tools/release-npm.sh` packs and checks all four in dependency order.
+
+   **What remains is the act, and it is the operator's.** The release script prints the four
+   `npm publish` lines and the tag line and never runs them; nothing reaches the registry until a
+   person pastes them. So this item stays in this section: today `npx @ziffer-io/mcp` still
+   resolves to nothing, and it will keep saying so here until the first publication has actually
+   happened rather than merely become possible. Note also that the first publish of each package
+   must be that manual one — npm cannot register a trusted publisher for a package that does not
+   exist yet, so CI takes over only from the second release.
+
+2. **All five tools ran against a live gateway on 2026-09-03; what is still untried is a
+   *deployed* one.** Until that day this item read, in these words, "`propose` and
+   `check_decision` have never been run against a live gateway [...] treat the two as
+   wired-and-untried rather than proven", and `tools/rehearse/03-loop.sh` exists to end it (the
+   transcript is `tools/rehearsal-2026-09-03.json`, `rehearsal GREEN: 4 of 4 steps`). That
+   step drives this server over a spawned stdio transport against `services/gateway` in a
+   container, over the composed configuration tree of a real sandbox tenant: `propose` returned
+   the gateway's answer verbatim, `check_decision` was polled until the receipt attached,
+   `explain_receipt` reported that receipt valid and refused one bound to a different proposal at
+   `9.3-3`, and `sandbox_status` and `get_integration_guide` answered beside them. What that run
+   did **not** cover is a deployed control plane rather than a local compose stack — and it was
+   driven by a script, which is item 3. It is evidence about that tree on that day and nothing
+   later; `tools/rehearse.sh` records each rehearsal as `tools/rehearsal-<date>.json`.
+
+3. **Nothing here has been exercised by a real coding agent.** The tool descriptions are written
+   for a model to act on, and whether a model reads them the way they were meant is a question
+   about models, not about this code. No test can answer it, and none here claims to.
+
+## Development
+
+```bash
+pnpm --filter @ziffer-io/mcp test    # embed the guide, build, run node --test
+```
+
+The build copies `docs/onboarding/sdk.md` into `src/generated/` (gitignored) so the published
+server carries the guide it serves. `src/guide.test.ts` reads that document from the repository
+and asserts the served text matches it, so an edit to the doc without a rebuild fails the suite
+rather than shipping a stale answer.
+
+## 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.