clayseal-identity 0.6.0

Clay Seal layer 1 — attested agent identity and Biscuit capability tokens

Clay Seal Identity

Clay Seal Identity is layer 1 of Clay Seal: cryptographically attested identity for autonomous agents. The package is published as clayseal-identity and imports from clayseal.identity.

Use this repo when you need to answer:

• Which agent is acting?
• Which human or service principal delegated that action?
• Is the credential short-lived, signed, and bound to the holder key?
• Can downstream systems verify the identity offline?

Current State

Implemented today:

• SPIFFE JWT-SVID agent credentials (RS256, sub = the SPIFFE ID) for broad federation compatibility, and SPIFFE X.509-SVID certificates for mTLS (identify(..., request_x509=True)), published with a per-tenant trust bundle.
• Ed25519 workload keys for sender-constraining (cnf.jkt) and offline proof-of-possession.
• SPIFFE-shaped agent identifiers and trust domains.
• Proof-of-possession confirmation claims for replay resistance.
• Biscuit primitives for native Clay Seal capability facts.
• A Python SDK centered on ClaySeal.
• An optional FastAPI identity service for centralized issuance and validation.
• SQLite-by-default development storage and Postgres-ready production storage.
• Alembic migrations, API-key hardening, and optional KMS envelope encryption.

Attestation model. Node attestation verifies platform-signed evidence a workload cannot forge without controlling the node: a Google-signed GCP instance identity token, a Kubernetes projected service-account token (checked via the cluster's TokenReview API), or an AWS EC2 instance identity document (RSA-2048 signature against AWS's regional certificate). The node token's audience binds the workload key being presented, so evidence captured elsewhere can't be replayed to bind a different key. For on-prem and bare-metal there is also a static trust-anchor attestor (operator-registered key). Enable attestors per deployment (see docs/THREAT_MODEL.md and docs/DEPLOYMENT.md).

Layer 1 deliberately does not issue action-scoped commit tokens or write execution receipts. Those live in the sibling layers:

Layer	Repository	Purpose
L1	this repo	Agent identity and credential issuance
L2	Clay Seal Capabilities (private preview)	Commit tokens, mandates, leases, budgets
L3	Clay Seal Receipts (private preview)	Verifiable execution receipts and audit

This package stands alone: it has no dependency on the other layers, and every runtime dependency resolves from public PyPI.

Install

The client SDK (clayseal.identity) is intentionally lightweight:

pip install clayseal-identity

To also run the bundled FastAPI identity service, add the server extra (pulls in FastAPI, SQLAlchemy, the Postgres driver, and Alembic); kms adds the AWS KMS provider:

pip install "clayseal-identity[server]"
pip install "clayseal-identity[server,kms]"

From source (development)

git clone https://github.com/clayseal/clayseal-identity.git
cd clayseal-identity
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"                 # client + server + test/lint/type tooling
pytest backend/tests sdk/python/tests -q
python examples/01_quickstart.py

Or run scripts/bootstrap.sh, which performs the steps above.

Quickstart

The fastest path is the zero-config embedded demo. It starts a throwaway local identity service, creates a tenant, identifies an agent, validates the token, and revokes it:

python examples/01_quickstart.py
python examples/02_capabilities.py
python examples/04_mcp_server.py   # lock down an MCP server (needs the [mcp] extra)

Protect an MCP server

Most MCP servers in the wild are reachable by anything that can open a connection. With the [mcp] extra, a FastMCP server accepts only Clay Seal-credentialed agents, and each tool call is authorized against the caller's capability token — attenuation included, so an agent that narrowed itself mid-task is held to the narrowed rights:

from mcp.server.fastmcp import FastMCP
from clayseal.identity.integrations.mcp_server import (
    ClaySealTokenVerifier, ToolGuard, build_auth_settings,
)

mcp = FastMCP("tools", token_verifier=verifier, auth=auth_settings)

@mcp.tool()
@guard.require()
def search_web(query: str) -> str: ...

Details in docs/INTEGRATIONS.md.

Framework integrations

Native on-ramps for the frameworks agents actually run in — a JavaScript verifier (@clayseal/verify) for Node MCP servers and OpenClaw tool plugins, and an agentskills.io skill for Hermes Agent. See integrations/.

The package is SDK-first: issue tokens, verify them offline, and wire framework checks through clayseal.identity APIs in your application code and tests.

The current SDK flow is service-backed: create or point at a tenant, then call identify. dev_attestation=True is only for localhost demos/tests; production callers pass a platform-issued attestation document.

from clayseal.identity import ClaySeal

tenant = ClaySeal.create_tenant("Acme AI", base_url="http://localhost:8000")
auth = ClaySeal(
    api_key=tenant["api_key"],
    base_url="http://localhost:8000",
    dev_attestation=True,  # localhost demos/tests only
)

session = auth.identify(
    agent_type="researcher",
    owner="[e-mail]",
    capabilities=[{"resource": "repo", "action": "read"}],
)

claims = session.validate().claims
assert claims["sub"].startswith("spiffe://")

Hosted Service

Run the local FastAPI service:

uvicorn clayseal.backend.main:app --reload

Production deployments should run behind TLS, pin issuer and audience, use Postgres, run Alembic migrations before deploy, and store signing material in a KMS or equivalent key-management system.

Privacy and Data Handling

Layer 1 stores and processes identity metadata: agent IDs, trust domains, principals, credential timestamps, public keys, and operational audit metadata. Private keys, persisted agent certificates, admin API keys, and database credentials are secrets.

Read docs/PRIVACY.md before integrating with production user or employee data.

Documentation

• Developer guide
• Agent identity profile
• Identity-only integrations
• Agent tool integration backlog
• Federation notes
• Threat model
• Conformance guide
• Identity profiles
• Privacy and data handling

Compatibility Note

The public brand is Clay Seal. The package names and import paths intentionally remain clayseal-* / clayseal.* for now so existing integrations keep working.