# qub

> Seal your words today. Prove when you said them. Even AI can't fake the past.

qub lets a person — or an AI agent — write something today that the world can only read at a future moment, and prove later that it was written before that moment arrived. As more of the internet becomes machine-generated, being able to point at something and prove "this existed at that exact moment, and I wrote it" gets more valuable, not less. qub is the simplest tool we know of for doing that.

A qub is sealed in the user's (or agent's) browser before anything is uploaded — the platform itself cannot read sealed content, including before the unlock moment arrives. Sealed bytes live in permanent public storage — a decentralised network qub does not run; verification works without qub being online. After the unlock time, anyone with the link can decrypt and verify the qub.

Public attribution is **opt-in per qub** — by default a qub goes up unsigned and there is no on-chain link from it back to a creator. Authors who want credit (a "called it" moment, a receipt that they said something first) can attach their fingerprint at seal time.

## What agents can do

- **Create qubs** — seal a qub with a future unlock date via API or MCP server
- **Create pacts** — stage a bilateral agreement, share the staging link, and co-sign when both parties are ready
- **Read qubs** — fetch qub status and content (if unlocked) as structured JSON
- **Verify qubs** — cryptographic proof that content existed before the unlock time
- **Monitor qubs** — check status, register webhooks for unlock notifications
- **Engage with sealed qubs** — increment watch counters, subscribe an email for reveal-time notification
- **Verify creator identity** — look up an author's verified email/handle by public-key fingerprint
- **Rotate API keys** — issue a new key with a grace period so deployments can roll over without downtime

## Use cases for AI agents

- Provably commit to predictions before outcomes are known
- Schedule time-locked announcements or reveals
- Timestamp ideas, designs, or hypotheses before exposure (`intent: "proof"`)
- Seal informal agreements between agents or between an agent and a human (`intent: "commitment"`)
- Author reply-qubs that link back to a parent qub via `reply_to` (qub_id inside the encrypted envelope) and `parent_tx_id` (public storage tag) — the conversational viral loop
- Create verifiable audit trails with cryptographic timing guarantees
- Build workflows that trigger on qub unlock events

## API

Base URL: `https://qub.social`

### Authentication

Agent integrations authenticate with an API key. Pass it in the
`Authorization` header:

```
Authorization: Bearer qub_sk_...
```

Required for `/api/v1/seal`, `/api/v1/webhooks`, and key rotation.
For `/api/v1/upload`, `/api/v1/upload-auth`, and the pact endpoints,
the API key is also accepted (browser callers without one supply a
Cloudflare Turnstile token in the request body as `turnstile_token`).

### Endpoints

| Method | Path | Auth | Description |
|--------|------|------|-------------|
| GET | `/api/v1/qub/{tx_id}` | Optional | Read qub status and content (JSON) |
| GET | `/api/v1/qub/{tx_id}/meta` | None | Lightweight metadata read (no decrypt). Returns `arweave_block_timestamp`, `intent`, `parent_tx_id` (reply-chain back-link), `author_fingerprint` (Author tag — the lookup key for the §9.5 attestation chain), `watching` (live watch count), `reactions` (called_it / wrong / total tallies for revealed predictions), and `denylisted` (moderation flag the embed iframe gates on). The viewer and the `<qub-embed>` iframe re-poll this every 30s during countdown; polling halts in the final minute before unlock. |
| GET | `/api/v1/qub/{tx_id}/bytes` | None | Raw sealed CBOR bytes (R2 cache-aside, immutable caching). Used by embed + SPA for client-side decrypt. |
| POST | `/api/v1/qub/{tx_id}/watch` | None | Increment the pre-reveal "watching" counter for social proof |
| POST | `/api/v1/qub/{tx_id}/view` | None | Increment the post-reveal view counter |
| POST | `/api/v1/qub/{tx_id}/verdict-watch` | None | Commit to watching for the verdict on a verdict-bearing qub. Per-device deduped (re-click no-op; unsubscribe doesn't decrement). Body: `{ device_id }`. Returns `{ count, watching }`. |
| GET | `/api/v1/qub/{tx_id}/verdict-watch` | None | Read the current verdict-watcher count without modifying the set. Used by the reveal-page 30s poll. |
| POST | `/api/v1/qub/{tx_id}/notify` | None | Subscribe an email to be notified when the qub unlocks |
| POST | `/api/v1/qub/{tx_id}/react` | None | Record a `called_it` / `wrong` reaction for a revealed prediction; returns updated tallies |
| POST | `/api/v1/seal` | API key | Create a qub (server-side encryption) |
| POST | `/api/v1/upload` | API key or Turnstile | Upload pre-sealed CBOR (client-side encryption) |
| POST | `/api/v1/upload-auth` | API key or Turnstile | Pre-check upload eligibility |
| GET | `/api/v1/entitlements` | None | Check device tier and remaining qubs |
| POST | `/api/v1/api-keys/rotate` | API key | Rotate the current API key, returns the new secret with a grace period |
| GET | `/api/v1/api-keys/mine` | Magic-link (device_id) | List the API keys owned by the verified email — backs `/developer/keys` |
| PATCH | `/api/v1/api-keys/{keyHash}` | Magic-link (device_id) | Update label / cap / IP allowlist / scope / disabled on a key the caller owns |
| GET | `/api/v1/handle/{handle}` | None | Public handle reverse lookup. Resolves a handle to its owning fingerprint and attestation record. 60-second edge cache. Used by viewer surfaces and `@handle` autocomplete. |
| POST | `/api/v1/webhooks` | API key | Register unlock notification webhook |
| GET | `/api/v1/webhooks` | API key | List registered webhooks |
| DELETE | `/api/v1/webhooks/{id}` | API key | Remove a webhook |
| POST | `/api/v1/pact/stage` | API key or Turnstile | Stage a signed pact envelope for co-signing |
| GET | `/api/v1/pact/stage/{id}` | None | Review a staged pact's terms and metadata |
| POST | `/api/v1/pact/cosign/{id}` | API key or Turnstile | Co-sign a staged pact and trigger upload to permanent storage |
| DELETE | `/api/v1/pact/stage/{id}` | API key or Turnstile | Retract a staged pact before co-signing (proof-of-possession required) |
| POST | `/api/v1/pact/invite/accept` | None | One-click accept of a pact invite from the email link — writes the cosign-enabling marker; the email click proves email control |
| GET | `/api/v1/pacts/mine` | None | Cross-device list of staged pacts authored by the device's linked email |
| GET | `/api/v1/identity/attestation/{fingerprint}` | None | Look up the attestation for a public key fingerprint |
| GET | `/api/v1/openapi.json` | None | OpenAPI 3.1 specification |
| GET | `/api/v1/og/{tx_id}.png` | None | Dynamic Open Graph image (sealed: reveal date + watching count; revealed: called-it percentage). R2 cache-aside. |
| GET | `/c/{tx_id}` | None | Viewer page (HTML for browsers, OG meta tags for bots, redirects to JSON for `Accept: application/json`) |
| GET | `/s/{code}` | None | 7-character short-URL redirect (302) to `/c/{tx_id}`. Allocated at upload and seal time; preferred for share surfaces because it saves ~56 characters vs the full storage `tx_id`. |
| GET | `/oembed` | None | oEmbed discovery endpoint for auto-embedding qub viewer cards on WordPress, Notion, Medium, Substack |

### Creating a qub (server-side seal)

```
POST /api/v1/seal
Authorization: Bearer qub_sk_...
Content-Type: application/json

{
  "body": "My prediction: the market will close above 5000 on Friday.",
  "unlock_at": 1746057600,
  "sender_label": "Agent Smith",
  "title": "Q1 BTC call"
}
```

`title` is optional — a short plaintext label (≤100 NFC code points,
no control characters) shown on the viewer countdown before reveal.
Bound to `qub_id` via `title_hash`, so a gateway cannot swap it.
Omit the field to leave the countdown without a creator-set title.

The `Author` tag is **opt-in per qub**: API callers attach
their fingerprint by passing `author_fingerprint` (64-char lowercase
hex of the signing pubkey, PROTOCOL.md §2.2) on the upload request.
Omit the field to seal an unattributed qub — nothing in permanent
storage links it to a creator. Attribution is decided per qub and is
permanent once written.

Response:

```json
{
  "tx_id": "abc123...",
  "delivery_url": "https://qub.social/c/abc123...",
  "short_delivery_url": "https://qub.social/s/aB12xYz",
  "qub_id": "f955de1c...",
  "unlock_at": 1746057600,
  "drand_round": 17754411
}
```

The `short_delivery_url` is present when a 7-character base62 short code was allocated at seal time; prefer it for social-channel share surfaces (tweets, QR matrices) because it saves ~56 characters vs the `/c/{tx_id}` form. Both URLs resolve to the same viewer page. Absent if allocation failed transiently — `delivery_url` is always usable as a fallback.

Note: The server-side seal endpoint passes plaintext through the server for convenience. For end-to-end encryption where plaintext never leaves your machine, use the MCP server.

### Reading a qub

```
GET /api/v1/qub/{tx_id}
```

Returns JSON with `status: "locked"` (with countdown metadata) or `status: "unlocked"` (with verified body content).

### Webhooks

Register a webhook to be notified when a qub unlocks:

```
POST /api/v1/webhooks
Authorization: Bearer qub_sk_...
Content-Type: application/json

{
  "tx_id": "abc123...",
  "url": "https://your-agent.example/callback",
  "secret": "your-hmac-secret-min-16-chars"
}
```

All three fields are required. `secret` must be at least 16 characters. The callback receives a POST with the qub data and an `X-Qub-Signature` HMAC-SHA256 header computed with `secret`.

### Notify-me (email subscription)

For human-facing flows where a webhook isn't appropriate, an email address can be subscribed to a sealed qub. The Worker's reveal-time cron sends a one-shot email when the qub unlocks. No verification step — best-effort delivery.

```
POST /api/v1/qub/{tx_id}/notify
Content-Type: application/json

{
  "email": "alice@example.com",
  "unlock_at": 1746057600,
  "locale": "en",
  "intent": "prediction"
}
```

Hard-capped at 1000 subscribers per qub. Rate-limited 5/min/IP. Response is always `{"ok": true}` on success — the user shouldn't be able to enumerate which qubs already have a given subscriber.

`intent` is optional and accepts `prediction | letter | secret | announcement | thesis | commitment | proof | verdict`. The eighth value, `verdict`, is system-emitted — only the `/verdict/{tx_id}` flow produces verdict-tagged qubs; agents should not pass it directly when sealing. When supplied, the reveal email uses an intent-aware subject and body where a per-intent template exists (e.g. "The prediction reveals now." instead of the generic "The qub just revealed."); intents without a per-intent template fall through to the generic copy. Unknown values are silently dropped server-side and fall back to the generic template — sending an unrecognised intent never errors.

### Engagement counters

Lightweight social-proof counters. Both endpoints are unauthenticated, rate-limited 10/min/IP, and return the new count.

```
POST /api/v1/qub/{tx_id}/watch          → { "count": 42 }              // pre-reveal
POST /api/v1/qub/{tx_id}/view           → { "count": 318 }             // post-reveal
POST /api/v1/qub/{tx_id}/verdict-watch  → { "count": 1248, "watching": true }
    // verdict-bearing qubs only — per-device deduped; body { device_id }
GET  /api/v1/qub/{tx_id}/verdict-watch  → { "count": 1248 }            // poll
```

### Pact staging (bilateral agreements)

A pact is a structured agreement between two parties, sealed as a qub with content type `0x03`. The staging flow:

1. **Party A stages** — sends a signed envelope containing the pact terms (title, key-value terms, party identifiers, optional notes) via `POST /api/v1/pact/stage`. Returns a `staging_id`. The Worker also emails Party B a link `https://qub.social/p/<staging_id>?t=<token>` carrying an HMAC-signed invite token.
2. **Party B accepts the invite** — clicks the email link. The client posts the token to `POST /api/v1/pact/invite/accept`, which writes the cosign-enabling marker; the email click proves email control.
3. **Party B reviews** — fetches the staged pact via `GET /api/v1/pact/stage/{id}`. Returns the CBOR envelope, terms summary, and Party A's public key.
4. **Party B co-signs** — sends their signature via `POST /api/v1/pact/cosign/{id}`. The Worker merges both signatures into the envelope and uploads to permanent storage. Returns the `tx_id` and delivery URL.
5. **Retraction** — Party A can retract before co-signing via `DELETE /api/v1/pact/stage/{id}` (proof-of-possession required).
6. **Cross-device discovery** — Party A on a new device can fetch their staged pacts via `GET /api/v1/pacts/mine?device_id=<id>` (resolves to the linked email and returns the `pact-by-email:*` author index).

Staged pacts expire after 7 days if not co-signed.

### Identity attestation lookup

Authors can link a verified email and a personalised handle to their
signing key so viewers can see who wrote a qub. Agents can verify
that link by looking it up by fingerprint:

```
GET /api/v1/identity/attestation/{fingerprint}
→ { "fingerprint": "...", "email": "...", "handle": "@alice", "verified_at": 1746057600 }
```

`fingerprint` is the lowercase 64-char hex of `SHA3-256(pubkey)` — the
same value returned in the `Author` tag and in `getQubMeta`'s
`author_fingerprint` field. Returns 404 if no attestation exists for
that fingerprint.

Establishing or revoking an attestation is a creator-side flow done in
the qub web app (email-confirmation challenge + ML-DSA-65 proof of
possession) and is not part of the agent API surface.

## MCP Server

For Claude and other tool-using LLMs, install the qub MCP server:

```json
{
  "mcpServers": {
    "qub": {
      "command": "qub-mcp",
      "env": { "QUB_API_KEY": "qub_sk_..." }
    }
  }
}
```

The MCP server encrypts locally using the same cryptographic library as the web app — plaintext never leaves your machine. Tools: `create_qub`, `read_qub`, `check_status`.

The MCP server is intentionally minimal — it covers the core seal/read/status operations and nothing else. For notify-me, engagement counters, identity linking, webhooks, and key rotation, use the HTTP API directly.

## Protocol

- **Encryption (inner):** drand timelock encryption (tlock) using the quicknet chain (BLS12-381, 3-second rounds). The qub cannot be opened until drand publishes the relevant round signature — qub does not run drand and cannot ask it to publish ahead of time.
- **Encryption (outer wrapper):** every upload to permanent storage is also AES-256-GCM-wrapped (PROTOCOL.md §13). The 32-byte wrapper key K rides as the URL fragment of the delivery URL (`#<base64url(K)>`); browsers do not transmit URL fragments to servers, so neither qub nor any storage gateway is byte-aware of K. Wrapped bytes in permanent storage are byte-indistinguishable from arbitrary ciphertext, closing the bulk-decrypt enumeration channel that the inner protocol layer alone left open.
- **Storage:** permanent public storage (immutable, censorship-resistant) — qub does not control it.
- **Hashing:** SHA3-256 for content integrity. The 32-byte `qub_id` preimage is 92 bytes covering version, content type, created/unlock timestamps, body hash, and the SHA3-256 of the optional NFC-normalised title (so a gateway cannot swap a title without the qub failing verification).
- **Authorship signing:** ML-DSA-65 (FIPS 204, post-quantum) — opt-in, keypair stays on the creator's device; verifiers don't need qub online to check it.
- **Public attribution:** opt-in per qub via the `Author` tag. There is no creator-keyed index on the qub side; the public profile at `/u/<handle>` is a verified-identity card and does not list a creator's qubs.
- **Serialisation:** Canonical CBOR (RFC 8949 deterministic profile).
- **Verification:** Any third party can independently verify a qub without qub's cooperation.

## Links

- Website: https://qub.social
- Full bundle (llms.txt + protocol + agent reference, single file): https://qub.social/llms-full.txt
- API spec: https://qub.social/api/v1/openapi.json
- Protocol spec: https://qub.social/protocol
- Sitemap: https://qub.social/sitemap.xml
- MCP discovery: https://qub.social/.well-known/mcp.json
- Source: https://github.com/qubsocial/qub-public


---

# Protocol Specification

Source: https://qub.social/protocol

qub is a protocol for cryptographic temporal commitments: a system for sealing words to a future date and proving, when that date arrives, exactly what was said and when.

Three primitives make it work. **drand** is a decentralised randomness beacon — the reveal date is enforceable by physics, not by any party's goodwill. **Permanent public storage** is a tamper-proof public store — no party can edit or delete a qub once it has been sealed. **ML-DSA-65** is a post-quantum digital signature — each qub is tied to a key pair whose secret never leaves the author's device.

Together these primitives make a statement that is time-locked, tamper-evident, and attributable — a receipt whose value grows as the world's ability to fabricate the past improves.

The remainder of this document is the normative specification required for interoperable implementations.

______________________________________________________________________

# qub Protocol Specification

| Field | Value |
| ----------- | ----------------------------- |
| **Version** | 1.0 (protocol version `0x01`, outer wrapper version `0x01`) |
| **Date** | 2026-05-01 |
| **Status** | Draft |
| **Reviewed through** | 2026-05-01 |

This document is the normative protocol specification for the qub timed commitment system. It defines data structures, serialisation rules, derivation formulas, and verification procedures required for interoperable implementations.

Scope: the protocol layer is intentionally language-neutral — the qub body is opaque plaintext / markdown / pact bytes, and locale-aware rendering is the viewer's responsibility (qub.social web app, `<qub-embed>` iframe, MCP clients, etc.).

______________________________________________________________________

## 1. Notation and Conventions

| Notation | Meaning |
| ------------------ | ----------------------------------------------- |
| `u8`, `u64`, `i64` | Unsigned/signed integers of specified bit width |
| `[u8; N]` | Fixed-length byte array of N bytes |
| `Vec<u8>` | Variable-length byte array |
| `Option<T>` | Value of type T, or absent |
| `String` | UTF-8 text string, NFC normalised |
| `||` | Byte concatenation |
| `SHA3-256(x)` | NIST SHA3-256 hash of byte string x (FIPS 202) |
| `ceil(x)` | Ceiling function: smallest integer ≥ x |
| CBOR | Concise Binary Object Representation (RFC 8949) |
| big-endian | Most significant byte first |

All integers in preimage constructions are encoded as **big-endian** fixed-width byte arrays (i64 → 8 bytes, u8 → 1 byte) unless otherwise specified.

All timestamps are **Unix seconds in UTC**.

______________________________________________________________________

## 2. Data Structures

### 2.1 ComposeQub (Creator In-Memory State)

Not serialised to CBOR. Not written to permanent storage. Local to the creator app.

```text
ComposeQub {
    draft_id:       [u8; 16],        // Random, generated locally
    created_at:     i64,             // Unix seconds UTC
    unlock_at:      Option<i64>,     // Unix seconds UTC; None while composing
    visibility:     u8,              // 0x01 = public (only value in MVP)
    content_type:   u8,              // 0x01 = text (only value in MVP)
    plaintext:      Vec<u8>,         // UTF-8 qub body
    sender_label:   Option<String>,  // Decorative display name; not authenticated
    status:         DraftStatus,     // Composing | Sealed | Uploaded | Failed
}
```

### 2.2 QubEnvelope (Decrypted Payload)

Serialised using canonical CBOR (§3). Encrypted inside the `SealedQub`. This is the structure that proves content integrity after decryption.

```text
QubEnvelope {
    version:             u8,              // Protocol major version (0x01 for v1)
    qub_id:              [u8; 32],        // Derived (see §4.1)
    content_type:        u8,              // Content type registry (see §6)
    created_at:          i64,             // Unix seconds UTC
    unlock_at:           i64,             // Unix seconds UTC
    outcome_at:          Option<i64>,     // V1.1 — when reality renders judgment (verdict-uplift-plan §3.1)
    sender_label:        Option<String>,  // Decorative; not authenticated in MVP
    reply_to:            Option<[u8; 32]>,// Parent qub_id for reply chains; not in qub_id preimage; not signed (see §9.3)
    body:                Vec<u8>,         // Content payload (UTF-8 for text, CBOR for pact)
    body_hash:           [u8; 32],        // SHA3-256(body) (see §4.2)
    sig_alg:             u8,              // Signature algorithm (see §9.2)
    author_signature:    Option<Vec<u8>>, // Set when sig_alg != 0x00
    author_pubkey:       Option<Vec<u8>>, // Set when sig_alg != 0x00
    cosigner_pubkey:     Option<Vec<u8>>, // Set for cosigned pact bilateral agreements
    cosigner_signature:  Option<Vec<u8>>, // Set for cosigned pact bilateral agreements
}
```

**Baseline (unsigned text qub):** `version` = `0x01`, `content_type` = `0x01`, `sig_alg` = `0x00`, all `Option` fields absent.

**Other v1 configurations:** `content_type` = `0x03` (pact body, see §6.1); `sig_alg` = `0x01` (ML-DSA-65) with `author_signature` and `author_pubkey` present (see §9.3); `cosigner_pubkey` and `cosigner_signature` present together for cosigned pacts (see §9.7); `reply_to` set to the parent qub's `qub_id` for reply-chain qubs (see §9.3 for the signature-scope implications).

### 2.3 SealedQub (Canonical Wire Format)

Serialised using canonical CBOR (§3). Written to permanent storage. This is the on-chain artifact.

```text
SealedQub {
    version:           u8,              // Protocol major version (0x01 for v1)
    qub_id:            [u8; 32],        // Same as QubEnvelope.qub_id
    visibility:        u8,              // 0x01 = public; v1 viewers reject other values
    unlock_at:         i64,             // Unix seconds UTC
    outcome_at:        Option<i64>,     // V1.1 — surfaced on the verdict-watch CTA
                                        //   before reveal; mirrors QubEnvelope.outcome_at;
                                        //   bound to qub_id via the §4.1 preimage.
    drand_chain_id:    String,          // drand chain hash (hex string)
    drand_round:       u64,             // Target drand round number
    tlock_ciphertext:  Vec<u8>,         // tlock-encrypted QubEnvelope CBOR bytes
    recipient_pubkey:  Option<[u8; 32]>,// Reserved field; accepted by canonical CBOR
                                        //   but not interpreted by the v1 reference viewer
    title:             Option<String>,  // Plaintext title surfaced on the viewer
                                        //   countdown before reveal. Bound to qub_id
                                        //   via title_hash (§4.1). 1..=100 NFC code
                                        //   points, no control characters.
}
```

### 2.4 RevealedQub (Viewer Application State)

Not serialised to CBOR. Local to the viewer app. Constructed after successful decryption and verification.

```text
RevealedQub {
    qub_id:              [u8; 32],
    arweave_tx_id:       String,
    visibility:          u8,
    content_type:        u8,
    created_at:          i64,
    unlock_at:           i64,
    outcome_at:          Option<i64>,       // V1.1 — carried forward from QubEnvelope.outcome_at / SealedQub.outcome_at; drives the reveal-page verdict-watch block (verdict-uplift-plan §5.1)
    drand_chain_id:      String,
    drand_round:         u64,
    sender_label:        Option<String>,
    title:               Option<String>,    // Carried forward from SealedQub.title
    reply_to:            Option<[u8; 32]>,
    body:                Vec<u8>,
    body_hash:           [u8; 32],
    body_hash_verified:  bool,
    author_signature:    Option<Vec<u8>>,
    author_pubkey:       Option<Vec<u8>>,
    signature_verified:  Option<bool>,
    cosigner_pubkey:     Option<Vec<u8>>,
    cosigner_signature:  Option<Vec<u8>>,
    cosigner_verified:   Option<bool>,
}
```

______________________________________________________________________

## 3. Canonical CBOR Profile

All `SealedQub` and `QubEnvelope` serialisation MUST conform to this profile. Two implementations given the same logical structure MUST produce identical bytes.

### 3.1 Encoding Rules

| Rule | Specification |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Standard | RFC 8949 §4.2.1 (Core Deterministic Encoding Requirements) |
| Map key ordering | Sorted by **encoded byte length** first (shorter before longer), then **lexicographically** (byte-by-byte for same-length encodings) |
| Integer encoding | Shortest form: 0–23 in initial byte; 24–255 in 2 bytes; 256–65535 in 3 bytes; etc. |
| Length encoding | **Definite lengths only.** No indefinite-length arrays, maps, byte strings, or text strings (additional info = 31 is forbidden). |
| Tags | **No CBOR tags** (major type 6 is forbidden). |
| Floating-point | **No floats** (major types 7 values 0xF9–0xFB are forbidden). |
| Text strings | UTF-8 encoded, **NFC normalised** (Unicode Normalization Form C). |
| Byte strings | Raw bytes. No base64 encoding at the CBOR layer. |
| Duplicate keys | **Reject with error.** Parsers MUST NOT silently accept duplicate map keys. |
| Simple values | Only `true` (0xF5), `false` (0xF4), and `null` (0xF6) are permitted. |
| Optional fields | Absent optional fields are **omitted** from the CBOR map entirely (not encoded as `null`). Present optional fields are included in sorted key order. |

### 3.2 Verified Canonical Key Orders

These key orders are normative. Implementations MUST emit keys in exactly this order. Debug assertions SHOULD verify ordering in non-release builds.

**QubEnvelope (version 0x01, unsigned, all optional fields absent):**

```text
"body"                (5 encoded bytes)
"qub_id"              (7 encoded bytes)
"sig_alg"             (8 encoded bytes)
"version"             (8 encoded bytes)
"reply_to"            (9 encoded bytes)   ← only if present (reply chains)
"body_hash"           (10 encoded bytes)
"unlock_at"           (10 encoded bytes)
"created_at"          (11 encoded bytes)
"outcome_at"          (11 encoded bytes)  ← only if present (V1.1 verdict mechanic)
"content_type"        (13 encoded bytes)
"sender_label"        (13 encoded bytes)  ← only if present
"author_pubkey"       (14 encoded bytes)  ← only if present
"cosigner_pubkey"     (16 encoded bytes)  ← only if present (pact cosign)
"author_signature"    (17 encoded bytes)  ← only if present
"cosigner_signature"  (19 encoded bytes)  ← only if present (pact cosign)
```

**QubEnvelope key order derivation:** each key is a CBOR text string. Encoded length = 1 byte header + string length (for strings under 24 bytes). Sort by total encoded length first, then lexicographically for same-length keys.

**SealedQub (version 0x01, public, no recipient):**

```text
"title"             (6 encoded bytes)   ← only if present
"qub_id"            (7 encoded bytes)
"version"           (8 encoded bytes)
"unlock_at"         (10 encoded bytes)
"outcome_at"        (11 encoded bytes)  ← only if present (V1.1 verdict mechanic)
"visibility"        (11 encoded bytes)
"drand_round"       (12 encoded bytes)
"drand_chain_id"    (15 encoded bytes)
"recipient_pubkey"  (17 encoded bytes)  ← only if present
"tlock_ciphertext"  (17 encoded bytes)
```

**PactTerms (pact body, content_type `0x03`):**

```text
"notes"         (6 encoded bytes)  ← only if present
"terms"         (6 encoded bytes)
"title"         (6 encoded bytes)
"party_a"       (8 encoded bytes)
"party_b"       (8 encoded bytes)
"pact_version"  (13 encoded bytes)
```

**PactTerm (row of the `terms` array):**

```text
"key"    (4 encoded bytes)
"value"  (6 encoded bytes)
```

**PartyIdentifier (party_a / party_b map):**

```text
"label"    (6 encoded bytes)
"contact"  (8 encoded bytes)  ← only if present
```

### 3.3 Byte Encoding Reference

| Type | CBOR encoding | Example |
| ---------------------------------- | ---------------------------------------------------------- | ----------------- |
| SHA3-256 hash (32 bytes) | `0x58 0x20` + 32 bytes | body_hash, qub_id |
| Timestamps (i64) | Major type 0 (positive) or 1 (negative), shortest encoding | Unix seconds |
| Version (u8, value 1) | `0x01` (single byte) | |
| Content type (u8, value 1) | `0x01` (single byte) | |
| sig_alg (u8, value 0) | `0x00` (single byte) | |
| ML-DSA-65 signature (3,309 bytes) | `0x59 0x0C 0xED` + 3,309 bytes | author_signature, cosigner_signature |
| ML-DSA-65 public key (1,952 bytes) | `0x59 0x07 0xA0` + 1,952 bytes | author_pubkey, cosigner_pubkey |

______________________________________________________________________

## 4. Normative Derivations

### 4.1 qub_id

The `qub_id` uniquely identifies a qub and binds the QubEnvelope to the SealedQub. It is derived deterministically from envelope content.

```text
qub_id = SHA3-256(
    "QUB_ID_V2"          ||  // domain separator: ASCII bytes [0x51 0x55 0x42 0x5F 0x49 0x44 0x5F 0x56 0x32] (9 bytes) + 0x00 padding (1 byte) = 10 bytes
    version              ||  // u8 (1 byte)
    content_type         ||  // u8 (1 byte)
    created_at           ||  // i64 big-endian (8 bytes)
    unlock_at            ||  // i64 big-endian (8 bytes)
    outcome_at_or_zero   ||  // i64 big-endian (8 bytes; 0 when outcome_at is absent)
    drand_round          ||  // u64 big-endian (8 bytes)
    body_hash            ||  // [u8; 32] (32 bytes)
    title_hash               // [u8; 32] (32 bytes; absent-sentinel = [0u8; 32])
)
// Total preimage: 108 bytes → 32-byte output
```

**Domain separator encoding:** The string `"QUB_ID_V2"` is 9 ASCII bytes. A single `0x00` padding byte is appended to reach 10 bytes for alignment. Implementations MUST use exactly these 10 bytes: `[0x51, 0x55, 0x42, 0x5F, 0x49, 0x44, 0x5F, 0x56, 0x32, 0x00]`.

**`outcome_at` encoding:** V1.1 extended the preimage from 92 to 100 bytes to fold the optional `outcome_at` field into the binding. Absent `outcome_at` is encoded as 8 zero bytes; the protocol validators reject `outcome_at <= 0` everywhere so this sentinel cannot collide with a legitimate value. See §3.2 (wire format) and the in-tree `tasks/verdict-uplift-plan.md` for the verdict mechanic that motivates this field.

**`drand_round` encoding:** V1.2 extended the preimage from 100 to 108 bytes to fold `drand_round` (the target drand round, §4.3) into the binding, and bumped the domain separator to `QUB_ID_V2`. This binds the timelock round into the qub identity: a gateway cannot rebind the ciphertext to a different (e.g. already-past) round than the displayed `unlock_at` implies. The unlock procedure (§8) additionally verifies that the round baked into the tlock ciphertext stanza matches `unlock_round(unlock_at)`, so the displayed unlock time is provably the round that gates decryption.

**Properties:**

- Changing any field in the QubEnvelope (body, timestamps, content type, version) produces a different qub_id.
- The qub_id is computed before encryption. Both QubEnvelope and SealedQub carry the same qub_id. The viewer verifies they match after decryption.
- qub_id does not depend on `sender_label`, `author_signature`, or `author_pubkey`. This means the same content sealed at the same time produces the same qub_id regardless of who signs it.
- Changing the SealedQub `title` (with everything else fixed) changes `qub_id` via `title_hash`. A gateway therefore cannot swap the plaintext title displayed on the countdown without invalidating the qub identity.
- Changing the SealedQub `outcome_at` (with everything else fixed) changes `qub_id` via the preimage. A gateway cannot swap the pre-reveal verdict-on date displayed on the countdown without invalidating the qub identity.
- Changing `drand_round` (with everything else fixed) changes `qub_id` via the preimage. A gateway cannot rebind the timelock ciphertext to a different round without invalidating the qub identity; combined with the §8 unlock-time stanza-round check, the displayed `unlock_at` is the round that actually gates decryption.

### 4.2 body_hash

```text
body_hash = SHA3-256(body)
```

Where `body` is the raw `Vec<u8>` content payload. For text qubs, this is the UTF-8 encoded qub body.

### 4.2.1 title_hash

```text
title_hash = SHA3-256(NFC(title).utf8_bytes)   if title is present
title_hash = [0u8; 32]                         if title is absent
```

Where `title` is the optional plaintext title surfaced on the viewer countdown before reveal (see §3.2). NFC normalisation runs at hash time so the digest is stable across visually-equivalent code-point sequences. The all-zeros sentinel is reserved for the absent case; an empty string is rejected at the canonical CBOR boundary as a non-canonical encoding of "absent" (the canonical encoding omits the field entirely).

### 4.3 Unlock-Round Mapping

```text
drand_round = ceil((unlock_at - chain_genesis_time) / chain_period_seconds)
```

| Parameter | Source | Example |
| ---------------------- | --------------------------------- | -------------------------------------- |
| `unlock_at` | User-chosen Unix seconds UTC | `1735689600` (2025-01-01 00:00:00 UTC) |
| `chain_genesis_time` | drand chain info (`genesis_time`) | `1595431050` |
| `chain_period_seconds` | drand chain info (`period`) | `30` |

The `ceil()` operation selects the **first drand round whose reveal time is ≥ unlock_at**. This ensures the qub does not become decryptable before the chosen unlock time.

**Edge case:** if `(unlock_at - chain_genesis_time)` is exactly divisible by `chain_period_seconds`, the result is that exact round — the qub unlocks precisely at that round’s reveal time.

**Validation:** `unlock_at` MUST be in the future at seal time. `unlock_at` MUST NOT be more than 10 years from `created_at` (to limit long-horizon drand dependency risk; the UI SHOULD warn for unlock dates beyond 2 years).

______________________________________________________________________

## 5. Wire Format Newtypes

Wire format newtypes provide compile-time safety against confusing CBOR bytes with JSON, raw plaintext, or other byte encodings.

| Type | Contains | Produced By | Consumed By |
| ----------------- | ----------------------------- | -------------------------- | ----------------------------------------- |
| `SealedQubCbor` | Canonical CBOR of SealedQub | `serialize_sealed_qub()` | Permanent-storage upload, viewer fetch |
| `QubEnvelopeCbor` | Canonical CBOR of QubEnvelope | `serialize_qub_envelope()` | tlock encrypt input, tlock decrypt output |

### 5.1 Construction Rules

```rust
// Production code — only through CBOR serialisers:
let sealed = SealedQubCbor::from_encoded(cbor_bytes);

// There is deliberately NO From<Vec<u8>> implementation.
// You cannot accidentally wrap arbitrary bytes in a wire format type.

// Accessing raw bytes:
let bytes: &[u8] = sealed.as_bytes();
let bytes: Vec<u8> = sealed.into_bytes();
```

### 5.2 Validation on Construction

`from_encoded()` SHOULD validate that the input begins with a valid CBOR map header. Full structural validation happens at parse time, not construction time, to avoid double-parsing.

______________________________________________________________________

## 6. Content Type Registry

| Value | Type | Max Body Size | Notes |
| ------ | --------------------------------------- | ----------------------- | --------------------------------------------------------------------- |
| `0x00` | Reserved (invalid) | — | MUST NOT be used |
| `0x01` | Plain text (UTF-8, restricted Markdown) | 50 KB paid / 10 KB free | See §10 for rendering rules. The free / paid split is enforced by the upload service; the protocol-layer hard ceiling is 50 KB. |
| `0x02` | Reserved (future) | — | Allocated for a future content type; not valid in v1. Viewers MUST reject per the rule below. |
| `0x03` | Pact (bilateral agreement, CBOR body) | 100 KB | Body is canonical CBOR `PactTerms` (§6.1). Cosigner signing per §9.7. |
| `0x04` | Verdict (creator self-grading, CBOR body) | 8 KB | Body is canonical CBOR `VerdictBody` (§6.2). Emitted only by the system-side `verdict` intent. Parent relationship is on the `Parent-Tx-Id` Arweave tag, not on the body. See verdict-uplift-plan §3.4. |

Viewers MUST reject unknown content types with a clear user-visible error. Viewers MUST NOT attempt to render unknown types as text.

### 6.1 Pact Body (`content_type = 0x03`)

A pact body is the canonical CBOR encoding of a `PactTerms` value:

```text
PactTerms {
    pact_version:  u8,                    // 0x01 for structured/v1
    title:         String,                // ≤ 200 bytes, NFC
    terms:         Vec<PactTerm>,         // ≤ 20 rows
    party_a:       PartyIdentifier,       // initiator
    party_b:       PartyIdentifier,       // counter-signer
    notes:         Option<String>,        // ≤ 5,000 bytes, NFC; absent key if none
}

PactTerm       { key: String (≤ 100), value: String (≤ 2,000) }   // NFC on both sides
PartyIdentifier{ label: String (≤ 100), contact: Option<String (≤ 320)> }
```

Canonical CBOR key orders for all three maps are given in §3.2. Total serialised pact CBOR MUST NOT exceed 100 KB (matches §6).

**Schema discriminator.** The first row in `terms` for a `structured/v1` pact MUST be `{ key: "pact_schema", value: "structured/v1" }`. Rows without this marker are "custom" pacts and receive no structured validation or schema-aware rendering.

**Frozen acknowledgement slots.** `structured/v1` pacts carry exactly four acknowledgement rows under these keys:

```text
"initiator_standard_terms"
"initiator_capacity_terms"
"counterparty_standard_terms"
"counterparty_capacity_terms"
```

The `value` for each is one of eight frozen English strings chosen by the `(role, kind)` pair, where `role ∈ { seller, buyer, provider, client }` and `kind ∈ { standard, capacity }`. The strings themselves are **normative protocol data** — both parties' ML-DSA-65 signatures commit to the exact bytes via `body_hash`. They are NOT localised; the signed body is language-neutral. Any wording change requires a new schema version (`structured/v2`).

The eight strings, their lookup (`acknowledgement_for(role, kind)`), and the rationale for each are pinned by the reference implementation. Conforming implementations MUST emit byte-identical acknowledgement values; golden-fixture SHA3-256 body-hash tests covering all four role combinations catch any drift.

**Viewer display order.** The acknowledgement strings contain phrases such as "described above", which presume the description / scope rows render ahead of the acknowledgements. Viewers MUST render the `terms` array in CBOR order; reordering breaks the prose semantics.

**Counter-party contact.** When Party B's `contact` is a valid email address, the qub upload service auto-dispatches a review / co-sign invite email at stage time and binds the eventual co-sign to verification of that same address (§9.7). Pacts whose Party B contact is absent can still be co-signed, but only through an out-of-band channel — the service refuses co-sign requests that cannot produce a matching 15-minute email-verification marker.

### 6.2 Verdict Body (`content_type = 0x04`)

A verdict body is the canonical CBOR encoding of a `VerdictBody` value:

```text
VerdictBody {
    verdict_version: u8,                  // 0x01 for structured/v1
    outcome:         u8,                  // 1=Right · 2=Partial · 3=Wrong · 4=Unfalsifiable
    reflection:      Option<String>,      // ≤ 2,000 bytes NFC; "what changed, what did you learn"
    evidence_url:    Option<String>,      // ≤ 2,048 bytes; HTTPS only; absent key when omitted
}
```

Canonical CBOR key order:

```text
"outcome"          (8 encoded bytes)
"reflection"       (11 encoded bytes)  ← only if present
"evidence_url"     (13 encoded bytes)  ← only if present
"verdict_version"  (16 encoded bytes)
```

Total serialised verdict CBOR MUST NOT exceed **8 KB** (matches the registry row above).

**Outcome enum.** The wire byte is intent-neutral; the four buckets `Right` / `Partial` / `Wrong` / `Unfalsifiable` cover every verdict-bearing intent's outcome space. Per-intent labels ("Called it" / "Kept it" / "Shipped" / "Confirmed" for `Right`, etc.) are a viewer-side rendering concern resolved against the parent qub's intent — the wire stays language- and intent-neutral. Values outside `1..=4` MUST be rejected at decode.

**Parent linkage.** A verdict qub does NOT carry the parent reference in its body. The parent qub's Arweave transaction id is emitted as the `Parent-Tx-Id` storage tag at upload time (§7 storage-tag layer). This keeps the body a self-contained signed statement of self-assessment; the audit chain ("right about what?") is established via the Arweave-tag lookup.

**Evidence URL safety (normative).** When `evidence_url` is present, validators (compose-side, wire-side, Worker edge) MUST enforce:

1. **HTTPS only.** The string MUST start with the byte sequence `https://`. Any other scheme — `http`, `ftp`, `javascript`, `data`, `file`, etc. — is rejected.
1. **Length cap.** ≤ 2,048 bytes (browser URL practical limit).
1. **NFC + hostile-codepoint check.** Same rule as `title` and `reflection` — bidi-override / zero-width / tag-block / BOM / C0 / C1 codepoints are rejected. Definition matches the Rust `crate::handle::contains_hostile_text_codepoint` and the TS `workers/api/src/utils/unicode.ts::isHostileCodepoint` (keep in lockstep).
1. **No whitespace, no ASCII controls.** Whitespace / DEL / sub-`0x20` bytes anywhere in the URL are rejected — closes the `\n`/`\t` injection vector the bidi rule doesn't cover.
1. **Non-empty host segment.** Everything between `https://` and the first `/`, `?`, or `#` MUST be non-empty.

**No server-side fetching.** The Worker MUST NOT proxy, fetch, or preview the URL. The protocol stores a string; rendering happens viewer-side with `rel="nofollow noopener noreferrer" target="_blank"` and a visible host displayed alongside the link text.

**Reflection.** Optional creator-written reflection text ("what changed, what did you learn"). Same NFC + hostile-codepoint validation as `title`. Empty / whitespace-only input collapses to absent at construction time.

**Schema version.** v1 supports `verdict_version = 0x01` only. Future schema revisions bump this byte and land alongside a new protocol version per §12.

______________________________________________________________________

## 7. Seal Protocol

The complete seal sequence. Each step is normative.

```text
 1. User composes plaintext and metadata in ComposeQub.
 2. Validate:
    a. body is non-empty.
    b. body size ≤ max for content_type and user tier (see §6).
    c. unlock_at is in the future.
    d. unlock_at ≤ created_at + 10 years.
    e. content_type is a known, supported value.
 3. Compute body_hash = SHA3-256(body).
 4. Set created_at = current Unix seconds UTC.
 5. Select drand chain. Load chain_genesis_time and chain_period_seconds, and
    compute drand_round = ceil((unlock_at - chain_genesis_time) / chain_period_seconds).
    (Computed here, before qub_id, because drand_round is bound into the qub_id
    preimage — §4.1, V1.2.)
 6. Compute qub_id (see §4.1), folding in drand_round from step 5.
 7. Construct QubEnvelope with all fields.
 8. Serialise QubEnvelope using canonical CBOR → bytes B.
    Assert: serialised output matches canonical profile (§3).
 9. Compute C = tlock_encrypt(B, drand_round, drand_chain_public_key).
10. Construct SealedQub with tlock_ciphertext = C, and matching qub_id, version,
    unlock_at, drand_chain_id, drand_round.
12. Serialise SealedQub using canonical CBOR → SealedQubCbor.
12a. Generate K = 32 random bytes (CSPRNG) and N = 12 random bytes (CSPRNG).
     Compute W = wrap_sealed_qub(SealedQubCbor, qub_id=qub_id, key=K, nonce=N)
     per §13. The bytes uploaded to permanent storage are the OuterWrapper CBOR W,
     never the bare SealedQubCbor. K leaves the device only as the URL
     fragment in step 16.
13. Display seal-time disclosure. User confirms.
14. Validate upload eligibility via the qub upload service (bot-detection, entitlement, rate limits).
15. Submit W (the OuterWrapper bytes) to the qub upload service; the service
    signs and uploads to permanent storage. The service is byte-blind to the inner
    SealedQubCbor and never receives K.
16. Receive arweave_tx_id from the service. Construct delivery URL as
    `<origin>/c/<arweave_tx_id>#<base64url(K)>` (or `<origin>/s/<short_code>#<base64url(K)>`
    when a short code is allocated). Browsers do not transmit URL fragments
    to servers, so K is never observed by qub.social or any storage gateway.
```

**Storage tag layer (out-of-band).** The qub upload service attaches a deliberately small set of storage transaction tags alongside the wrapped payload. `Content-Type=application/octet-stream` is normatively required. The reference service additionally attaches three optional tags when the creator chooses to surface them: `Intent` (allowlist-validated compose intent — e.g., `quote`, `reply`, `commitment`), `Author` (creator's §9.3 pubkey fingerprint as 64-char lowercase hex), and `Parent-Tx-Id` (parent qub's storage transaction id for reply chains, 43-char base64url).

The `Author` tag is **opt-in per qub**: the reference creator app attaches it only when the user explicitly enables public attribution at seal time. When the toggle is off — the default — no `Author` tag is written and the qub is unattributed on the chain: nothing in permanent storage links the upload to a creator's handle, email, or other qubs. When the toggle is on, the `Author` fingerprint resolves to the creator's chosen `@handle` via the §9.5 attestation chain. Reply-chain relationships and `Intent` are non-identifying. The outer wrapper (§13) protects the inner *body* from ciphertext correlation — preventing a harvester from recognising and bulk-decrypting qub-shaped uploads after their drand round publishes.

The reference service intentionally does NOT attach `App-Name`, `App-Version`, or `Type` tags: any such single-value filter would return the entire qub corpus to a GraphQL query, which is inconsistent with the wrapper's body-only confidentiality scope.

A conforming verifier MUST NOT depend on any storage tag for §11 third-party verification; the body hash / qub_id / signature commit only to the inner CBOR, never to the tag set.

______________________________________________________________________

## 8. Unlock Protocol

The complete unlock sequence. Each step is normative.

```text
 1. Viewer opens delivery URL. Extract arweave_tx_id from path AND
    K = base64url_decode(fragment) from the URL fragment. If the fragment
    is absent or malformed → display "this URL is missing its decryption
    key" and stop; the viewer MUST NOT contact the storage gateway
    without K, since fetching wrapped bytes the viewer cannot decrypt
    serves no purpose and only leaks the access attempt.
 2. Check denylist. If tx_id is denylisted → display block message. Stop.
 3. Fetch OuterWrapper bytes from permanent storage (with multi-gateway fallback).
 3a. Unwrap: parse the bytes as OuterWrapper (§13), verify the wrapper
    `version` byte is `0x01`, and compute SealedQubCbor =
    unwrap_sealed_qub(OuterWrapper, key=K). Any AEAD authentication
    failure (wrong K, tampered ciphertext, swapped qub_id-as-AAD,
    swapped nonce) → display "this URL's decryption key does not match
    the stored qub" and stop. Authentication failures are
    indistinguishable to the viewer per §13.5.
 4. Parse SealedQubCbor → SealedQub.
 5. Validate: SealedQub.version is known (0x01). Reject unknown versions.
 6. If current time < SealedQub.unlock_at → display countdown. Poll or wait.
 6a. Round-binding check (V1.2). Recompute expected_round =
    ceil((SealedQub.unlock_at - chain_genesis_time) / chain_period_seconds).
    Reject unless SealedQub.drand_round == expected_round AND the round baked
    into the tlock ciphertext stanza (read via the age/tlock header, no signature
    required) == expected_round. The stanza round is the one that actually gates
    decryption; without this check a malicious creator could bind the ciphertext
    to an already-past round while displaying a future countdown, so anyone
    reading the stored bytes could decrypt before unlock_at. Implementations with
    no chain identity (test mocks) skip this check.
 7. Once current time ≥ SealedQub.unlock_at:
    a. Fetch drand round signature for SealedQub.drand_round from drand network.
    b. Compute B = tlock_decrypt(SealedQub.tlock_ciphertext, round_signature).
 8. Parse B → QubEnvelope.
 9. Validate QubEnvelope.version is known.
10. Verify: SHA3-256(QubEnvelope.body) == QubEnvelope.body_hash.
    Fail → integrity error.
11. Verify: QubEnvelope.qub_id == SealedQub.qub_id.
    Fail → integrity error.
12. Verify: QubEnvelope.unlock_at == SealedQub.unlock_at.
    Fail → integrity error.
13. Verify: QubEnvelope.content_type is known and renderable.
    Known values: 0x01 (text), 0x03 (pact). Unknown → display error.
14. If QubEnvelope.sig_alg != 0x00 → verify author signature (see §9.4).
15. If cosigner_pubkey or cosigner_signature present → verify cosigner (see §9.7).
16. Render content using appropriate renderer (see §10 for text, §6 for pact).
17. Construct RevealedQub for display.
```

______________________________________________________________________

## 9. Authorship Signing

### 9.1 Rationale

Qubs are stored in permanent storage. Authorship signatures must remain unforgeable indefinitely, which is why v1.0 uses the post-quantum ML-DSA-65 scheme (FIPS 204) rather than a classical scheme whose security may degrade within the qub’s permanent lifetime.

### 9.2 Algorithm Registry

| `sig_alg` | Scheme | Key Size | Signature Size |
| --------- | ----------------------- | ----------- | -------------- |
| `0x00` | No signature (unsigned) | — | — |
| `0x01` | ML-DSA-65 (FIPS 204) | 1,952 bytes | 3,309 bytes |

Viewers MUST reject unknown `sig_alg` values.

### 9.3 Signed Preimage Construction

```text
sig_input = SHA3-256(
    "QUB_AUTHOR_SIG_V1"  ||    // domain separator (17 bytes)
    version              ||    // u8 (1 byte)
    qub_id               ||    // [u8; 32] (32 bytes)
    body_hash            ||    // [u8; 32] (32 bytes)
    unlock_at            ||    // i64 big-endian (8 bytes)
    0x00                       // u8 (1 byte): MUST be 0x00 in v1.0
)

// Total preimage: 91 bytes → 32-byte hash

signature = Sign(author_secret_key, sig_input)
```

**Domain separator:** `"QUB_AUTHOR_SIG_V1"` is 17 ASCII bytes: `[0x51, 0x55, 0x42, 0x5F, 0x41, 0x55, 0x54, 0x48, 0x4F, 0x52, 0x5F, 0x53, 0x49, 0x47, 0x5F, 0x56, 0x31]`. No padding.

**Trailing byte:** the 91st preimage byte MUST be `0x00`. The reference implementation exposes this as the constant `ORG_ID_PRESENT_INDIVIDUAL = 0x00` in `crates/qub-core/src/signing.rs`; viewers reconstructing `sig_input` for verification MUST emit the same byte.

**Signature scope — what is and isn't covered.** `sig_input` commits to four envelope fields: `version`, `qub_id`, `body_hash`, `unlock_at` (plus the fixed domain separator and `org_id_present` byte). Three of those four are structural invariants: `qub_id` is itself derived from `version`, `content_type`, `created_at`, `unlock_at`, `outcome_at`, `drand_round`, and `body_hash` via the §4.1 preimage, so any change to those fields produces a different `qub_id` and invalidates the signature transitively. The directly-authenticated surface is therefore:

| Field | Authenticated by signature | How |
| ------------------------- | :-: | --- |
| `version` | ✓ | Direct input to `sig_input` |
| `qub_id` | ✓ | Direct input |
| `body_hash` | ✓ | Direct input |
| `unlock_at` | ✓ | Direct input |
| `content_type` | ✓ | Transitively, via `qub_id` preimage |
| `created_at` | ✓ | Transitively, via `qub_id` preimage |
| `outcome_at` | ✓ | Transitively, via `qub_id` preimage |
| `drand_round` | ✓ | Transitively, via `qub_id` preimage (V1.2) |
| `body` | ✓ | Transitively, via `body_hash = SHA3-256(body)` |
| `author_pubkey` | — (implicit) | Key that verified the signature is the author, by definition |
| `sender_label` | **✗** | Display-only text; mutable without signature breakage |
| `reply_to` | **✗** | Threading pointer; mutable without signature breakage |
| `cosigner_pubkey` / `cosigner_signature` | — | Independently signed over the same `sig_input` (see §9.7) |
| `drand_chain_id`, `tlock_ciphertext`, `visibility` | — | Outer `SealedQub` fields, not inside the envelope — covered by their own structural invariants (round / chain consistency) but not by the author signature. (`drand_round` is now bound transitively via the `qub_id` preimage — see above.) |

**Security implications of non-authenticated fields.**

- A party with write access to the stored bytes could swap `sender_label` ("Alice" → "Mallory") without invalidating the author signature. The `author_pubkey` inside the envelope remains the true identity anchor — viewers MUST derive the display identity from `author_pubkey` (via the §9.5 attestation layer) rather than trusting `sender_label`.
- A `reply_to` field can likewise be edited post-signing. Because `qub_id` is content-addressed, an attacker can't point `reply_to` at a non-existent target, but they can silently re-parent a reply to a different existing qub.

Implementations that display `sender_label` or `reply_to` to end users MUST surface the authenticated identity (pubkey fingerprint, attestation) as the primary identity signal, not the label.

### 9.4 Verification Procedure

```text
1. Read sig_alg from QubEnvelope.
2. If sig_alg == 0x00 → unsigned. No verification. Display "unsigned qub."
3. If sig_alg is unknown → reject. Display "unrecognised signature scheme."
4. Extract author_signature and author_pubkey. If either is absent → integrity error.
5. Reconstruct sig_input using fields from QubEnvelope (same formula as §9.3).
6. Verify(author_pubkey, sig_input, author_signature).
7. If verification succeeds → display "signed by [key fingerprint]."
8. If verification fails → display "signature verification failed."
```

Signature verification is the most expensive operation (especially ML-DSA-65). It SHOULD be performed after all cheaper checks (hash, qub_id, unlock_at) have passed.

### 9.5 Identity Attestations

Identity attestations — the mapping of `author_pubkey` to human-recognisable identity claims such as a qub handle, email address, social handle, or passkey credential — are a **viewer-side progressive enhancement** and are **not required** for signature verification. Viewers that resolve attestations to a display identity MUST apply the precedence:

```text
handle > email > social > fingerprint
```

The fingerprint fallback is the lowercase hex of `SHA3-256(author_pubkey)`; it is always available for any signed qub. Viewers MAY abbreviate it for display — the reference viewer renders `qub:` followed by the first and last four bytes (`qub:<8 hex>…<8 hex>`).

A conforming verifier can complete every check in §9.4 without contacting the qub API, without any network beyond permanent storage and drand, and without any server-side lookup. Attestation resolution is a separate best-effort step performed only after signature verification has succeeded.

### 9.6 Size Impact

| | Ed25519 | ML-DSA-65 |
| ------------------------------ | -------- | ----------- |
| Signature | 64 bytes | 3,309 bytes |
| Public key | 32 bytes | 1,952 bytes |
| Total per qub | 96 bytes | 5,261 bytes |
| Storage cost delta (at ~$5/MB) | ~$0.0005 | ~$0.026 |

For a text qub of 500–2,000 bytes, ML-DSA-65 roughly triples the stored size. The absolute cost is negligible.

### 9.7 Cosigner Verification (Pact Bilateral Agreements)

For bilateral agreements (`content_type` = `0x03`), a second signature layer proves both parties consented to the same terms.

**Envelope fields:**

- `cosigner_pubkey`: ML-DSA-65 public key of the counter-signer (Party B).
- `cosigner_signature`: Signature over the same `sig_input` as the author (§9.3).

Both fields MUST be present together or both absent. If exactly one is present, viewers MUST report an integrity error.

**Verification procedure:**

```text
1. If cosigner_pubkey absent and cosigner_signature absent → no cosigner. Done.
2. If exactly one is present → integrity error.
3. Verify cosigner_pubkey != author_pubkey (prevent self-cosigning).
   Fail → display "cosigner pubkey must differ from author."
4. Reconstruct sig_input using the same formula as §9.3.
5. Verify(cosigner_pubkey, sig_input, cosigner_signature).
6. Success → display "co-signed by [cosigner fingerprint]."
7. Failure → display "co-signature verification failed."
```

**Properties:**

- The cosigner signs the identical `sig_input` as the author — both parties commit to the same `qub_id`, `body_hash`, and `unlock_at`.
- `qub_id` derivation (§4.1) does NOT include cosigner fields. Adding a cosigner to an existing envelope does not change the `qub_id`.
- A pact can be author-signed only (one-sided commitment), cosigner-only (unusual), or both (full bilateral proof).

**Email-binding gate (operational).** When a staged pact carries a Party B email contact (§6.1), the qub upload service MUST refuse the co-sign request unless a short-lived email-verification marker exists matching both the staging id and the normalised-email hash of that contact. The marker is written by `/api/v1/auth/verify` when the magic-link token carries a `staging_id` and the verified address matches `SHA-256(normalise_email(party_b.contact))` — where `normalise_email(addr)` preserves the local-part case and lowercases only the domain part (per RFC 5321 §2.3.11), and `SHA-256` here is the NIST FIPS 180-4 hash (distinct from the SHA3-256 used in §4 derivations) — and expires 900 seconds (15 minutes) after issue. This is an operational anti-impersonation gate, NOT part of the on-chain qub proof — a third-party verifier replaying §11 needs only permanent storage and drand, without any server-side lookup. The marker exists server-side only and is never part of the signed body.

**Size impact (ML-DSA-65 author + cosigner):**

| Component | Size |
| ------------------------- | ---------------- |
| Author signature | 3,309 bytes |
| Author public key | 1,952 bytes |
| Cosigner signature | 3,309 bytes |
| Cosigner public key | 1,952 bytes |
| **Total crypto overhead** | **10,522 bytes** |
| Storage cost delta | ~$0.05 |

______________________________________________________________________

## 10. Markdown Rendering and Sanitisation

This section is security-critical. The viewer renders text qubs (`content_type` = `0x01`) using a restricted Markdown subset.

### 10.1 Allowed Elements

- Headings: `#` through `####` (no `#####` or `######`)
- Emphasis: bold (`**`), italic (`*`), strikethrough (`~~`)
- Lists: ordered (`1.`) and unordered (`-`, `*`)
- Blockquotes (`>`)
- Code: inline spans (\`\`\`) and fenced blocks (\`\`\`\`\`)
- Horizontal rules (`---`)
- Line breaks (two trailing spaces or blank line)
- Paragraphs

### 10.2 Forbidden Elements

| Element | Handling |
| ------------------------------------ | ------------------------------------------------------------------------------------------------ |
| Raw HTML (`<div>`, `<script>`, etc.) | Stripped entirely. No HTML passes through. |
| Images (`![alt](url)`) | Stripped. Image syntax is removed from output. |
| Links (`[text](url)`) | URL rendered as visible plain text. Not auto-linked. Not clickable without explicit user action. |
| Dangerous URL schemes | `javascript:`, `data:`, `vbscript:`, `file:` — stripped. |
| Iframes, embeds, objects | Stripped. |
| HTML entities | Decoded to display characters only if safe. |

### 10.3 Implementation

Implementations MUST use a **strict allowlist parser**, not a blocklist. The recommended approach:

1. Parse Markdown using `pulldown-cmark` (or equivalent).
1. Walk the AST and drop any node not in the allowlist (§10.1).
1. For link nodes: emit the URL as visible text, not as a clickable `<a>` element.
1. Convert the filtered AST into a **typed intermediate representation** (e.g., a `MarkdownNode` enum with only safe variants). Raw HTML is structurally unrepresentable in this IR.
1. Render from the typed IR to the target view layer (e.g., reactive view components, DOM nodes). No HTML string concatenation or `innerHTML` at any point.

Blocklist approaches are fragile because new Markdown extensions or parser quirks can introduce unfiltered elements. The typed-AST approach makes XSS structurally impossible — there is no variant that can carry arbitrary HTML.

### 10.4 Size and Structure Limits

- Maximum rendered heading depth: `####` (H4). `#####` and deeper are rendered as bold text.
- No limit on paragraph count (body size limits in §6 are the constraint).
- Fenced code blocks: no syntax highlighting in MVP. Rendered as monospace preformatted text.

______________________________________________________________________

## 11. Third-Party Verification

Any third party can verify a public qub without qub cooperation. The verification procedure:

```text
1. Obtain arweave_tx_id (from delivery URL or direct knowledge).
2. Fetch SealedQubCbor from any storage gateway.
3. Confirm storage block inclusion (block height, block timestamp).
4. Parse SealedQubCbor → SealedQub.
5. Fetch drand round signature for SealedQub.drand_round.
6. tlock_decrypt(tlock_ciphertext, round_signature) → QubEnvelope CBOR bytes.
7. Parse → QubEnvelope.
8. Verify SHA3-256(body) == body_hash.
9. Verify QubEnvelope.qub_id == SealedQub.qub_id.
10. Verify QubEnvelope.unlock_at == SealedQub.unlock_at.
11. If sig_alg != 0x00: verify author_signature (see §9.4).
12. All checks pass → qub is verified.
```

**What verification proves:**

| Proof | What it establishes |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Commitment | The ciphertext existed by the storage block timestamp. |
| Integrity | The plaintext body matches the committed hash and has not been altered. |
| Timing | The content was unreadable until the drand round, which corresponds to the chosen unlock time (subject to tlock and drand security assumptions). |

**What verification does NOT prove:**

| Non-proof | Why |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorship | The `sender_label` is decorative. Without `sig_alg` ≥ `0x01`, anyone could have sealed this content. |
| Intent | The qub proves content and timing, not what the creator subjectively meant. |
| Pre-event timing | Storage block inclusion may lag actual upload by minutes. The commitment timestamp is the block time, not the moment the user pressed “seal.” |

______________________________________________________________________

## 12. Versioning

### 12.1 Protocol Version

The `version` field (u8) in both `SealedQub` and `QubEnvelope` identifies the major protocol version.

- Viewers MUST reject unknown major versions with a clear error.
- Known major versions MAY tolerate unknown optional fields if forward compatibility rules allow (optional fields absent from the canonical key order are ignored).
- Content types (`content_type`) and signature schemes (`sig_alg`) are version-gated: new values may only be introduced alongside a new protocol version or explicit registry update.

### 12.2 Version History

| Version | Value | Description |
| ------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| v1 | `0x01` | Public text qubs (`content_type 0x01`), pact bilateral agreements (`0x03`, `structured/v1` schema, ML-DSA-65 author + cosigner), tlock, SHA3-256 |

### 12.3 Forward Compatibility

A v1 viewer encountering a QubEnvelope with unknown optional CBOR map keys (keys not in the §3.2 canonical order) SHOULD ignore those keys and proceed with verification using known fields. This allows future minor additions (e.g., new metadata) without requiring a major version bump.

A v1 viewer encountering `sig_alg` = `0x01` (ML-DSA-65) but lacking ML-DSA-65 verification support SHOULD display the qub content with a “signature present but not verifiable” notice, not reject the qub entirely. The reference implementation today rejects every `sig_alg` value other than `0x00` and `0x01` because the v1 registry contains no other valid algorithm — strict rejection and soft-fail are observationally identical until a third algorithm is registered. The soft-fail behaviour above becomes load-bearing once §9.2 admits a new entry, and the reference viewer will be updated to soft-fail at that point.

### 12.4 Outer Wrapper Version

The OuterWrapper described in §13 carries its own `version` byte, **independent** of `SealedQub.version` and `QubEnvelope.version`. The two version spaces evolve separately: a future post-quantum-safe symmetric replacement bumps the wrapper byte without touching the inner protocol version, and a future protocol-layer addition (e.g., a new envelope field) bumps the inner version without touching the wrapper byte.

| `OUTER_WRAPPER_VERSION_*` | Value | Algorithm | Status |
| ------------- | ------ | --------- | ------ |
| `OUTER_WRAPPER_VERSION_1` | `0x01` | AES-256-GCM with 12-byte nonce, 16-byte authentication tag, AAD bound to `qub_id` | v1 default |
| — | `0x02`–`0xFF` | Reserved | Future |

Viewers MUST reject unknown wrapper versions with a clear error. The protocol intentionally keeps the wrapper version space narrow until a concrete migration driver appears (e.g., NIST guidance favouring a different AEAD); a `0x02` slot will be allocated in the same revision that introduces the algorithm.

______________________________________________________________________

## 13. Outer Encryption Wrapper

### 13.1 Rationale

The protocol layers (`QubEnvelope` → tlock → `SealedQub`) make a sealed qub **time-locked**: the body is unreadable until `unlock_at` and the drand round signature has been published. After unlock, however, the round signature is public and the canonical CBOR shape of `SealedQub` is recognisable, so a harvester who indexed permanent-storage transactions could bulk-decrypt the entire qub corpus.

The outer encryption wrapper closes that channel by interposing an additional symmetric AEAD layer between the canonical `SealedQubCbor` and the bytes written to permanent storage. The 256-bit key `K` lives **only** in the URL fragment of the delivery URL and on user devices; browsers do not transmit URL fragments to servers, so qub.social, every storage gateway, and every CDN in front of either is observationally blind to `K`. Every qub in permanent storage is therefore an opaque ciphertext whose plaintext is irrecoverable without the URL the creator chose to share.

Net effect:

- **Enumeration immunity by default.** Wrapped bytes in permanent storage are byte-indistinguishable from arbitrary ciphertext. A harvester strategy of "GraphQL-query for qub-shaped uploads, bulk-decrypt with public drand signatures" does not terminate with plaintext.
- **Crypto-shredding privacy posture.** qub.social literally cannot decrypt its own corpus. Subpoenas reach ciphertext, not plaintext.
- **Two-tier confidentiality ladder.** Default = link-controlled access (this section). Recipient-encrypted private qubs (a reserved Phase-2 feature, not yet specified) layer on top as the second tier.

### 13.2 Layering

```text
plaintext body                       ← QubEnvelope.body (§2.2)
  ↓ canonical CBOR (§3)
envelope CBOR
  ↓ tlock encrypt to drand round (§7 step 10)
tlock_ciphertext (inside SealedQub) (§2.3)
  ↓ canonical CBOR (§3)
SealedQubCbor bytes                  ← inner wire artifact
  ↓ AES-256-GCM(K, nonce, AAD=qub_id) (§7 step 12a, this section)
OuterWrapper CBOR bytes              ← uploaded to permanent storage (§7 step 15)
```

Seal and unlock at the protocol layer (§7, §8) are unchanged below the wrapper boundary; the wrapper attaches at the call site of `seal()` and detaches at the call site of `unlock()`.

### 13.3 OuterWrapper Data Structure

```rust
struct OuterWrapper {
    version:    u8,           // 0x01, see §12.4
    qub_id:     [u8; 32],     // copied from inner SealedQub; AEAD AAD
    nonce:      [u8; 12],     // 96-bit AEAD nonce
    ciphertext: Vec<u8>,      // AES-256-GCM(K, nonce, SealedQubCbor, AAD=qub_id) || 16-byte tag
}
```

**Field invariants.**

- `version` MUST equal `0x01` for v1.0 wrapper bytes.
- `qub_id` MUST equal the `qub_id` field of the SealedQub recovered after unwrapping. The unwrap step does not enforce this directly (the AEAD AAD binding makes byte-level tampering impossible), but the unlock layer checks the relationship transitively: if a creator wraps a `SealedQubCbor` whose inner `qub_id` does not match the wrapper `qub_id`, §8 step 11 fails.
- `nonce` MUST be 96 bits (12 bytes), generated fresh by a CSPRNG for every wrap operation. Reusing a nonce under the same key permits AEAD nonce-reuse attacks that recover the plaintext; producers MUST treat (`key`, `nonce`) pairs as one-shot.
- `ciphertext` is the AES-256-GCM output: ciphertext bytes concatenated with the 16-byte authentication tag. `ciphertext.len() == SealedQubCbor.len() + 16` exactly.

**CBOR encoding.** Canonical CBOR per §3, with the same key-ordering rule (sorted by encoded byte length ascending, then lexicographically). The four keys are:

| Key | Encoded bytes | Order |
| --- | ------------: | ----: |
| `nonce` | 6 | 1 |
| `qub_id` | 7 | 2 |
| `version` | 8 | 3 |
| `ciphertext` | 11 | 4 |

The first byte of the OuterWrapper CBOR is therefore the definite-length map header for a 4-entry map (`0xA4`).

### 13.4 AAD Binding to `qub_id`

The wrapper binds `qub_id` as AEAD additional authenticated data. This is the load-bearing structural defence against three classes of attack:

| Attack | Defence |
| ------ | ------- |
| Move ciphertext under a different `qub_id` field in the wrapper | AAD mismatch → AEAD authentication fails |
| Mix the URL fragment of qub A with the permanent-storage bytes of qub B | AAD mismatch → AEAD authentication fails |
| Tamper with the `qub_id` field of the wrapper after upload | AAD mismatch → AEAD authentication fails |

Carrying `qub_id` in the wrapper plaintext does not weaken enumeration immunity meaningfully — `qub_id` is itself a SHA3-256 hash of the §4.1 preimage with no recoverable preimage from the digest, and an enumerator who already harvested the wrapper bytes learns nothing from the visible `qub_id` that they could not infer from the existence of the upload itself.

### 13.5 Wrap and Unwrap Algorithms

```text
wrap_sealed_qub(SealedQubCbor S, qub_id Q, key K, nonce N):
    require K.len() == 32 and N.len() == 12 and Q.len() == 32
    C := AES_256_GCM_encrypt(key=K, nonce=N, msg=S, aad=Q)
    // C includes the 16-byte authentication tag at the end
    return canonical_cbor_encode(OuterWrapper{
        version:    0x01,
        qub_id:     Q,
        nonce:      N,
        ciphertext: C,
    })

unwrap_sealed_qub(OuterWrapper bytes W, key K):
    require K.len() == 32
    O := canonical_cbor_decode(W) as OuterWrapper
    require O.version == 0x01           // §12.4
    P := AES_256_GCM_decrypt(
            key=K, nonce=O.nonce, ciphertext=O.ciphertext, aad=O.qub_id
         )
    // any AEAD failure → DECRYPT_FAILED, indistinguishable to caller
    return P                            // P is the inner SealedQubCbor
```

**Failure-mode collapse.** Wrong `K`, wrong nonce, AAD mismatch, and tampered ciphertext all produce the same `DECRYPT_FAILED` error. This is a deliberate AEAD property: distinguishing the failure mode would create a side channel a remote attacker could probe by sending malformed wrappers and timing the response. Reference implementations MUST collapse all AEAD failures to a single error shape.

### 13.6 Key Material and Distribution

The wrapping key `K` is a 256-bit uniform random value generated per-qub by a CSPRNG. The reference implementations source it from:

- WASM creator: `getrandom` (WebCrypto under the `wasm_js` backend).
- Worker server-side seal route: `crypto.getRandomValues`.

Distribution: `K` MUST be encoded as URL-safe base64 (RFC 4648 §5, no padding) and appended to the delivery URL as the fragment component:

```text
delivery_url = <origin>/c/<arweave_tx_id>#<base64url(K)>
```

The fragment is never transmitted to any server by a conforming browser. Recovery channels (server-side history index, opt-in email auto-send) that persist the full delivery URL — including the fragment — beyond the user's device are an explicit trade against the default crypto-shredding posture and MUST be gated on explicit user consent.

**Fragment loss.** If a user loses the URL fragment and has no recovery channel, the qub is unreadable. This is the load-bearing trade-off of the design and MUST be disclosed to the user at seal time. The MVP strengthens the seal-time disclosure with explicit "save this URL" copy and a verified-email recovery channel for users who opt in.

### 13.7 Out-of-Scope for this Section

- Authorship signing (§9) is unchanged: signatures are computed inside the inner `QubEnvelope` and are recovered after unwrap → tlock decrypt → CBOR parse.
- Recipient-encrypted private qubs (a reserved Phase-2 feature, not yet specified) compose on top of this wrapper as a second confidentiality tier; both tiers can be active simultaneously.
- Pacts (§6, content_type `0x03`) are wrapped exactly like text qubs; the wrapper is byte-blind to inner content type.

### 13.8 Public qubs (wrapper omission)

The outer wrapper is **optional at the delivery layer**. A creator may seal a qub as **public**, in which case the canonical `SealedQubCbor` is written to permanent storage **directly**, with no `OuterWrapper` layer and no key `K`:

```text
SealedQubCbor bytes  ──(public)──▶  uploaded to permanent storage as-is
SealedQubCbor bytes  ──(private)─▶  AES-256-GCM(K, …) ▶ OuterWrapper ▶ uploaded
```

A public qub is **time-locked but not link-gated**: it stays unreadable until its drand round publishes (the tlock layer is unchanged), but after unlock anyone who has the `arweave_tx_id` can decrypt it — no URL fragment is required, because there is no `K`. This is the deliberate trade for surfaces the server must drive: reveal-notification emails, third-party embeds, and richer post-reveal SEO all need a link that works without a secret the server never holds (§13.6).

Consequences a producer MUST account for:

- **No enumeration immunity.** Public qubs forgo the §13.1 enumeration-immunity property by construction. The reference upload service stamps a `Visibility: public` permanent-storage tag on them (and only them) so they are intentionally discoverable; private qubs carry no such tag and keep their byte-indistinguishability.
- **Plaintext title exposed at seal time.** The §3.2 `title` field is plaintext inside `SealedQubCbor`. Under the wrapper it is hidden until a viewer supplies `K`; without the wrapper it is world-readable on permanent storage **from the moment of upload**, before unlock. Conforming creator apps MUST disclose this at seal time.
- **Detection is structural.** A conforming viewer/embed distinguishes the two shapes by parse: bytes that parse as `OuterWrapper` take the unwrap-with-`K` path; bytes that parse as a bare `SealedQubCbor` are accepted directly. No wire flag is required, and `qub_id` does not bind visibility — the same content is byte-identical at the `SealedQub` layer whether sealed public or private.

Private (wrapped) remains the default; public is an explicit per-qub creator choice.

______________________________________________________________________

## 14. Test Vectors

### 14.1 qub_id Derivation

```text
Input:
  version      = 0x01
  content_type = 0x01
  created_at   = 1735689600 (2025-01-01 00:00:00 UTC)
  unlock_at    = 1736294400 (2025-01-08 00:00:00 UTC)
  outcome_at   = absent
  drand_round  = 4695445  (= (1736294400 - 1595431050) / 30, drand mainnet params §14.2)
  body         = "Hello, future."  (UTF-8, 14 bytes)
  title        = absent

Intermediate:
  body_hash  = SHA3-256("Hello, future.")
             = 76ab8b3f843c6ed4f2d0fd75b9f457b4
               ad49dd4450f9c22723ae430e3af3211d
  title_hash = [0u8; 32]   (title absent — §4.2.1 sentinel)

Domain separator (10 bytes):
  [0x51, 0x55, 0x42, 0x5F, 0x49, 0x44, 0x5F, 0x56, 0x32, 0x00]

Preimage (108 bytes — V1.2):
  domain_separator    ||  // 10 bytes
  0x01                ||  // version
  0x01                ||  // content_type
  0x0000000067748580  ||  // created_at as i64 big-endian (1735689600)
  0x00000000677DC000  ||  // unlock_at as i64 big-endian (1736294400)
  0x0000000000000000  ||  // outcome_at_or_zero (outcome_at absent)
  0x000000000047A595  ||  // drand_round as u64 big-endian (4695445)
  body_hash           ||  // 32 bytes
  title_hash              // 32 bytes (all-zeros sentinel; title absent)

Expected output:
  qub_id = SHA3-256(preimage)
         = 3a9fcb31b750d985c262fada6d4f777f
           d6a28be831d941d85c131f5a4bbaf8a4
```

Implementations MUST produce identical `body_hash` and `qub_id` values for this input. This test vector SHOULD be the first unit test written. The canonical values above were computed by the reference implementation and MUST match bit-for-bit. Historical preimage layouts (pre-launch — no live qubs depended on these): the 92-byte V1.0 qub_id was `3d9fc2390eab043d38a1669ed3b71be76f9eefe872b9569ab1aaa027b88392b0`; the 100-byte V1.1 qub_id (after folding `outcome_at_or_zero`) was `b0d032898ad629795150fdcb3f84e518f59ed05b7a2a82bc24ebdb87f52144ed`. V1.2 folds `drand_round` in and bumps the domain separator to `QUB_ID_V2`.

### 14.2 Unlock-Round Mapping

```text
Input:
  unlock_at           = 1735689600
  chain_genesis_time  = 1595431050
  chain_period_seconds = 30

Calculation:
  (1735689600 - 1595431050) / 30 = 4675285.0
  ceil(4675285.0) = 4675285

drand_round = 4675285
```

### 14.3 Canonical CBOR Round-Trip

Implementations MUST verify that `serialize(parse(serialize(qub))) == serialize(qub)` for all valid inputs. This is a property test, not a single vector.

### 14.4 PactTerms CBOR (content_type 0x03)

```text
Input:
  pact_version = 1
  title        = "Scooter deposit"
  terms        = [
    { key: "Item",    value: "Honda Metropolitan scooter" },
    { key: "Price",   value: "$100" },
    { key: "Deposit", value: "$10" }
  ]
  party_a      = { label: "Alice" }
  party_b      = { label: "Bob", contact: "bob@example.com" }
  notes        = absent

Canonical CBOR key order (PactTerms):
  "notes"(6) < "terms"(6) < "title"(6) < "party_a"(8) < "party_b"(8) < "pact_version"(13)

Canonical CBOR key order (PactTerm):
  "key"(4) < "value"(6)

Canonical CBOR key order (PartyIdentifier):
  "label"(6) < "contact"(8)
```

The canonical CBOR bytes and SHA3-256 `body_hash` are computed by the reference implementation. Implementations MUST produce byte-identical CBOR for this input.

Implementations MUST also verify that `serialize(parse(serialize(pact))) == serialize(pact)` for all valid `PactTerms` inputs (property test).

### 14.5 Outer Wrapper Cross-Language Vectors

The outer wrapper (§13) has a separate canonical fixture at [`crates/qub-core/tests/vectors/wrapper_v1.json`](../../crates/qub-core/tests/vectors/wrapper_v1.json). Each case fixes a `(key, nonce, qub_id, sealed_cbor)` tuple as opaque hex inputs and asserts a specific `expected_wrapper_hex` output. Both reference implementations consume the same JSON file:

- Rust: `crates/qub-core/tests/wrapper_vectors.rs` (`cargo test -p qub-core --test wrapper_vectors`).
- TypeScript: `workers/api/src/crypto/__tests__/wrapper.test.ts` (`npm test`).

The fixture currently pins three cases:

| Case | Coverage |
| ---- | -------- |
| `basic-text-public` | Smallest realistic `SealedQub` shape; no optional fields. Establishes the canonical wrapper shape for a v1.0-typical qub. |
| `with-recipient-pubkey` | `SealedQub` with `recipient_pubkey` set (Phase 2 path). Different inner CBOR key set, different `qub_id`. |
| `longer-body` | ~4 KiB body — exercises multi-byte CBOR length prefixes inside both the inner envelope and the outer ciphertext. |

Implementations MUST produce byte-identical `expected_wrapper_hex` for the recorded inputs. Regenerating the fixture requires `QUB_REGEN_VECTORS=1 cargo test -p qub-core --test wrapper_vectors` and is reserved for deliberate format changes.

______________________________________________________________________

## 15. Crypto Profile Governance (Future)

This section is informative for v1 and becomes normative the first time a second algorithm enters any of qub's cryptographic primitives.

### 15.1 Current Posture

Protocol v1 binds exactly one algorithm per primitive:

- **Signature**: ML-DSA-65 (`sig_alg = 0x01`; 1952-byte public key, 3309-byte signature) and unsigned (`sig_alg = 0x00`). The §9.2 registry defines no other values; a v1 verifier MUST reject every `sig_alg` outside `{0x00, 0x01}`. A future Ed25519 entry is anticipated (§15.3) but is not allocated in v1.
- **Timelock**: drand quicknet only — the chain hash, public key, genesis time, and period are fixed network parameters carried by the reference `DrandTimelockProvider::quicknet()` (`crates/qub-core/src/tlock.rs`) and `config/drand-endpoints.json`.
- **Outer wrapper**: AES-256-GCM v1 only (§13).

Verifiers currently hardcode key and signature lengths per primitive. No agility surface is exposed by the wire format.

### 15.2 Intended Shape

When a second algorithm enters the protocol, the verifier will be configured for a named `CryptoProfile` (e.g., `ExqubV1`) listing the exact set of permitted values per primitive — sig_algs, drand chains, wrapper versions, content types. The profile is fixed at verify time, never negotiated in-band. Any value outside the active profile is rejected.

This guarantees that adding ML-DSA-87 or activating Ed25519 cannot retroactively weaken existing verifier configurations: a v1 verifier remains a v1 verifier even after a v2 profile is published.

### 15.3 Trigger Conditions

Promote §15 to normative status when any of the following is proposed:

- A second `sig_alg` byte (Ed25519 activation, ML-DSA-87, or any new entry in the §9 registry).
- A second drand chain in production use.
- A second outer-wrapper version.

Until then §15 is a placeholder that fixes the migration shape so future PRs land against a known target rather than re-litigating the negotiation surface from scratch.


---

# AI Agent Support — quotas, monetisation, hardening

Source: docs/AI-AGENT-SUPPORT.md

---
authority: S
status: current
reviewed-on: 2026-05-23
cadence: 90d
coupled-to:
  - workers/api/src/middleware/*
  - tools/qub-mcp/**
---

# AI Agent Hardening: Monetisation, Quotas, and Abuse Mitigation

|Field      |Value                              |
|-----------|-----------------------------------|
|**Version**|1.2                                |
|**Date**   |2026-04-18                         |
|**Status** |Draft — implementation guide       |
|**Depends**|AI agent support (shipped 2026-04-09); identity layer (Phase G, 2026-04-07); verify-gate (2026-04-10)|

> **1.2 reviewed-through (2026-04-18).** No architectural change. Reviewed against the current embed surface after the F4 polish arc closed — F4-f live watching refresh, F4-k error recoverability + skeleton, F4-l taste + a11y, F4-m state-enter fade + brand-dot pulse, plus the new F4-e BCP 47 locale infrastructure and F4-g publisher-facing contract in [`EMBED.md`](EMBED.md). API key lifecycle, quotas, and webhook hardening are orthogonal to the embed — AI agents that integrate at the API layer (`seal`, `qub-read`, webhooks) should still consult this doc; agents that only _embed_ an already-sealed qub on a third-party surface should consult `EMBED.md` and [`tools/qub-mcp/README.md`](../tools/qub-mcp/README.md) instead.

This document specifies the monetisation model, per-key quota enforcement, and abuse mitigations required before API keys are issued to external consumers. The AI agent endpoints (`seal`, `qub-read`, `upload` with API key, webhooks) are functional but currently lack payment gating, quota enforcement, and hardening against adversarial use.

-----

## 1. Current Gaps

### 1.1 Monetisation

- API keys bypass Turnstile but have no payment attached.
- The `POST /api/v1/seal` endpoint requires a valid key but does not check entitlements or quotas.
- Every sealed qub costs real AR tokens from the server wallet. There is no mechanism to recover this cost from API consumers.
- There is no relationship between API keys and Stripe customers.

### 1.2 Abuse Vectors

|Vector                |Risk                                                                                   |Severity (current)|
|----------------------|---------------------------------------------------------------------------------------|------------------|
|Storage cost drain    |Each seal/upload burns AR from the server wallet permanently                           |Critical          |
|Key proliferation     |Manual key provisioning and Stripe customer linking exist, but a single actor can still issue multiple keys via separate Stripe customers. Per-key quotas + the daily storage-spend ceiling cap the blast radius.|Medium (was High) |
|Sybil free-tier       |Anonymous browsers could previously create unlimited free-tier qubs by clearing IndexedDB. The Phase G identity layer + the verify-gate (2026-04-10) bind the free tier to an email-verified identity from the second qub onwards.|Medium (was High) |
|Webhook relay abuse   |Webhook URL validation rejects HTTPS-on-private-IPs and requires ownership verification (challenge/response). Mandatory shared secret prevents unauthenticated relay.|Low (was High)    |
|Content liability     |The seal endpoint sees plaintext; permanent storage means no takedown possible. Mitigated by audit logging + the verify-gate (Sybil resistance) + content reporting flow.|Medium            |
|Read endpoint scraping|High-volume fetches through our Worker burn storage-gateway goodwill and compute. Mitigated by R2 response cache (Phase 3) + per-key `max_reads_per_day` quota.|Low (was Medium)  |
|Replay / stolen keys  |Key rotation endpoint with 1-hour grace period is live. Optional IP allowlist per key. No expiry yet — keys are still long-lived until rotated by the owner.|Low (was Medium)  |

### 1.3 Phase G identity status (added 2026-04-07)

The magic-link + device-linking layer added in Phase G changes the threat model for the free tier and the web app:

- **Email + device binding**: `POST /api/v1/auth/magic-link` issues an HMAC-signed, single-use token bound to `{ email, device_id }`. `POST /api/v1/auth/verify` consumes the token and writes a `VerifiedRecord` (per email, by hash) plus an `IdentityRecord` (per email) plus a reverse `device_link` index.
- **Per-identity free-tier cap**: free-tier qubs are counted against the `IdentityRecord`, not the device. A user clearing IndexedDB no longer resets their free counter.
- **Identity recovery**: `GET /api/v1/identity?device_id=...` surfaces the linked record without a magic-link round-trip — used by the post-purchase success page so the Stripe webhook can auto-link the device.
- **Token hygiene**: 15-minute expiry, single-use enforcement via the `magic:<sha256(token)>` KV gate, and HMAC verification with the `AUTH_SECRET`. Failure modes (`expired`, `bad_signature`, `malformed`, `bad_payload`, `token_used`) are tracked in `m:auth_verify_failed:<reason>:<date>` for forensic visibility.
- **The web-app verify-gate** (added 2026-04-10): an inline modal blocks the second free-tier seal until the user has linked an email. This is the moment of Sybil-resistance friction — the seal is permanent, the email is the only cross-device identity recovery path, so the user is forced to commit. Telemetry events `verify_gate_opened/submitted/success/failed` plus `m:verify_gate_*` daily counters expose the funnel for tuning.

The API surface is unchanged for AI agents — the verify-gate only applies to browser flows. Agents using `POST /api/v1/seal` or `POST /api/v1/upload` with an API key are governed by the per-key quota system in §2 instead.

-----

## 2. Per-Key Quota Model

### 2.1 Extended ApiKeyRecord

Extend the `ApiKeyRecord` stored in the `API_KEYS` KV namespace:

```
apikey:{sha256(key)} → {
  client_id:          string,
  scope:              string[],        // ["upload", "seal", "read", "webhooks"]
  rate_limit:         number,          // requests per minute
  created_at:         number,          // Unix seconds
  tier:               "free" | "builder" | "enterprise",
  qubs_remaining:     number,          // decremented on seal/upload
  qubs_total:         number,          // lifetime allocation
  reads_today:        number,          // reset daily
  max_reads_per_day:  number,
  webhook_limit:      number,          // max concurrent webhooks
  stripe_customer_id: string | null,   // null for free tier
  stripe_subscription_id: string | null,
  ip_allowlist:       string[] | null, // optional IP restriction
  disabled:           boolean,         // admin kill switch
  last_used_at:       number | null
}
```

### 2.2 Tier Definitions

|Tier       |qubs                                            |Reads                                            |Webhooks|Rate limit|Price                |
|-----------|------------------------------------------------|-------------------------------------------------|--------|----------|---------------------|
|Builder    |1,000/month base + $0.005/extra                 |100,000/month base + $0.50/100k extra            |25      |60/min    |$29 USD/mo + overage |
|Enterprise |Unlimited                                       |Unlimited                                        |250     |500/min   |Custom               |

- **No free API-key tier.** Free agentic use does not require an API key — agents seal locally via the MCP server (`tools/qub-mcp`) and upload sealed bytes through `POST /api/v1/upload` (Turnstile-gated; identity-keyed Sybil quota of `FREE_TIER_QUB_CAP` per verified email). Server-side `POST /api/v1/seal` is paid-only. The `tier: "free"` discriminant on `ApiKeyRecord` remains as a defensive guard but no provisioning path exists; admin-issued keys for special cases are the only way one comes into being.
- **MCP publishing is opt-in.** `create_qub` writes a permanent, irreversible, paid artifact to Arweave, and an MCP-connected agent is steerable by prompt injection in any document it reads — so the `qub-mcp` server disables `create_qub` unless the operator sets `QUB_MCP_ALLOW_CREATE`, and caps `unlock_at` at a configurable future horizon (default one year). The capability-scoped read tools (`read_qub`, `check_status` — the wrapper key *is* the read capability) are never gated. See `tools/qub-mcp/README.md`.
- Builder tier base counters reset monthly on `invoice.paid`. Overage past the in-base allowance flows to Stripe via the v2 MeterEvents API; an hourly cron emits one event per non-zero delta. The `invoice.upcoming` webhook force-flushes the last hour of usage so it lands on the imminent invoice. PAYMENTS.md §13.3.
- Builder customers ship with a default `max_monthly_charge_usd: 100` runaway-bill cap. When the projected end-of-period overage charge exceeds this value, the seal + read paths reject with 402 `MONTHLY_CAP_REACHED`. Self-serve at `/developer/keys` (magic-link bound) — customers can raise, lower, or clear the cap; admin endpoint `POST /api/v1/admin/api-keys/:hash/cap` is the operator backstop.
- Builder customers receive a transactional email the first time their period seal usage crosses 50%, 80%, and 100% of the base allowance. Locale-aware via the customer's `IdentityRecord.locale`. At-most-once per threshold per period; reset on `invoice.paid`. See PAYMENTS.md §16.7.
- Enterprise tier has no hard qub limit but is usage-monitored.

### 2.3 Quota Enforcement Points

|Endpoint              |Quota check                                                                                  |
|----------------------|---------------------------------------------------------------------------------------------|
|`POST /api/v1/seal`   |`disabled == false`. Builder: track `seals_used_this_period` in QuotaDO; project `MONTHLY_CAP_REACHED` against optional `max_monthly_charge_usd`. Enterprise: legacy `qubs_remaining > 0` decrement-and-reject.|
|`POST /api/v1/upload` |Identical Builder semantics; identity-keyed Sybil quota for the browser path.                |
|`GET /api/v1/qub/:id` |Builder: track `reads_used_this_period` via `ctx.waitUntil`; same `MONTHLY_CAP_REACHED` projection. Enterprise: legacy `reads_today < max_reads_per_day` increment-and-reject.|
|`POST /api/v1/webhooks`|Count existing webhooks for this key; reject if `>= webhook_limit`.                         |
|All endpoints         |`disabled == false`, rate limit per `rate_limit` field.                                      |

-----

## 3. Stripe-Provisioned API Keys

### 3.1 Self-Service Flow (Builder Tier)

```text
1. Agent owner visits qub.social/developer (or POST /api/v1/api-keys/checkout)
2. Stripe Checkout for Builder 3-item subscription:
     - $29 USD/month base
     - metered seal-overage ($0.005/qty)
     - metered read-overage ($0.50/100k qty)
3. On checkout.session.completed webhook:
   a. Generate API key: qub_sk_ + 32 random hex chars
   b. SHA256-hash the key
   c. Store ApiKeyRecord in API_KEYS KV with tier=builder,
      qubs_remaining=1000, all *_this_period counters at 0
   d. Persist key in apikey-provisioned:{session_id} (15-min TTL,
      AES-GCM-wrapped) for one-time retrieval, plus
      apikey-retrieve-bind:{session_id} holding the HMAC of the
      buyer-presented retrieval_secret (F-01 — retrieval is now
      POST with body { session_id, retrieval_secret }, the bind
      key alone is not sufficient)
4. On invoice.paid webhook (monthly renewal):
   a. Reset qubs_remaining to qubs_total (1000)
   b. Zero seals_used_this_period, reads_used_this_period,
      seals_reported_this_period, reads_reported_this_period
   c. Advance period_start from invoice.lines.data[0].period.start
   d. quotaReset on the QuotaDO so its counters mirror the KV reset
5. On invoice.upcoming webhook (~1h before invoice generates):
   a. Look up key by stripe_customer_id
   b. Force-flush via reportUsageForKey so the last hour of overage
      lands on the upcoming invoice
6. On customer.subscription.deleted webhook:
   a. Look up key by stripe_customer_id
   b. Force-flush any unreported overage (final invoice accuracy)
   c. Set disabled=true
```

### 3.2 Key Lifecycle

|Event                          |Action                                     |
|-------------------------------|--------------------------------------------|
|Subscription created           |Provision key, set tier and quotas           |
|Monthly invoice paid           |Reset qubs_remaining to tier allocation; reset all `*_this_period` counters and `notified_<pct>pct` flags|
|Subscription cancelled         |Set disabled=true                           |
|Payment failed (after retries) |Set disabled=true                           |
|Chargeback                     |Set disabled=true, flag for review          |
|Admin revocation               |Set disabled=true via denylist endpoint     |
|Customer self-disable          |`PATCH /api/v1/api-keys/:hash` body `{ disabled: true }` — same audit-log trail as admin disable|

### 3.3 Self-Serve Dashboard

`/developer/keys` is the customer-facing surface. Auth: magic-link sign-in writes a `device_link:<device_id>` → email mapping; the dashboard reads it and resolves the keys-by-email index. Per-key card supports inline label, monthly cap, IP allowlist (CIDR-aware), and disable/re-enable. Rotation runs through `POST /api/v1/api-keys/rotate` and currently requires the raw key as Bearer; an in-app rotation flow is a follow-up.

### 3.4 Enterprise Tier

Enterprise keys are provisioned manually by admin. No self-service checkout. Custom rate limits and quotas set per agreement.

-----

## 4. Webhook Hardening

### 4.1 URL Validation

On webhook creation, reject URLs that:

- Use `http://` (require HTTPS only)
- Resolve to private IP ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `169.254.0.0/16`, `::1`, `fc00::/7`
- Resolve to link-local or loopback addresses
- Contain userinfo (`https://user:pass@host`)
- Use non-standard ports (allow 443 only, or 443 + 8443)

### 4.2 Ownership Verification

On webhook creation:

```text
1. Generate a random challenge token (32 hex chars)
2. POST to the webhook URL with body: { "type": "verification", "challenge": "<token>" }
3. Expect the endpoint to respond with 200 and body containing the challenge token
4. If verification fails within 10 seconds, reject the webhook registration
5. Store the verified URL; re-verify if the URL is changed
```

This prevents registering webhooks pointing to URLs the caller does not control.

### 4.3 Delivery Constraints

|Constraint           |Value                                                     |
|----------------------|----------------------------------------------------------|
|Delivery timeout      |5 seconds per attempt                                     |
|Max retries           |10 (current), with exponential backoff (1min, 2min, 4min...)|
|Max payload size      |Response body ignored (fire-and-forget POST)              |
|Secret requirement    |Mandatory (not optional) — reject registrations without a secret|
|Concurrent deliveries |Max 10 per cron invocation (prevent Worker CPU timeout)   |

### 4.4 Per-Key Webhook Cap

Enforce `webhook_limit` from the ApiKeyRecord. Before creating a new webhook, count existing webhooks for this `api_key_hash` and reject if at or above the limit.

-----

## 5. Rate Limit Tightening

### 5.1 Per-Key Rate Limits

Authenticated callers get per-key rate limits that vary by tier. The browser (no-key) lane is enforced via per-IP limits in `kv.ts::checkRateLimit`.

|Endpoint       |Browser (no key) |Builder  |Enterprise|
|---------------|-----------------|---------|----------|
|`seal`         |Blocked          |60/min   |500/min   |
|`upload`       |5/10min          |60/min   |500/min   |
|`qub-read`     |30/min           |60/min   |500/min   |
|`webhooks` CRUD|—                |60/min   |500/min   |

Builder ships with a single per-key `rate_limit: 60/min` (PAYMENTS.md §16.1). Per-endpoint sub-buckets above the per-key budget are P2 hardening — the table reflects the per-key cap, not separate sub-limits.

Implementation note (F-03 / 2026-05 security review): authenticated buckets are keyed by `apikey:${apiKeyInfo.keyHash}` across `upload.ts`, `upload-auth.ts`, `seal.ts`, and `webhooks.ts`. The pre-F-03 shape (`apikey:${clientIp}`) allowed cross-key DoS at shared egress IPs and per-key cap evasion across multiple IPs.

### 5.2 Global Safety Limits

Regardless of tier, enforce global safety limits to protect infrastructure:

|Limit                              |Value                                |
|-----------------------------------|-------------------------------------|
|Max request body size              |100 KB (existing MAX_SERIALISED)     |
|Max seal body size                 |50 KB (existing MAX_PAID_BODY)       |
|Max concurrent storage submissions |5 per minute across all keys         |
|Max webhook registrations (global) |1,000 total across all keys          |

### 5.3 Storage Cost Protection

The server wallet has a finite AR balance. Add a circuit breaker:

```text
1. Track daily storage submissions in METRICS: m:arweave_uploads:{date}
2. Set a daily ceiling (e.g. 500 uploads/day)
3. When ceiling is reached, reject all seal/upload requests with 503
4. Alert admin (via metrics dashboard or external notification)
5. Ceiling is configurable per environment (staging: 50, production: 500)
```

-----

## 6. Read Endpoint Hardening

### 6.1 R2 Response Cache

Cache permanent-storage responses in R2 to reduce gateway load and latency:

```text
1. On GET /api/v1/qub/:tx_id:
   a. Check R2: qub-cache/{tx_id}
   b. If hit: use cached SealedQubCbor bytes
   c. If miss: fetch from permanent storage, store in R2, then process
2. Cache is write-once (sealed qubs are immutable)
3. No TTL needed (content is permanent)
4. Denylist check happens before cache lookup
```

This also benefits the viewer-meta bot handler and webhook delivery (which need to fetch sealed qubs).

### 6.2 Daily Read Counter

Track `reads_today` in the ApiKeyRecord. Reset daily via:

- Option A: cron trigger resets all keys at midnight UTC
- Option B: store `reads_reset_date` in the record; reset on first read of a new day

Option B avoids scanning all keys and is simpler. On each read request:

```text
1. If reads_reset_date != today: set reads_today=0, reads_reset_date=today
2. If reads_today >= max_reads_per_day: return 429
3. Increment reads_today
```

-----

## 7. Key Management

### 7.1 Key Rotation

Add an endpoint for key rotation:

```text
POST /api/v1/api-keys/rotate
Authorization: Bearer qub_sk_<old_key>
→ { "key": "qub_sk_<new_key>" }
```

- Generate new key, copy all quota state from old record
- Delete old key record
- Grace period: old key remains valid for 1 hour after rotation (dual-active)

### 7.2 Admin Key Management

Add admin endpoints (authenticated via ADMIN_SECRET):

```text
GET  /api/v1/admin/api-keys              — list all keys (client_id, tier, usage)
POST /api/v1/admin/api-keys/:hash/disable — disable a key
POST /api/v1/admin/api-keys/:hash/enable  — re-enable a key
```

### 7.3 IP Allowlist

Optional `ip_allowlist` field in ApiKeyRecord. When set (non-null, non-empty), reject requests from IPs not in the list. Useful for enterprise keys with known infrastructure.

-----

## 8. Content Moderation for Seal Endpoint

The `POST /api/v1/seal` endpoint receives plaintext, which creates additional moderation responsibility compared to the upload endpoint (which only sees opaque ciphertext).

### 8.1 Audit Logging

Log all seal requests to R2 (not the body itself, but metadata):

```text
seal-audit/YYYY/MM/DD/HH.ndjson

{ "ts": "...", "client_id": "...", "body_size": 1234, "body_hash": "hex...", "qub_id": "hex...", "tx_id": "...", "ip": "hashed" }
```

This enables retroactive investigation without storing plaintext.

### 8.2 Size and Rate Anomaly Detection

Flag keys that:

- Seal more than 50 qubs in an hour (potential automation abuse)
- Consistently seal at maximum body size (potential data exfiltration)
- Seal identical content repeatedly (potential spam)

These flags can be checked in the metrics dashboard. Automated enforcement (key disable) is a Phase 2 consideration.

### 8.3 Verify-gate (added 2026-04-10)

The web-app verify-gate (`crates/qub-app/src/components/verify_gate.rs`) is the browser-side complement to the per-key quota system. It blocks the second free-tier seal until the user has linked an email via the magic-link flow described in §1.3, raising the Sybil cost from "clear IndexedDB" to "burn an email address".

This is important for the seal endpoint's content-liability surface: it means every free-tier qub older than the first one is attributable to an email-verified identity that the moderation team can correlate against reports. Combined with §8.1 audit logging, an abuse complaint about a specific `tx_id` can be traced back to an `IdentityRecord` even when the Worker never saw plaintext.

The gate is intentionally a hard stop with no skip button — see the component-level docstring for the rationale. Telemetry funnel events: `verify_gate_opened`, `verify_gate_email_submitted`, `verify_gate_success`, `verify_gate_failed{reason}`. KV daily counters: `m:verify_gate_opened`, `m:verify_gate_submitted`, `m:verify_gate_success`, `m:verify_gate_failed`.

-----

## 9. Implementation Phases

### Phase 1: Hardening (before issuing any external API keys)

|#|Item                                              |Effort|Files                                  |Status|
|-|--------------------------------------------------|------|---------------------------------------|------|
|1|Extend ApiKeyRecord with quota fields             |Small |`kv.ts`, `middleware/apikey.ts`         |Done  |
|2|Enforce qubs_remaining in seal and upload          |Small |`routes/seal.ts`, `routes/upload.ts`   |Done  |
|3|Enforce reads_today in qub-read                   |Small |`routes/qub-read.ts`, `kv.ts`          |Done  |
|4|Enforce webhook_limit per key                     |Small |`routes/webhooks.ts`                   |Done  |
|5|Webhook URL validation (HTTPS, no private IPs)    |Small |`routes/webhooks.ts`                   |Done  |
|6|Make webhook secret mandatory                     |Small |`routes/webhooks.ts`                   |Done  |
|7|Block free tier from seal endpoint                |Small |`routes/seal.ts`                       |Done  |
|8|Add disabled check to authenticateApiKey          |Small |`middleware/apikey.ts`                  |Done  |
|9|Daily storage submission ceiling (circuit breaker)|Small |`routes/seal.ts`, `routes/upload.ts`   |Done  |

### Phase 2: Monetisation

|#|Item                                              |Effort|Files                                  |Status|
|-|--------------------------------------------------|------|---------------------------------------|------|
|1|Stripe subscription product for Builder tier      |Medium|Stripe Dashboard config                |TODO  |
|2|API key provisioning via checkout webhook          |Medium|`routes/payment.ts`, `kv.ts`, `routes/api-key-checkout.ts`|Done|
|3|Monthly qub reset via invoice.paid webhook        |Medium|`routes/payment.ts`                    |Done  |
|4|Subscription cancellation → key disable           |Small |`routes/payment.ts`                    |Done  |
|5|Developer documentation page                      |Medium|`crates/qub-app/src/pages/developer.rs` |Done  |

### Phase 3: Operational Maturity

|#|Item                                              |Effort|Files                                  |Status|
|-|--------------------------------------------------|------|---------------------------------------|------|
|1|Webhook ownership verification (challenge/response)|Medium|`routes/webhooks.ts`                  |Done  |
|2|R2 response cache for permanent-storage reads     |Medium|`routes/qub-read.ts`, `routes/webhooks.ts`, R2 config|Done|
|3|Key rotation endpoint                             |Small |`routes/api-key-rotate.ts`, `middleware/apikey.ts`|Done|
|4|Admin key management endpoints                    |Small |`routes/admin-keys.ts`                 |Done  |
|5|Seal audit logging to R2                          |Small |`routes/seal.ts`, `utils/r2log.ts`     |Done  |
|6|IP allowlist enforcement                          |Small |`middleware/apikey.ts`                  |Done  |
|7|Anomaly detection metrics                         |Medium|`routes/seal.ts`                       |Done  |

-----

## 10. Metrics to Add

|Metric key                         |Tracked by        |Purpose                            |
|-----------------------------------|------------------|-----------------------------------|
|`m:api_seals:{date}`               |seal.ts           |Daily API seal count               |
|`m:api_reads:{date}`               |qub-read.ts       |Daily API read count               |
|`m:api_uploads:{date}`             |upload.ts         |Daily API-key uploads              |
|`m:arweave_uploads:{date}`         |seal.ts, upload.ts|Daily total storage submissions    |
|`m:webhook_deliveries:{date}`      |webhooks.ts       |Daily webhook deliveries           |
|`m:webhook_failures:{date}`        |webhooks.ts       |Daily webhook delivery failures    |
|`m:api_key_disabled:{month}`       |apikey.ts         |Monthly key disablements           |
|`m:quota_exhausted:{date}`         |seal.ts, upload.ts|Daily quota exhaustion rejections  |
|`m:arweave_ceiling_hit:{date}`     |seal.ts, upload.ts|Daily circuit breaker activations  |


---

# Identity attestation model

Source: docs/IDENTITY.md

---
authority: A
status: current
reviewed-on: 2026-06-06
cadence: 30d
coupled-to:
  - workers/api/src/routes/auth.ts
  - workers/api/src/routes/identity.ts
  - workers/api/src/routes/attestation.ts
  - crates/qub-app/src/components/verify_gate.rs
  - crates/qub-app/src/pages/signature.rs
  - crates/qub-app/src/storage/identity.rs
---

# qub Identity Attestation Specification

|Field              |Value                                       |
|-------------------|--------------------------------------------|
|**Version**        |1.7                                         |
|**Date**           |2026-06-06                                  |
|**Reviewed through**|2026-06-06 (auth-flow and PWA code-first sweep)|
|**Status**         |Draft — Companion to PROTOCOL.md v1.0 and PDD v1.0|

This document specifies the **layered identity attestation model** that sits alongside qub's authorship signing (PROTOCOL.md §9). It defines how a cryptographic author public key is progressively mapped to human-recognisable identity claims — email, social accounts, passkeys — without compromising the self-contained verifiability of the underlying signature.

Identity attestations are **orthogonal to signatures**. A qub carries the ML-DSA-65 signature and public key in its envelope (PROTOCOL.md §9). Identity attestations live in qub KV, keyed by public key fingerprint, and are fetched at viewer render time as a best-effort progressive enhancement. Signature verification is complete without any attestation lookup; identity display is additive.

-----

## 1. Principles

1. **Signing is opt-in.** Unsigned qubs (`sig_alg = 0x00`, PROTOCOL.md §9.2) remain the default for the MVP and for anonymous use cases forever. A viewer that encounters an unsigned qub MUST NOT attempt identity resolution.
2. **No account required for bare-keypair signing.** Consistent with PDD Product Truth #4, a user MAY generate an ML-DSA-65 keypair locally (Layer 0, §3.1) and sign qubs without ever creating a qub account or verifying any external identity claim.
3. **Attestations are mutable and revocable.** Unlike the on-chain qub body, attestations live in Cloudflare KV, not on Arweave. A user MAY revoke or re-issue any attestation at any time. Viewers MUST treat attestation data as a snapshot in time (see §3, `verified_at`).
4. **Signature verification is self-contained.** Per PROTOCOL.md §12, a third party verifying a signed qub needs only Arweave and drand. Identity resolution is a separate, best-effort enhancement that requires qub API availability. A viewer that cannot reach the qub API MUST still display the verified signature with a fingerprint fallback.
5. **The public key is the stable anchor.** Every attestation binds to the `author_pubkey` carried in `QubEnvelope`. Attestations follow the key, not the user, not the device, and not the handle. Revoking a key revokes every attestation on it at once.
6. **Layers are independent and additive.** A user MAY present any combination of attestation layers against a single keypair. No layer requires any other layer.

### 1.1 Out of Scope — Pact Email-Binding Marker

The short-lived `pact-email-verified:<staging_id>:<email_hash>` KV marker used by the pact co-sign flow (PROTOCOL.md §9.7) is NOT an identity attestation and lives outside this spec. It is an operational anti-impersonation gate, not an identity claim:

- The marker is keyed by staging id + normalised-email hash, not by pubkey fingerprint.
- It is ephemeral (15-minute TTL on the magic-link path; 7-day TTL on the invite-token path, capped by the staging record's lifetime) — attestations are durable until revoked.
- It is never surfaced to viewers or to the signed qub body.
- It does not enroll an email against a keypair — it only proves, for the next window, that the controller of the counter-party mailbox is the entity attempting to co-sign.

The marker can be written via two routes, both operational and outside this spec:

1. **Magic-link verify path** — Party B requests a magic link, clicks it, and `/auth/verify` calls `resolvePactBinding` to write the marker.
2. **Invite-accept path (`POST /api/v1/pact/invite/accept`)** — the staged-pact email itself carries an HMAC-signed `?t=<token>` so receipt of the URL is proof of email control. Same trust model as the magic-link verify, scoped to a single staging_id, with optional PC-3 fingerprint pinning. Eliminates the separate magic-link round-trip for the common cosign case.

A user who has a Layer 1 (email) attestation still needs to cross the pact email-binding marker to co-sign, because the two mechanisms answer different questions: the Layer 1 attestation says "this keypair belongs to this email"; the marker says "this live session controls this email right now." A user without a Layer 1 attestation can still co-sign pacts addressed to them — they simply verify the email-binding marker without ever publishing an identity claim.

### 1.2 Out of Scope — Phase G Device-Linking Cache

The Phase G `device:<device_id>` → email reverse index and the `identity:<email>` record used for free-tier quota accounting (workers `auth.ts`, client `storage::identity`) are NOT identity attestations and live outside this spec. They are a device-session cache keyed by an opaque per-browser device_id, not by pubkey fingerprint, and they never appear in a signed qub envelope or on a viewer author line.

Three operational notes that commonly confuse this boundary:

1. **Code-first verification is the default device-linking UX.** The inline verify gate used by the 2nd-qub cap, drawer "Link email", and installed-PWA flows calls `POST /api/v1/auth/code/request`, emails a 6-digit code, and verifies it with `POST /api/v1/auth/code/verify` inside the same browser/PWA context. The pending challenge is keyed as `auth-code:<sha256(email:device_id)>`, expires after 10 minutes, and allows 5 wrong-code attempts. On a correct code the Worker mints an internal HMAC token and delegates to the same `/auth/verify` identity-merge path as magic links. Wrong codes increment the attempt counter; a correct code is consumed only after the identity merge succeeds, so a transient 503 from the verifier can be retried with the same code while it remains within TTL. This path links `device:<device_id>` → email and hydrates local `IdentityCache`; it does not create a pubkey attestation unless a separate proof-of-possession flow is run.
2. **Magic links remain available for compatibility and pact binding.** `/api/v1/auth/magic-link` and `/api/v1/auth/verify` still exist. Pact co-signing uses them because the HMAC token carries `staging_id` and optional `cosigner_fingerprint` binding metadata. Legacy clients may also still verify via a clicked link. On iOS, a Mail-tapped link opens the default browser rather than a standalone home-screen PWA, so the old magic-link UX can still cross browser contexts; the default code-first path avoids that hop by keeping the final verification request inside the app that requested the code.
3. **Hard-reset sign-out now unbinds server state best-effort.** The account-popover "sign out" flow first calls `POST /api/v1/auth/signout` with the current `device_id`, which deletes `device_link:<device_id>` on the Worker. It then clears local identity cache, signing key, drafts, upload queue, staged pacts, entitlements, device ID, relevant web storage, and in-memory identity/signing/attestation signals. Every step is best-effort; the signed-out state is defined by the local clear pass, while the server unbind prevents the same browser from immediately rehydrating the prior email on next boot.

None of these behaviours changes attestation resolution: a qub signed by a keypair that happens to share an email with the device-linked identity is still resolved purely via `identity:<fingerprint>` (§4, §5). The device-linking cache never short-circuits signature or attestation verification.

**IdentityRecord scope.** The `identity:<email>` record (defined in `workers/api/src/kv.ts`) additionally carries fields outside this spec's scope: `account_id`, `stripe_customer_id`, `last_active_at`, `anniversary_opt_out`, `last_seen_*` (IP-hash / country / CF-ray / ASN / AS-org) device-telemetry cache, `sanctions_geo_risk_level` / `sanctions_triage_*` triage state, and the `risk_tier` / `risk_assessed_at` email-classifier fields documented in §8. This spec normatively covers only the `handle*`, `profile`, and (in §8) `risk_*` fields; the rest are convenience-cache / billing / operational-triage state and MUST NOT be returned in customer-safe DTOs.

**Per-IdentityRecord locale.** `PUT /api/v1/identity/locale` (handler at `workers/api/src/routes/identity-locale.ts`) updates the `IdentityRecord.locale` field post-hoc so future server-sent emails (verify, sign-in, reveal-notify, lifecycle, alerts) land in the user's current UI locale rather than the locale captured at first verify. This is also out of scope for attestation resolution.

**Account erasure cascade.** `POST /api/v1/account/delete` → emailed confirmation → confirm POST triggers `eraseAccount` (`workers/api/src/utils/account-erasure.ts`), which clears `identity:<email>` plus every related projection — including `email_fp:<email>`, `verified:<sha256(email)>`, the `handle:<handle>` forward index (tombstoned, not deleted), per-fingerprint AttestationRecords whose only attestation referenced this email, and the avatar R2 object. Erasure is not an attestation operation but it does cascade through the attestation surface.

-----

## 2. Pubkey Fingerprint

The **pubkey fingerprint** is the derived identifier that binds attestations to a public key. It is used both as the KV lookup key (§4) and as the viewer-facing display fallback (§5) when no richer attestation is available.

### 2.1 Derivation

```text
fingerprint = SHA3-256(author_pubkey_bytes)
```

- The input `author_pubkey_bytes` is the raw serialised public key exactly as it appears in the `author_pubkey` field of `QubEnvelope` (PROTOCOL.md §2.2). For ML-DSA-65 this is 1,952 bytes; for Ed25519 it is 32 bytes.
- SHA3-256 is the same hash function used for `body_hash` (PROTOCOL.md §4.2) and `qub_id` (§4.1), chosen for consistency with the rest of the protocol.
- The output is always 32 bytes.
- The fingerprint is **derived**, never stored in the qub envelope or the Arweave payload. Viewers and the qub API compute it from `author_pubkey` at resolution time.

### 2.2 Display Format

```text
qub:<first 4 bytes hex>…<last 4 bytes hex>
```

- The prefix `qub:` is literal.
- `<first 4 bytes hex>` is the lower-case hex encoding of bytes `[0..4]` of the fingerprint (8 hex characters).
- The middle ellipsis is the Unicode HORIZONTAL ELLIPSIS character `…` (U+2026).
- `<last 4 bytes hex>` is the lower-case hex encoding of bytes `[28..32]` of the fingerprint (8 hex characters).

Example: `qub:7f3a1b2c…9e8d7c6b`

The short form is designed for inline viewer display when no richer attestation is resolved. The collision space (64 bits visible) is acceptable for UI disambiguation, not for cryptographic identification — the full 32-byte fingerprint (or, authoritatively, `author_pubkey`) is the identity anchor.

-----

## 3. Attestation Types

Six attestation types are defined. Each is independent: a user MAY hold any subset against the same keypair.

|Layer|Type      |Identifier|Viewer display                                        |Mechanism            |
|-----|----------|----------|------------------------------------------------------|---------------------|
|0    |Bare      |—         |`qub:7f3a1b2c…9e8d7c6b`                               |Auto-generated locally|
|1    |Email     |`email`   |`verified email` pill (no address shown on public surfaces)|SendGrid code challenge|
|1    |Handle    |`handle`  |`@markharper`                                         |Auto-allocated alongside email; user-renameable subject to a 30-day cooldown|
|2    |X         |`x`       |`@mark on X`                                          |OAuth 2.0             |
|2    |GitHub    |`github`  |`@mark on GitHub`                                     |OAuth 2.0             |
|2    |Google    |`google`  |`mark@example.com on Google`                          |OAuth 2.0 + OIDC      |
|3    |Passkey   |`passkey` |No new display (durability upgrade, see §3.6)         |WebAuthn registration |

### 3.1 Layer 0 — Bare Keypair

A Layer 0 identity is a bare ML-DSA-65 keypair generated locally in the creator's browser the first time the user opts into authorship signing. The private key is stored in IndexedDB; the public key becomes `author_pubkey` on any qub the user subsequently signs.

- **Acquisition:** Auto-generated by the creator app. No server round-trip. No account. No email.
- **Stored in KV:** Nothing. Layer 0 is the absence of any KV record — a viewer that queries `identity:<fingerprint>` and receives 404 is looking at a Layer 0 author.
- **Verification procedure:** None. The signature alone proves "this key signed this qub"; Layer 0 does not claim that the key belongs to anyone in particular.
- **Viewer display:** The fingerprint, per §2.2.
- **Revocation:** Not applicable — there is nothing to revoke. To abandon a Layer 0 identity, the user deletes the local keypair.

Layer 0 is the default for opt-in signing. Every higher layer is additive on top of a Layer 0 keypair.

**Secret-key storage (F-05, 2026-05 security review).** Layer 0 secret keys are persisted in IndexedDB AES-256-GCM-wrapped under a non-extractable Web Crypto `CryptoKey` generated on first save (`crates/qub-app/src/storage/key_wrap.rs`). The wrap defeats offline disk extraction — a copy of the IndexedDB image alone no longer yields the raw secret. The wrap key itself is stored as a structured-cloned `CryptoKey` in the `device` object store with `extractable: false`, so the browser keeps the underlying bytes in opaque key storage rather than scripts' addressable memory. Threat-model scope: this wrap does **not** defend against same-origin XSS or malicious browser extensions, which can call the unwrap path directly — for those, mitigation lives at the CSP + extension-policy layer. The user is assumed authorised on their own device; no passphrase is prompted.

### 3.2 Layer 1 — Email

A Layer 1 attestation binds a keypair to a verified email address. It is distinct from the Phase G device-linking cache in §1.2: entering a 6-digit auth code in the verify gate proves mailbox control for the browser/device account record, but it does not publish an attestation for a signing key. A public email attestation is written only when the Worker also verifies proof-of-possession of the ML-DSA private key. Two acquisition paths converge on the same KV record shape.

**Path A — Combined with `/auth/verify` compatibility flow.** On `POST /api/v1/auth/verify`, the client may include `pubkey_b64url` + `signature_b64url` alongside the HMAC auth token. The signature is ML-DSA-65 over the **auth proof-of-possession challenge** (§6.2) — the domain separator `"QUB_IDENTITY_AUTH_V1"` (20 bytes) concatenated with the UTF-8 bytes of the auth token. The Worker verifies the signature, derives the fingerprint as `SHA3-256(pubkey)`, and writes the attestation in the same round-trip as identity verification. This path remains supported for legacy magic-link clients and future combined flows, but the current default PWA/web readiness gate is code-first device linking (§1.2) and does not pass pubkey/signature material.

**Path B — Standalone code challenge (rebind, multi-device, or post-verify setup).** The user submits their email plus their `pubkey_b64url` and `fingerprint` to `/api/v1/identity/attestation/email/begin`. The Worker computes `SHA3-256(pubkey)` and rejects with `400 fingerprint_mismatch` if it doesn't equal the claimed fingerprint — the entry-point guard against pubkey-squatting, applied before any SendGrid send. On match, the Worker emails a 6-digit verification code. The user then submits the code plus a proof-of-possession signature (§6.2) over the challenge `"QUB_IDENTITY_EMAIL_V1" || fingerprint || code || timestamp`. On success, the Worker writes the attestation to KV.

- **Stored in KV:** `{ type: "email", value: "<normalised_address>", verified_at: <unix_seconds> }`. Identical shape whichever path wrote it.
- **Verification procedure:** Path A piggybacks on the auth token (single-use, 15-minute TTL, HMAC-signed). Path B uses a 6-digit code (10-minute TTL, single-use, 5-attempt cap).
- **Viewer display:** Email attestations surface as a boolean **"verified email"** pill on the `/u/<handle>` profile card; the address itself is never rendered on a public surface. The viewer countdown / reveal byline resolves to `@<handle>` (handle attestations always win, see §5.3) — so the email never reaches a viewer-facing string. The address remains in the attestation record returned by `GET /api/v1/identity/attestation/<fingerprint>` and is surfaced to the signed-in creator on `/signature`.
- **Revocation:** The user calls `DELETE /api/v1/identity/attestation/email` with a fresh proof-of-possession signature. The KV record is rewritten with the email entry removed. Viewers fetching after revocation see only the remaining attestations.
- **Conflict handling (Path A only):** When a fingerprint already has an email attestation bound to a *different* email, Path A refuses to silently overwrite — the verify call still succeeds and `attestation_created` returns `false`. The signal is intentionally opaque (Path A returns `attestation_created: false` for any combined-flow failure — bad signature, missing pubkey, email collision — without distinguishing them). The client surfaces the unspecified failure and falls back to Path B, which DOES surface the explicit conflict at begin-time via `409 email_already_attested`.

### 3.2.5 Layer 1 — Handle

A Layer 1 **handle** attestation binds an **email-verified identity** to a qub-native display name (`@markharper`). Handles beat email in viewer precedence (§5.3), so the public author line never has to leak a real-world contact address for an email-verified user.

**Email-scoped, not fingerprint-scoped (B-handle-email-scope, 2026-05-09).** The handle is a property of the **email-keyed `IdentityRecord`** (`identity:<email>`), not the per-fingerprint attestation record. All fingerprints linked via the same email observe the same handle. A user with three browsers / devices verifying the same email sees one handle, not three. Anonymous fingerprints (no email yet) cannot have a handle.

The IdentityRecord carries four handle fields:

```
identity:<email>
  handle:              "markharper"
  handle_claimed_at:   <unix_seconds>          // when first attached
  handle_renamed_at:   <unix_seconds> | null   // last rename (cooldown source)
  handle_shape:        "auto" | "user" | null  // tombstone TTL discriminator
```

**Resolution.** A reader given a fingerprint joins fingerprint → email (from the attestation record) → IdentityRecord → handle. The wire shape on `GET /api/v1/identity/attestation/<fingerprint>` is preserved: the response still carries a `{ type: "handle", value }` entry, but the value is sourced from the IdentityRecord. The per-fingerprint attestation record may carry a transitional `type: "handle"` entry during the migration window for back-compat readers; the IdentityRecord's value wins on conflict.

**Auto-allocation.** Every email-verified identity gets a handle at first email-verify. `handleEmailVerify` and `maybeCreateAttestation` route through `applyHandleOnEmailVerify`, which resolves five cases:

1. *(a)* Identity has no handle, fingerprint has no handle → autoalloc + write to IdentityRecord.
2. *(b)* Identity has a handle, fingerprint doesn't → fingerprint inherits via the join (no write).
3. *(c)* Fingerprint has a legacy handle entry, identity doesn't → migrate the value onto the IdentityRecord, repoint reverse index.
4. *(d)* Both sides agree → idempotent no-op.
5. *(e)* Both sides disagree → **409 `handle_conflict`**, surfacing both values for client-side resolution.

Allocation draws from the canonical wordlist in `crates/qub-core/src/handle_wordlist.rs` in the shape `<adj>_<noun>_<3 digits>` (e.g. `quiet_fox_482`); on a 5-draw collision exhaustion the allocator falls back to `qub_<first 8 hex of fingerprint>`. Allocation is soft-fail — a KV hiccup writes the email entry without a handle, and the user can re-attest later. Gated by the `flags:handle_autoalloc_enabled` KV flag so the rollout can be dark-launched.

**Rename.** `POST /api/v1/identity/attestation/handle/rename` moves the handle on the IdentityRecord. PoP signature over the challenge `"QUB_IDENTITY_HANDLE_RENAME_V1" || fingerprint || utf8(current_handle) || utf8(new_handle) || timestamp_be` (29 + 32 + |current| + |new| + 8 bytes). Both handles are in the preimage so a signature for `A → B` cannot be replayed for `A → C`. **Cooldown gate is email-scoped:** the rename handler reads `IdentityRecord.handle_renamed_at` as the source of truth. A rename via any one device blocks renames via every sibling fingerprint for 30 days.

A rename is a **single write to the IdentityRecord** plus a reverse-index repoint. There is no sibling propagation pass: every other fingerprint sees the new handle on its next read because the projection joins through the IdentityRecord. The legacy per-fingerprint cooldown stamp `handle_rename_cooldown:<fingerprint>` continues to be written for back-compat readers; the rename handler itself no longer consults it.

**Release.** `DELETE /api/v1/identity/attestation/handle` clears the handle from the IdentityRecord. Challenge domain separator `"QUB_IDENTITY_HANDLE_DELETE_V1"` (29 bytes). The forward index is tombstoned — not deleted — for 1 hour (auto-shape) or 30 days (user-chosen) so published embed caches see `410 Gone` instead of a cold 404.

**Anonymous fingerprints (no email).** Cannot rename — `POST /handle/rename` returns `404 no_email_attestation`. They never had a handle in the new model.

**Email revoke.** Removing the email entry from a fingerprint's attestation record breaks the join: that fingerprint's projection returns `handle: null`. The IdentityRecord and its handle stay intact for the email's other linked fingerprints.

- **Stored on the IdentityRecord:** `handle`, `handle_claimed_at`, `handle_renamed_at`, `handle_shape` (see schema above).
- **Reverse index:** `handle:<normalised>` in `ENTITLEMENTS` KV. Active claims are `version: 2` with `{ email, claimed_at }`; legacy claims are `version: 1` with `{ fingerprint, claimed_at }`; tombstones share the shape with `fingerprint: null` and `released_at`/`released_shape` set. Resolvers prefer the email shape via `readHandleOwner`.
- **Verification procedure:** Normalisation in `qub_core::handle::normalise_handle` — strip leading `@`, fold ASCII uppercase, length 3-20, charset `[a-z0-9_]`, reject starts-with-digit, reject against the reserved-word deny list. Server normalises defensively before every read and every write.
- **Viewer display:** `@<handle>`, via the `viewer.identity.handle` i18n key. A handle MUST NOT elevate the trust claim over its backing attestations; the profile page at `/u/<handle>` surfaces the verified email (when present) so the verification trail is one click away.

**Migration (2026-05-09 onward).** Production rolls in three phases: (6a) dual-write — every verify/rename/revoke writes both the IdentityRecord and the legacy per-fingerprint handle entry; reads prefer the IdentityRecord. (6b) Backfill via `workers/api/scripts/backfill-handles-to-identityrecord.mjs`, which scans `identity:<fingerprint>` records, groups by email, picks most-recent rename per email, and copies onto the IdentityRecord. (6c) Stop writing the legacy entry; sweep existing copies; drop the read-fallback path. Staging skipped 6a/6b via the 2026-05-08 KV wipe and started clean on the new flow.

**Character set.** The `[a-z0-9_]` rule above is the V1 baseline. §3.2.6 defines the V2 multi-script handle policy adopted from 2026-05-12 onward to support Korean, Chinese, Japanese, Thai, Hindi, Farsi, Bangla, Vietnamese, Greek, and Arabic. V1 handles are a strict subset of V2 — every existing claim remains valid.

### 3.2.6 Handle Character Set — V2 (Multi-Script)

This section is the canonical character-set specification for `qub_core::handle::normalise_handle` going forward. The V1 baseline in §3.2.5 (ASCII `[a-z0-9_]`, length 3–20 code points, no leading digit, reserved-word filter) is preserved as a strict subset; V2 widens the alphabet to cover the ten target scripts without invalidating any existing handle.

The decisions below are the design conclusion of a charset review (GitHub issue #45). The rationale lives in §6.6.

**Normalisation pipeline.** A V2 handle is accepted only after surviving every step below, in order. The first failing step determines the error variant returned to the client.

1. Strip a leading `@` if present.
2. Reject if the length is outside 3–20 code points (pre-normalisation pre-check).
3. Apply Unicode **NFC** normalisation. NFKC is explicitly NOT used (it folds visually-distinct characters such as fi → fi or full-width digits → ASCII digits).
4. Lowercase via Unicode default casing — `String::to_lowercase` (Rust) and `String.prototype.toLowerCase` (TypeScript), never any locale-specific variant. The Turkish dotted/dotless-i locale MUST NOT be applied; TS ↔ Rust output must be byte-identical.
5. Re-check length 3–20 code points (NFC and lowercase may have changed it).
6. Reject if any code point is in the invisible / control blocklist of §3.2.6.5.
7. Reject if any code point is outside the script allowlist of §3.2.6.2.
8. Reject if the handle violates the mixed-script policy of §3.2.6.3.
9. Reject if the leading code point is an ASCII digit (`0-9`) or a combining mark (general category `Mn`, `Mc`, `Me`).
10. Reject if the handle matches a literal entry in the reserved-word deny list (lower-cased, NFC-normalised comparison) — see §3.2.6.6.

#### 3.2.6.1 Length

Length stays at 3–20 code points, measured after NFC normalisation and lowercase. CJK handles can be meaningful in 3 code points; Indic and Arabic handles rarely exceed 20 even with attached vowel marks. A future revision MAY revisit the upper bound on user feedback.

#### 3.2.6.2 Allowed Scripts

A handle code point MUST belong to one of:

- **Common** — restricted further to ASCII digits `0-9` and the connector `_` only (§3.2.6.4).
- **Latin** — covers English, Vietnamese (with diacritics, NFC-handled), and every other Latin-script language.
- **Greek**
- **Cyrillic** — covers Russian (already shipped in `locales/ru.json`) and other Cyrillic languages.
- **Arabic** — covers Arabic and Persian/Farsi (Persian uses the extended Arabic Unicode block).
- **Hebrew** — included for RTL-handling symmetry. No language ask yet, but excluding it would leave the RTL coverage asymmetric.
- **Devanagari** — Hindi.
- **Bengali** — Bangla.
- **Thai**
- **Han (CJK Unified Ideographs)** — Chinese hanzi, Japanese kanji, Korean hanja.
- **Hiragana** and **Katakana** — Japanese.
- **Hangul** — Korean syllables and conjoining jamo.

Implementation: an allowlist on the Unicode `Script` and `Script_Extensions` properties. Every other script — including Tibetan, Khmer, Lao, Armenian, Georgian, Ethiopic, all symbol and currency blocks, emoji, math notation, dingbats, private use, surrogates, and unassigned code points — is rejected.

**Example handles by script:**

|Script              |Example      |Note                                          |
|--------------------|-------------|----------------------------------------------|
|Latin               |`markharper` |V1-compatible                                 |
|Latin (Vietnamese)  |`nguyễn_văn` |NFC-precomposed diacritics                    |
|Greek               |`μαρκος`     |                                              |
|Cyrillic            |`николай`    |                                              |
|Arabic              |`محمد`       |RTL                                           |
|Hebrew              |`יוסי`       |RTL                                           |
|Devanagari          |`राम`        |Hindi                                         |
|Bengali             |`রাহুল`      |Bangla                                        |
|Thai                |`สมชาย`      |                                              |
|Han                 |`小明`       |Single-script Chinese                         |
|Han + Hiragana      |`たろう小林` |Japanese — exception in §3.2.6.3              |
|Hangul              |`민준`       |Korean syllables                              |

#### 3.2.6.3 Mixed-Script Policy

The mixed-script policy is **UTS #39 Moderately Restrictive**: a handle is in a single script plus Common, with three explicit multi-script exceptions:

1. Han + Hiragana + Katakana — Japanese.
2. Han + Hangul — mixed Korean (rare but legitimate).
3. Han alone — Chinese / single-script CJK.

**Latin + (any other allowed script) is forbidden.** This is the rule that defeats the canonical homograph attack — a registration like `mark` where the `a` is Cyrillic U+0430 instead of Latin U+0061 — by requiring the entire handle to be either all-Latin or all-Cyrillic, never a silent mix.

The script of each code point is determined by its Unicode `Script_Extensions` property, which correctly classifies CJK punctuation shared between Han / Hiragana / Katakana. Common-script code points (the ASCII digits and underscore permitted by §3.2.6.4) do not contribute to the script set.

#### 3.2.6.4 Digits and Connectors

Only ASCII digits (`0-9`) and the ASCII underscore (`_`) are permitted from the Common script. Native digit forms — Arabic-Indic `٠-٩` (U+0660–U+0669), Eastern Arabic-Indic `۰-۹` (U+06F0–U+06F9), Devanagari `०-९` (U+0966–U+096F), Bengali `০-৯` (U+09E6–U+09EF), Thai `๐-๙` (U+0E50–U+0E59), and so on — are rejected.

Rationale: digits round-trip unchanged through NFC, so the only way to prevent visual ambiguity (`mark_123` vs `mark_۱۲۳`) is to choose one canonical digit form. ASCII `0-9` is the universal choice that every keyboard can produce. Underscore is the sole connector, matching V1.

The leading-character rule from V1 carries over and is extended: the first code point MUST NOT be a digit, and MUST NOT be a combining mark (general category `Mn`, `Mc`, `Me`).

#### 3.2.6.5 Invisible and Control Character Blocklist

A handle MUST NOT contain any of:

- **`Cc`** — C0 / C1 control characters (U+0000–U+001F, U+007F–U+009F).
- **`Co`** — private-use area (U+E000–U+F8FF and the two supplementary PUA planes).
- **`Cs`** — surrogate code points (U+D800–U+DFFF).
- **`Cf`** — format characters, including specifically:
  - Zero-width characters: U+200B (ZWSP), U+200C (ZWNJ), U+200D (ZWJ), U+2060 (WJ), U+FEFF (BOM).
  - Bidi control characters: U+200E (LRM), U+200F (RLM), U+202A–U+202E (LRE / RLE / PDF / LRO / RLO), U+2066–U+2069 (LRI / RLI / FSI / PDI).
  - Tag characters: U+E0000–U+E007F.
- **Variation selectors** — U+FE00–U+FE0F (VS1–VS16) and U+E0100–U+E01EF (VS17–VS256).

These categories defeat invisible-character duplicates of an existing handle, bidi-spillover spoofs (an RLO mid-handle that visually reorders surrounding text), and emoji-skin-tone-style variation selectors that change appearance without changing the underlying code point sequence.

Combining marks (`Mn`, `Mc`, `Me`) are permitted *except* at the leading position — see §3.2.6.4. This admits legitimate Latin / Devanagari / Bengali handles whose precomposed NFC form is unavailable for every base-combiner pairing.

#### 3.2.6.6 Reserved Words

The reserved-word deny list in `crates/qub-core/src/handle_reserved.rs` is widened in V2 to include script-localised forms of high-risk terms (`админ`, `관리자`, `管理员` for `admin`; analogous forms for `qub`, `support`, `help`, `api`, `claude`, `anthropic`). The TypeScript mirror in `workers/api/src/routes/handle-alloc.ts` MUST be kept in lock-step — the TS-side comment explicitly says "Keep synced with `crates/qub-core/src/handle_reserved.rs`".

Comparison is on the lower-cased, NFC-normalised candidate handle against the deny list's lower-cased entries. The match is literal, not skeleton-based — visually-confusable cross-script registrations (`mark` vs all-Cyrillic `маrk`) are prevented by the §3.2.6.3 mixed-script policy rather than by a UTS #39 confusable-skeleton index. Mixed Latin + Cyrillic in a single handle is forbidden; an all-Cyrillic handle that visually resembles a Latin one is permitted as a distinct, single-script registration — see §6.6.1 for residual-risk discussion.

#### 3.2.6.7 Auto-Allocation Wordlist

The auto-allocator at `crates/qub-core/src/handle_wordlist.rs` stays English-only (`<adj>_<noun>_<3 digits>`, fallback `qub_<8 hex>`). Users who want a multi-script handle rename to one explicitly. Keeping auto-allocation ASCII preserves the auto-shape detector (`is_auto_allocated_shape`) and avoids the per-locale wordlist authoring cost in this revision.

#### 3.2.6.8 Public Rendering

Every surface that displays a handle inside potentially mixed-direction prose MUST wrap it in HTML `<bdi>` to prevent bidi spillover from surrounding text. This is already the pattern for tx_id and fingerprint short forms; V2 extends it to handles.

Surfaces requiring the wrap include the viewer countdown / reveal byline, the `/u/<handle>` profile card, the `/signature` settings page, the sealed / revealed identity rows in the drawer, email subject lines and HTML bodies that mention a handle, and the embed bundle's author line.

URLs that carry a handle (the `/u/<handle>` canonical link, share URLs, `og:url`) MUST percent-encode the handle at link-construction time. The canonical helpers — `qub_core::handle::encode_handle_for_url` (Rust) and `encodeHandleForUrl` / `handleProfilePath` in `workers/api/src/utils/handle-url.ts` (TS) — leave the RFC 3986 unreserved set (`ALPHA / DIGIT / "-" / "_" / "." / "~"`) untouched and percent-encode everything else, matching `encodeURIComponent` byte-for-byte. The cross-implementation fixture at `crates/qub-core/tests/vectors/handle_url_v1.json` is the authoritative byte-level contract, asserted by `crates/qub-core/tests/handle_url_vectors.rs` and `workers/api/src/utils/__tests__/handle-url-cross-impl.test.ts`. Encoding directly via `percent_encoding::utf8_percent_encode` against the crate-built-in `NON_ALPHANUMERIC` set is NOT compliant — it encodes `_` (which is in the unreserved set), producing different URLs from the TS side for any V1 ASCII handle (`orange_fox_612` → `orange%5Ffox%5F612`).

The Worker router and the Leptos router both decode percent-encoded UTF-8 transparently (`leptos_router::location::Url::unescape` → `js_sys::decode_uri_component`; `decodeURIComponent` on the Worker side), so server- and client-side handle resolution see the same bytes the validator accepted.

#### 3.2.6.9 Migration

V1 handles are a strict subset of V2:

- ASCII characters round-trip through NFC unchanged.
- ASCII characters are stable under `to_lowercase`.
- The V1 regex `[a-z0-9_]` is fully covered by the V2 allowlist (Common + Latin script).
- V1-issued PoP signatures continue to verify under the V1 domain separators (`QUB_IDENTITY_HANDLE_RENAME_V1`, `QUB_IDENTITY_HANDLE_DELETE_V1`, `QUB_IDENTITY_PROFILE_SET_V1`); V2 handles also sign under the same V1 separators with the literal NFC bytes concatenated. There is no dual-verify split.

V2 deployment therefore requires **no data migration of existing handles or attestation records**.

Failing to add a script to §3.2.6.2 after a real-world request is reversible — extend the allowlist, redeploy, no data change. Failing to *exclude* a script that we later regret is harder, since claimed handles persist. The allowlist is therefore deliberately narrow at launch.

### 3.3 Layer 2 — Social (X / GitHub / Google)

A Layer 2 attestation binds a keypair to a verified social-platform account.

- **Acquisition:** Standard OAuth 2.0 authorisation code flow (Google also uses OIDC). The Worker receives the authorisation code, exchanges it for an access token, reads the user's profile, and extracts `platform_id` (the stable numeric identifier) and `display_handle` (the current username / handle).
- **Stored in KV:** `{ type: "<x|github|google>", value: "<display_handle>", platform_id: "<string>", verified_at: <unix_seconds> }`. OAuth access tokens and refresh tokens are **NOT** stored — only the verified claim.
- **Verification procedure:** The OAuth token exchange and profile read are proof that, at verification time, whoever controlled the keypair also controlled the social account. The keypair fingerprint is bound via a proof-of-possession signature submitted alongside the OAuth `state` parameter.
- **Viewer display:** `@<display_handle> on X`, `@<display_handle> on GitHub`, or `<email> on Google`.
- **Revocation:** `DELETE /api/v1/identity/attestation/<type>` with proof-of-possession. Re-verification is required if the user wants to re-attest after a handle change on the source platform (see §6.3, staleness).

OAuth platforms beyond X, GitHub, and Google MAY be added in future revisions by extending the identifier registry below. Implementations MUST reject unknown type identifiers at the API boundary.

### 3.4 Attestation Type Identifier Registry

|Identifier|Status |Notes                          |
|----------|-------|-------------------------------|
|`email`   |Shipped (Phase 2)|SendGrid code challenge |
|`handle`  |Shipped (Phase 2)|Auto-allocated alongside email; user-renameable subject to a 30-day cooldown; V2 multi-script charset per §3.2.6 |
|`x`       |Reserved (Phase 3, schema-only) |OAuth 2.0; no handler wired |
|`github`  |Reserved (Phase 3, schema-only) |OAuth 2.0; no handler wired |
|`google`  |Reserved (Phase 3, schema-only) |OAuth 2.0 + OIDC; no handler wired |
|`passkey` |Reserved (Phase 3, schema-only) |WebAuthn registration ceremony; no handler wired |

The `AttestationEntry.type` union in `workers/api/src/kv.ts` carries all six identifiers so the wire shape forward-compatibly accepts Phase 3 types — but only `email` and `handle` have route handlers, validation, or KV write paths in the current codebase. Phase 3 types are reserved schema only.

Implementations MUST treat unknown identifiers as a client error (`400 Bad Request`) at the attestation-creation endpoint, and MUST skip them silently at the viewer resolution step (forward compatibility).

### 3.5 Layer 3 — Passkey

A Layer 3 attestation binds a keypair to a WebAuthn credential for **cross-device durability**, not for viewer-facing identity.

- **Acquisition:** WebAuthn registration ceremony. The browser generates a credential (on-device or synced via the platform's passkey provider), and the Worker stores the resulting credential ID. Subsequent logins from other devices use the passkey to unlock (or re-derive) the stored ML-DSA-65 private key.
- **Stored in KV:** `{ type: "passkey", credential_id: "<base64url>", verified_at: <unix_seconds> }`. The WebAuthn public key is stored on the Worker side in the same record but is not part of the viewer-visible attestation payload.
- **Verification procedure:** WebAuthn registration + a proof-of-possession signature over the credential ID.
- **Viewer display:** **None.** A passkey attestation MUST NOT alter the viewer display. A signed qub with only a Layer 0 + Layer 3 stack displays exactly as a Layer 0 qub — the fingerprint. A signed qub with Layer 1 + Layer 3 displays the email, same as Layer 1 alone. The passkey is a keypair durability / cross-device recovery mechanism, not an identity claim.
- **Revocation:** The user removes the credential through the normal account settings flow. This is the only layer whose revocation has an operational side-effect beyond viewer display: losing the last passkey without an alternative recovery path MAY permanently orphan the keypair.

### 3.6 Why Passkeys Do Not Change Display

A passkey proves "the same human can re-authenticate from another device." It does not prove any externally-recognisable identity claim — there is no email, no handle, no platform profile. Showing "passkey-verified" in the viewer would imply a trust claim the passkey does not actually make. The right abstraction is: passkey = durability, email/social = identity.

### 3.7 Profile and Avatar — Self-Declared, Not Attested

A creator may attach a `ProfileBlock` (display name, URL, avatar) to their attestation record. These fields are **self-declared**, not externally attested — they carry no third-party verification claim — so they sit alongside the §3 attestation types rather than as one of them. They are covered normatively in §10 (Profile metadata) and are surfaced on the `/u/<handle>` page (§7.5) and as bylines on opt-in publicly-attributed qubs.

-----

## 4. KV Schema

Attestations and their auxiliary state are stored across the `ENTITLEMENTS` and `DENYLIST` KV namespaces and the `AVATARS` R2 bucket. The fingerprint-keyed attestation record is the canonical surface; the rest are indexes, rate-limit buckets, projection hints, and tombstones written by the attestation handlers.

|Pattern                              |Namespace   |Purpose                                                                 |
|-------------------------------------|------------|------------------------------------------------------------------------|
|`identity:<fingerprint>`             |ENTITLEMENTS|AttestationRecord — the per-keypair attestation list                    |
|`identity:<email>`                   |ENTITLEMENTS|IdentityRecord — email-keyed; carries `handle`, `profile`, free-tier quota; out of scope for this spec but see §1.2 |
|`attest_pending:<fingerprint>`       |ENTITLEMENTS|Path B begin → verify state (code hash, expires_at, attempts)           |
|`attest_email_rate:<email_hash>:<hour>` |ENTITLEMENTS |Per-email per-hour rate cap on email-attestation begins                 |
|`attest_ip_rate:<ip>:<hour>`         |ENTITLEMENTS|Per-IP per-hour rate cap on email-attestation begins                    |
|`handle:<normalised>`                |ENTITLEMENTS|Forward index — `version: 2` `{email, claimed_at}` (active) / `version: 1` `{fingerprint, claimed_at}` (legacy) / tombstone with `fingerprint: null` + `released_at` |
|`handle_rename_cooldown:<fingerprint>` |ENTITLEMENTS|Legacy per-fingerprint rename stamp — written for back-compat readers only; the rename handler reads `IdentityRecord.handle_renamed_at` instead (§3.2.5) |
|`email_fp:<email>`                   |ENTITLEMENTS|Projection hint — which fingerprints have an email entry attesting `<email>`; lets address-keyed surfaces (e.g. login-email change §9.3 step 7) enumerate without scanning |
|`deny:avatar:<fingerprint>`          |DENYLIST    |Operator moderation ban on a fingerprint's avatar; blocks re-upload     |
|`avatar/<fingerprint>` (R2)          |AVATARS     |Re-encoded 512×512 WebP, capped at 150 KiB (§10.1)                      |

The `<fingerprint>` segment is the 64-character lower-case hex encoding of the full 32-byte SHA3-256 fingerprint (§2.1) — not the short display form. `<email>` is the normalised lower-cased address; `<email_hash>` is `sha256(lowercased email)` so KV dumps never leak addresses.

The inline KV-key documentation in `workers/api/src/kv.ts` (around the `handleKey`, `attestPendingKey`, `attestEmailRateKey`, and related helpers) is the operational source of truth; this table mirrors the keys an implementer needs to understand the spec, not every operational marker.

### 4.1 Record Shape

```text
identity:<fingerprint>  →  {
    attestations: [
        { type: "email",   value: "mark@example.com", verified_at: <unix_seconds> },
        { type: "handle",  value: "markharper", verified_at: <unix_seconds> },
        { type: "x",       value: "@mark", platform_id: "12345", verified_at: <unix_seconds> },
        { type: "github",  value: "@mark", platform_id: "67890", verified_at: <unix_seconds> },
        { type: "passkey", credential_id: "<base64url>", verified_at: <unix_seconds> }
    ],
    pubkey_alg: 0x01,        // sig_alg registry value; PROTOCOL.md §9.2
    created_at: <unix_seconds>,
    updated_at: <unix_seconds>
}
```

The `{ type: "handle", value, verified_at }` entry shown above is the **projected wire shape** returned by `GET /api/v1/identity/attestation/<fingerprint>`, not the canonical store. Per §3.2.5, the handle is owned by the email-keyed `IdentityRecord` (`identity:<email>`); the response synthesises the handle entry by joining fingerprint → email → IdentityRecord at read time. A transitional `type: "handle"` entry MAY also exist directly on the per-fingerprint AttestationRecord during the migration window for back-compat readers, but the IdentityRecord value wins on conflict.

### 4.2 Field Semantics

|Field                |Type   |Required|Notes                                                        |
|---------------------|-------|--------|-------------------------------------------------------------|
|`attestations`       |array  |yes     |Zero or more attestation entries. MAY be empty after a revocation that leaves no entries — the record itself SHOULD then be deleted. |
|`attestations[].type`|string |yes     |Identifier from §3.4.                                        |
|`attestations[].value`|string|varies  |Email address, handle, etc. Absent for `passkey`.            |
|`attestations[].platform_id`|string|OAuth only|Stable platform identifier, used to detect handle changes.|
|`attestations[].credential_id`|string|passkey only|base64url-encoded WebAuthn credential ID.         |
|`attestations[].verified_at` |i64   |yes     |Unix seconds UTC of verification.                            |
|`pubkey_alg`         |u8     |yes     |`sig_alg` registry value (`0x01` = ML-DSA-65).               |
|`created_at`         |i64    |yes     |Unix seconds UTC of record creation.                         |
|`updated_at`         |i64    |yes     |Unix seconds UTC of the most recent attestation update.      |

### 4.3 Ordering and Concurrency

The `attestations` array is ordered by `verified_at` ascending. Readers MUST NOT rely on array ordering for correctness — viewer precedence is defined structurally in §5.3, not by array position.

Record writes are **last-writer-wins on `updated_at`**. Cloudflare Workers KV does not expose transactions to request handlers, so the Worker performs a non-atomic read-then-mutate-then-write against `identity:<fingerprint>` when appending or revoking an attestation entry (`handleEmailVerify` and `handleEmailDelete` in `workers/api/src/routes/attestation.ts`). Under concurrent writes against the same fingerprint two requests can both observe the pre-write record, mutate their own copies, and race; the later write silently overwrites the earlier.

Phase 2 accepts this race because:

1. Each fingerprint belongs to a single keypair held by a single user, so self-inflicted contention is rare. The dominant write path is "one email attestation per key, one attestation per user-driven action."
2. Every concrete operation (email verify, email delete) carries its own proof-of-possession signature (§6.2), so a losing writer cannot have forged the request — only the write-order is ambiguous.
3. `updated_at` lets a future reconciler detect out-of-order writes after the fact.

If contention becomes observable under real load, a Phase 3 revision MAY introduce a Durable Object per fingerprint to serialise writes. The on-disk shape does not change; only the write-path wrapper does.

-----

## 5. Viewer Identity Resolution

### 5.1 Procedure

```text
1. Viewer decrypts the qub per PROTOCOL.md §8, producing a RevealedQub.
2. Viewer verifies the signature per PROTOCOL.md §9.4.
   If signature verification fails → display "signature verification failed."
   Identity resolution MUST NOT be attempted.
3. If sig_alg == 0x00 (unsigned) → display "unsigned qub."
   Identity resolution MUST NOT be attempted.
4. Compute fingerprint = SHA3-256(author_pubkey_bytes).
5. Issue GET /api/v1/identity/attestation/<fingerprint_hex>.
6. On 200: render the richest available attestation per §5.3.
7. On 404 or network error: fall back to §2.2 fingerprint display.
```

### 5.2 Non-Blocking Fetch Requirement

The identity fetch MUST NOT block the reveal. The viewer renders the qub body immediately, with the §2.2 fingerprint as the initial author-line value. The identity request runs in parallel; on success, the author line is updated in place. A viewer implementation MUST tolerate an attestation response arriving after the user has already dismissed the reveal.

### 5.3 Precedence

When a record contains multiple attestations, the viewer displays a **single** richest form for the byline, selected by:

```text
handle  >  x  >  github  >  google  >  fingerprint
```

Email attestations never participate in viewer-byline selection — the address is never rendered as a public byline. Email surfaces only as a boolean **"verified email"** pill on the `/u/<handle>` profile card (no address shown). A passkey attestation also never participates in viewer selection (§3.5).

Rationale: handles are the qub-native display name and are chosen by the user (or auto-allocated on their behalf) without leaking a real-world contact address. The handle auto-allocates at email-verify time, so any email-verified creator already has a handle — the byline path resolves to handle in practice. Social handles come next, ordered by prevalence in the current target audience; fingerprint is the universal fallback. A future revision MAY surface multiple attestations simultaneously on a verification panel, but the byline MUST show exactly one.

### 5.4 Staleness Indication

Viewers MAY show a relative-time annotation on the verified-email pill or the social-attestation badge for attestations older than 180 days (e.g. "verified email · 8 months ago"). This is a UI-layer decision, not a protocol requirement.

-----

## 6. Security Considerations

**The substantive threat-model content for the identity layer has moved to `docs/SECURITY-DESIGN.md` §5** (Identity-Layer Threats). That doc is the single authoritative home for qub's security design — threat model, defence-in-depth layers, enforcement matrix, post-incident posture. Maintaining the threat enumeration in two places drifts; this section is preserved as a deep-link anchor for cross-refs from §3 (attestation flows) and §5 (viewer resolution).

What you'll find in `docs/SECURITY-DESIGN.md` §5:

- §5.1 Attestation Binding Attack — the email pre-registration race and the 6-digit-code mitigation.
- §5.2 Proof-of-Possession — the seven domain-separated challenge shapes (AUTH, EMAIL, DELETE, HANDLE_RENAME, HANDLE_DELETE, PROFILE_SET, AVATAR_SET), the timestamp-window replay protection, the `V<n>` nonce-reservation rule.
- §5.3 Attestation Staleness — `platform_id`-based drift detection, `verified_at` surfacing, no silent OAuth refresh.
- §5.4 Privacy Model — opt-in attribution per qub, email never displayed publicly, the two structural guards.
- §5.5 Revocation Boundary — future-only viewer resolution; key rotation as a Phase 3 concern.
- §5.6 Multi-Script Handle Threats — homograph spoofing, bidi spillover, invisible-character duplicates, NFC ambiguity, cross-impl drift, operational rollback. Each maps to a §3.2.6 validation-pipeline step.

The §3.2 attestation flows and the §5.3 viewer-precedence rules continue to be specified here; the threat reasoning that justifies them lives next door.

-----

## 7. Phasing

### 7.1 Phase 2

- Layer 0 — bare keypair signing, fingerprint display.
- Layer 1 — email attestation via SendGrid code challenge.
- Layer 1 — qub handle (auto-allocated alongside email; personalised subject to a 30-day cooldown). Gated by `flags:handle_autoalloc_enabled` and `flags:handle_rename_enabled` for dark-launch; see §3.2.5.

Rationale: email verification is already scheduled for Phase 2 (PDD §4.3, §8.5). Layer 0 is a prerequisite for any signing at all. The handle rides alongside email in the same verify round-trip so the viewer byline never settles on a raw email while the norm is being set. Together they give the MVP-adjacent signed experience the clearest utility per unit of implementation cost.

### 7.2 Phase 3

- Layer 2 — social OAuth (X, GitHub, Google).
- Layer 3 — passkey durability upgrade.

Rationale: both layers share infrastructure with Phase 3 work already scoped (Cross-Device Identity via Passkeys, FUTURE.md §7; expanded account model). Layer 2 and Layer 3 are independent — phase ordering here is about operational readiness, not technical dependency.

### 7.3 Independence

Layers are independent by design. A user who completes Phase 2 acquires Layer 0 + Layer 1 and can stay there indefinitely. A user who later acquires a passkey gains Layer 3 on top of the existing Layer 1 without revalidating the email. Implementation phasing reflects rollout priority, not structural coupling.

### 7.4 Shipped — qub-Native Handle

The handle-attestation proposal originally tracked as `docs/HANDLE-LAUNCH.md` (never written; design absorbed directly into this document) landed in the Phase 2 rollout. The normative integration lives in §3.2.5 (allocation, rename, release); §3.4 (identifier registry); §4.1 (record shape example); §5.3 (precedence); and the `QUB_IDENTITY_HANDLE_RENAME_V1` / `QUB_IDENTITY_HANDLE_DELETE_V1` domain separators introduced alongside the existing `QUB_IDENTITY_*` family. This document is authoritative for implementation.

The V2 multi-script handle character set adopted on 2026-05-12 (§3.2.6, §6.6) extends this work in preparation for shipping the ten additional locales tracked under GitHub issue #45. V1 handles remain valid and round-trip through V2 unchanged; the implementation work is tracked separately from the policy decision recorded here.

### 7.5 Public Profile Pages

The public profile page at `/u/<handle>` (and the `/@<handle>` Worker-side redirect) is the public surface for the handle layer. It is a verified-identity card: handle, optional self-declared `display_name` + URL, "verified email" pill (when an email attestation is on the record — the address itself is never displayed), and the cryptographic fingerprint short form. The page does not list a creator's qubs; opt-in public attribution (PROTOCOL.md §7 Arweave-tag layer) is the only mechanism that ties a sealed qub to a creator, and visitors who want to see a specific qub follow that qub's delivery URL directly.

Two write surfaces extend the attestation schema without breaking the §4.1 record shape:

- A `profile?: { display_name?: string, url?: string, updated_at: i64 }` block on `AttestationRecord`. The block is optional — every email-verified creator gets an attestation record with attestations, but the profile block is created only on first set and deleted when both fields end up empty.
- A `POST /api/v1/identity/attestation/profile` endpoint with its own domain-separated PoP signature (`QUB_IDENTITY_PROFILE_SET_V1`, 27 bytes). The challenge shape is `domain || fingerprint || prev_updated_at_be(8) || display_name_len_be(2) || display_name_nfc_utf8 || url_len_be(2) || url_utf8 || timestamp_be(8)`. `prev_updated_at` is a CAS token — a stale capture cannot replay across an intervening edit.

Validation rules enforced server-side:

- `display_name` is NFC-normalised, **1–50 graphemes** (counted via `Intl.Segmenter`) with a secondary 200-code-point storage ceiling, free of Unicode general-category Cc/Cf control chars. The banned range covers C0/C1 controls (`U+0000`-`U+001F`, `U+007F`-`U+009F`), zero-width/bidi controls (`U+200B`-`U+200F`, `U+2028`-`U+202F`, `U+2060`-`U+206F`), and `U+FEFF`.
- `url` parses through `new URL(s)`, has `.protocol` ∈ {`http:`, `https:`}, and is ≤ 512 chars. `javascript:` / `data:` / `file:` / `mailto:` are explicitly rejected at the validator boundary.
- Either field may be omitted or empty to clear it; if both end up empty, the entire `profile` block is removed.
- Rate limit: 10 sets per hour per fingerprint via the standard `checkRateLimit(env, "profile:" + fingerprint, 10, 3600)` helper.

Bot UAs hitting `/u/:handle` receive a stub with `og:title` (display_name or `@handle`) and a JSON-LD `Person` schema with `name` + `url`. Browsers fall through to the SPA shell from `env.PAGES_ORIGIN`. The `@handle` byline on viewer-side surfaces (countdown, reveal, cosigner badges) hyperlinks to `/u/<handle>` for opt-in publicly-attributed qubs, so the byline is a navigable identity anchor and the profile page is the destination.

Layered-model placement: the profile block carries no externally-attested claim — it sits at the *self-declared* level alongside the handle, not at Layer 2 / Layer 3 attestation. A future revision MAY surface a "verified URL" badge if we add a domain-attestation flow, but the launch shape is explicitly self-declared.

## 8. Email Risk Classifier

The verifying email address is classified at sign-up time and the result is persisted on the per-identity record. The output drives downstream rate-limit ratchets (Phase 2: pact stage cap), but does **not** influence attestation resolution — an identity attestation continues to be a public claim about a fingerprint regardless of how the underlying email was tiered.

Implementation: `workers/api/src/utils/email-risk.ts`. Feature-flagged via `flags:email_risk_classifier_enabled` in the `ENTITLEMENTS` KV; when off the verify path is unchanged.

### 8.1 Tiers

| Tier | Meaning | Treatment |
|---|---|---|
| `blocked` | Domain on the bundled disposable-email denylist | Hard-rejected at `/auth/magic-link`, `/auth/code/request`, and `/identity/attestation/email/begin` with `400 email_not_supported`. Token / code / SendGrid send never fires. |
| `risky` | Domain has no MX records (NXDOMAIN, or empty MX answer) | Verification proceeds; persisted on the identity. Downstream limits ratchet. |
| `neutral` | Recognised free-mail provider (gmail/outlook/yahoo/icloud/proton/aol/gmx/fastmail/hey/tutanota and common alias domains) | Verification proceeds. Informational only — current downstream limits are unchanged for `neutral`. |
| `trusted` | Custom or business domain with MX present (or any address verified before the classifier shipped) | Verification proceeds at full default limits. |

A missing `risk_tier` on a legacy identity record MUST be treated as `trusted`. Users predate the classifier and have an already-trusted operating history.

### 8.2 Signal sources

1. **Disposable-domain denylist.** Bundled as `workers/api/src/data/disposables.json` from the public list at <https://github.com/disposable-email-domains/disposable-email-domains>. Refreshed via `workers/api/scripts/refresh-disposables.sh` on a quarterly chore commit cadence — no runtime fetch dependency on the upstream repo.
2. **MX presence probe** via Cloudflare DNS-over-HTTPS (`cloudflare-dns.com/dns-query`, `application/dns-json`). 1.5 s timeout. Treats DoH non-200 / timeout as `unknown` and **fails open** — does not promote to `risky` on infrastructure error. A telemetry counter (`m:email_risk_classifier_error:<date>`) makes the outage rate observable.
3. **Free-mail provider lookup.** Inline static map in `email-risk.ts`. Pure; no I/O.

### 8.3 Caching

The full `RiskAssessment` is cached at `email_risk:<sha256(lowercased email)>` in `ENTITLEMENTS` KV with a 90-day TTL. Re-verifies of the same address pay no DoH round-trip. The cache key hashes the address so a KV dump never carries plaintext emails into operator tooling.

Invalidation: rely on TTL. If a domain transitions from "no MX" (configuration error) to "MX live", the user re-classifies on the next verify after cache expiry. An operator override is out of scope for the initial ship; if false-positive rate proves higher than expected, follow-up will introduce a `risk_tier_override` field plus a `support@qub.social` escalation flow.

### 8.4 Persistence on the identity

Two new optional fields on `IdentityRecord` (`workers/api/src/kv.ts`):

```ts
risk_tier?: "trusted" | "neutral" | "risky" | "blocked";
risk_assessed_at?: number;  // unix seconds UTC
```

Both are written by the shared `/auth/verify` verifier. That includes clicked magic links and successful `/auth/code/verify` submissions, because the code endpoint mints an internal auth token and delegates to `/auth/verify` after checking the 6-digit code. The classifier does not run inside `/identity/attestation/email/verify` because that path predates an identity record and writes to `AttestationRecord` only — the canonical "we now own this email for account/device purposes" event is the shared auth verifier.

### 8.5 Privacy posture

The classifier never sees plaintext content; it operates on the address alone. Cached assessments are hashed-keyed. The disposable list is a static bundle, so no per-request signal about the user's email is sent to a third party. The MX probe leaks the *domain* to Cloudflare's public DNS resolver, which is the same exposure the user's own MX-resolving mail client would create — net-new third-party exposure is zero.

-----

## 9. Login Email Rotation (Email Change)

A user MAY change the canonical login email on their `IdentityRecord` (`identity:<email>` in `ENTITLEMENTS` KV) without losing identity continuity — handle, sealed-history index, tier, signed-attestation bindings, and Sybil counter all carry across the swap. This is **not** an attestation operation in the §3 sense — it does not verify a new email against a keypair — but the swap does keep existing attestations consistent: step 7 (§9.3) rewrites the stored `email` *value* on every `identity:<fingerprint>` record that attested the old address, so signed-qub author resolution and the `/u/<handle>` profile keep working without the user re-running any flow. Binding a *new* signing key to the email still uses the standalone `/identity/attestation/email/{begin,verify}` flow (which, as a byproduct, transfers the per-`IdentityRecord` handle via the existing `applyHandleOnEmailVerify`).

### 9.1 Endpoints

Three POST endpoints under `/api/v1/identity/email/change/`:

| Endpoint | Purpose |
|---|---|
| `POST .../begin`   | Validate the new address, classify it (§8), reject collision, mint two HMAC tokens (verify + cancel), persist a 30-min pending record, dispatch two emails. |
| `POST .../verify`  | HMAC-verify the link from the NEW address, single-use-tombstone it (`magic:<sha256>`), perform the atomic identity swap. |
| `POST .../cancel`  | HMAC-verify the link from the OLD address, single-use-tombstone it, delete the pending record. Self-serve — no auth, the HMAC is the credential. |

All three return 503 with `code: "AUTH_DISABLED"` when `AUTH_SECRET` is unset.

### 9.2 KV layout

| Key | Lifetime | Purpose |
|---|---|---|
| `email_change_pending:<old_email>` | 30 min TTL | `EmailChangePending` record carrying both nonces; one outstanding change per identity (a fresh `/begin` overwrites). |
| `magic:<sha256(token)>`            | 30 min TTL | Single-use tombstone for verify + cancel tokens (shared namespace with magic-link auth). |
| `email_change_old_rate:<sha256(old)>:<day>` | 24 h TTL | 3/24h per-old-email cap. |
| `email_change_new_rate:<sha256(new)>:<day>` | 24 h TTL | 1/24h per-new-email cap (anti-spam: prevents flooding a victim's inbox). |
| `email_change_ip_rate:<ip>:<day>`           | 24 h TTL | 10/24h per-IP cap. |

The pending record snapshots the requester's locale (resolved from `IdentityRecord.locale` if absent on the request body) so both outbound emails go in a consistent language even if the user's UI locale changes mid-flow.

### 9.3 Atomic swap (load-bearing order)

The verify handler runs the swap in this exact sequence so any partial failure leaves the user reachable on the OLD email:

1. Read `email_change_pending:<old_email>`. Reject if the verify nonce on the token doesn't match the record's `verify_nonce`.
2. Read `identity:<old_email>`. Reject with `IDENTITY_MISSING` if absent (out-of-band deletion).
3. Re-check `identity:<new_email>` is absent. Reject with `EMAIL_TAKEN` and clear the pending if a third party registered while pending.
4. Write `identity:<new_email>` with the same record, `email` field updated, risk tier re-classified against the new address.
5. Update each `device_link:<device_id>` in `IdentityRecord.device_ids` → `<new_email>`.
6. Copy `verified:<sha256(old)>` → `verified:<sha256(new)>`, then delete the source.
7. Migrate the address-keyed identity surfaces onto the new email (`migrateEmailScopedSurfaces`): rewrite the `email` attestation entry on **every** `identity:<fingerprint>` record that attested the old address — reconciling any stale per-fingerprint `handle` entry to the canonical `IdentityRecord` handle in the same pass — re-point the `handle:<handle>` reverse-index owner, and move the `email_fp:<email>` projection hint. **Best-effort**: a failure here logs and is swallowed rather than failing the swap, which has already committed at step 5. Without this step the §5 viewer-resolution and `/u/<handle>` read paths join through the now-deleted old `IdentityRecord` and fall back to stale per-fingerprint handle entries.
8. Delete `identity:<old_email>` (LAST — keeps the user reachable on the old address through every prior step).
9. Delete `email_change_pending:<old_email>`. The verify-token tombstone was already written by `consumeMagicToken` at the top of the handler.

Pact email-binding markers (§1.1, ≤15 min TTL) and rate-limit buckets self-clean and don't need explicit migration.

Step 7 is keyed by address, not by the immutable `account_id`, because the attestation namespace (`identity:<fingerprint>`), the handle reverse index (`handle:<handle>`), and the projection hint (`email_fp:<email>`) all predate the `account_id` layer and still resolve through the email. The `account_id` reverse index, Stripe bindings, and Builder-key ownership are deliberately *not* in this list — they survive the swap untouched because they key off `account_id` (§9.1 carries the account-id re-point as step 4b in code).

### 9.4 Recovery primitive

The OLD-address notification carries a single-use cancel link. This is the recovery channel against an unauthorised `/begin` (the request endpoint is unauthenticated by design — same trust model as magic-link, see §6.5 — so without the cancel link the rightful holder of the old address would have no way to abort an adversarial change request). Self-serve: the HMAC + nonce + tombstone is the credential; forcing login defeats the purpose if the bad actor took over the user's local device. A `/cancel` after `/verify` already won returns `NO_PENDING` (the pending record was deleted by the swap).

### 9.5 Eventual-consistency window

Cloudflare KV writes propagate asynchronously across regions (~60s worst case). During the window between step 4 and step 7 — and any cross-region read lag thereafter — a stale region may observe `identity:<old_email>` AND `identity:<new_email>` simultaneously. The user remains reachable on both addresses during that window, never on neither. Documented here as "this is fine" rather than "this is a bug" — the alternative (delete-then-write) would create a real outage window where the user is reachable on neither.

### 9.6 Out of scope for §9

- **Account merge.** Combining two distinct existing identities into one is a separate, harder problem (handles, sealed-history merge, Sybil counter aggregation). Not addressed by this flow.
- **Removing email entirely.** A future "anonymous mode" would lift the device-linking record entirely; not part of this rotation flow.
- **Attesting a new keypair.** Step 7 (§9.3) rewrites the `email` *value* on attestation records that already attest the old address, so existing fingerprints keep resolving after the swap. It does **not** create an attestation on a keypair that never attested the old address — binding a fresh signing key (e.g. after the user clears browser data and regenerates their ML-DSA key) still uses the standalone `/identity/attestation/email/{begin,verify}` flow.
- **Sealed `Author` Arweave tags.** Per-qub authorship tags are immutable bytes on Arweave, set at seal time. A login-email swap does not retroactively rewrite them (and could not — Arweave is append-only).

-----

## 10. Profile metadata

Beyond the attestation entries (§3), a keypair carries an optional **profile block** — self-declared display metadata surfaced on the `/u/<handle>` card and the viewer author line. It is stored in the `ProfileBlock` (`workers/api/src/kv.ts`), dual-written to both the per-fingerprint `AttestationRecord.profile` and the email-scoped `IdentityRecord.profile` so it survives ML-DSA key rotation.

**Keyless-device read path.** Because the block is mirrored onto the email-scoped `IdentityRecord`, it is also projected (read-only) into the device-session `GET /api/v1/identity?device_id=…` response (`workers/api/src/routes/identity.ts`) — the same out-of-scope device-session endpoint described in §1's IdentityRecord note. This is the only identity lookup a device with **no local signing key** can make (a fresh browser, a second device, or one whose IndexedDB was cleared cannot compute a fingerprint to hit `GET /identity/attestation/<fingerprint>`). The projection lets the signature page render the creator's established display name / website / avatar before any key is generated or portable-unlocked. The projection is hand-written and carries only the `profile` sub-fields — never the triage state §1 forbids in customer-safe DTOs.

The block has independent **field-groups**, each with its own write endpoint, proof-of-possession challenge domain, and concurrency primitive:

|Field-group |Fields |Endpoint |Challenge domain |Concurrency |
|------------|-------|---------|-----------------|------------|
|Text |`display_name`, `url` |`POST /api/v1/identity/attestation/profile` |`QUB_IDENTITY_PROFILE_SET_V1` |CAS token `updated_at` |
|Avatar |`has_avatar`, `avatar_version` |`POST /api/v1/identity/avatar` |`QUB_IDENTITY_AVATAR_SET_V1` |last-writer-wins |

All challenges are signed with the ML-DSA-65 keypair and carry a ±120s timestamp, exactly as the §6.2 attestation challenges do.

### 10.1 Avatar

A creator MAY upload one square profile picture. The image is stored in the dedicated `AVATARS` R2 bucket keyed `avatar/<fingerprint>`; the `ProfileBlock` records `has_avatar`, a monotonic `avatar_version`, and an `avatar_fp` pointer. `avatar_fp` is the fingerprint that owns the R2 object — needed when handle lookup resolves to a sibling fingerprint (a user with multiple devices verifying the same email has multiple fingerprints sharing one handle and one canonical avatar); without `avatar_fp`, profile renders would 404 the R2 object for every sibling that didn't itself upload.

`handleAvatarGet` also carries a server-side fallback for legacy records whose IR mirror predates the `avatar_fp` field: when the requested fingerprint has no R2 object, the handler walks fingerprint → email entry → `IdentityRecord.profile.avatar_fp` and re-issues the R2 fetch against the canonical key before returning 404. This recovers avatars on accounts that uploaded before the `avatar_fp` mirror landed in `handleAvatarSet`; new uploads populate `avatar_fp` on the first write and don't need the fallback.

- **Re-encode is the security boundary.** The client crops, rotates, and re-encodes the picked file to a 512×512 WebP on a `<canvas>` before upload. The uploaded artifact is therefore always a fresh raster the browser produced — EXIF stripped, and an SVG (active-content) payload impossible. The Worker independently magic-byte-sniffs the decoded bytes and accepts only PNG / JPEG / WebP, rejecting SVG and everything else regardless of the client-supplied content type. Hard size ceiling: 150 KiB.
- **Challenge.** `QUB_IDENTITY_AVATAR_SET_V1` (26 bytes) ‖ `fingerprint` (32) ‖ `SHA3-256(image bytes)` (32; all-zero for a removal) ‖ `timestamp_be` (8). The image hash binds the signature to the exact bytes uploaded; a captured request cannot be replayed against a substituted image.
- **No CAS token.** An avatar is a single binary with no merge, so writes are last-writer-wins. `avatar_version` increments on every upload *and* every removal and rides as the `?v=` query on the public, immutably-cached `GET /api/v1/identity/avatar/<fingerprint>` URL purely for cache-busting.
- **Retention.** The R2 object is deleted on attestation revoke and on an admin moderation ban (`deny:avatar:<fingerprint>` in `DENYLIST`, which also blocks re-upload); the daily retention-sweep cron deletes orphans whose fingerprint has no live attestation record. See `docs/DATA-RETENTION.md`.

The avatar is a best-effort progressive enhancement: a viewer that cannot load it falls back to the handle monogram (profile card) or omits it (viewer author line). It never blocks signature verification or identity resolution.

-----

## 11. Sealed-History Index

Adjacent to the attestation surface — and load-bearing for the cross-device experience — is the per-IdentityRecord **sealed-history index**. It is a server-side mirror of the user's qubs, so signing in on a new device restores the list immediately.

- **Server cap.** `IDENTITY_SEALED_HISTORY_CAP = 1000` entries (`workers/api/src/kv.ts`). Writes past the cap drop the oldest entry by `sealed_at` after the merge pass.
- **Client cap.** `SEALED_HISTORY_CAP = 1000` mirrored in `crates/qub-app/src/storage/identity.rs`. The client's local sealed-history index follows the same shape and bound.
- **Merge semantics.** `merge_sealed_history` (client side) and `mergeSealedHistory` (Worker side) perform a deterministic dedup keyed on `(tx_id, content_type)`. On conflict the entry with the greater `sealed_at` wins; ties break on lexically-greater `tx_id`. Same algorithm both sides so a client → server push and a server → client hydrate converge regardless of order.
- **Hydration.** On boot, a linked client calls `GET /api/v1/identity?device_id=<id>` and merges the server's sealed-history index into its local one. The local copy is the authoritative read source for the drawer's "Sealed" and "Revealed" lists; the server copy exists only to seed new devices.

The sealed-history index is **not** an attestation surface — it carries no proof-of-possession signature, is keyed by `identity:<email>` rather than by fingerprint, and is never resolved on a viewer-facing render path. It is documented here because the read path through `GET /api/v1/identity` is adjacent to attestation lookup and operators reading this spec to debug identity issues need to know the surface exists.

-----

## 12. Operator Surfaces

Two admin-facing endpoints expose attestation state to operators; neither is reachable without `Authorization: Bearer <ADMIN_API_TOKEN>`.

- **`GET /api/v1/admin/metrics/attestations`** (`workers/api/src/routes/admin-attestations.ts`) — identity & attestation health rollup. Stitches the auth funnel (magic-link issuance plus the shared verify success/failure breakdowns from `m:auth_*` counters — code-first verifications fold into the shared verify counters because `/auth/code/verify` delegates to `/auth/verify`; the endpoint does not separately surface the `m:auth_code_*` issue/verify counters), the attestation funnel (email begin → verify → revoke, handle auto-allocation / rename / revoke / cooldown blocks, profile updates from `m:attest_*` / `m:handle_*` counters), and the email-risk-classifier rollup into one response. Powers the Identity tab of `/admin/dashboard`.
- **Existing admin key-management endpoints** (`workers/api/src/routes/admin-keys.ts`) cover Builder API keys, not identity attestations — listed here for completeness so the two namespaces aren't confused.

Two public-facing helper routes also sit adjacent to the attestation surface but are NOT operator-only:

- **`GET /@<handle>`** (`workers/api/src/routes/handle-alias.ts`) — 302 redirect to the canonical `/u/<handle>` SPA route. Exists because the Leptos router's `path!` macro can't parse a literal `@` segment alongside a `:handle` parameter; the Worker handles the prettier URL form.
- **`GET /u/<handle>` (bot UA)** (`workers/api/src/routes/profile-meta.ts`) — bot-aware SSR for the profile page. Renders title + Open Graph + JSON-LD `Person` schema for crawlers; browsers fall through to the SPA shell. Mirrors `routes/viewer-meta.ts` for qub-viewer pages.