gama-mandate 0.10.3__tar.gz

gama_mandate-0.10.3/AUTHORS

@@ -0,0 +1 @@
+GAMA

gama_mandate-0.10.3/CHANGELOG.md

@@ -0,0 +1,124 @@
+# Changelog
+
+## 0.10.3 — 2026-11-09
+- PyPI distribution name is **`gama-mandate`**. `agent-mandate` was rejected by
+  PyPI as too similar to an existing project (`agentmandate`). Import package and
+  console scripts are unchanged (`mandate`, `mandate-broker`, `mandate-mcp`).
+- Code identical to 0.10.2.
+
+## 0.10.2 — 2026-11-09
+- Published to GitHub: https://github.com/gamai-io/mandate (public, CI green on
+  Python 3.9–3.12). Release v0.10.1 with wheel, sdist, and checksums.
+- Correct project URLs, README CI/license badges, install-from-git instructions.
+
+## 0.10.1 — 2026-11-09
+- Security: the broker requires a bearer token for non-loopback binds
+  (`--token` / `MANDATE_BROKER_TOKEN`); broker and witness reject request bodies
+  over 256 KiB (413).
+- Lint: `ruff` config, clean `ruff check .`, CI lint + build/`twine check`.
+- Packaging: `py.typed`, sdist/README install instructions, governance files
+  (`SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `AUTHORS`,
+  `RELEASE.md`).
+- PyPI name `agent-mandate` verified available (2026-11-09).
+- 71 tests.
+
+## 0.10.0 — 2026-11-09
+- **Off-host STH witness**: pins the latest signed tree head, rejects rollback
+  (smaller tree), rejects split-view (same size, different root), and requires a
+  valid consistency proof for growth. State is written atomically (0600).
+- CLI: `mandate witness accept | verify | show | serve | push`.
+- Loopback HTTP witness with a bearer token (`/sth`, `/state`, `/health`);
+  `--allow-remote` required to bind elsewhere.
+- 8 witness tests + 68 total.
+
+## 0.9.0 — 2026-11-09
+- **Merkle transparency log** over ledger entries (RFC 6962/9162 style):
+  `Leaf=SHA256(0x00||JCS(entry))`, `Node=SHA256(0x01||L||R)`, MTH, inclusion
+  proofs, consistency proofs.
+- **Signed tree head** via `ssh-keygen -Y sign` in namespace `mandate-log`;
+  `log_id` is the log key SHA256 fingerprint.
+- CLI: `mandate log head | sth-verify | proof | verify-inclusion | consistency |
+  verify-consistency`.
+- Refuses to build a log over an invalid ledger hash chain.
+- 9 Merkle tests + 60 total. Off-host **witness/anchor** is still required to
+  rule out split-view; tracked in PLAN.md.
+
+## 0.8.0 — 2026-11-09
+- **Effect journal** (SQLite) with a lease-based state machine:
+  `intent → executing → executed → receipted`, plus `failed` / `abandoned`.
+- **Idempotent write adapter**: `mode=file` or `mode=sqlite` (a trusted SQL
+  statement runs in the same transaction as the idempotency insert). The
+  idempotency key is the **grant nonce**.
+- The authorisation receipt is now appended **after** the effect commits,
+  fixing the old "ledger says executed but no effect happened" crash window.
+- **Crash recovery on start**: `executing` with a committed effect → finish the
+  receipt; without an effect → abandoned; `executed` without a receipt →
+  receipted. Duplicate `execute` returns the same receipt/result instead of an
+  error.
+- Config: `write`, `journal_db`, `lease_s`; `/health` reports journal counts.
+- 43 tests (crash-after-effect recovery, crash-before-effect abandon, writer
+  failure, concurrent single effect, journal payload mismatch).
+
+## 0.7.0 — 2026-11-09
+- Canonicalization is now **RFC 8785 (JCS)**: UTF-16 code-unit key ordering,
+  ECMAScript number serialization, minimal string escaping, and strict rejection
+  of non-finite numbers, lone surrogates, non-string keys, and integers outside
+  the IEEE-754 safe range. Passes the RFC 8785 reference vector.
+- **Breaking:** commitment/receipt hashes change (e.g. `1170.0` serializes as
+  `1170`). Regenerate grants and ledgers from earlier versions.
+- CI: GitHub Actions test matrix on Python 3.9–3.12.
+
+## 0.6.0 — 2026-11-09
+- `allowed_signers` now requires an explicit `namespaces="mandate"` scope
+  (`namespaces="mandate-broker"` for broker result keys). A key without a scope
+  is rejected, so a grant key cannot sign broker receipts and vice versa.
+- Validity windows (`valid-after` / `valid-before`) are enforced in Mandate's
+  own check and by OpenSSH.
+- Key revocation: `mandate revoke --pub key.pub` writes the SHA256 fingerprint to
+  `trust/revoked_signers`; `redeem`, `verify`, and `verify-result` reject revoked
+  keys. Configurable via `--revoked` / `MANDATE_REVOKED`.
+- `mandate signers` lists parsed principals, namespaces, validity, and fingerprints.
+- 37 tests (namespace scope, validity window, revocation, revoke CLI).
+
+## 0.5.0 — 2026-11-09
+- Grant `audience`: a grant can be bound to one broker (`mandate grant --audience <broker>`).
+  The broker verifies `audience == broker_name` and rejects unbound grants by default
+  (`--allow-any-audience` to opt out). Closes cross-broker replay.
+- Broker-side re-derivation: `erp.derive` re-reads counterparty/amount/currency from the
+  source of truth and rejects the effect if the agent's intent diverges
+  (`derivation_mismatch`), not just at the precondition amount check.
+- 33 tests (audience mismatch, unbound grant, currency derivation mismatch).
+
+## 0.4.0 — 2026-11-09
+Security fixes from an independent multi-agent audit (Claude + subagent + web):
+- `mandate grant` recomputes commitment/render_hash/proposal_id from the intent and rejects a mismatched proposal (approval-confusion fix).
+- `redeem` enforces policy (unknown effects denied) and binds the grant to the agent (`agent` field), closing the actor-swap self-approval bypass.
+- CLI/MCP redeem now performs the nonce check and append under one file lock; ledger append is fsync'd and anchored with `<ledger>.head`; `verify_chain` rejects empty or truncated ledgers.
+- Intent schema validation: unknown effect/amount fields and non-finite amounts are rejected; `params` must be flat scalars.
+- `render` quotes every value (no `|` injection) and includes all params.
+- ERP: NaN/non-dict amounts rejected; only `bind_params` can fill query placeholders.
+- `execute` refuses non-loopback brokers (unless `--allow-remote`) and does not follow redirects.
+- MCP adapter moved into the package and shipped as `mandate-mcp`; `verify-result` validates the signed broker result entry.
+- `doctor` fails when signers are missing; `max_uses` is honestly fixed at 1.
+
+## 0.3.0 — 2026-11-09
+- Read-only ERP precondition (SQLite `mode=ro`, named-param query, amount tolerance).
+- SMTP adapter for `message.send` (`dry_run` default, `live` reads password from env).
+- Broker `--config`, `/health` reports `smtp` and `erp`.
+- Preconditions run before the nonce claim, so a failed check does not consume the grant.
+- Packaging: `pyproject.toml`, console scripts `mandate` / `mandate-broker`,
+  `mandate init`, `mandate doctor`, `mandate version`.
+
+## 0.2.0 — 2026-11-09
+- Effect broker: `/execute` + `/health`, loopback by default.
+- Atomic nonce claim (SQLite `UNIQUE`) prevents double execution.
+- `render_hash` bound into commitment and grant (approver signs the rendered summary).
+- Signed result entry chained after the authorisation receipt.
+
+## 0.1.0 — 2026-11-09
+- Canonical commitment (JCS), stable ids.
+- Intent / Grant / Receipt objects.
+- Off-host Ed25519 grant via `ssh-keygen -Y sign`.
+- One-shot redeem, replay detection, hash-chained ledger, offline verification.
+- Agent cannot self-approve; unknown effects denied.
+- MCP adapter and agent skill.

gama_mandate-0.10.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GAMA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gama_mandate-0.10.3/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md
+include PLAN.md
+include LICENSE
+include CHANGELOG.md
+include policy.json
+recursive-include spec *.md
+recursive-include docs *.md
+recursive-include skills *.md
+recursive-include examples *.json
+recursive-include trust *
+recursive-include mandate/data *.json

gama_mandate-0.10.3/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: gama-mandate
+Version: 0.10.3
+Summary: Signed, verifiable business commitments for AI agents: canonical commitment, off-host Ed25519 grant, one-shot redemption, hash-chained receipts.
+Author: GAMA
+License: MIT
+Project-URL: Homepage, https://github.com/gamai-io/mandate
+Project-URL: Repository, https://github.com/gamai-io/mandate
+Project-URL: Issues, https://github.com/gamai-io/mandate/issues
+Project-URL: Changelog, https://github.com/gamai-io/mandate/blob/main/CHANGELOG.md
+Keywords: ai-agents,trust,approval,commitment,ed25519,audit
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS
+Dynamic: license-file
+
+# Mandate
+
+[![tests](https://github.com/gamai-io/mandate/actions/workflows/test.yml/badge.svg)](https://github.com/gamai-io/mandate/actions/workflows/test.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Signed, verifiable business commitments for AI agents.**
+
+Most agent safety tools answer *"is this tool allowed?"*. Mandate answers the
+question that actually matters: **"who ordered this exact payment, to this
+supplier, for this amount?"** A tool permission is not a business mandate.
+
+Every consequential effect becomes a canonical **Commitment** object. An agent
+signs the intent; a human co-signs a **Grant** with an Ed25519 key; execution
+produces a hash-chained **Receipt**. Anyone can verify the whole chain offline.
+
+> Approval workflows are ephemeral events. A Mandate is a durable, portable,
+> cryptographically bound artifact — a commit, not a log line.
+
+## Why it is not another approval gate
+
+| Approval gate | Mandate |
+|---|---|
+| Asks "may this tool run?" | Asks "is this exact effect authorised?" |
+| Identity is a self-asserted field | Approver proves possession of an off-host key |
+| Approval is a mutable DB row | Grant + receipt are signed, content-addressed |
+| Logs what happened | Lets anyone prove what was authorised |
+
+## Install
+
+CLI + broker + MCP adapter. There is **no web UI** by design: Mandate is a
+local trust primitive you embed in your own stack.
+
+```bash
+python3 -m pip install gama-mandate
+# or from source / git
+python3 -m pip install "git+https://github.com/gamai-io/mandate.git"
+
+mandate doctor                      # checks python, ssh-keygen, policy
+mandate init --dir ./my-deployment  # policy, allowed_signers, config, example
+```
+
+## Quickstart
+
+```bash
+export PYTHONPATH=$PWD
+
+# 1. on the approver's device (never on the agent host)
+ssh-keygen -t ed25519 -f ~/.ssh/mandate -C mandate
+# append the PUBLIC key to trust/allowed_signers as: renato ssh-ed25519 AAAA... mandate
+
+# 2. agent proposes
+./bin/mandate propose --intent examples/intent.json --out /tmp/proposal.json
+
+# 3. human grants (signs the commitment, bound to one broker + the agent)
+./bin/mandate grant --proposal /tmp/proposal.json --approver renato \
+  --key ~/.ssh/mandate --audience local-broker --out /tmp/grant.json
+
+# 4. agent redeems exactly once
+./bin/mandate redeem --intent examples/intent.json --grant /tmp/grant.json \
+  --ledger ledger.jsonl
+
+# 5. or let the effect broker execute it (credentials stay in the broker)
+./bin/mandate-broker --port 8899 --signers trust/allowed_signers \
+  --ledger ledger.jsonl --nonce-db broker/used.sqlite &
+./bin/mandate execute --broker http://127.0.0.1:8899 \
+  --intent examples/intent.json --grant /tmp/grant.json
+
+# 5. anyone verifies offline
+./bin/mandate verify --receipt ... --intent examples/intent.json --grant /tmp/grant.json
+./bin/mandate verify-result --entry /tmp/result.json --broker-signers trust/broker_signers
+./bin/mandate chain --ledger ledger.jsonl
+```
+
+Exit codes for `check`: `0` allow · `10` ask (grant required) · `20` deny.
+
+## Effect broker (Phase 2)
+
+`bin/mandate-broker` is the only component that executes effects. It verifies
+the grant, **atomically claims the nonce** (SQLite `UNIQUE`, so two concurrent
+requests cannot both succeed), runs the effect handler, and appends a signed
+result entry to the hash-chained ledger. The agent calls it over loopback; the
+agent never holds the effect credentials.
+
+The shipped handlers are a sandbox (they record the effect under `effects/` or
+`outbox/`). Wiring real credentials (SQL write, SMTP, payment) is Phase 2
+completion — see `PLAN.md`.
+
+### Adapters
+
+**ERP precondition (read-only).** Before a grant is consumed, the broker runs a
+named-parameter SQLite query against master data. No row → `counterparty_not_found`;
+amount outside `tolerance_pct` → `amount_mismatch`. The grant is **not**
+consumed when a precondition fails, so a corrected request can retry safely.
+
+**SMTP (`message.send`).** `mode=dry_run` writes an `.eml` to the outbox;
+`mode=live` sends via SMTP. The password is read from the env var named in
+`password_env` and never logged or returned.
+
+```json
+"erp": {"db": "erp.sqlite", "checks": {"payment.send": {
+  "query": "SELECT invoice_total FROM vendors WHERE name = :target",
+  "amount_field": "invoice_total", "tolerance_pct": 0.5}}},
+"smtp": {"mode": "dry_run", "host": "", "user": "",
+         "password_env": "MANDATE_SMTP_PASSWORD", "from": "noreply@gama.local"}
+```
+
+## Key scoping and revocation
+
+An `allowed_signers` line **must** declare its namespace scope:
+
+```
+renato namespaces="mandate" ssh-ed25519 AAAAC3Nza... mandate
+gama-broker namespaces="mandate-broker" ssh-ed25519 AAAAC3Nza... broker
+```
+
+Optional validity: `valid-after="YYYYMMDD" valid-before="YYYYMMDD"`.
+Revoke a key by fingerprint:
+
+```bash
+mandate revoke --pub key.pub --reason "laptop lost"
+mandate --signers trust/allowed_signers signers   # inspect scopes + fingerprints
+```
+
+### Idempotent writes and recovery
+
+The broker keeps a SQLite **effect journal** (`journal_db`). The flow is
+`intent → executing → executed → receipted`; the authorisation receipt is
+written only **after** the effect commits. On startup the broker recovers:
+a committed effect without a receipt gets one; a claimed grant with no effect is
+abandoned; a duplicate `execute` returns the original receipt and result.
+
+`write.mode=sqlite` runs a trusted configured statement together with an
+idempotency insert in **one transaction**, keyed by the grant nonce:
+
+```json
+"write": {"mode": "sqlite", "db": "erp.sqlite",
+          "statement": "INSERT INTO payments(nonce,vendor,amount) VALUES(:nonce,:target,:amount)"}
+```
+
+## Transparency log
+
+Every ledger entry is a leaf in an RFC 6962/9162-style Merkle tree
+(`Leaf=SHA256(0x00||JCS(entry))`, `Node=SHA256(0x01||L||R)`). A signed tree
+head (STH) fixes the root and size; inclusion and consistency proofs verify
+offline:
+
+```bash
+mandate log head  --ledger ledger.jsonl --log-name log1 --log-key ~/.ssh/mandate-log --out sth.json
+mandate --signers trust/allowed_signers log sth-verify --sth sth.json
+mandate log proof --ledger ledger.jsonl --index 3 --out proof.json
+mandate log verify-inclusion --entry entry.json --proof proof.json --sth sth.json
+mandate log consistency --ledger ledger.jsonl --first 2 --second 3 --out cons.json
+mandate log verify-consistency --old old_sth.json --new sth.json --proof cons.json
+```
+
+A single log cannot prevent **split-view** by its operator; pin the STH on a
+second machine (witness/anchor). The STH signer needs
+`namespaces="mandate-log"` in `allowed_signers`.
+
+### Off-host witness
+
+```bash
+# on the second machine
+mandate --signers log_signers witness serve --state witness.json \
+  --token "$WITNESS_TOKEN" --port 8898
+
+# on the log host
+mandate witness push --url http://witness:8898 --sth sth.json --token "$WITNESS_TOKEN"
+mandate witness push --url http://witness:8898 --sth sth_new.json --proof cons.json --token "$WITNESS_TOKEN"
+mandate witness show --state witness.json
+```
+
+The witness pins the latest STH and rejects rollback or a same-size different
+root (split-view). Growth requires a consistency proof from the pinned root.
+`witness verify` checks without pinning; `witness accept` pins locally.
+
+## Design invariants
+
+1. **Effect, not tool.** The registry keys on `payment.send`, not on
+   `gama_sql`. The same effect is the same commitment regardless of executor.
+2. **Canonical bytes.** **RFC 8785 (JCS)** canonical JSON; the commitment is the
+   hash of `{v, effect, requested_by, render_hash}`. Same content ⇒ same id, in
+   any RFC 8785 implementation.
+3. **Off-host key.** The approver's private key never lives where the agent
+   runs. The host stores only public keys (`trust/allowed_signers`).
+4. **One-shot, nonce-bound.** A grant is redeemable once; replays fail.
+5. **Agent cannot self-approve.** Enforced in code, not by convention.
+6. **Fail closed.** Unknown effects are denied. Missing signer ⇒ invalid.
+
+## Layout
+
+```
+spec/       MANDATE-1 data model
+mandate/    stdlib-only reference implementation
+bin/        CLI
+adapters/   MCP server
+tests/      unit + bypass tests (red-team)
+docs/       THREAT_MODEL, NON_GOALS, PLAN
+skills/     agent skill instructions
+```
+
+## Status
+
+**Alpha** — reference implementation v0.10.1: canonical commitment, Ed25519 grant
+bound to the executing agent, one-shot redeem under a file lock, hash-chained
+receipts with a `.head` anchor, idempotent effect journal + write adapter,
+effect broker with signed result entries, read-only ERP preconditions, SMTP
+adapter, Merkle transparency log with an off-host witness, MCP server
+(`mandate-mcp`), and a red-team test suite. See `PLAN.md` for the roadmap and
+`docs/THREAT_MODEL.md` for the known limits.
+
+## Honest limitation
+
+Cryptography proves *who authorised what*. It does **not** isolate
+credentials. Until the credentials that cause the effect (SQL write, payment
+API, mail) live only in an effect broker, a compromised agent can bypass
+Mandate entirely. That broker is the next milestone — see `PLAN.md`.

gama_mandate-0.10.3/PLAN.md

@@ -0,0 +1,41 @@
+# Plan
+
+## Phase 1 — Core (done, v0.1)
+- [x] Canonical commitment (JCS), stable ids
+- [x] Intent / Grant / Receipt objects
+- [x] Ed25519 grant signing via OpenSSH (`ssh-keygen -Y sign`)
+- [x] One-shot redeem with nonce, replay detection
+- [x] Hash-chained ledger + offline verification
+- [x] Agent cannot self-approve
+- [x] Fail-closed policy (unknown effect = deny)
+- [x] Bypass tests: tamper, replay, wrong signer, expiry, self-approval
+
+## Phase 2 — Effect broker (core done, v0.2)
+- [x] Broker is the only executor; agent never runs the effect itself
+- [x] HTTP `/execute` + `/health`, loopback-only by default
+- [x] Atomic nonce claim (SQLite UNIQUE) → no double execution under concurrency
+- [x] `render_hash`: the human signs the rendered summary, bound into the commitment
+- [x] Signed result entry chained after the authorisation receipt
+- [x] Read-only ERP precondition (SQLite, fail-closed target + amount check)
+- [x] SMTP adapter (`dry_run` default; `live` reads password from env)
+- [ ] Move write credentials (SQL write, payment, WA) into the broker
+- [ ] Per-effect adapters + integration tests against a fake ERP
+
+## Phase 3 — Transparency + interop
+- [x] Merkle transparency log (RFC 6962/9162 style) with inclusion + consistency proofs
+- [x] Signed tree head via Ed25519 (`mandate-log` namespace)
+- [x] Off-host witness/anchor for the STH (rules out split-view)
+- [ ] Export receipt as JWS / C2PA-style manifest
+- [ ] OIDC/WebAuthn co-sign (passkeys) alongside Ed25519
+- [ ] Provenance enforcement: `data_ref` required for every choice parameter
+
+## Phase 4 — Ecosystem
+- [ ] MCP server packaged for Claude Code / opencode / Cursor
+- [ ] Shell shim + GitHub Action for CI bypass tests
+- [ ] Policy packs per domain (trade, finance, ops)
+- [ ] `mandate audit` diff of policy and trust-root changes
+
+## Definition of done for v1.0
+An agent with no credentials to the target system cannot cause a consequential
+effect without a valid, single-use, human-signed grant, and an auditor can prove
+that offline.

gama_mandate-0.10.3/README.md

@@ -0,0 +1,217 @@
+# Mandate
+
+[![tests](https://github.com/gamai-io/mandate/actions/workflows/test.yml/badge.svg)](https://github.com/gamai-io/mandate/actions/workflows/test.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**Signed, verifiable business commitments for AI agents.**
+
+Most agent safety tools answer *"is this tool allowed?"*. Mandate answers the
+question that actually matters: **"who ordered this exact payment, to this
+supplier, for this amount?"** A tool permission is not a business mandate.
+
+Every consequential effect becomes a canonical **Commitment** object. An agent
+signs the intent; a human co-signs a **Grant** with an Ed25519 key; execution
+produces a hash-chained **Receipt**. Anyone can verify the whole chain offline.
+
+> Approval workflows are ephemeral events. A Mandate is a durable, portable,
+> cryptographically bound artifact — a commit, not a log line.
+
+## Why it is not another approval gate
+
+| Approval gate | Mandate |
+|---|---|
+| Asks "may this tool run?" | Asks "is this exact effect authorised?" |
+| Identity is a self-asserted field | Approver proves possession of an off-host key |
+| Approval is a mutable DB row | Grant + receipt are signed, content-addressed |
+| Logs what happened | Lets anyone prove what was authorised |
+
+## Install
+
+CLI + broker + MCP adapter. There is **no web UI** by design: Mandate is a
+local trust primitive you embed in your own stack.
+
+```bash
+python3 -m pip install gama-mandate
+# or from source / git
+python3 -m pip install "git+https://github.com/gamai-io/mandate.git"
+
+mandate doctor                      # checks python, ssh-keygen, policy
+mandate init --dir ./my-deployment  # policy, allowed_signers, config, example
+```
+
+## Quickstart
+
+```bash
+export PYTHONPATH=$PWD
+
+# 1. on the approver's device (never on the agent host)
+ssh-keygen -t ed25519 -f ~/.ssh/mandate -C mandate
+# append the PUBLIC key to trust/allowed_signers as: renato ssh-ed25519 AAAA... mandate
+
+# 2. agent proposes
+./bin/mandate propose --intent examples/intent.json --out /tmp/proposal.json
+
+# 3. human grants (signs the commitment, bound to one broker + the agent)
+./bin/mandate grant --proposal /tmp/proposal.json --approver renato \
+  --key ~/.ssh/mandate --audience local-broker --out /tmp/grant.json
+
+# 4. agent redeems exactly once
+./bin/mandate redeem --intent examples/intent.json --grant /tmp/grant.json \
+  --ledger ledger.jsonl
+
+# 5. or let the effect broker execute it (credentials stay in the broker)
+./bin/mandate-broker --port 8899 --signers trust/allowed_signers \
+  --ledger ledger.jsonl --nonce-db broker/used.sqlite &
+./bin/mandate execute --broker http://127.0.0.1:8899 \
+  --intent examples/intent.json --grant /tmp/grant.json
+
+# 5. anyone verifies offline
+./bin/mandate verify --receipt ... --intent examples/intent.json --grant /tmp/grant.json
+./bin/mandate verify-result --entry /tmp/result.json --broker-signers trust/broker_signers
+./bin/mandate chain --ledger ledger.jsonl
+```
+
+Exit codes for `check`: `0` allow · `10` ask (grant required) · `20` deny.
+
+## Effect broker (Phase 2)
+
+`bin/mandate-broker` is the only component that executes effects. It verifies
+the grant, **atomically claims the nonce** (SQLite `UNIQUE`, so two concurrent
+requests cannot both succeed), runs the effect handler, and appends a signed
+result entry to the hash-chained ledger. The agent calls it over loopback; the
+agent never holds the effect credentials.
+
+The shipped handlers are a sandbox (they record the effect under `effects/` or
+`outbox/`). Wiring real credentials (SQL write, SMTP, payment) is Phase 2
+completion — see `PLAN.md`.
+
+### Adapters
+
+**ERP precondition (read-only).** Before a grant is consumed, the broker runs a
+named-parameter SQLite query against master data. No row → `counterparty_not_found`;
+amount outside `tolerance_pct` → `amount_mismatch`. The grant is **not**
+consumed when a precondition fails, so a corrected request can retry safely.
+
+**SMTP (`message.send`).** `mode=dry_run` writes an `.eml` to the outbox;
+`mode=live` sends via SMTP. The password is read from the env var named in
+`password_env` and never logged or returned.
+
+```json
+"erp": {"db": "erp.sqlite", "checks": {"payment.send": {
+  "query": "SELECT invoice_total FROM vendors WHERE name = :target",
+  "amount_field": "invoice_total", "tolerance_pct": 0.5}}},
+"smtp": {"mode": "dry_run", "host": "", "user": "",
+         "password_env": "MANDATE_SMTP_PASSWORD", "from": "noreply@gama.local"}
+```
+
+## Key scoping and revocation
+
+An `allowed_signers` line **must** declare its namespace scope:
+
+```
+renato namespaces="mandate" ssh-ed25519 AAAAC3Nza... mandate
+gama-broker namespaces="mandate-broker" ssh-ed25519 AAAAC3Nza... broker
+```
+
+Optional validity: `valid-after="YYYYMMDD" valid-before="YYYYMMDD"`.
+Revoke a key by fingerprint:
+
+```bash
+mandate revoke --pub key.pub --reason "laptop lost"
+mandate --signers trust/allowed_signers signers   # inspect scopes + fingerprints
+```
+
+### Idempotent writes and recovery
+
+The broker keeps a SQLite **effect journal** (`journal_db`). The flow is
+`intent → executing → executed → receipted`; the authorisation receipt is
+written only **after** the effect commits. On startup the broker recovers:
+a committed effect without a receipt gets one; a claimed grant with no effect is
+abandoned; a duplicate `execute` returns the original receipt and result.
+
+`write.mode=sqlite` runs a trusted configured statement together with an
+idempotency insert in **one transaction**, keyed by the grant nonce:
+
+```json
+"write": {"mode": "sqlite", "db": "erp.sqlite",
+          "statement": "INSERT INTO payments(nonce,vendor,amount) VALUES(:nonce,:target,:amount)"}
+```
+
+## Transparency log
+
+Every ledger entry is a leaf in an RFC 6962/9162-style Merkle tree
+(`Leaf=SHA256(0x00||JCS(entry))`, `Node=SHA256(0x01||L||R)`). A signed tree
+head (STH) fixes the root and size; inclusion and consistency proofs verify
+offline:
+
+```bash
+mandate log head  --ledger ledger.jsonl --log-name log1 --log-key ~/.ssh/mandate-log --out sth.json
+mandate --signers trust/allowed_signers log sth-verify --sth sth.json
+mandate log proof --ledger ledger.jsonl --index 3 --out proof.json
+mandate log verify-inclusion --entry entry.json --proof proof.json --sth sth.json
+mandate log consistency --ledger ledger.jsonl --first 2 --second 3 --out cons.json
+mandate log verify-consistency --old old_sth.json --new sth.json --proof cons.json
+```
+
+A single log cannot prevent **split-view** by its operator; pin the STH on a
+second machine (witness/anchor). The STH signer needs
+`namespaces="mandate-log"` in `allowed_signers`.
+
+### Off-host witness
+
+```bash
+# on the second machine
+mandate --signers log_signers witness serve --state witness.json \
+  --token "$WITNESS_TOKEN" --port 8898
+
+# on the log host
+mandate witness push --url http://witness:8898 --sth sth.json --token "$WITNESS_TOKEN"
+mandate witness push --url http://witness:8898 --sth sth_new.json --proof cons.json --token "$WITNESS_TOKEN"
+mandate witness show --state witness.json
+```
+
+The witness pins the latest STH and rejects rollback or a same-size different
+root (split-view). Growth requires a consistency proof from the pinned root.
+`witness verify` checks without pinning; `witness accept` pins locally.
+
+## Design invariants
+
+1. **Effect, not tool.** The registry keys on `payment.send`, not on
+   `gama_sql`. The same effect is the same commitment regardless of executor.
+2. **Canonical bytes.** **RFC 8785 (JCS)** canonical JSON; the commitment is the
+   hash of `{v, effect, requested_by, render_hash}`. Same content ⇒ same id, in
+   any RFC 8785 implementation.
+3. **Off-host key.** The approver's private key never lives where the agent
+   runs. The host stores only public keys (`trust/allowed_signers`).
+4. **One-shot, nonce-bound.** A grant is redeemable once; replays fail.
+5. **Agent cannot self-approve.** Enforced in code, not by convention.
+6. **Fail closed.** Unknown effects are denied. Missing signer ⇒ invalid.
+
+## Layout
+
+```
+spec/       MANDATE-1 data model
+mandate/    stdlib-only reference implementation
+bin/        CLI
+adapters/   MCP server
+tests/      unit + bypass tests (red-team)
+docs/       THREAT_MODEL, NON_GOALS, PLAN
+skills/     agent skill instructions
+```
+
+## Status
+
+**Alpha** — reference implementation v0.10.1: canonical commitment, Ed25519 grant
+bound to the executing agent, one-shot redeem under a file lock, hash-chained
+receipts with a `.head` anchor, idempotent effect journal + write adapter,
+effect broker with signed result entries, read-only ERP preconditions, SMTP
+adapter, Merkle transparency log with an off-host witness, MCP server
+(`mandate-mcp`), and a red-team test suite. See `PLAN.md` for the roadmap and
+`docs/THREAT_MODEL.md` for the known limits.
+
+## Honest limitation
+
+Cryptography proves *who authorised what*. It does **not** isolate
+credentials. Until the credentials that cause the effect (SQL write, payment
+API, mail) live only in an effect broker, a compromised agent can bypass
+Mandate entirely. That broker is the next milestone — see `PLAN.md`.

gama_mandate-0.10.3/docs/NON_GOALS.md

@@ -0,0 +1,11 @@
+# Non-goals
+
+- **Not a sandbox.** Mandate does not isolate code execution.
+- **Not an observability platform.** It emits receipts; shipping them to a
+  SIEM is someone else's job.
+- **Not a model.** No LLM is called anywhere in the decision path.
+- **Not a payment processor.** It authorises effects; it does not move money.
+- **Not a replacement for legal contracts.** A signed grant proves authorisation,
+  not legal validity.
+- **Not zero-config in production.** A trust root (public keys) and a policy
+  must be provisioned deliberately.