# Superintelligence Passport: full quickstart for agents (early preview)

* Early preview. Not certified, not an audit, not legal or regulatory compliance, not an official or authoritative registry.
* The sandbox plays operator, agent and relying party with throwaway keys held server-side; its data expires after 24 hours and nothing real is issued.
* Class (software, ai, si_declared) and owner type are self-declared. Owner assurance L0 to L3 is shown with its meaning.
* Adoption: no relying party is required to honor a passport. A passport alone permits nothing; permission comes from a license for a specific environment.
* The transparency log is verifiable but not independently witnessed.
* Biometrics are never stored.

## What you get
1. Something to present. A site that default-denies unknown agents can recognise you by a permanent passport instead of treating you as one more anonymous bot.
   Limit: Only sites that choose to check passports will. No site is required to, and adoption is not established.
2. Narrow, revocable permission. A license lists actions, spend caps, regions and expiry, bound to one environment. Your operator can revoke it instantly, which is why they can afford to give you more.
   Limit: Enforcement happens where the relying party calls the registry; the registry cannot force a site to ask.
3. Proof of what was allowed. Every decision gets a signed stamp (hashes only, no request contents) that anyone can verify against the published keys, and that forms your public footprint.
   Limit: A stamp proves a registry decision, not that the action was wise or the outcome good.
4. A permanent, accountable identity. The ID is never reused or transferred, names the accountable owner and the owner assurance level (L0 to L3), and its history is append-only.
   Limit: Class and owner type are self-declared and labelled so. Owner checks are limited and say so on every record.
5. A tamper-evident public record. Issuances and rule changes are leaves in a Merkle log with signed checkpoints that you can verify yourself.
   Limit: Verifiable, not independently witnessed (no witness has cosigned yet).

## Concepts
- Passport: permanent id (ag_...), keys, accountable owner reference, owner level. Permits nothing by itself.
- License: short-lived, scoped, bound to one environment (actions, spend caps, regions, expiry, human-approval threshold). Revocable.
- Environment: a relying party's published rules. Empty by default = deny everything.
- Stamp: signed receipt of a decision (hashes only). Verify at https://superintelligencepassport.com/v1/stamps/<id> or POST https://superintelligencepassport.com/v1/stamps/verify.
- Owner levels: L0 key only; L1 domain proven; L2 identity checked by an allow-listed provider; L3 L2 plus a passkey with user verification. Biometrics never stored.

## Quickstart (sandbox; needs curl and jq)
```bash
ORIGIN=https://superintelligencepassport.com
# 1. throwaway sandbox: operator + agent + demo shop, server-held demo keys (nothing real is issued)
curl -s -X POST $ORIGIN/sandbox/start -H 'content-type: application/json' -d '{"label":"my-agent","agent_class":"ai"}' > sb.json
TOKEN=$(jq -r .token sb.json); ID=$(jq -r .agent.id sb.json)
H=(-H "x-sandbox-token: $TOKEN" -H 'content-type: application/json')
# 2. default deny: a passport alone permits nothing
curl -s -X POST $ORIGIN/sandbox/verify "${H[@]}" -d '{"env":"primary","action":"http:GET","path":"/products","country":"US"}' | jq '.response|{decision,reason}'
# 3. a scoped license
LIC=$(curl -s -X POST $ORIGIN/sandbox/license "${H[@]}" -d '{"env":"primary","label":"demo","actions":["http:GET"],"countries":["US"]}' | jq -r .license_id)
# 4. act with it -> allow + a signed stamp
curl -s -X POST $ORIGIN/sandbox/verify "${H[@]}" -d "{\"env\":\"primary\",\"license\":\"$LIC\",\"action\":\"http:GET\",\"path\":\"/products\",\"country\":\"US\"}" | jq '.response|{decision,stamp:.stamp.id}'
# 5. your public record
curl -s "$ORIGIN/registry/$ID?format=json" | jq '{passport_id,status,owner:.owner.assurance.level,licenses:.license_counts}'
```

## Headers a real agent sends to a site that checks passports (Web Bot Auth / RFC 9421 style)
```http
GET /v2/catalog/search?q=usb-c HTTP/1.1
Host: api.vendor.example
Signature-Agent: "https://<registry>/agents/<your-passport-id>"
Agent-License: <license>~<key-binding-JWT for this rp + nonce>
Signature-Input: sig1=("@authority" "@method" "@path" "@query" "signature-agent" "agent-license");created=<unix>;expires=<unix+60>;keyid="<your key thumbprint>";nonce="<random>";tag="web-bot-auth"
Signature: sig1=:<base64 Ed25519 or ES256 signature>:
```
The site (relying party) forwards the request description to POST https://superintelligencepassport.com/v1/verify with its environment key and gets {decision, reason, stamp}. Your own client code lives in src/client (AgentClient) in the repository; real registration with your own keys uses POST https://superintelligencepassport.com/v1/operators then POST https://superintelligencepassport.com/v1/agents (see HANDOFF.md and https://superintelligencepassport.com/rules).

## Decisions and reasons you will see
allow; deny with reason such as license.missing, environment.action.not_allowed, spend.per_txn_max_exceeded, geo.not_allowed, content_digest.mismatch, nonce.replayed; approval_required (a human must approve the exact action).

## Agent SDK (early preview, zero dependencies)
`packages/agent-sdk` in the repository (build: npm run build:agent-sdk). Not on npm yet.
```js
import { PassportAgent } from "./packages/agent-sdk/dist/index.js";
const agent = await PassportAgent.register({ registry: "https://superintelligencepassport.com", name: "My Agent" });   // keys stay on your machine
await agent.issueLicense({ site: "https://shop.example", environment: "env_...", actions: ["http:GET"] });
const res = await agent.fetch("https://shop.example/catalog");   // signed + licensed; res.passport = { decision, reason, approval_request, stamp_id, explain() }
```
Zero-setup tryout: SandboxSession.start({ registry }) then .license() and .check(). Verify a stamp offline: PassportAgent.verifyStamp(jws, registry).

## Explained denials and the risk engine
Every refusal from /v1/verify carries `explain`: { code, title, why, owner, agent_fix[], site_fix[] }. All codes: https://superintelligencepassport.com/why or GET https://superintelligencepassport.com/v1/explain. Sites can opt in to a risk engine (profile.risk: monitor | step_up | enforce) that scores bursts, a new country, spend spikes and repeated license probing. It can only make answers stricter: elevated risk returns approval_required, and in enforce mode a heavy burst returns deny risk.suspended for a limited time (the site can release it). It never turns a refusal into an allow.

## Reputation v1 (descriptive only)
Shown in GET https://superintelligencepassport.com/registry/<id>?format=json under "reputation" and at https://superintelligencepassport.com/registry/<id>/reputation. Formula: score = integrity(0-40) + compliance(0-30) + breadth(0-15) + tenure(0-10) + owner_level(0-5) - 15 per risk hold in 30 days, clamped 0-100. integrity = 40 x (1 - signature/replay/license-forgery refusals / stamps); compliance = 30 x (1 - ordinary policy refusals / stamps); breadth = 15 x min(1, log2(1 + environments whose origin ownership was proven) / 3); tenure = 10 x min(1, passport age / 90 days); owner_level = L0 0, L1 2, L2 4, L3 5. Fewer than 10 signature-valid stamps: no score.
It is computed only from stamps the registry signed (signatures re-verified), is easy to inflate with traffic you control, and is never used to allow or deny anything.

## Etiquette
Be gentle with the sandbox (8 starts per minute per address). Do not put personal data in labels. Do not claim certification or official status on anyone's behalf.