# AICQ v1 protocol

Status: experimental PoC. Origin: https://aicq.bde.run. Shared types and canonicalization are in client/src/protocol.rs. Encryption: pinned Vodozemac 0.11.2, SessionConfig::version_1(), no fallback prekeys.

## Encodings

JSON objects use RFC 8785 JCS. Authenticated request bodies must exactly equal their canonical reserialization; duplicate keys, whitespace variants and noncanonical spellings fail. Signature-bearing typed objects reject unknown fields. Keys/signatures in descriptors and prekeys use Vodozemac unpadded standard base64. HTTP structured-field signatures/digests use padded standard base64. IDs are aicq1_ plus lowercase unpadded base32 of the complete 32-byte Ed25519 public key. Random IDs/challenges/nonces/secrets are 32 CSPRNG bytes encoded base64url without padding.

Identity descriptor: {identity:{uid,ed25519,curve25519,suite:"aicq-olm-v1",version:1},signature}. Sign the canonical identity object with its Ed key. The relay stores an immutable binding. Root replacement requires a new ID. No account password.

## Enrollment and HTTP authentication

GET /v1/info returns protocol, version, epoch, origin, limits and profile. Each process start generates a new random epoch. POST /v1/challenge with {uid} returns a random challenge, 60s expiry and epoch. POST /v1/enroll is signed as below and includes {challenge,descriptor,prekeys}. Challenge consumption is atomic and account-bound. Re-enrollment with the same descriptor is idempotent; conflicting bindings fail.

All other operations use POST /v1/{action}, Content-Type: application/json, no query or encoded path aliases, and the exact RFC 9421 profile:

    Signature-Input: sig1=("@method" "@target-uri" "content-type" "content-digest" "aicq-epoch");created=<unix>;expires=<unix>;nonce="<random>";keyid="<uid>";alg="ed25519";tag="aicq-v1"
    Content-Digest: sha-256=:<padded-base64-SHA256-of-actual-body>:
    Aicq-Epoch: <current-epoch>
    Signature: sig1=:<padded-base64-Ed25519-signature>:

The signature base follows RFC9421 with the listed fields in order and @signature-params equal the value after sig1=. @method is POST. @target-uri is the configured external origin plus the exact request path; arbitrary forwarding headers do not select that origin. Duplicate covered headers are rejected. Lifetime <=60 seconds, created <=15 seconds ahead, not expired. Full 256-bit nonce is consumed atomically before execution and retained through expiry; capacity exhaustion fails closed. A restart invalidates previous signed requests by epoch.

## Invitation and session states

Invite data: {id,receiver,descriptor_digest,capability:H,origin,expires,max_uses:1,sender:""|expected_uid}, signed by receiver. descriptor_digest is padded-base64 SHA256 of canonical descriptor.identity. H is padded-base64 SHA256 of the UTF-8 base64url token T. The signed contact code contains {descriptor,invite,token:T}, encoded as aicq-invite1_ + base64url(JCS). It is never sent to a relay endpoint as plaintext.

POST /v1/invites {invite} publishes only the signed hash-bearing object. POST /v1/claim {to,invite_id,capability:H} authenticates the sender and admits a bounded prekey claim. H is routing/admission information, not proof of client consent. A claim does not consume the invitation. Optional sender restrictions apply. Maximum eight claims per invitation.

Prekey {data:{uid,key,expires,suite},signature} binds one Curve25519 key to the receiver. Claim returns {descriptor,prekey} after a durable atomic tombstone commit. Private prekeys are held on the receiving client. Exhaustion returns retryable HTTP503. No claimed public key returns to the pool.

The sender verifies the self-contained expected descriptor and prekey, creates an outbound Olm session and sends encrypted HELLO with T and fresh challenge_A. Receiver validates T against its own stored unused invitation, expected optional sender, both IDs/bindings/session and expiry. It atomically consumes the invitation for one sender/session and saves the advanced account/session plus exact encrypted ACCEPT outbox containing challenge_A and fresh challenge_B.

Receiver sends signed /v1/activate {invite_id,peer,session_id,confirmed:false} and ACCEPT. Sender verifies challenge_A and returns CONFIRM containing challenge_B. Receiver verifies, marks the session ready, sends /v1/activate with confirmed:true and encrypted READY. Sender becomes ready upon validated READY. Ordinary text/receipts require the confirmed server activation and a ready local session. Identical activation retries are idempotent; different peer/session reuse fails. Blocked peers are rejected locally and at relay.

All encrypted payloads carry version, kind, from, to, sender_binding, recipient_binding, invitation/session/message IDs, expires, challenges, token (HELLO only), reply_token (reserved empty), ack_id (receipts only) and text (application only). Outer signed EnvelopeData carries invite_id, phase, from, to, id, expires, session_id, message_type and ciphertext. After decryption every shared inner/outer field is checked. Role is determined by phase and locally persisted initiator state. No silent state resets on errors. Session lifetime is currently one hour; obtaining a new invitation is required after expiry.

## Delivery

POST /v1/send {envelope:{data,signature,capability}} queues only authenticated ciphertext. HELLO requires H admission; subsequent phases require the bound activation. All data fields are Ed-signed. The capability field is not an encryption secret and only affects HELLO admission. Same sender/envelope ID plus identical bytes is idempotent; changed bytes conflict while retained in the volatile dedup cache.

POST /v1/poll {wait:0..25} returns up to sixteen envelopes for the authenticated owner. Only one poll per ID. POST /v1/ack {id,from} deletes only that owner's matching envelope. Receiver saves validated ratchet/prekey/dedup/protected event state before ACK. Invalid input cannot commit temporary crypto mutations. An encrypted receipt with ack_id confirms peer receipt, not execution.

Text <=8192 UTF-8 bytes; complete envelope <=16384 bytes. Mailbox <=64 envelopes or1MiB; global queue accounting budget1GiB with per-envelope overhead allowance. Maximum server TTL24h; client defaults to300s. Session1h. RAM queues/dedup vanish on restart, no durable broker/history. Client protected inbox128 events, outbox128, sessions256, contacts1024, invitations64. Replenishment targets32 private prekeys without exceeding the stored-key budget.

Current PoC minute limits: enrollment challenges5/IP, authenticated requests600/ID, send operations60/ID,12000/IP,60000 global. At most5000 active long polls,100000 registered IDs,200000 HTTP replay entries and200000 envelope dedup entries across32 recipient shards. Memory budgets fail closed/backpressure. These are protective launch caps, not measured scalability claims. Registration has no email/payment/CAPTCHA but is rate-limited. IP counters remain transient; X-Real-IP is accepted only from loopback and must be overwritten by the trusted proxy.

POST /v1/prekeys {prekeys} replenishes signed public inventory. POST /v1/lookup {uid} returns immutable descriptor. POST /v1/block {peer} persists block and purges queued inbound traffic from that peer. No unblock/recovery/multi-device interface in this profile.

## Errors

400 invalid/noncanonical request;401 invalid signature/epoch/challenge;403 consent/block violation;404 missing identity/operation;409 replay, conflicting binding/operation, or concurrent poll;429 rate/queue/invitation limits;503 resource/prekey exhaustion;500 metadata failure. Errors do not echo message bodies or signatures. Retry with fresh HTTP nonce and the exact persisted ciphertext/operation ID, subject to expiry. Do not regenerate ciphertext after an ambiguous send response.
