feat(B5): single-use top-up codes (redeem + mint CLI)

Completes the hybrid allocation model — the flat free grant (B4) plus
top-up codes that extend an account's allocation.

- topup.rs: redeem(account, raw_code) — timing-safe, single-use. A
  conditional `UPDATE … WHERE redeemed_by IS NULL RETURNING value` claims
  the code atomically (concurrent double-redeem → exactly one winner), then
  raises accounts.allocation_total in the same tx. Only sha256(code) is
  stored; a not-found code and an already-redeemed code return the SAME
  generic error via the same path (no "valid but spent" oracle). Raising
  the total automatically lifts every percent-limited key's effective cap;
  hardcap keys stay pinned (by design).
- mint(value, count, denomination) — inserts codes (hash-only), returns the
  raw codes once. Exposed as `helexa-upstream mint --value --count
  [--denomination]` (raw codes to stdout, one per line) — the seam the
  future faucet bot calls. Bot itself out of scope.
- POST /web/v1/redeem (session-protected) → {allocation_total} | generic 400.

Validated against Postgres: redeem raises the 1_000_000 free grant to
1_500_000, second redemption + unknown code both generic-400, and a
concurrent race for one code yields exactly one HTTP 200.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01F6o3ddqmYNh9kzdwq6eowh

crates/helexa-upstream/src/lib.rs

@@ -21,6 +21,7 @@ pub mod error;
 pub mod handlers;
 pub mod ledger;
 pub mod state;
+pub mod topup;
 pub mod web;
 
 use anyhow::Result;

crates/helexa-upstream/src/main.rs

@@ -20,6 +20,22 @@ enum Commands {
         #[arg(short, long, default_value = "helexa-upstream.toml")]
         config: String,
     },
+    /// Mint single-use top-up codes and print them (one per line). The raw
+    /// codes are shown only here — only their hash is stored. (The future
+    /// faucet bot calls the same path.)
+    Mint {
+        #[arg(short, long, default_value = "helexa-upstream.toml")]
+        config: String,
+        /// Tokens each code grants.
+        #[arg(long)]
+        value: i64,
+        /// How many codes to mint.
+        #[arg(long, default_value_t = 1)]
+        count: u32,
+        /// Optional human label (e.g. "small", "beta-launch").
+        #[arg(long)]
+        denomination: Option<String>,
+    },
 }
 
 #[tokio::main]
@@ -40,6 +56,25 @@ async fn main() -> Result<()> {
             tracing::info!(listen = %cfg.server.listen, "starting helexa-upstream");
             helexa_upstream::run(cfg).await?;
         }
+        Commands::Mint {
+            config,
+            value,
+            count,
+            denomination,
+        } => {
+            let cfg = UpstreamConfig::load(&config)
+                .map_err(|e| anyhow::anyhow!("failed to load config from '{config}': {e}"))?;
+            let pool =
+                helexa_upstream::db::connect_and_migrate(&cfg.db.url, cfg.db.max_connections)
+                    .await?;
+            let codes =
+                helexa_upstream::topup::mint(&pool, value, count, denomination.as_deref()).await?;
+            // Raw codes to stdout (one per line) for the operator to distribute;
+            // logs/diagnostics go to stderr via tracing.
+            for code in codes {
+                println!("{code}");
+            }
+        }
     }
 
     Ok(())

crates/helexa-upstream/src/topup.rs

@@ -0,0 +1,82 @@
+//! Single-use top-up codes (#B5) — the second half of the hybrid allocation
+//! model. Each code grants `value` tokens to the account that redeems it,
+//! raising `accounts.allocation_total`. Minting codes is operator/CLI side
+//! (the future faucet bot calls the same `mint` path); redemption is a
+//! `/web/v1` action.
+//!
+//! Security: only `sha256(code)` is stored. Redemption is **timing-safe and
+//! single-use** — a conditional `UPDATE … WHERE redeemed_by IS NULL` does
+//! the claim atomically (concurrent double-redeem → exactly one winner), and
+//! a not-found code and an already-redeemed code return the **same** generic
+//! failure with the same code path (no oracle for "valid but spent").
+
+use crate::crypto::{random_token, sha256};
+use sqlx::Row;
+use sqlx::postgres::PgPool;
+use uuid::Uuid;
+
+#[derive(Debug, thiserror::Error)]
+pub enum TopUpError {
+    /// Code unknown OR already redeemed — deliberately indistinguishable.
+    #[error("invalid or already-redeemed code")]
+    Invalid,
+    #[error(transparent)]
+    Db(#[from] sqlx::Error),
+}
+
+/// Redeem `raw_code` for `account_id`, raising the account's
+/// `allocation_total` by the code's value. Returns the new total.
+pub async fn redeem(pool: &PgPool, account_id: Uuid, raw_code: &str) -> Result<i64, TopUpError> {
+    let mut tx = pool.begin().await?;
+    // Atomic single-use claim. `redeemed_by IS NULL` is the guarantee: under
+    // concurrent redemption exactly one UPDATE touches the row.
+    let claimed = sqlx::query(
+        "UPDATE top_up_codes SET redeemed_by = $1, redeemed_at = now() \
+         WHERE code_hash = $2 AND redeemed_by IS NULL RETURNING value",
+    )
+    .bind(account_id)
+    .bind(sha256(raw_code))
+    .fetch_optional(&mut *tx)
+    .await?;
+    let Some(row) = claimed else {
+        // Not found or already redeemed — same path, same error.
+        return Err(TopUpError::Invalid);
+    };
+    let value: i64 = row.get("value");
+    let new_total: i64 = sqlx::query(
+        "UPDATE accounts SET allocation_total = allocation_total + $1 WHERE id = $2 \
+         RETURNING allocation_total",
+    )
+    .bind(value)
+    .bind(account_id)
+    .fetch_one(&mut *tx)
+    .await?
+    .get("allocation_total");
+    tx.commit().await?;
+    Ok(new_total)
+}
+
+/// Mint `count` codes each worth `value` tokens, optionally tagged with a
+/// `denomination` label. Returns the raw codes (shown once — only their
+/// hash is stored). The CLI prints these; the future faucet bot calls this.
+pub async fn mint(
+    pool: &PgPool,
+    value: i64,
+    count: u32,
+    denomination: Option<&str>,
+) -> Result<Vec<String>, sqlx::Error> {
+    let mut codes = Vec::with_capacity(count as usize);
+    for _ in 0..count {
+        let raw = format!("helexa-topup-{}", random_token());
+        sqlx::query(
+            "INSERT INTO top_up_codes (code_hash, value, denomination) VALUES ($1, $2, $3)",
+        )
+        .bind(sha256(&raw))
+        .bind(value)
+        .bind(denomination)
+        .execute(pool)
+        .await?;
+        codes.push(raw);
+    }
+    Ok(codes)
+}

crates/helexa-upstream/src/web.rs

@@ -35,6 +35,7 @@ pub fn router(state: &AppState) -> Router<AppState> {
             "/web/v1/keys/{id}/limit",
             axum::routing::patch(update_key_limit),
         )
+        .route("/web/v1/redeem", post(redeem))
         .layer(axum::middleware::from_fn_with_state(
             state.clone(),
             require_session,
@@ -565,3 +566,29 @@ async fn update_key_limit(
     }
     Ok(StatusCode::NO_CONTENT.into_response())
 }
+
+#[derive(Deserialize)]
+struct RedeemReq {
+    code: String,
+}
+
+/// `POST /web/v1/redeem` — redeem a single-use top-up code, raising the
+/// account's allocation. Returns the new total. Generic 400 for an invalid
+/// or already-redeemed code (no oracle).
+async fn redeem(
+    State(state): State<AppState>,
+    Extension(user): Extension<AuthUser>,
+    Json(req): Json<RedeemReq>,
+) -> WebResult<Response> {
+    let acct = account_id_for(&state, user.0).await?;
+    match crate::topup::redeem(&state.pool, acct, &req.code).await {
+        Ok(new_total) => Ok(Json(json!({ "allocation_total": new_total })).into_response()),
+        Err(crate::topup::TopUpError::Invalid) => {
+            Err(WebError::BadRequest("invalid or already-redeemed code"))
+        }
+        Err(crate::topup::TopUpError::Db(e)) => {
+            tracing::error!(error = %e, "redeem db error");
+            Err(WebError::Internal)
+        }
+    }
+}

crates/helexa-upstream/tests/web_pg.rs

@@ -294,3 +294,132 @@ async fn fingerprint_abuse_silently_deactivates_all_no_clue() {
         "deactivated account's key looks like any invalid key"
     );
 }
+
+#[tokio::test]
+async fn topup_redeem_raises_allocation_single_use() {
+    let Some((base, pool)) = spawn_or_skip("topup_redeem_raises_allocation_single_use").await
+    else {
+        return;
+    };
+    let email = unique_email();
+    post(
+        format!("{base}/web/v1/register"),
+        json!({"email": email, "password": "password123"}),
+        None,
+    )
+    .await;
+    pool.execute(
+        sqlx::query("UPDATE users SET email_verified = true WHERE email = $1").bind(&email),
+    )
+    .await
+    .unwrap();
+    let token = post(
+        format!("{base}/web/v1/login"),
+        json!({"email": email, "password": "password123"}),
+        None,
+    )
+    .await
+    .json::<Value>()
+    .await
+    .unwrap()["token"]
+        .as_str()
+        .unwrap()
+        .to_string();
+
+    // Mint a code worth 500_000 (mint path used by the CLI/faucet).
+    let codes = helexa_upstream::topup::mint(&pool, 500_000, 1, Some("test"))
+        .await
+        .unwrap();
+    let code = &codes[0];
+
+    // Redeem → allocation_total rises from the 1_000_000 free grant.
+    let r = post(
+        format!("{base}/web/v1/redeem"),
+        json!({"code": code}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 200);
+    assert_eq!(
+        r.json::<Value>().await.unwrap()["allocation_total"],
+        1_500_000
+    );
+
+    // Single-use: a second redemption fails generically (no oracle).
+    let r = post(
+        format!("{base}/web/v1/redeem"),
+        json!({"code": code}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 400);
+
+    // Unknown code: same generic 400.
+    let r = post(
+        format!("{base}/web/v1/redeem"),
+        json!({"code": "helexa-topup-does-not-exist"}),
+        Some(&token),
+    )
+    .await;
+    assert_eq!(r.status(), 400);
+}
+
+#[tokio::test]
+async fn topup_concurrent_double_redeem_one_winner() {
+    let Some((base, pool)) = spawn_or_skip("topup_concurrent_double_redeem_one_winner").await
+    else {
+        return;
+    };
+    // Two verified accounts.
+    let mut tokens = Vec::new();
+    for _ in 0..2 {
+        let email = unique_email();
+        post(
+            format!("{base}/web/v1/register"),
+            json!({"email": email, "password": "password123"}),
+            None,
+        )
+        .await;
+        pool.execute(
+            sqlx::query("UPDATE users SET email_verified = true WHERE email = $1").bind(&email),
+        )
+        .await
+        .unwrap();
+        let t = post(
+            format!("{base}/web/v1/login"),
+            json!({"email": email, "password": "password123"}),
+            None,
+        )
+        .await
+        .json::<Value>()
+        .await
+        .unwrap()["token"]
+            .as_str()
+            .unwrap()
+            .to_string();
+        tokens.push(t);
+    }
+    let code = helexa_upstream::topup::mint(&pool, 100, 1, None)
+        .await
+        .unwrap()
+        .remove(0);
+
+    // Both accounts race to redeem the same code; exactly one wins.
+    let (a, b) = tokio::join!(
+        post(
+            format!("{base}/web/v1/redeem"),
+            json!({"code": code}),
+            Some(&tokens[0])
+        ),
+        post(
+            format!("{base}/web/v1/redeem"),
+            json!({"code": code}),
+            Some(&tokens[1])
+        ),
+    );
+    let wins = [a.status(), b.status()]
+        .iter()
+        .filter(|s| s.as_u16() == 200)
+        .count();
+    assert_eq!(wins, 1, "exactly one redemption wins the single-use code");
+}