research/README.md

# Capability licensing and accountable inference

## A clean-room reference implementation

This repository is a standalone, reproducible demonstration of the cryptographic
mechanisms behind the Meanwhile capability-licensing research line. Every primitive here
was written from scratch for this repository, on top of the standard Python
`cryptography` package, and shares no code with any production or research system. Every
checkable claim in this README is backed by a runnable example and a test you can execute
locally in minutes, on any machine, with no GPU and two pinned dependencies.

The payloads throughout are stand-in blobs. Nothing in this repository is a real model.

---

## The gap, in one sentence each

A doctor, an engineer, a solicitor, an accountant, a pilot who reaches for a chat
interface to help make a consequential decision is a person the system has already
vetted: they hold a licence, they were examined to earn it, they can be audited,
suspended, and struck off, and they answer for what they do. The software sitting in the
middle of that same decision carries none of it: no record of which capability produced
which part of the answer, no way to trace an output back to a source, no authorisation
that says this system was ever cleared to do this task, and no attestation that the thing
that ran is the thing that was approved.

Every professional in that list is licensed. The system in the middle of their decisions
is not.

The research line is about closing that gap without waiting for the model vendors to do
it. The model is a commodity. The accountability layer around it is the value, and it can
be built on hardware the customer already controls. None of the individual mechanisms is
new: gated decrypt-at-load, cryptographic erasure, signed provenance, and hardware
attestation all have prior art. The claim is about the assembly, stated as an existence
proof of composition, never as invention of a part.

This repository demonstrates the cryptographic core of that assembly, small enough to
audit in an afternoon.

---

## What this repository demonstrates

Four claims. Each is a runnable example that prints its evidence and a pytest module that
asserts it.

| # | Claim | Example | Tests |
|---|-------|---------|-------|
| 1 | A three-tier certificate chain (self-signed root, organisational signer, leaf capability certificate, Ed25519 throughout) verifies offline against a trust store, and a tampered, expired, or wrongly-issued certificate FAILS verification. | `examples/issue_certificate.py` | `tests/test_certificates.py` |
| 2 | An output can be bound, by digest and signature, to the certificates of its composition (weight-source and context-source axes); the binding verifies VALID while the composition is intact and INVALID the moment a referenced certificate is revoked or crypto-erased. | `examples/verify_output_provenance.py` | `tests/test_provenance.py` |
| 3 | Revocation of an encrypted capability unit works at three graded rungs: soft (advisory list entry, reported by verifiers, reversible), access-gated (wrapping key withheld, decryption denied, recoverable), and crypto-erasure (wrapping key destroyed, permanent). | `examples/revoke_three_rungs.py` | `tests/test_revocation.py` |
| 4 | Cryptographic erasure defeats even an exfiltrated copy: an envelope-encrypted unit decrypts under a valid licence, a stolen byte-for-byte copy decrypts BEFORE erasure, and after the wrapping key is destroyed both the original and the stolen copy raise on every decrypt attempt. | `examples/crypto_erasure_undecryptable.py` | `tests/test_erasure.py` |

Claim 4 is the strongest and cleanest in the set because it rests on standard
cryptography, not on model behaviour: AES-256-GCM ciphertext without its key is not
degraded or obfuscated, it is gone.

---

## Reproduce every claim

Requires Python 3.10 or later, no GPU, and network access only for the initial
`pip install`.

```sh
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
./run_all.sh
```

`run_all.sh` runs all four examples (each prints its evidence and a final
`RESULT: PASS`) and then the full test suite. Everything can also be run individually:

```sh
python examples/issue_certificate.py            # claim 1
python examples/verify_output_provenance.py     # claim 2
python examples/revoke_three_rungs.py           # claim 3
python examples/crypto_erasure_undecryptable.py # claim 4
python -m pytest tests/ -v                      # all claims, asserted
```

A `Makefile` offers the same steps (`make venv`, then `PYTHON=.venv/bin/python make all`).

---

## The four mechanisms, and what lives where

The research line composes four mechanisms. This repository reimplements the
cryptographic core of the first three; the fourth, and everything requiring real model
weights or a GPU, is referenced to research result records instead, never asserted as
reproduced here.

**Status vocabulary**, used consistently below:

- **Demonstrated here** - runnable and asserted in this repository, on stand-in payloads.
- **Referenced** - a measured result in the research programme's registry, cited by
  result identifier (RR-...). Those records are internal to the programme; they are cited
  so the boundary between what this repository shows and what it merely reports is
  explicit, not so this README can borrow their weight.
- **Open** - a named question not yet answered anywhere.

### 1. The certificate-chain authority

Think of the way a browser decides whether to trust a website: a root authority signs
intermediate authorities, they sign individual certificates, and any party can check the
chain without phoning home. Revoke once at the authority and every checker that consults
the revocation list stops trusting it. This repository applies that shape to model
capabilities: root, organisational signer, per-capability leaf, Ed25519 signatures over a
canonical encoding, offline chain verification against a caller-held trust store.

- **Demonstrated here:** issue, chain verification, expiry, tamper detection, untrusted
  issuer rejection, role separation (a leaf cannot issue certificates), and the authority
  not retaining leaf private keys.
- **Referenced:** the same mechanism enforced in front of a real capability load on a
  real inference engine, on an 8B open-weights base (RR-2026-07-16-C3).

### 2. Signed output provenance

The full research goal is per-source attribution on two axes: weight-source (which base
model and which capability-adapters produced each part of an output) and context-source
(which supplied or retrieved material informed it). This repository demonstrates the
certificate side of that: binding an output, by digest and Ed25519 signature, to the
exact certificates of its composition, and verifying that binding against the live state
of the authority. Revoke or erase a referenced source and the same output flips from
VALID to INVALID. Provenance here is not a static stamp; it is a claim checked against
the authority's current state.

- **Demonstrated here:** output binding on both axes, digest and signature verification,
  chain verification of every referenced certificate, invalidation on revocation and on
  erasure, detection of a substituted certificate and of a tampered output.
- **Referenced:** the measured attribution results behind the weight-source axis. On a
  dense merged model, per-unit attribution is a genuine null (held-out F1 0.296 against a
  pre-registered 0.70 bar; RR-2026-07-15-WPROV01). When composition is routed, the
  provenance is the routing decision itself: recovered at macro-F1 0.943 with about
  +0.34% logging overhead on an 8B base (RR-2026-07-15-WPROV02). A prior-art survey
  found the capability-adapter provenance axis unoccupied, with existing
  content-credential standards as the natural outer envelope, not competitors
  (RR-2026-07-15-WPROV03).
- **Open:** context-source attribution (design direction only; the axis appears here
  only as a referenced certificate, not as measured attribution), harder capability
  pairs without literal markers, more than two adapters, per-span attribution, and
  engine-native routing logs.

### 3. The three-rung revocation ladder

Revoking a licence should have graded strength depending on how badly you need the
capability and its outputs gone:

- **Soft (advisory).** An entry on a revocation list. Verifiers that consult the list
  report the certificate revoked and a compliant key authority refuses release, but the
  ciphertext and its wrapping key still exist. Reversible by removing the entry.
- **Access-gated.** The wrapping key is withheld at the authority. Decryption is denied
  at use-time even for an otherwise valid licence. Recoverable: the authority can
  re-release.
- **Cryptographic erasure.** The wrapping key is destroyed. The ciphertext, and every
  copy of it anywhere, is permanently undecryptable. Irreversible by construction: the
  reference implementation refuses to re-release or reinstate what no longer exists.

The asymmetry is the honest shape of the ladder, not a rough edge to paper over: the
first two rungs are administrative states that depend on parties honouring the
authority, and only the third is final at the level of the cryptography itself. In the
research build, the reversibility of the first two rungs by a privileged administrator
is a live, recorded defect in the programme's issue tracker; this reference
implementation makes the same asymmetry explicit in its API.

- **Demonstrated here:** all three rungs on an envelope-encrypted stand-in unit,
  including the recovery paths (reinstate, re-release) and the refusal paths after
  erasure.
- **Referenced:** the same ladder driven end to end against a real sealed adapter on a
  real engine, where a valid licence produced the adapter's trained behaviour and each
  rung denied the load with zero decrypt calls on the deny paths (RR-2026-07-16-C3).

### 4. Attestation

A provenance map or licence check the engine reports about ITSELF is only as trustworthy
as the engine. The research line's fourth mechanism is attestation: process isolation so
the orchestrating host never holds plaintext weights, and hardware-rooted measurement of
the code that touches plaintext.

- **Demonstrated here:** nothing beyond the output-binding in claim 2. This repository
  makes no attestation claims.
- **Referenced:** software process isolation with a default-deny effect surface
  (host decrypt count zero, roughly 1.2 KB of output and attestation returning from
  349 MB of weights; RR-2026-07-16-F), explicitly NOT a hardware enclave; and
  within-run TPM-rooted attestation, trust-on-first-use, still in flight after repeated
  adversarial rescoping (RR-2026-07-16-F1).
- **Open / future work:** memory-sealing. Nothing in the research line yet protects
  plaintext weights from a privileged host or reads of GPU memory. That requires
  confidential-computing hardware (a memory-encrypting CPU enclave and a
  confidential-computing GPU) and is stated strictly in the future tense.

---

## Honest scope and bounds

A sceptical reader should be able to read just this section and know where the edges are.

1. **Stand-in payloads.** Every sealed unit here is a labelled random blob. No model
   weights, no adapters, no trained behaviour. The claim demonstrated is about the
   cryptography around a unit, which is indifferent to what the unit contains.
2. **Clean-room reference code, not the research build.** This repository was written
   from scratch for public reproduction. It is a third artefact, distinct from both the
   research build and any production system, and shares code with neither. Where the
   research records demonstrate the same mechanism, that is stated as a reference, not
   as identity of code.
3. **The referenced GPU demonstrations have their own boundary.** They drove a faithful
   in-memory mirror of the platform-coupled orchestration (the real cryptographic
   key-store code, with record-keeping reproduced in memory), not the live application,
   and the governance primitives around the kill-switch (quorum, custody, restore-proof
   logging) are covered by that programme's test suite rather than by the
   demonstrations. Nothing referenced here is a production system, and none of it has
   shipped to one.
4. **The ladder is asymmetric on purpose.** Soft and access-gated revocation are
   reversible administrative states; only crypto-erasure is cryptographically final.
   This repository's API enforces exactly that asymmetry.
5. **Erasure removes the sealed unit, not "the capability from the model".** Crypto-
   erasure destroys a capability that was factored into a separate encrypted unit at
   build time. Whether a capability can be factored so cleanly that no recoverable
   residual remains in the base model is an open research question in the programme; on
   current evidence, behavioural isolation held on a synthetic proxy while
   representational isolation remains unproven. The honest phrasing is "removes the
   licensed unit with a cryptographic guarantee".
6. **The erasure guarantee is scoped to key destruction.** If the wrapping KEY, rather
   than the ciphertext, had been exfiltrated before erasure, destroying the authority's
   copy would not help. Key custody (external key-stores, hardware modules, backup
   semantics that cannot resurrect a destroyed key) is named open work.
7. **Containment, not alignment.** Everything here bounds what a system can DO and caps
   the blast radius of a revocation, against an auditable, cooperating licensee. None of
   it makes a model benevolent, and none of it stops a determined owner of the machine.
8. **Research artefact, not a production system.** The code favours readability over
   hardening: keys live in process memory, there is no persistence, no side-channel
   engineering, and no security audit. Do not deploy it. Its job is to make the
   mechanisms checkable.

---

## Claim provenance

Every substantive claim above, mapped to its evidence class. **Demonstrated here** means
you can run it in this repository. **Referenced** means it rests on a named result
record internal to the research programme, cited by identifier only. **Open** means not
yet answered anywhere.

| # | Claim | Status | Traces to |
|---|-------|--------|-----------|
| 1 | Certificate chain issues and verifies offline; tampered, expired, and wrongly-issued certificates fail. | Demonstrated here | `examples/issue_certificate.py`, `tests/test_certificates.py` |
| 2 | Output binding to composition certificates verifies VALID intact, INVALID on revocation or erasure of a referenced certificate. | Demonstrated here | `examples/verify_output_provenance.py`, `tests/test_provenance.py` |
| 3 | Three-rung revocation ladder, with recovery on the first two rungs and permanent refusal on the third. | Demonstrated here | `examples/revoke_three_rungs.py`, `tests/test_revocation.py` |
| 4 | After key destruction, both the original ciphertext and a pre-existing exfiltrated copy are permanently undecryptable; both decrypted fine before. | Demonstrated here | `examples/crypto_erasure_undecryptable.py`, `tests/test_erasure.py` |
| 5 | The same mechanisms enforced around a real 8B adapter on a real inference engine, with trained behaviour appearing under a valid licence and every rung denying cleanly. | Referenced | RR-2026-07-16-C3 |
| 6 | Dense-merged per-unit weight attribution is a null (F1 0.296 vs 0.70 bar); routed composition recovers attribution at macro-F1 0.943 for +0.34% overhead. | Referenced | RR-2026-07-15-WPROV01, RR-2026-07-15-WPROV02 |
| 7 | The capability-adapter provenance axis is unoccupied in prior art; content-credential standards are the outer envelope, not competitors. | Referenced | RR-2026-07-15-WPROV03 |
| 8 | Process isolation with a default-deny effect surface; not a hardware enclave. | Referenced | RR-2026-07-16-F |
| 9 | Within-run TPM-rooted attestation, trust-on-first-use; in flight, conservatively scoped. | Referenced | RR-2026-07-16-F1 |
| 10 | Memory-sealing and GPU/VRAM protection. | Open (future work, needs confidential-computing hardware) | - |
| 11 | Clean capability factorisation with no recoverable residual in the base model. | Open | - |
| 12 | Context-source attribution as a measured result. | Open (the axis appears here only as a certificate reference) | - |

Nothing marked *Demonstrated here* claims more than its example and tests show. Nothing
marked *Referenced* is reproduced in this repository, and this repository's passing
tests lend it no additional weight. Nothing marked *Open* is asserted at all.

---

## Repository layout

```
README.md                     this file
LICENSE                       MIT
requirements.txt              two pinned dependencies: cryptography, pytest
run_all.sh                    run every example, then the test suite
Makefile                      the same, as make targets
src/capability_licensing/
  certificates.py             Ed25519 three-tier authority + offline chain verification
  envelope.py                 AES-256-GCM envelope encryption of capability units
  revocation.py               the revocation ledger (soft rung)
  keystore.py                 wrapping-key custody (access-gated + erasure rungs)
  provenance.py               signed output-to-composition binding + verification
examples/                     one runnable script per claim, printing PASS/evidence
tests/                        pytest suite asserting every claim
```

## Requirements

- Python 3.10 or later (developed and verified on 3.13)
- `cryptography` (pinned) for Ed25519 and AES-256-GCM
- `pytest` (pinned) for the test suite
- No GPU, no network access after install, no services, no containers

## Licence

MIT. See `LICENSE`.