cryptify: mint an upload challenge and verify it at finalize, reducing to a SenderClaim

[rubenhensen]

What to build

The cryptify half of the upload proof: mint a challenge at init, verify the answer at finalize, and reduce the result to a SenderClaim. This ticket deliberately stops before the email — the template split, the wording and the kill switch are the sibling ticket, which is blocked by this one.

Every decision below is made. This body is self-contained.

Why

upload_init requires nothing of the uploader; upload_finalize reads a sender identity out of the container (main.rs:942-963) and treats it as theirs. Nothing connects the two, so anyone holding a container someone else sealed can have PostGuard mail strangers in that person's name. cryptify holds no decryption key and never decrypts, so no check inside the container can help — the fix has to bind the uploader to the identity the container claims.

1. Mint and store the challenge

In upload_init, generate 32 random bytes with the idiom already used for the two tokens at main.rs:448 (bytes_to_hex(&rand::random::<[u8; 32]>())) and:

• store it on FileState,
• return it in InitResponse as challenge (hex string), beside max_chunk_size_bytes.

Adding it to the response is additive; existing clients ignore the field.

2. Verify at finalize

upload_finalize accepts an optional X-PostGuard-Proof request header carrying a base64 signature. After the container's pub_id is read (:942):

let claim = match proof_header {
    Some(sig) => {
        let ok = pg_core::verify_challenge(
            &vk.public_key, &pub_id, uuid, challenge.as_bytes(), &sig);
        if ok { SenderClaim::Proven { .. } } else { SenderClaim::Unproven }
    }
    None => SenderClaim::Unproven,
};

verify_challenge derives the identity from the container's own pub_id and verifies under it. That is deliberate and is what removes any identity-comparison step: either the uploader holds the key for the identity the container claims, or they do not. Do not add a separate claimed-identity field to the request and compare it.

A present-but-invalid proof and an absent proof both resolve to Unproven in this ticket. Do not reject either — the rollout policy is decided in the sibling ticket, and rejecting here would break every client that has not shipped the header.

verify_challenge and its domain separator come from the pg-core ticket this one is blocked by. Do not reimplement the message construction locally.

3. The type

pub enum SenderClaim {
    Proven { email: String, attrs: Vec<(String, String)> },
    Unproven,
}

Written exactly once, as the return value of the verification. Do not assign a default and patch it afterwards — the point is that no code path produces a Proven except the verifying branch. Keep the existing state.sender / state.sender_attributes fields as they are for now; the sibling ticket is what stops the templates reading them.

4. Persistence

FileState gains the challenge and the claim, so both must survive a restart — #302/#303 made these sessions durable and a session that reboots mid-upload must still be finalizable.

store.rs needs: new columns on upload_sessions (:389-406), the INSERT/upsert column lists (:431-479), and the positional read (:357, row.get(N) — indices shift, check every one). CREATE TABLE IF NOT EXISTS will not migrate a deployed database, so add a real migration that ALTER TABLEs the columns onto an existing table and is a no-op on a fresh one.

Tests

1. init returns a challenge, and it is stored on the session.
2. A finalize carrying a correct signature yields Proven with the container's identity.
3. A signature made with a different identity's key yields Unproven — not an error, not Proven.
4. A signature over a different challenge yields Unproven.
5. No header at all yields Unproven.
6. Round-trip: persist a session carrying a challenge and a claim, reload it from SQLite, and get the same values back.
7. Migration: open a database created without the new columns, run the migration, and confirm existing rows survive and load.

Scope fence

• Do not touch templates/email/*, src/email.rs, EN_STRINGS/NL_STRINGS, or sender_display. The email is the sibling ticket.
• Do not change the accounting key — a separate ticket canonicalizes it.
• Do not reject any upload that fails or omits the proof.
• Do not add a config flag here.
• Touch no file under .github/workflows/.

Acceptance check

cargo test -p cryptify --all-targets
cargo fmt --all -- --check
cargo clippy -p cryptify --all-targets -- -D warnings

All green. Also show test 3 red: make the verification ignore the derived identity, confirm a wrong-key signature starts reporting Proven, then revert. Put that in the PR description.

Part of #338, itself part of #247. Decided in #358.

[rubenhensen]

The pg-core half has shipped — here is the exact API, which differs from the sketch above

#362 merged as #368 (af6116c1). The body above sketches the call as pg_core::verify_challenge(...); the shipped signature is below, read off origin/main. Use this, do not reimplement the message construction.

pg-core/src/challenge.rs, re-exported as the unconditional pub mod challenge; at pg-core/src/lib.rs:178 — no feature gate, and cryptify already depends on pg-core by path, so nothing needs publishing for this ticket.

pub const CHALLENGE_DOMAIN: &[u8] = b"postguard/challenge/v1";

pub fn sign_challenge<R: RngCore + CryptoRng>(
    key: &SigningKeyExt,
    context: &str,
    challenge: &[u8],
    rng: &mut R,
) -> Signature;

pub fn verify_challenge(
    vk: &VerifyingKey,   // the IBS verifying key (master public key)
    pol: &Policy,        // the policy whose identity the signer must hold a key for
    context: &str,       // the same context the signature was requested under
    challenge: &[u8],
    sig: &Signature,
) -> bool;

Four things about it that bear on this ticket:

1. context is &str, not bytes. The ticket's sketch passes uuid; pass the uuid as the context string.
2. challenge is &[u8]. The challenge is stored and returned as a hex string, so decode it before verifying — the signer signs the decoded bytes, not the hex text. Whichever you choose, the client half (postguard-js#239) has to agree, and its body says signChallenge(pubSignKey, uuid, challengeBytes) — decoded bytes. Match that.
3. verify_challenge returns false, never an error, including for a policy no identity derives from. So there is no error branch to route to Unproven — a false is the Unproven arm.
4. derive_ibs canonicalizes, so a container spelling the address Alice@Example.COM verifies under a key issued for alice@example.com. That is deliberate and is why no identity-comparison step is needed. If you key on the raw attribute value anywhere, canonicalize it yourself — see accounting_key in cryptify/src/main.rs, which cryptify: canonicalize the default-tier accounting key, so one identity cannot mint unlimited quota buckets #363 just landed for exactly this reason.

The domain separator is applied inside sign_challenge/verify_challenge and is not an argument. Do not prepend it, and do not construct the signed message locally.

/dobby

[dobby-coder]

Thanks for the detailed spec update, @rubenhensen — I'm on it. I'll wire this up against the actual shipped pg_core::challenge::sign_challenge / verify_challenge API from #368 (context as &str, hex-decoding the challenge before verify) rather than the original sketch, and push the change up for review.