# rnv-mcp-identity

[![OpenSSF Baseline](https://www.bestpractices.dev/projects/13437/baseline)](https://www.bestpractices.dev/projects/13437)

An identity and authorization layer for MCP servers. On every tool call it asks one
question, is this caller who it claims to be, and is this action within what it's
allowed to do?, and answers with exactly one of three outcomes:

- **allow:** identity resolved, verified, and the action is in scope.
- **deny:** verified, but out of scope; or an identity was presented and failed
  verification.
- **unknown:** identity could not be established at all. The call is refused.

An unknown caller never acts. That rule is the whole project: *resolve or refuse,
never guess.*

> Status: reference implementation, complete at v0.1.0, Apache-2.0. Built under
> AIII, the [Artificial Intelligence Identification Initiative](https://rnvizion.dev/aiii/): a build record, not a standards
> bid. It composes on existing standards (the MCP authorization model, WIMSE
> workload identity, RFC 7800 key confirmation, RFC 7638 thumbprints, EAT
> attestation) rather than replacing them.

**Live demo:** [Identity Gate on Hugging Face Spaces](https://huggingface.co/spaces/RNVizion/rnv-mcp-identity), running this engine on the released v0.1.0.

## What's here

- **`src/rnv_mcp_identity/`** — the library: a framework-agnostic decision engine
  (L1 identity, L2 verification, L3 authorization) plus a FastMCP middleware
  adapter. The core has no runtime dependencies.
- **`examples/`** — a runnable FastMCP server guarded by the layer, an in-process
  test, and an HTTP client. Start here to watch it allow one call and refuse three.
- **`docs/SPEC.md`** — the normative spec: the decision sequence, the capability and
  policy model, the threat model, and the v0 wire format.
- **`docs/AAIF-READINESS.md`** — the foundation-readiness assessment, retired: the
  evaluation, the conclusion, and why the submission was not pursued.

## Quickstart

```
pip install -e ".[dev,verify,fastmcp]"
python -m pytest -q                                # the full suite
python -m pytest -q tests/test_demo_inprocess.py   # just the guarded-server demo
```

Run the demo over real HTTP:

```
python examples/demo_server.py        # terminal 1
python examples/demo_client_http.py   # terminal 2
```

## The wire format (v0)

The identity token rides in the `mcp-agent-identity` header and a holder-of-key
proof in `mcp-agent-proof`. The proof binds to the exact token, so a stolen token
alone can't act. The reference client in `examples/` is the normative example; see
docs/SPEC.md section 10.

## Docs

- `docs/SPEC.md` — the specification
- `docs/ROADMAP.md` — where this is going
- `docs/PRIOR-ART.md` — what it builds on, and the gap it fills
- `docs/GOVERNANCE.md` — how decisions are made
- `CONTRIBUTING.md` — how to help
- `SECURITY.md` — how to report vulnerabilities
- `docs/AAIF-READINESS.md` — foundation-readiness assessment

## License

Apache-2.0. See `LICENSE`.

## A note on affiliation

This project *aspires* to become a foundation-hosted project and is not affiliated
with, endorsed by, or accepted into the AAIF or the Linux Foundation. See
docs/AAIF-READINESS.md for an honest account of where it stands.

## Verifying a release

Each GitHub release carries the build artifacts, a `SHA256SUMS` manifest, a
Sigstore signature over that manifest (`SHA256SUMS.sigstore.json`), and a
CycloneDX SBOM (`sbom.cdx.json`).

Check integrity (hashes):

```
sha256sum -c SHA256SUMS
```

Verify authenticity and the signer's identity (keyless Sigstore):

```
pip install sigstore
python -m sigstore verify identity \
  --cert-identity "https://github.com/RNVizion/rnv-mcp-identity/.github/workflows/release.yml@refs/tags/v0.1.0" \
  --cert-oidc-issuer "https://token.actions.githubusercontent.com" \
  --bundle SHA256SUMS.sigstore.json \
  SHA256SUMS
```

A valid result proves the manifest was produced by this repository's release
workflow under GitHub's OIDC, not by a third party. Replace the tag in
`--cert-identity` with the release you are verifying.