qub Protocol Specification

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

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

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

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

qub Protocol Specification

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

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

1. Notation and Conventions

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

All timestamps are Unix seconds in UTC.

2. Data Structures

2.1 ComposeQub (Creator In-Memory State)

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

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

2.2 QubEnvelope (Decrypted Payload)

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

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

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

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

2.3 SealedQub (Canonical Wire Format)

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

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

2.4 RevealedQub (Viewer Application State)

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

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

3. Canonical CBOR Profile

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

3.1 Encoding Rules

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):

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

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

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

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

PactTerms (pact body, content_type 0x03):

"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):

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

PartyIdentifier (party_a / party_b map):

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

3.3 Byte Encoding Reference

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.

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

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

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

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

Properties:

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

4.2 body_hash

body_hash = SHA3-256(body)

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

4.2.1 title_hash

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

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

4.3 Unlock-Round Mapping

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

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.

5.1 Construction Rules

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

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:

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:

"initiator_standard_terms"
"initiator_capacity_terms"
"counterparty_standard_terms"
"counterparty_capacity_terms"

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

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

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

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

6.2 Verdict Body (content_type = 0x04)

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

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

Canonical CBOR key order:

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

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

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

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

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

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

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

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

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

7. Seal Protocol

The complete seal sequence. Each step is normative.

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

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

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

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

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

8. Unlock Protocol

The complete unlock sequence. Each step is normative.

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

9. Authorship Signing

9.1 Rationale

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

9.2 Algorithm Registry

Viewers MUST reject unknown sig_alg values.

9.3 Signed Preimage Construction

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

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

signature = Sign(author_secret_key, sig_input)

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

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

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

Security implications of non-authenticated fields.

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

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

9.4 Verification Procedure

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

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

9.5 Identity Attestations

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

handle > email > social > fingerprint

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

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

9.6 Size Impact

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

9.7 Cosigner Verification (Pact Bilateral Agreements)

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

Envelope fields:

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

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

Verification procedure:

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

Properties:

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

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

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

10. Markdown Rendering and Sanitisation

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

10.1 Allowed Elements

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

10.2 Forbidden Elements

10.3 Implementation

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

1. Parse Markdown using pulldown-cmark (or equivalent).
2. Walk the AST and drop any node not in the allowlist (§10.1).
3. For link nodes: emit the URL as visible text, not as a clickable <a> element.
4. 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.
5. Render from the typed IR to the target view layer (e.g., reactive view components, DOM nodes). No HTML string concatenation or innerHTML at any point.

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

10.4 Size and Structure Limits

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

11. Third-Party Verification

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

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

What verification proves:

What verification does NOT prove:

12. Versioning

12.1 Protocol Version

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

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

12.2 Version History

12.3 Forward Compatibility

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

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

12.4 Outer Wrapper Version

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

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

13. Outer Encryption Wrapper

13.1 Rationale

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

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

Net effect:

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

13.2 Layering

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

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

13.3 OuterWrapper Data Structure

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

Field invariants.

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

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

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

13.4 AAD Binding to qub_id

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

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

13.5 Wrap and Unwrap Algorithms

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

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

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

13.6 Key Material and Distribution

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

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

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

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

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

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

13.7 Out-of-Scope for this Section

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

13.8 Public qubs (wrapper omission)

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

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

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

Consequences a producer MUST account for:

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

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

14. Test Vectors

14.1 qub_id Derivation

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

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

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

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

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

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

14.2 Unlock-Round Mapping

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)

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

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

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

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

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

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

14.5 Outer Wrapper Cross-Language Vectors

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

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

The fixture currently pins three cases:

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

15. Crypto Profile Governance (Future)

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

15.1 Current Posture

Protocol v1 binds exactly one algorithm per primitive:

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

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

15.2 Intended Shape

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

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

15.3 Trigger Conditions

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

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

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