# Omniscient Invite Protocol: v1 (draft)

**Status:** draft, not yet reviewed. Pre-launch, this document will be timestamped and published (plan §14). Any change after publication gets a new version number and date.

This document defines exactly how challenges are generated, how a submission is checked, and how events are recorded, in enough detail for anyone to re-implement verification independently. [`test-vectors.json`](test-vectors.json) contains worked examples. The reference implementation is in `src/core/`.

## 1. Notation

- `u32(n)`: `n` as a 4-byte unsigned big-endian integer.
- `u64(n)`: `n` as an 8-byte unsigned big-endian integer.
- `utf8(s)`: the UTF-8 bytes of string `s`.
- `lp(b)`: `u32(len(b)) || b`, a length-prefixed byte string. Every variable-length field is length-prefixed, so no two different inputs can encode to the same bytes.
- `||`: byte concatenation.
- `SHA-256`: as defined in FIPS 180-4.
- Hex is always lowercase.

## 2. Word list

- **List:** the BIP-39 English word list, 2,048 words, used **only as a vocabulary**. No phrase in this project is, or may be used as, a cryptocurrency wallet seed. The BIP-39 checksum is not used.
- **File:** [`wordlist/bip39-english.txt`](wordlist/bip39-english.txt), with one word per line and LF line endings.
- **SHA-256 of the file:** `2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda`
- **Identifier (`WORDLIST_ID`):** `bip39-english@sha256:2f5eed53a4727b4bf8880d8f3f199efc90e58503646d9ff8eff3a2ed3b24dbda`
- **Properties:** every word matches `^[a-z]{3,8}$`, all words are distinct, and every first-4-letter prefix is distinct. Prefixes are **not** accepted as input; only full words are.

## 3. Phrase generation

1. Draw 33 bytes (264 bits) from a CSPRNG (`crypto.getRandomValues`).
2. Read those bits as 24 consecutive 11-bit big-endian integers `i₀ … i₂₃`, each in `[0, 2047]`. Because 2,048 = 2¹¹ exactly, each word is uniformly and independently distributed, with no modulo bias.
3. The phrase is `WORDS[i₀] … WORDS[i₂₃]`, in order.
4. Entropy: 24 × 11 = **264 bits**.

The generator computes the commitment (§5) and then discards the phrase. The entropy buffer is zeroed. The phrase is never returned, stored, logged or shown to anyone. Erasing it from memory is best-effort (plan §5.5).

## 4. Input normalization

Each of the 24 submitted word fields is normalized as follows:
1. Reject the field if it is longer than 64 UTF-16 code units (this caps processing work).
2. Strip leading and trailing whitespace (`\s` as defined by ECMAScript).
3. Apply Unicode NFKD.
4. Lowercase with the locale-independent `String.prototype.toLowerCase`.
5. Accept the result only if it is exactly one of the 2,048 list words. Otherwise the submission is rejected.

All rejections, whether the input is malformed or valid words are simply wrong, return the same generic response: *"The submission could not be verified."* Nothing in the response says which field or word was at fault.

## 5. Challenge commitment

Each challenge has:
- `challenge_id`: 16 random bytes, written as 32 lowercase hex characters.
- `salt`: 32 random bytes, public.

```
commitment = SHA-256(
    lp(utf8("omniscient-invite/challenge-commitment/v1"))
 || lp(utf8(WORDLIST_ID))
 || lp(utf8(challenge_id))
 || lp(salt)
 || u32(24)
 || lp(utf8(word₀)) || … || lp(utf8(word₂₃))
)
```

The server stores only `challenge_id`, `salt`, `commitment` and lifecycle metadata. A submission is verified by normalizing its words (§4), recomputing the commitment with the active challenge's `challenge_id` and `salt`, and comparing it with the stored commitment in **constant time**.

## 6. Message rules

- **Request:** `POST /submit` with `Content-Type: application/x-www-form-urlencoded` (an optional `charset=utf-8` is allowed; nothing else, and no multipart). The body is at most 32 KiB, and it is parsed strictly:
  - body bytes must be printable ASCII;
  - every pair must be `name=value`;
  - percent-escapes must be well-formed, and `+` means a space;
  - the decoded bytes must be valid UTF-8.

  Nothing is silently repaired: invalid UTF-8 is rejected rather than replaced with U+FFFD.
- **Origin:** if the browser sends `Sec-Fetch-Site`, it must be `same-origin`; if it sends `Origin`, it must equal the site's origin. Clients that send neither (for example `curl`) are allowed.
- **Field set:** the body contains **exactly** the fields `message`, `w1` … `w24`, each exactly once. Any missing, duplicate or extra field causes rejection.
- **Line endings:** CRLF and lone CR are converted to LF. This is the **only** change ever made to message text, and it is disclosed here.
- **Length:** 1–777 Unicode code points (a limit chosen deliberately) after line-ending conversion, and the message must contain at least one non-whitespace character.
- **Rejected characters:**
  - Lone UTF-16 surrogates (not well-formed Unicode).
  - C0 controls except TAB (U+0009) and LF (U+000A), plus DEL and C1 controls (U+007F–U+009F).
  - Bidirectional embedding, override and isolate controls (U+202A–U+202E, U+2066–U+2069). Without this rule, the displayed text could differ from its logical order, as in "Trojan Source" attacks.
- **Published form:** the accepted message is published immediately, with no moderation. It is shown as escaped plain text and also offered as its exact UTF-8 bytes, together with `message_sha256 = hex(SHA-256(utf8(message)))`. That value can be checked with standard tools, for example `sha256sum`.

## 7. Audit log (hash chain)

Every lifecycle action appends an event. Event `n` (with `seq` starting at 0) has a hash computed as:

```
event_hash = SHA-256(
    lp(utf8("omniscient-invite/audit-event/v1"))
 || u64(seq)
 || prev_hash                                  -- 32 bytes; 32 zero bytes for seq 0
 || lp(utf8(type))
 || lp(utf8(timestamp))                        -- RFC 3339 UTC, millisecond precision, e.g. 2026-11-16T12:00:00.000Z
 || u32(k)                                     -- number of payload fields
 || lp(utf8(key₁)) || lp(utf8(value₁)) || …    -- keys sorted by UTF-16 code unit order, unique
)
```

The `prev_hash` of event `n` is the `event_hash` of event `n−1`. Payload values are always strings: numbers are written in decimal and binary values in lowercase hex.

Planned event types (payload keys may be refined before v1 is frozen):

| type | payload |
|---|---|
| `challenge.created` | `challenge_id`, `salt`, `commitment`, `wordlist_id`, `expires_at` |
| `challenge.consumed` | `challenge_id`, `submission_id` |
| `challenge.expired` | `challenge_id` |
| `submission.accepted` | `submission_id`, `challenge_id`, `message_sha256` |
| `system.maintenance` | `reason` (`accept_failed`, `rotate_failed`, `create_failed`) |
| `system.resumed` | (none) |
| `checkpoint.key` | `algorithm` (`ed25519`), `public_key`, `key_id` (see §7.1) |

After a successful submission, three events are appended in one atomic step, in this order: `submission.accepted`, `challenge.consumed`, `challenge.created` (the next challenge). An expiry appends `challenge.expired` followed by `challenge.created`.

Submission identifiers are `s-` followed by a 6-digit sequence number, starting at `s-000001`.

### 7.1 Signed checkpoints

A checkpoint is a signed statement that, at `timestamp`, the log's head was event `seq` with hash `head_hash`. Anyone who saves checkpoints can later prove that a log being shown has been rewritten: a valid checkpoint whose `head_hash` does not match that log's event `seq` is a signed contradiction.

```
checkpoint_message =
    lp(utf8("omniscient-invite/checkpoint/v1"))
 || lp(utf8(log_id))                           -- "challenge-authority-v1"
 || u64(seq)
 || head_hash                                  -- 32 bytes
 || lp(utf8(timestamp))                        -- RFC 3339 UTC, millisecond precision
signature = Ed25519-Sign(private_key, checkpoint_message)   -- RFC 8032 (pure Ed25519), 64 bytes
```

- `public_key` is the 32-byte Ed25519 public key in lowercase hex, and `key_id = SHA-256(public_key bytes)` in lowercase hex.
- Before the first checkpoint signed with a key, a `checkpoint.key` event announcing that key is appended to the log. The key is therefore committed in the hash chain itself.
- A checkpoint at `seq` is valid only if its signature verifies under the key of the **latest `checkpoint.key` event with sequence number ≤ `seq`**, and its `key_id` matches that key. A key change is always visible in the log; it never silently invalidates or replaces earlier checkpoints.
- A checkpoint is made after every change to the log, so its `seq` is normally the current head. At most one checkpoint exists per `seq`, and checkpoints are append-only.
- The private key is held only as a deployment secret and is never published, logged or stored in the database.

A checkpoint is published as JSON: `{ "logId", "seq", "headHash", "timestamp", "keyId", "signature" }` (hex strings except `seq`).

## 8. Rotation

- Each challenge expires 24 hours after creation. A challenge is expired from the exact millisecond of its `expires_at`, and the correct phrase is rejected from then on.
- Rotation is triggered by a timer at `expires_at` and is also checked before every submission, so a missed timer can never extend a challenge's life.
- After a successful submission, the current challenge is consumed and the next one is created in the same atomic step.
- A challenge accepts at most one submission, even if several correct submissions arrive at the same moment.
- If anything fails after a correct phrase has been verified (for example, creating the next challenge), the whole step is rolled back: no submission is accepted and the challenge stays active. The system then enters maintenance mode, records a `system.maintenance` event, and accepts nothing until an operator resumes it, which records `system.resumed`. Resuming is the only operator action; it cannot edit, hide or remove any record.

## 9. HTTP interface

Every rejection of `POST /submit` returns the same response: status 400, the same body and the same headers, after at least 300 ms. This holds whatever the reason (size, content type, origin, parsing, field rules, wrong or expired words), so a response never reveals why it failed. A browser form submission that is accepted gets `303 See Other` to `/submissions/{id}`. A client that sends `Accept: application/json` gets `201` with a JSON receipt instead. If the system is in maintenance mode, the response is `503`.

Public read endpoints (`GET`/`HEAD`, CORS `*`, no credentials):

| Endpoint | Returns |
|---|---|
| `/api/status` | mode, the active challenge (id, salt, commitment, word list, times), the log head, the latest checkpoint and the current checkpoint key |
| `/api/log?from=&limit=` | audit events in order (at most 500 per page) and a `next` link |
| `/api/log.ndjson` | the complete audit log from event 0, one JSON event per line |
| `/api/submissions?before=&limit=` | published submissions, newest first |
| `/api/submissions/{id}` | one submission record (JSON) |
| `/api/submissions/{id}/raw` | the exact accepted message bytes (`text/plain; charset=utf-8`, as a download), with an `X-Message-SHA256` header |
| `/api/challenges/{id}` | one challenge's public record and status |
| `/api/checkpoints?from=&limit=` | signed checkpoints in order (at most 500 per page) and a `next` link |
| `/api/checkpoints/latest` | the most recent signed checkpoint, and the key that signed it |
| `/submissions/{id}` | human-readable page for one submission (message shown as escaped plain text) |

Any other path returns 404, and any other method on a known path returns 405.
