# qub

> Seal your words today. Prove when you said them.

qub is a timed commitment system. You compose a message, choose an unlock date, and qub timelock-encrypts it using drand's distributed randomness network. The sealed qub is stored permanently on Arweave. Before the unlock time, nobody — not even qub — can read the content. After the unlock time, anyone with the link can decrypt and verify the message.

## What agents can do

- **Create qubs** — seal a message 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
- **Manage identity** — link a device to an email via magic link, recover a previously-linked identity for cross-device qub history
- **Attest identity** — verify an email against a signing key so authored qubs display a verified identity
- **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
- Create verifiable audit trails with cryptographic timing guarantees
- Build workflows that trigger on qub unlock events

## API

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

### Authentication

There are three authentication paths:

1. **API key** — programmatic access. Pass `Authorization: Bearer qub_sk_...`. Required for `/api/v1/seal`, `/api/v1/webhooks`, and key rotation.
2. **Cloudflare Turnstile** — browser-only. The token is passed in the request body as `turnstile_token`. Used by `/api/v1/upload` and `/api/v1/upload-auth` when no API key is present.
3. **Magic link (email)** — user-facing identity verification. The browser requests a magic link via `/api/v1/auth/magic-link`, the user clicks it, and the resulting `/api/v1/auth/verify` call links a device to an email so the same identity can be recovered on a new device. Tokens are HMAC-signed, single-use, and expire in 15 minutes. This is the path the web app uses; agents typically don't need it unless they're impersonating a browser session.

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

### 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 (Arweave block timestamp + intent tag + current watching count); no decrypt. The viewer and the `<qub-embed>` iframe re-poll this every 30s during countdown so watching counts climb live; 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}/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/checkout` | API key or Turnstile | Create Stripe checkout session for qub credits |
| POST | `/api/v1/api-keys/checkout` | Turnstile | Create Stripe checkout session for a Builder API key |
| GET | `/api/v1/api-keys/provisioned` | None | One-time retrieval of a newly provisioned API key (by Stripe `session_id`) |
| POST | `/api/v1/api-keys/rotate` | API key | Rotate the current API key, returns the new secret with a grace period |
| POST | `/api/v1/auth/magic-link` | None | Issue a magic-link token to an email + device |
| POST | `/api/v1/auth/verify` | None | Verify a magic-link token, link the device, return the identity |
| GET | `/api/v1/identity` | None | Read-only lookup of the linked identity for a device |
| GET | `/api/v1/creator/qubs` | None | Identity-scoped aggregate of a creator's sealed qubs (oldest, next reveal, total watchers) |
| 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 Arweave |
| DELETE | `/api/v1/pact/stage/{id}` | API key or Turnstile | Retract a staged pact before co-signing (proof-of-possession required) |
| POST | `/api/v1/identity/attestation/email/begin` | None | Start email attestation — sends a 6-digit code |
| POST | `/api/v1/identity/attestation/email/verify` | None | Verify the 6-digit code to link email to signing key |
| DELETE | `/api/v1/identity/attestation/email` | None | Revoke email attestation (proof-of-possession required) |
| GET | `/api/v1/identity/attestation/{fingerprint}` | None | Look up the attestation for a public key fingerprint |
| POST | `/api/v1/report` | None | Submit a content report for moderation |
| 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 | `/api/v1/lifecycle/unsubscribe` | None | One-click unsubscribe from creator lifecycle emails (token in query string) |
| 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 Arweave `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"
}
```

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"
}
```

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.

### 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
```

### Identity recovery

After a magic-link verify, the device → email link is stored server-side. A new browser on the same device can recover the linked identity (and the user's sealed-history index) without re-clicking a magic link:

```
GET /api/v1/identity?device_id=<32-hex>
→ { "ok": true, "email": "...", "tier": "free", "qubs_remaining": 8, "sealed_history": [...], "locale": "en" }
```

Returns 404 with `{"code": "NOT_LINKED"}` if the device hasn't been linked yet.

### Creator qubs summary

Aggregates the creator's `sealed_history` into the three retention-facing facts the `/identity` surface needs in a single round-trip — oldest sealed qub, next upcoming reveal, and total watchers across every qub they've sealed. Same device-id auth surface as `/api/v1/identity`.

```
GET /api/v1/creator/qubs?device_id=<32-hex>
→ {
    "oldest_sealed":  { "tx_id": "...", "sealed_at": 1700000000, "unlock_at": 1710000000, "intent": "prediction" },
    "next_reveal":    { "tx_id": "...", "sealed_at": 1720000000, "unlock_at": 1750000000, "intent": "letter", "days_remaining": 42 },
    "aggregate_watchers": 1337,
    "qub_count": 12,
    "truncated": false
  }
```

Returns 404 `{"code": "NOT_LINKED"}` when the device isn't linked. `next_reveal` is `null` once every qub has already unlocked. `truncated: true` means the aggregate was computed over the 200 most recent seals (defensive cap — not reached in practice).

### 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`.
2. **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.
3. **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 Arweave. Returns the `tx_id` and delivery URL.
4. **Retraction** — Party A can retract before co-signing via `DELETE /api/v1/pact/stage/{id}` (proof-of-possession required).

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

### Email attestation

Link an email address to a signing key so viewers can see who authored a qub. The flow:

1. **Begin** — `POST /api/v1/identity/attestation/email/begin` with the email, public key fingerprint, and a proof-of-possession signature. Sends a 6-digit code via email.
2. **Verify** — `POST /api/v1/identity/attestation/email/verify` with the code and fingerprint. On success, the attestation is stored and visible to viewers.
3. **Revoke** — `DELETE /api/v1/identity/attestation/email` with a proof-of-possession signature. Removes the attestation.
4. **Lookup** — `GET /api/v1/identity/attestation/{fingerprint}` returns the current attestation for a public key (used by viewers during reveal).

## 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:** drand timelock encryption (tlock) using quicknet chain (BLS12-381, 3-second rounds)
- **Storage:** Arweave permanent storage (immutable, censorship-resistant)
- **Hashing:** SHA3-256 for content integrity (body_hash, qub_id derivation)
- **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/svailsa/qub


---

# Protocol Specification

Source: https://qub.social/protocol

# qub Protocol Specification

| Field | Value |
| ----------- | ----------------------------- |
| **Version** | 1.0 (protocol version `0x01`) |
| **Date** | 2026-04-16 |
| **Status** | Draft — Companion to PDD v1.0 |
| **Reviewed through** | 2026-04-18 (F4-e embed locale infrastructure, F4-g publisher contract — no protocol change; both live in the viewer presentation layer, not the wire format) |

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.

The PDD (§7) provides a summary; this document provides the complete specification.

Scope: the protocol layer is intentionally language-neutral — the qub body is opaque plaintext / markdown / voice / pact bytes, and locale-aware rendering is the viewer's responsibility (qub.social web app, `<qub-embed>` iframe, MCP clients, etc.). Embed presentation, loader URL pinning, and BCP 47 locale resolution are specified in [`docs/EMBED.md`](../../docs/EMBED.md), not here.

______________________________________________________________________

## 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 stored on Arweave. 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 message 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
    sender_label:        Option<String>,  // Decorative; not authenticated in MVP
    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>>, // Phase 2+
    author_pubkey:       Option<Vec<u8>>, // Phase 2+
    cosigner_pubkey:     Option<Vec<u8>>, // Phase 2+ (pact bilateral agreements)
    cosigner_signature:  Option<Vec<u8>>, // Phase 2+ (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).

### 2.3 SealedQub (Canonical Wire Format)

Serialised using canonical CBOR (§3). Uploaded to Arweave. 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, 0x00 = private (Phase 2+)
    unlock_at:         i64,             // Unix seconds UTC
    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]>,// Phase 2+ (private qubs only)
}
```

### 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,
    created_at:          i64,
    unlock_at:           i64,
    drand_chain_id:      String,
    drand_round:         u64,
    sender_label:        Option<String>,
    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>,
}
```

______________________________________________________________________

## 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)
"body_hash"           (10 encoded bytes)
"unlock_at"           (10 encoded bytes)
"created_at"          (11 encoded bytes)
"content_type"        (13 encoded bytes)
"sender_label"        (13 encoded bytes)  ← only if present
"author_pubkey"       (14 encoded bytes)  ← Phase 2+, only if present
"cosigner_pubkey"     (16 encoded bytes)  ← Phase 2+, only if present (pact)
"author_signature"    (17 encoded bytes)  ← Phase 2+, only if present
"cosigner_signature"  (19 encoded bytes)  ← Phase 2+, only if present (pact)
```

**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
"qub_id"            (7 encoded bytes)
"version"           (8 encoded bytes)
"unlock_at"         (10 encoded bytes)
"visibility"        (11 encoded bytes)
"drand_round"       (12 encoded bytes)
"drand_chain_id"    (15 encoded bytes)
"recipient_pubkey"  (17 encoded bytes)  ← only if present (Phase 2+)
"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 | Phase 2+ |
| ML-DSA-65 public key (1,952 bytes) | `0x59 0x07 0xA0` + 1,952 bytes | Phase 2+ |

______________________________________________________________________

## 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_V1"    ||    // domain separator: ASCII bytes [0x51 0x55 0x42 0x5F 0x49 0x44 0x5F 0x56 0x31] (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)
    body_hash           // [u8; 32] (32 bytes)
)
// Total preimage: 60 bytes → 32-byte output
```

**Domain separator encoding:** The string `"QUB_ID_V1"` 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, 0x31, 0x00]`.

**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.

### 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 message body.

### 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()` | Arweave 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 | Phase | Max Body Size | Notes |
| ------------- | --------------------------------------- | ------- | ------------- | --------------------------------------------------------------------- |
| `0x00` | Reserved (invalid) | — | — | MUST NOT be used |
| `0x01` | Plain text (UTF-8, restricted Markdown) | MVP | 50 KB | See §11 for rendering rules |
| `0x02` | Voice (Opus audio) | Phase 2 | 2 MB | Duration-capped |
| `0x03` | Pact (bilateral agreement, CBOR body) | Phase 2 | 100 KB | Body is canonical CBOR `PactTerms` (§6.1). Cosigner signing per §9.7. |
| `0x04`–`0x0F` | Reserved for qub-defined types | — | — | Assigned in future spec revisions |
| `0x10`–`0x7F` | Reserved for future standardisation | — | — | Requires spec approval |
| `0x80`–`0xFE` | Experimental / private use | — | — | Not guaranteed interoperable |
| `0xFF` | Reserved (invalid) | — | — | MUST NOT be used |

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.

______________________________________________________________________

## 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, PDD §8.4).
    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. Compute qub_id (see §4.1).
 6. Construct QubEnvelope with all fields.
 7. Serialise QubEnvelope using canonical CBOR → bytes B.
    Assert: serialised output matches canonical profile (§3).
 8. Select drand chain. Load chain_genesis_time and chain_period_seconds.
 9. Compute drand_round = ceil((unlock_at - chain_genesis_time) / chain_period_seconds).
10. Compute C = tlock_encrypt(B, drand_round, drand_chain_public_key).
11. 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.
13. Display seal-time disclosure. User confirms.
14. Validate upload eligibility via the qub upload service (bot-detection, entitlement, rate limits).
15. Submit SealedQubCbor to the qub upload service; the service signs and uploads to Arweave.
16. Receive arweave_tx_id and delivery URL from the service.
```

______________________________________________________________________

## 8. Unlock Protocol

The complete unlock sequence. Each step is normative.

```text
 1. Viewer opens delivery URL. Extract arweave_tx_id from path.
 2. Check denylist. If tx_id is denylisted → display block message. Stop.
 3. Fetch SealedQubCbor from Arweave (with multi-gateway fallback).
 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.
 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 §11 for text, §6 for pact).
17. Construct RevealedQub for display.
```

______________________________________________________________________

## 9. Authorship Signing (Phase 2+)

### 9.1 Rationale

Qubs are stored permanently on Arweave. Authorship signatures must remain unforgeable indefinitely. This makes post-quantum signatures (ML-DSA-65) preferable over classical schemes (Ed25519), whose security may degrade within the qub’s permanent lifetime.

### 9.2 Algorithm Registry

| `sig_alg` | Scheme | Key Size | Signature Size | Status |
| ------------- | ----------------------- | ----------- | -------------- | ----------------- |
| `0x00` | No signature (unsigned) | — | — | MVP default |
| `0x01` | ML-DSA-65 (FIPS 204) | 1,952 bytes | 3,309 bytes | Phase 2 default |
| `0x02` | Ed25519 | 32 bytes | 64 bytes | Reserved fallback |
| `0x03`–`0xFF` | Reserved | — | — | Future |

Viewers MUST reject unknown `sig_alg` values. Viewers that support `sig_alg` = `0x00` but not `0x01` SHOULD display “signature present but not verifiable by this viewer version” rather than silently ignoring the signature.

### 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)
    org_id_present             // u8 (1 byte): 0x00 = individual, 0x01 = org
    // org_id                  // [u8; 32] only if org_id_present == 0x01 (Phase 4+)
)

// Individual (MVP/Phase 2): total preimage = 91 bytes → 32-byte hash
// Org-delegated (Phase 4+): total preimage = 123 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.

**org_id_present:** In Phase 2, this is always `0x00` (individual signing). In Phase 4+, `0x01` indicates the signature was made under an org delegation, and `org_id` ([u8; 32]) follows. This ensures individual signatures are structurally distinct from org-delegated signatures — preventing cross-context reuse.

**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`, and `body_hash` via the §4.1 preimage, so any change to `content_type` or `created_at` 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 |
| `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_round`, `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 |

**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.
- For reply chains to carry end-to-end integrity, future protocol versions SHOULD either include `reply_to` in `sig_input` or require a separate `reply_sig` over `(qub_id, reply_to)`. Neither is part of Phase 2.

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 email, social handles, or passkey credentials — are defined in [`IDENTITY.md`](IDENTITY.md). Attestation resolution is a **viewer-side progressive enhancement** and is **not required** for signature verification.

A conforming verifier can complete every check in §9.4 without contacting the qub API, without any network beyond Arweave and drand, and without any server-side lookup. Identity display (beyond the fallback fingerprint defined in IDENTITY.md §2) 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 |
| Arweave 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 (Phase 2+ — 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 §12 needs only Arweave 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** |
| Arweave cost delta | ~$0.05 |

______________________________________________________________________

## 10. Private qub Encryption (Phase 2+)

Private qubs use two encryption layers: tlock for time-binding, and recipient-key encryption for audience restriction.

### 10.1 Encryption Stack

```text
Layer 1 (inner): AES-256-GCM with key derived from X25519 key exchange
Layer 2 (outer): tlock against drand round (same as public qubs)

Encrypt:
  1. Sender performs X25519(sender_ephemeral_secret, recipient_pubkey) → shared_secret
  2. Derive AES key via HKDF-SHA256(shared_secret, salt, "QUB_PRIVATE_V1")
  3. Encrypt QubEnvelope CBOR bytes with AES-256-GCM → inner_ciphertext
  4. tlock_encrypt(inner_ciphertext, drand_round) → outer_ciphertext
  5. SealedQub.tlock_ciphertext = outer_ciphertext
  6. SealedQub.recipient_pubkey = recipient's X25519 public key

Decrypt (after drand round):
  1. tlock_decrypt(outer_ciphertext, round_signature) → inner_ciphertext
  2. Recipient performs X25519(recipient_secret, sender_ephemeral_pubkey) → shared_secret
  3. Derive AES key via HKDF-SHA256(shared_secret, salt, "QUB_PRIVATE_V1")
  4. Decrypt inner_ciphertext with AES-256-GCM → QubEnvelope CBOR bytes
```

### 10.2 Post-Quantum Note

X25519 is not quantum-resistant. Private qubs stored permanently on Arweave face long-term quantum decryption risk. ML-KEM-768 (FIPS 203) is the intended future replacement, gated on library maturity and viewer bundle impact assessment. The `version` field and protocol versioning support introducing ML-KEM without breaking existing private qubs.

______________________________________________________________________

## 11. Markdown Rendering and Sanitisation

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

### 11.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

### 11.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. |

### 11.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 (§11.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.

### 11.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.

______________________________________________________________________

## 12. 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 Arweave gateway.
3. Confirm Arweave 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 Arweave 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 | Arweave block inclusion may lag actual upload by minutes. The commitment timestamp is the block time, not the moment the user pressed “seal.” |

______________________________________________________________________

## 13. Versioning

### 13.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.

### 13.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 |

### 13.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.

______________________________________________________________________

## 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)
  body         = "Hello, future."  (UTF-8, 14 bytes)

Intermediate:
  body_hash = SHA3-256("Hello, future.")
            = 76ab8b3f843c6ed4f2d0fd75b9f457b4
              ad49dd4450f9c22723ae430e3af3211d

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

Preimage (60 bytes):
  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)
  body_hash              // 32 bytes

Expected output:
  qub_id = SHA3-256(preimage)
         = f955de1c44502eea9c2132506c765f3b
           949fb79f26ecfcb27b6787c374c7ba01
```

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.

### 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).


---

# AI Agent Support — quotas, monetisation, hardening

Source: docs/AI-AGENT-SUPPORT.md

# 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)|
|----------------------|---------------------------------------------------------------------------------------|------------------|
|Arweave 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 Arweave 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 Arweave 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 Arweave 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/day|Webhooks|Seal access|Rate limit|Price       |
|-----------|---------|---------|--------|-----------|----------|------------|
|Free API   |5 total  |100      |3       |No         |10/min    |$0          |
|Builder    |200/month|5,000    |25      |Yes        |60/min    |$29 AUD/mo  |
|Enterprise |Unlimited|50,000   |250     |Yes        |500/min   |Custom      |

- Free tier qubs are non-renewable (5 total, ever). Free tier cannot use the `seal` endpoint — they must seal client-side using the MCP server and upload via `POST /api/v1/upload`.
- Builder tier qubs reset monthly via Stripe subscription webhook.
- Enterprise tier has no hard qub limit but is usage-monitored.

### 2.3 Quota Enforcement Points

|Endpoint              |Quota check                                                            |
|----------------------|-----------------------------------------------------------------------|
|`POST /api/v1/seal`   |`tier != "free"`, `qubs_remaining > 0`, decrement on success           |
|`POST /api/v1/upload` |`qubs_remaining > 0`, decrement on success (API key path only)         |
|`GET /api/v1/qub/:id` |`reads_today < max_reads_per_day`, increment on success                 |
|`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 subscription ($29 AUD/month)
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=200
   d. Email the key to the customer (one-time display)
4. On customer.subscription.deleted webhook:
   a. Look up key by stripe_customer_id
   b. Set disabled=true
5. On invoice.paid webhook (monthly renewal):
   a. Reset qubs_remaining to 200
```

### 3.2 Key Lifecycle

|Event                          |Action                                     |
|-------------------------------|--------------------------------------------|
|Subscription created           |Provision key, set tier and quotas           |
|Monthly invoice paid           |Reset qubs_remaining to tier allocation     |
|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     |

### 3.3 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

Replace the current flat per-IP rate limits with per-key limits that vary by tier:

|Endpoint       |Free API |Builder  |Enterprise|
|---------------|---------|---------|----------|
|`seal`         |Blocked  |10/min   |60/min    |
|`upload`       |5/10min  |20/min   |60/min    |
|`qub-read`     |30/min   |100/min  |500/min   |
|`webhooks` CRUD|5/min    |10/min   |30/min    |

### 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 Arweave submissions |5 per minute across all keys         |
|Max webhook registrations (global) |1,000 total across all keys          |

### 5.3 Arweave Cost Protection

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

```text
1. Track daily Arweave 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 Arweave 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 Arweave, 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 Arweave 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 Arweave 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 Arweave 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

# qub Identity Attestation Specification

|Field      |Value                                       |
|-----------|--------------------------------------------|
|**Version**|1.0                                         |
|**Date**   |2026-04-13                                  |
|**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) — 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 15 minutes, that the controller of the counter-party mailbox is the entity attempting to co-sign.

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.

Two operational notes that commonly confuse this boundary:

1. **Cross-browser magic-link hydration.** When a user clicks "Link email" in browser A but opens the SendGrid link in browser B (Gmail opens links in the system default browser — a Comet user lands in Chrome), the HMAC-bound `device_id` in the token is A's. The Worker correctly links `device:<A_id>` → email even though `/auth/verify` runs in B. B persists its own local `IdentityCache` from the verify response; A's local cache stays empty until the app on A next boots and calls `GET /api/v1/identity?device_id=<A_id>` to mirror the server-side link. This boot-hydration path is local-cache plumbing only — no attestation is created, resolved, or touched.
2. **Sign-out is local-only.** The drawer "sign out" action clears the local `IdentityCache` and leaves the `device:<id>` → email server record intact. A signed-out user on the same browser will therefore re-hydrate on the next app boot. Making sign-out sticky across restarts would require a separate "logout sentinel" IDB record — explicitly out of scope here.

Neither behaviour 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.

-----

## 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

Five 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`   |`mark@example.com (verified)`                         |SendGrid code challenge|
|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.

### 3.2 Layer 1 — Email

A Layer 1 attestation binds a keypair to a verified email address.

- **Acquisition:** The user submits their email to qub. The Worker emails a 6-digit verification code via SendGrid. The user 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> }`.
- **Verification procedure:** Code-based challenge. Codes (not links) are preferred because codes are harder to silently intercept and cannot be forwarded through URL previewers or mail scanners (§6.1). Codes expire after 10 minutes and are single-use.
- **Viewer display:** `<email> (verified)`, e.g. `mark@example.com (verified)`.
- **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.

### 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`   |Phase 2|SendGrid code challenge        |
|`x`       |Phase 3|OAuth 2.0                      |
|`github`  |Phase 3|OAuth 2.0                      |
|`google`  |Phase 3|OAuth 2.0 + OIDC               |
|`passkey` |Phase 3|WebAuthn registration ceremony |

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.

-----

## 4. KV Schema

Attestations are stored in the `IDENTITY` KV namespace. The key format extends the pattern documented in FUTURE.md §3.3 Decision 3:

|Pattern                  |Purpose              |Phase |
|-------------------------|---------------------|------|
|`identity:<fingerprint>` |Identity attestations|Phase 2|

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.

### 4.1 Record Shape

```text
identity:<fingerprint>  →  {
    attestations: [
        { type: "email",   value: "mark@example.com", 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>
}
```

### 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 Canonicalisation

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`. The Worker MUST apply an atomic read-modify-write under a KV transaction when mutating the `attestations` array.

-----

## 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/<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, selected by:

```text
email  >  x  >  github  >  google  >  fingerprint
```

A passkey attestation never participates in viewer selection (§3.5).

Rationale: email is the most widely recognised identity anchor; social handles are next, ordered by prevalence in the current target audience; and fingerprint is the universal fallback. A future revision MAY surface multiple attestations simultaneously (e.g. a verification panel listing all attested identities), but the default author line MUST show exactly one.

### 5.4 Staleness Indication

Viewers MAY show a relative-time annotation for attestations older than 180 days, e.g. `mark@example.com (verified 8 months ago)`. This is a UI-layer decision, not a protocol requirement.

-----

## 6. Security Considerations

### 6.1 Attestation Binding Attack

**Threat:** A hostile user registers someone else's email address against their own keypair before the legitimate owner does.

**Mitigation:** Email verification uses a **6-digit code** challenge, not a magic link. Codes are harder to intercept than links (links appear in URL previewers, referer headers, browser history, and some corporate mail-scanning pipelines). The code is delivered to the email address being claimed, so only the current controller of that mailbox can complete the attestation.

Social OAuth mitigates this by construction — the platform itself performs the binding, and the OAuth flow is only completable by the current account holder.

### 6.2 Proof-of-Possession

Every attestation creation, update, and deletion request MUST include a proof-of-possession signature: the client signs a challenge with the ML-DSA-65 private key that owns the fingerprint. This prevents pubkey squatting — you cannot create an attestation for a keypair you do not control, even if you know the public key.

The challenge format is domain-separated:

```text
"QUB_IDENTITY_<OP>_V1" || fingerprint || timestamp || nonce
```

where `<OP>` is `CREATE`, `UPDATE`, or `DELETE`. Timestamps must be within a 120-second window of Worker receipt to limit replay.

### 6.3 Attestation Staleness

Social handles change. A user who was `@mark` on X in 2026 may be `@markharper` in 2027, and someone else may then take `@mark`. qub addresses this in three ways:

1. `platform_id` is stored alongside the display handle (§3.3). Re-verification can detect handle drift by comparing the current OAuth profile against the stored `platform_id`.
2. `verified_at` is exposed to viewers, which MAY annotate old attestations (§5.4).
3. Re-verification is explicit and manual. qub does not silently refresh OAuth tokens — the entire point of OAuth token omission (§3.3) is to keep attestations as a **static snapshot**, not a live feed.

A viewer that cares about live identity correctness MUST treat attestations older than the staleness threshold with appropriate UI caution, or prompt the user to re-verify.

### 6.4 Privacy Model

Attestations are **public by design.** Anyone who can decrypt a signed qub can fetch `identity:<fingerprint>` and read every bound attestation. Users MUST opt in explicitly for each attestation type, and the opt-in flow MUST present this consequence clearly.

The system does not support private attestations — the point of an attestation is for a third party to resolve it. A user who wants pseudonymous signing simply remains at Layer 0.

### 6.5 Revocation Boundary

Revoking an attestation only affects **future** viewer resolutions. Viewers that cached an earlier resolution MAY continue displaying the previous value until their cache expires. This is acceptable because attestations are non-authoritative enhancements — the authoritative artefact is the signature, not the identity label.

Revoking the underlying keypair (by generating a new one) is out of scope for this spec. Key rotation is a Phase 3 concern and will be specified in a future revision.

-----

## 7. Phasing

### 7.1 Phase 2

- Layer 0 — bare keypair signing, fingerprint display.
- Layer 1 — email attestation via SendGrid code challenge.

Rationale: email verification is already scheduled for Phase 2 (PDD §4.3, §8.5). Layer 0 is a prerequisite for any signing at all. 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.