Metadata-Version: 2.4
Name: swarrm
Version: 1.1.1
Summary: Swarrm — signed receipts, a transparency log, and local verification of captured AI-agent evidence
Author-email: Maximilian Carl Friede <proof@swarrm.ai>
License-Expression: LicenseRef-Swarrm-Proprietary AND Apache-2.0
Project-URL: Homepage, https://swarrm.ai
Project-URL: Verify, https://swarrm.ai/verify
Project-URL: Open verifier & specs, https://github.com/capxholding/swarrm-verify
Keywords: ai-agents,audit,evidence,transparency-log,tamper-evident,verification
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-APACHE-2.0.txt
Requires-Dist: cryptography>=42
Requires-Dist: uvicorn>=0.29
Requires-Dist: rfc8785>=0.1
Requires-Dist: httpx>=0.27
Requires-Dist: fastapi>=0.110
Requires-Dist: web3<8,>=7.16
Requires-Dist: asn1crypto>=1.5
Requires-Dist: cbor2==6.1.4
Requires-Dist: jinja2>=3.1
Requires-Dist: python-multipart>=0.0.9
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: anyio>=4; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15; extra == "dev"
Requires-Dist: detect-secrets>=1.5; extra == "dev"
Requires-Dist: lizard==1.23.0; extra == "dev"
Requires-Dist: pathspec==1.1.1; extra == "dev"
Dynamic: license-file

# Swarrm

**Signed receipts, a tamper-evident log, and locally verifiable assurance for AI agents.**

Each supported action captured through an enabled integration — a model call, a
tool run, a refund, a payment — becomes a **signed receipt** in an append-only,
**tamper-evident** log (RFC 6962 Merkle tree, Ed25519 / DSSE). A bounded selected
set of receipts exports as a **self-contained evidence bundle** that anyone you
share it with can verify **offline** — no account or live Swarrm service. Swarrm
fails an export explicitly instead of returning a partial bundle when its
mandatory state closure or response bounds cannot be met. Long-running logs use
an explicit sparse checkpoint-proof profile: it validates the complete stored
hash chain, then carries genesis, head and the earliest carried timing proof for
each exported entry. It does not claim that omitted intermediate checkpoint
history travelled in that bundle. Self-hosted capture keeps payloads in your environment;
hosted capture necessarily handles them in transit. The evidence log stores
commitments and operational metadata, not model or business payloads.

Ordinary application logs are editable, so they are testimony, not evidence.
These records are verifiable: flip a single byte and the bundle fails.

## Status

**Launched as `1.1.1`. Offline verification earns at most base E1 integrity.
The explicit live, relying-party-rooted profile can earn cumulative E2/E3.
Counterparty Assurance v1 is CWT/COSE-only; favourable `PASS` is not enabled.**

What is genuinely proven, offline, today — this part is the product's foundation
and it holds up: signed receipts, canonical (RFC 8785) encoding, RFC 6962 Merkle
inclusion and consistency, checkpoint and key-log validation, hostile-input
limits, and base evidence-bundle verification — implemented in two distinct
code paths (Python here, Rust in the open
[swarrm-verify](https://github.com/capxholding/swarrm-verify) repo) and pinned by
a shared adversarial fixture suite. **Flip one byte and the bundle fails.**

What was **withdrawn** after an internal audit on 2026-08-03 remains withdrawn:
the old routes could derive favourable labels from a subject's own declarations.
The later B29 profile did not restore those routes; it introduced stricter,
explicitly live checks rooted in material the relying party supplies:

- the **`Swarrm Verified` mark** — it read declaration-derived inputs, so a
  subject could award it to itself; it now renders `UNMARKED_ASSURANCE_WITHDRAWN`;
- the old **E2/E3 assurance badges in offline reports** — bundle-carried anchor,
  timestamp and recorder-key material remains insufficient. Offline reports
  stop at E1 and show those items only as facts or claims. E1 is unaffected;
- the **"qualified" timestamp label** — it was an unsigned producer boolean, not
  derived from an EU trusted-list root;
- **B28 Counterparty Assurance `PASS`** — the v1 verifier checks a
  nonce-bound exact action, organisation-root passport chain, current mandate,
  action-specific authorization and durable replay locally. Its public result
  still converts every otherwise favourable candidate to
  `INDETERMINATE/PASS_NOT_ENABLED` until the independent review, compromise
  drill and limited relying-party rollout gates are complete.

Claims ≤ mechanism: the operated anchor path currently uses a public
**staging** chain (Base Sepolia), timestamps are **non-qualified**, and no
external security audit or paid production deployment has been completed. Use
the offline path as a tamper-evident flight recorder whose base E1 record can be
verified locally. A relying party can explicitly run the online profile against
Base or Base Sepolia with its own TSA root to evaluate E2, and can additionally
supply the trusted active recorder key to evaluate cumulative E3. Neither level
is a third-party assurance mark. B28 is a separate pre-action protocol: a valid,
unexpired authorization can be verified locally, but obtaining a new one
requires the online delegated Action Authority. No `Swarrm Verified` mark ships.

## Quickstart

```bash
pipx install swarrm==1.1.1          # Python 3.11+  (or: pip install swarrm==1.1.1)
swarrm demo                           # synthetic agent traffic → receipts → bundle → VERIFIED
swarrm verify demo_out/bundle.json    # the demo flips one byte → NOT VERIFIED
```

The exact version pin prevents a later release from silently changing the
reviewed bytes. Before creating an organisation root, download the matching
GitHub release wheel, runtime requirements, `SHA256SUMS`, `PROVENANCE.json`
and their Sigstore bundles. Verify each signature against the
`capxholding/swarrm-core/.github/workflows/ci.yml@refs/heads/main` identity, the
GitHub Actions OIDC issuer and the exact workflow SHA. Require the provenance
`source_commit` to equal the release tag's peeled commit; verify the wheel from
`SHA256SUMS` and the runtime-requirements digest from the signed provenance.
In a clean virtual environment, install `requirements-docker.txt` with
`pip install --require-hashes --only-binary=:all: -r`, then install the verified
wheel with `pip install --no-deps`; do not resolve broad dependency ranges at
ceremony time. If those matching signed assets are unavailable, stop. The
release never asks a served webpage to generate or decrypt the root. This signed, hash-locked
local environment is the boundary used by the root ceremony.

Two minutes, no account, fully local. One config knob — `EVD_PROFILE` (for
example `dev`, `trial`, `edge`, `node`, or the KMS-only managed `production`
profile) — sets every default; `swarrm doctor` prints what's effective and
whether it is actually recording. The CLI is one word: `up` (dev stack), `demo`,
`verify BUNDLE`, `wrap -- CMD` (capture an MCP tool), `node`, `incident`,
`status`, `doctor`.

## Verify it yourself — offline, and open

`swarrm verify <bundle.json>` checks a bundle entirely locally. So does the
in-browser verifier at [swarrm.ai/verify](https://swarrm.ai/verify) —
client-side, nothing leaves the page.

The verifier has an **open-source, separately implemented Rust path**
([github.com/capxholding/swarrm-verify](https://github.com/capxholding/swarrm-verify),
Apache-2.0) that must agree with this package's Python verifier on a shared
adversarial fixture suite. Agreement catches implementation divergence; it is
not independent external assurance. The normative wire-format specifications
(`evd/*`) are published openly in that repository.

## The evidence ladder

Each receipt carries the assurance it has actually earned:

- **E0 — signed.** The receipt exists and is intact, signed by a known key.
- **E1 — in the log.** Included in an append-only, checkpointed log; it cannot be
  altered in the presented authenticated history without verification failing.
  A bundle proves its carried receipts and, when present, its signed export
  manifest; it does not prove that the producer captured or exported every
  relevant action. **This is what the offline verifier proves today.**
- **E2 — independently rooted time and public commitment.** The explicit live
  verifier must re-read a checkpoint covering that receipt from Base (`8453`)
  or Base Sepolia (`84532`) **and** verify its RFC 3161 token to a TSA root the
  relying party supplied out of band. Bundle-carried material and an offline run
  never award E2.
- **E3 — cumulative dual attestation.** Every E2 requirement must hold, then
  both the issuer signature and recorder co-signature must verify, with the
  recorder active in the authenticated log under the non-issuer `recorder` role
  and its key supplied out of band by the relying party. Recorder possession by
  itself is an inspectable fact, not a level, and does not prove legal or
  organisational independence.

The levels are cumulative and post-action. They do not supply or strengthen a
B28 Counterparty Assurance identity, authority, exact-action or replay verdict.

## What's in the package

The cryptographic log and receipts; capture surfaces (proxy, recorder, MCP
wrapper, SDK, OpenTelemetry); L2 anchoring + RFC 3161 timestamping; the offline
verifier; evidence-report rendering; and an out-of-path Evidence Node for
independently reading an authoritative source. The wire-format specifications and
the second verifier implementation are open source (Apache-2.0) in the
[swarrm-verify](https://github.com/capxholding/swarrm-verify) repository.

The launched product also includes local organisation-root onboarding and the
`swarrm-b28/v1` Counterparty Assurance profile. The visible flow is **create
organisation → connect/sign in → register agent**. Underneath it, the
verified local tool creates the customer-controlled root, the root authorizes a
registration template and admin passkey, the passkey selects that exact
template, and the agent proves control of its dedicated key before the Passport
& Status Authority issues its immutable passport. A root-signed limit grant may
then delegate exact action authorization to the separate Action Authority. B28
proves identity and current proof-bearing authority at a signed checkpoint, and
evaluates exact-action and durable replay requirements. The current B28 path
does not authorize execution: `should_execute` is false even for an otherwise
favourable candidate. It does not predict behaviour, certify the action outcome, or
evaluate Node/source/coverage, history, or post-action evidence readiness in v1.
The authority plane supports a dual-signed organisation-root successor
ceremony with monotonic continuity and old-runtime fencing. It cannot recover
from loss of the old root unless a successor was already authorized, and B28
presentations cannot import a successor as a new relying-party trust anchor.
The external compromise/revocation drill therefore remains a gate for enabling
favourable `PASS`; it does not gate the stable product release.

## License

The `swarrm` package is proprietary — © 2026 Capx Holding, all rights reserved.
The published wire-format specifications and the Rust/WASM verifier are
Apache-2.0.

Homepage: [swarrm.ai](https://swarrm.ai)
