ciris-server 0.4.1__tar.gz → 0.4.2__tar.gz

{ciris_server-0.4.1 → ciris_server-0.4.2}/Cargo.lock

@@ -994,7 +994,7 @@ dependencies = [
 
 [[package]]
 name = "ciris-server"
-version = "0.4.1"
+version = "0.4.2"
 dependencies = [
  "anyhow",
  "async-trait",

{ciris_server-0.4.1 → ciris_server-0.4.2}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ciris-server"
-version = "0.4.1"   # 0.1 = lens-only (agent ~2.9.7); 0.3 = +auth subsystem / one-wheel; 0.4 = +federation peering/identity (capacity scoring, consent:replication, register_federation_key gate, root-bootstrap, NodeCode); 0.4.1 = self-attested first-run root claim (fresh-founder hybrid PoP, #887); 0.5 = +registry (~2.9.8); 1.0 = +node (~2.9.10). Patch forward on breakage.
+version = "0.4.2"   # 0.1 = lens-only (agent ~2.9.7); 0.3 = +auth subsystem / one-wheel; 0.4 = +federation peering/identity (capacity scoring, consent:replication, register_federation_key gate, root-bootstrap, NodeCode); 0.4.1 = self-attested first-run root claim (fresh-founder hybrid PoP, #887); 0.4.2 = one-time claim PIN on fresh boot (operator-presence gate); 0.5 = +registry (~2.9.8); 1.0 = +node (~2.9.10). Patch forward on breakage.
 edition = "2021"
 # MSRV floor is set by the substrate: ciris-verify v5.2.0 requires 1.86
 # (persist v6.0.1 is 1.83). Build with the higher of the two.

{ciris_server-0.4.1 → ciris_server-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ciris-server
-Version: 0.4.1
+Version: 0.4.2
 License-File: LICENSE
 Summary: The fabric node — the federation's headless cohabitation runtime (registry + lens [+ node] over one shared substrate), as the abi3 wheel CIRISAgent consumes. agent = fabric node + brain.
 Author-email: Eric Moore <eric@ciris.ai>

{ciris_server-0.4.1 → ciris_server-0.4.2}/src/auth/bootstrap.rs

@@ -45,7 +45,7 @@
 //! converts, so an operator can drop the agent's `seed/root_pub.json` in verbatim.
 
 use std::path::Path;
-use std::sync::Arc;
+use std::sync::{Arc, Mutex};
 
 use axum::extract::State;
 use axum::http::{HeaderMap, StatusCode};
@@ -57,10 +57,18 @@ use ciris_persist::verify::canonical::ceg_produce_canonicalize;
 use ciris_persist::wa_cert::{TokenType, WaCert, WaRole};
 use serde::{Deserialize, Serialize};
 use sha2::{Digest, Sha256};
+use subtle::ConstantTimeEq;
 
 use super::store;
 use super::verify;
 
+/// Env: an OPTIONAL filesystem path the one-time claim PIN is ALSO written to on a
+/// fresh (unclaimed) boot, for headless ops that cannot scrape the console log. The
+/// default is console/log ONLY — the PIN is the operator-presence secret and is
+/// NEVER served over any HTTP route. When set, the PIN file is written `0600` and
+/// the operator is responsible for removing it after the claim.
+pub const ENV_CLAIM_PIN_FILE: &str = "CIRIS_CLAIM_PIN_FILE";
+
 /// Env: a filesystem path to a `root_pub.json`-shaped seed (the agent's shape).
 pub const ENV_SEED_PATH: &str = "CIRIS_ROOT_SEED_PATH";
 /// Env: the ROOT public key (base64/base64url Ed25519) — the seed-less inline form.
@@ -439,6 +447,81 @@ fn root_wa_id_for_identity(identity_key_id: &str) -> String {
     format!("wa-root-{identity_key_id}")
 }
 
+// ─── One-time CLAIM PIN — the operator-presence secret (console-only) ─────────
+
+/// Crockford base32 alphabet (excludes I, L, O, U to stay operator-typable —
+/// no visual confusion with 1/0 and no accidental words).
+const CLAIM_PIN_ALPHABET: &[u8; 32] = b"0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/// Number of PIN characters (rendered as two dash-separated groups of 4).
+const CLAIM_PIN_LEN: usize = 8;
+
+/// Generate a cryptographically-random, operator-typable one-time claim PIN —
+/// [`CLAIM_PIN_LEN`] Crockford-base32 chars rendered `XXXX-XXXX`.
+///
+/// This is the **operator-presence secret** that gates the first-run ownership
+/// claim. It closes the hole that the NodeCode alone is a PUBLIC, freely-shareable
+/// handle (served by `GET /v1/federation/node-code`): knowing the NodeCode is not
+/// enough — the claimant must ALSO present this PIN, which is printed ONLY to the
+/// node's console/log on a fresh boot and NEVER exposed via any HTTP route.
+///
+/// Sourced from `getrandom` (the OS CSPRNG). Rejection-free: the alphabet is
+/// exactly 32 chars, so each random byte maps to one symbol via a 5-bit mask with
+/// zero modulo bias.
+pub fn generate_claim_pin() -> String {
+    let mut bytes = [0u8; CLAIM_PIN_LEN];
+    getrandom::fill(&mut bytes).expect("OS CSPRNG (getrandom) for the one-time claim PIN");
+    let mut chars: Vec<char> = bytes
+        .iter()
+        .map(|b| CLAIM_PIN_ALPHABET[(b & 0x1F) as usize] as char)
+        .collect();
+    // Render as two dash-separated groups of 4 (XXXX-XXXX) for typability.
+    chars.insert(4, '-');
+    chars.into_iter().collect()
+}
+
+/// Print the unmissable "OWNERSHIP UNCLAIMED" banner at startup — the NodeCode (a
+/// PUBLIC handle) PLUS the one-time claim PIN (the console-only operator-presence
+/// secret). Optionally ALSO writes the PIN to [`ENV_CLAIM_PIN_FILE`] (`0600`) for
+/// headless ops. The PIN is NEVER served over HTTP.
+pub fn announce_ownership_unclaimed(node_code: &str, claim_pin: &str) {
+    tracing::warn!(
+        "\n\
+         ╔══════════════════════════════════════════════════════════════════════╗\n\
+         ║  OWNERSHIP UNCLAIMED — this node has no ROOT owner yet.               ║\n\
+         ║                                                                      ║\n\
+         ║  To claim ownership (POST /v1/setup/root), present BOTH:             ║\n\
+         ║                                                                      ║\n\
+         ║    NodeCode : {node_code}\n\
+         ║    CLAIM PIN: {claim_pin}   (one-time; console-only — NEVER over HTTP)\n\
+         ║                                                                      ║\n\
+         ║  The NodeCode is a PUBLIC handle (GET /v1/federation/node-code).     ║\n\
+         ║  The PIN is the operator-presence secret: it is printed ONLY here    ║\n\
+         ║  and is consumed on the first successful claim.                      ║\n\
+         ╚══════════════════════════════════════════════════════════════════════╝"
+    );
+
+    // Optional headless-ops sink: write the PIN to a 0600 file when configured.
+    if let Ok(path) = std::env::var(ENV_CLAIM_PIN_FILE) {
+        let path = path.trim();
+        if !path.is_empty() {
+            match std::fs::write(path, format!("{claim_pin}\n")) {
+                Ok(()) => {
+                    #[cfg(unix)]
+                    {
+                        use std::os::unix::fs::PermissionsExt;
+                        let _ =
+                            std::fs::set_permissions(path, std::fs::Permissions::from_mode(0o600));
+                    }
+                    tracing::info!(pin_file = %path, "one-time claim PIN ALSO written to file (0600; remove after claim)");
+                }
+                Err(e) => {
+                    tracing::warn!(pin_file = %path, error = %e, "could not write claim PIN file (PIN remains available on the console)")
+                }
+            }
+        }
+    }
+}
+
 // ─── POST /v1/setup/root — the first-run root-claim route ────────────────────
 
 #[derive(Clone)]
@@ -451,6 +534,12 @@ struct SetupState {
     /// THIS node's raw Ed25519 pubkey (base64) — the second half of the NodeCode
     /// identity pin.
     node_pubkey_ed25519_base64: String,
+    /// The one-time claim PIN minted on a fresh (unclaimed) boot — the
+    /// operator-presence secret. `Some(pin)` while unclaimed-and-armed; set to
+    /// `None` once a ROOT exists at boot (already claimed → no PIN), or CLEARED on
+    /// the first successful claim (consume-once; no replay). Held behind a `Mutex`
+    /// so the claim handler can take it. NEVER reachable via any HTTP route.
+    claim_pin: Arc<Mutex<Option<String>>>,
 }
 
 /// The FRESH founder's self-attested hybrid identity (the claimant's OWN keys).
@@ -503,6 +592,14 @@ struct SetupRootRequest {
     /// NOT the federation directory.
     #[serde(default)]
     founder: Option<Founder>,
+    /// The one-time CLAIM PIN printed to THIS node's console/log on a fresh boot —
+    /// the operator-presence secret (CONSOLE-ONLY; never served over HTTP). It is
+    /// verified (constant-time) against the boot PIN before ROOT is bound, and
+    /// consumed on success. It rides INSIDE the signed body, so it is
+    /// signature-bound (it cannot be stripped/swapped without breaking the hybrid
+    /// PoP signature). REQUIRED.
+    #[serde(default)]
+    claim_pin: Option<String>,
 }
 
 #[derive(Debug, Serialize)]
@@ -557,11 +654,69 @@ fn verify_node_code_pin(st: &SetupState, req: &SetupRootRequest) -> Option<Respo
     None
 }
 
+/// Verify the one-time CLAIM PIN in the signed claim body against the boot PIN
+/// held in [`SetupState`], using a CONSTANT-TIME comparison (no early-return on
+/// first-byte mismatch, no length-leaking shortcut beyond the unavoidable
+/// length-equality flag). Returns `None` on a match; `Some(401)` when the PIN is
+/// absent, when no boot PIN is armed (already-claimed / mis-bootstrapped node), or
+/// when it does not match. The PIN is the operator-presence secret: it is printed
+/// ONLY to the console and is NEVER served over any HTTP route.
+fn verify_claim_pin(st: &SetupState, req: &SetupRootRequest) -> Option<Response> {
+    // The armed boot PIN. A missing/cleared PIN means the route must not admit a
+    // claim (node already claimed at boot, or PIN already consumed) → reject.
+    let armed = match st.claim_pin.lock() {
+        Ok(g) => g.clone(),
+        Err(_) => None,
+    };
+    let Some(expected) = armed else {
+        return Some(err(
+            StatusCode::UNAUTHORIZED,
+            "this node is not armed for a first-run claim (no one-time PIN) — \
+             ownership may already be claimed",
+        ));
+    };
+
+    let Some(supplied) = req.claim_pin.as_deref() else {
+        return Some(err(
+            StatusCode::UNAUTHORIZED,
+            "first-run ROOT claim must carry `claim_pin` (the one-time PIN printed \
+             on this node's console at boot)",
+        ));
+    };
+
+    // Constant-time equality over the raw bytes. `subtle::ConstantTimeEq` requires
+    // equal-length slices to compare byte-by-byte; a length difference is folded in
+    // WITHOUT an early return so the path does not short-circuit on first mismatch.
+    let a = supplied.as_bytes();
+    let b = expected.as_bytes();
+    let len_ok = a.len() == b.len();
+    // Pad/truncate the supplied bytes to the expected length so `ct_eq` always runs
+    // over `expected.len()` bytes (a mismatched length still does full work, then
+    // the `len_ok` flag forces the result false).
+    let mut padded = vec![0u8; b.len()];
+    for (i, slot) in padded.iter_mut().enumerate() {
+        *slot = if i < a.len() { a[i] } else { 0 };
+    }
+    let bytes_eq: bool = padded.ct_eq(b).into();
+    if len_ok && bytes_eq {
+        return None;
+    }
+    Some(err(StatusCode::UNAUTHORIZED, "invalid one-time claim PIN"))
+}
+
 /// `POST /v1/setup/root` — first-time-setup ROOT claim for a FRESH node with no
 /// baked seed.
 ///
-/// # Security model — three independent gates
+/// # Security model — four independent gates
 ///
+/// 0. **One-time CLAIM PIN (operator-presence)** — the claim MUST carry the
+///    `claim_pin` printed to THIS node's console/log on a fresh boot, verified
+///    CONSTANT-TIME against the boot PIN held in [`SetupState`]. The PIN is NEVER
+///    served over any HTTP route, so it proves the claimant has operator-level
+///    access to the node's console — closing the hole that the NodeCode alone is a
+///    PUBLIC, freely-shareable handle. A wrong/missing PIN → `401` (no ROOT). On
+///    success the PIN is CONSUMED (cleared from state) so it cannot be replayed.
+///    The PIN rides inside the signed body, so it is signature-bound.
 /// 1. **First-run only** — allowed ONLY when no ROOT WaCert exists; after a ROOT
 ///    exists the route returns `409 Conflict` (no silent re-claim).
 /// 2. **NodeCode identity-pin (CEG §0.10)** — the claim MUST carry THIS node's
@@ -601,9 +756,13 @@ fn verify_node_code_pin(st: &SetupState, req: &SetupRootRequest) -> Option<Respo
 ///     "key_id": "...",
 ///     "ed25519_pubkey_b64": "...",
 ///     "ml_dsa_65_pubkey_b64": "..."
-///   }
+///   },
+///   "claim_pin": "XXXX-XXXX"
 /// }
 /// ```
+/// `claim_pin` is the one-time PIN printed to the node's console on a fresh boot
+/// (console-only; NEVER served over HTTP). It is inside the signed body, so the
+/// signature binds it.
 /// (`node_code` may instead be supplied as the decoded `key_id` +
 /// `pubkey_ed25519_base64` pair at the top level — the node-pin half, distinct
 /// from the `founder` object.) The signature MUST cover the body bytes verbatim.
@@ -654,6 +813,17 @@ async fn setup_root(
         return resp;
     }
 
+    // (0/operator-presence) One-time CLAIM PIN. The claim must carry the PIN that
+    //     was printed to THIS node's console/log on a fresh boot — verified
+    //     CONSTANT-TIME against the boot PIN. The PIN is NEVER served over HTTP, so
+    //     possessing it proves operator-level console access, closing the hole that
+    //     the NodeCode alone is a freely-shareable PUBLIC handle. A wrong/missing
+    //     PIN → 401 (no ROOT minted). The PIN is signature-bound (inside the signed
+    //     body). It is NOT consumed here — only on a fully-successful claim below.
+    if let Some(resp) = verify_claim_pin(&st, &req) {
+        return resp;
+    }
+
     // (3) Self-attested hybrid proof-of-possession. A FRESH founder is not in the
     //     directory, so we verify the body signature against the founder's OWN
     //     pubkeys (NOT the directory) under Strict policy (both sigs required).
@@ -772,11 +942,17 @@ async fn setup_root(
     };
     match store::upsert(&st.engine, cert).await {
         Ok(()) => {
+            // Consume the one-time PIN: clear it so it can never be replayed. (The
+            // route is also 409-closed now that a ROOT exists — this is defence in
+            // depth + makes the consumed-once invariant directly assertable.)
+            if let Ok(mut guard) = st.claim_pin.lock() {
+                *guard = None;
+            }
             tracing::info!(
                 identity = %founder.key_id,
                 wa_id = %wa_id,
                 "first-run ROOT claim: self-attested founder registered + bound as ROOT \
-                 (founder → SYSTEM_ADMIN)"
+                 (founder → SYSTEM_ADMIN); one-time claim PIN consumed"
             );
             (
                 StatusCode::CREATED,
@@ -865,11 +1041,20 @@ async fn register_founder_key(
 /// `node_key_id` + `node_pubkey_ed25519_base64` are THIS node's steward identity
 /// (the same `key_id` + raw Ed25519 pubkey carried on its NodeCode, CEG §0.10);
 /// the first-run claim is identity-pinned to them (see [`setup_root`]).
+///
+/// `claim_pin` is the one-time operator-presence secret: `Some(pin)` arms the
+/// route for a fresh (unclaimed) node — the boot path mints it via
+/// [`generate_claim_pin`], prints it via [`announce_ownership_unclaimed`], and the
+/// claim is gated on it (constant-time, consumed on success). `None` (an
+/// already-claimed node) leaves the route un-armed — every claim attempt is `401`
+/// (and `409` once the first-run check sees the existing ROOT). The PIN is held in
+/// state ONLY; it is NEVER served over any HTTP route.
 pub fn router(
     engine: Arc<Engine>,
     policy: HybridPolicy,
     node_key_id: String,
     node_pubkey_ed25519_base64: String,
+    claim_pin: Option<String>,
 ) -> Router {
     Router::new()
         .route("/v1/setup/root", axum::routing::post(setup_root))
@@ -878,6 +1063,7 @@ pub fn router(
             policy,
             node_key_id,
             node_pubkey_ed25519_base64,
+            claim_pin: Arc::new(Mutex::new(claim_pin)),
         })
 }
 

{ciris_server-0.4.1 → ciris_server-0.4.2}/src/compose.rs

@@ -84,11 +84,14 @@ pub async fn serve(cfg: ServerConfig) -> Result<()> {
     // POST /v1/setup/root claim then lets the founder claim ROOT on a fresh node.
     // Either way the founder's identity becomes WaRole::Root → UserRole::SystemAdmin,
     // which is what the owner-gated POST /v1/federation/peering requires. Idempotent.
-    match crate::auth::bootstrap::bootstrap_if_needed(&engine).await {
-        Ok(outcome) => tracing::info!(?outcome, "root-user bootstrap evaluated"),
+    let bootstrap_outcome = match crate::auth::bootstrap::bootstrap_if_needed(&engine).await {
+        Ok(outcome) => {
+            tracing::info!(?outcome, "root-user bootstrap evaluated");
+            outcome
+        }
         // A bad seed must not silently downgrade owner-claim to "open forever"; fail boot.
         Err(e) => return Err(anyhow::anyhow!("root-user bootstrap: {e}")),
-    }
+    };
 
     // The node's OWN self-signed SignedKeyRecord as JSON — built ONCE at boot
     // (stable for the node's lifetime), served verbatim by
@@ -106,6 +109,32 @@ pub async fn serve(cfg: ServerConfig) -> Result<()> {
     let node_code_response_json = crate::federation_nodecode::render_response_json(&node_code)
         .map_err(|e| anyhow::anyhow!("render this node's NodeCode response: {e}"))?;
 
+    // ── One-time CLAIM PIN — the operator-presence secret for the first-run
+    //    ownership claim (CIRISServer first-run-PIN). On a FRESH, UNCLAIMED boot
+    //    (no ROOT WaCert, no seed → BootstrapOutcome::NoSeedAvailable) mint a
+    //    cryptographically-random, operator-typable PIN, print it in an unmissable
+    //    banner ALONGSIDE the NodeCode, and arm the POST /v1/setup/root route with
+    //    it. If a ROOT already exists (AlreadyBootstrapped / SeededRoot) NO PIN is
+    //    minted — the route is 409-closed anyway. The PIN closes the hole that the
+    //    NodeCode alone is a freely-shareable PUBLIC handle; it is printed ONLY to
+    //    the console/log (optionally CIRIS_CLAIM_PIN_FILE) and is NEVER served over
+    //    any HTTP route.
+    let claim_pin: Option<String> = if bootstrap_outcome
+        == crate::auth::bootstrap::BootstrapOutcome::NoSeedAvailable
+    {
+        let pin = crate::auth::bootstrap::generate_claim_pin();
+        let node_code_str = crate::nodecode::encode(&node_code).map_err(|e| {
+            anyhow::anyhow!("encode this node's NodeCode for the claim banner: {e}")
+        })?;
+        crate::auth::bootstrap::announce_ownership_unclaimed(&node_code_str, &pin);
+        Some(pin)
+    } else {
+        tracing::info!(
+            "node already has a ROOT owner — no first-run claim PIN minted (setup/root is closed)"
+        );
+        None
+    };
+
     // ── ONE shared Reticulum edge runtime — the node's single federation
     //    transport identity. From here the node IS a Reticulum node. ───────────
     let edge = build_edge(&engine, &cfg, Arc::clone(&signer), Arc::clone(&pqc)).await?;
@@ -184,6 +213,7 @@ pub async fn serve(cfg: ServerConfig) -> Result<()> {
                         strict,
                         node_code.key_id.clone(),
                         node_code.pubkey_ed25519_base64.clone(),
+                        claim_pin.clone(),
                     ))
                     // sessions/tokens: login / logout / me / refresh / owner-hint
                     .merge(crate::auth::session::router(Arc::clone(&engine)))

{ciris_server-0.4.1 → ciris_server-0.4.2}/tests/root_bootstrap.rs

@@ -126,14 +126,30 @@ fn founder_signer(key_id: &str) -> LocalSigner {
     )
 }
 
+/// A known, fixed one-time claim PIN the tests arm the router with (the boot path
+/// mints a random one; here we pin a value so a test can supply the correct PIN).
+const TEST_CLAIM_PIN: &str = "TEST-PIN1";
+
 /// Serve the bootstrap (setup) router on an ephemeral port; return its base URL.
-/// Pins the router to the node's identity (`key_id` + its Ed25519 pubkey).
+/// Pins the router to the node's identity (`key_id` + its Ed25519 pubkey) and arms
+/// it with the known [`TEST_CLAIM_PIN`].
 async fn serve(engine: Arc<Engine>, node_key_id: &str) -> (String, tokio::task::JoinHandle<()>) {
+    serve_with_pin(engine, node_key_id, Some(TEST_CLAIM_PIN.to_string())).await
+}
+
+/// Serve the bootstrap router armed with an EXPLICIT claim PIN (or `None` for an
+/// un-armed/already-claimed node).
+async fn serve_with_pin(
+    engine: Arc<Engine>,
+    node_key_id: &str,
+    claim_pin: Option<String>,
+) -> (String, tokio::task::JoinHandle<()>) {
     let app = bootstrap::router(
         engine,
         HybridPolicy::Strict,
         node_key_id.to_string(),
         node_pubkey_b64(),
+        claim_pin,
     );
     let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
         .await
@@ -257,7 +273,9 @@ fn founder_claim_body(node_key_id: &str, founder_key_id: &str) -> serde_json::Va
             "key_id": founder_key_id,
             // Pubkeys are filled in by the caller after signing (they come off the
             // HybridSignature), so this placeholder is replaced below.
-        }
+        },
+        // The one-time operator-presence PIN (signature-bound, inside the body).
+        "claim_pin": TEST_CLAIM_PIN,
     })
 }
 
@@ -509,6 +527,230 @@ async fn first_run_setup_root_requires_a_pin() {
     );
 }
 
+// ─── one-time CLAIM PIN — the operator-presence secret gate ──────────────────
+
+/// Helper: build a fully-signed first-run claim body for `founder_key_id` pinning
+/// `node_key_id`, with an explicit `claim_pin`. Returns the signed body bytes +
+/// the two signature headers (base64).
+async fn signed_claim_with_pin(
+    node_key_id: &str,
+    founder_key_id: &str,
+    claim_pin: Option<&str>,
+) -> (Vec<u8>, String, String) {
+    let fsigner = founder_signer(founder_key_id);
+    let probe = fsigner.sign_hybrid(b"probe").await.expect("probe sign");
+    let mut claim = serde_json::json!({
+        "node_code": node_code_string(node_key_id),
+        "founder": {
+            "key_id": founder_key_id,
+            "ed25519_pubkey_b64": BASE64.encode(&probe.classical.public_key),
+            "ml_dsa_65_pubkey_b64": BASE64.encode(&probe.pqc.public_key),
+        }
+    });
+    if let Some(pin) = claim_pin {
+        claim["claim_pin"] = pin.into();
+    }
+    let body = serde_json::to_vec(&claim).unwrap();
+    let sig = fsigner.sign_hybrid(&body).await.expect("sign setup body");
+    (
+        body,
+        BASE64.encode(&sig.classical.signature),
+        BASE64.encode(&sig.pqc.signature),
+    )
+}
+
+/// The correct PIN + valid founder sig + correct node pin → 201, ROOT bound. The
+/// happy path is already covered by `first_run_setup_root_claims_then_rejects_second_claim`
+/// (which supplies `TEST_CLAIM_PIN`); this test additionally asserts the PIN is
+/// CONSUMED after a successful claim — a fresh, validly-signed claim with the SAME
+/// correct PIN is now rejected (the route is 409-closed, AND the PIN is cleared).
+#[tokio::test]
+async fn claim_pin_is_consumed_after_successful_claim() {
+    let node_key_id = "ciris-pin-consume-node";
+    let founder_key_id = "ciris-pin-consume-founder";
+    let engine = node(node_key_id).await;
+    register_self(&engine, node_key_id).await;
+    let (base, _h) = serve(Arc::clone(&engine), node_key_id).await; // armed with TEST_CLAIM_PIN
+    let client = reqwest::Client::new();
+
+    let (body, ed_b64, mldsa_b64) =
+        signed_claim_with_pin(node_key_id, founder_key_id, Some(TEST_CLAIM_PIN)).await;
+    let resp = client
+        .post(format!("{base}/v1/setup/root"))
+        .header("x-ciris-signing-key-id", founder_key_id)
+        .header("x-ciris-signature-ed25519", &ed_b64)
+        .header("x-ciris-signature-ml-dsa-65", &mldsa_b64)
+        .body(body)
+        .send()
+        .await
+        .expect("POST setup/root (correct PIN)");
+    assert_eq!(resp.status(), 201, "correct PIN → claim succeeds");
+    assert_eq!(
+        store::list_by_role(&engine, WaRole::Root, 10)
+            .await
+            .expect("list roots")
+            .len(),
+        1,
+        "exactly one ROOT after a correct-PIN claim"
+    );
+
+    // A second VALID claim (fresh founder, same correct PIN) is now rejected: the
+    // route is first-run-closed (409) AND the PIN was consumed.
+    let (body2, ed2, ml2) =
+        signed_claim_with_pin(node_key_id, "ciris-pin-replayer", Some(TEST_CLAIM_PIN)).await;
+    let resp2 = client
+        .post(format!("{base}/v1/setup/root"))
+        .header("x-ciris-signing-key-id", "ciris-pin-replayer")
+        .header("x-ciris-signature-ed25519", &ed2)
+        .header("x-ciris-signature-ml-dsa-65", &ml2)
+        .body(body2)
+        .send()
+        .await
+        .expect("POST setup/root (replay)");
+    assert_eq!(
+        resp2.status(),
+        409,
+        "after a successful claim the route is first-run-closed (PIN also consumed)"
+    );
+    assert_eq!(
+        store::list_by_role(&engine, WaRole::Root, 10)
+            .await
+            .expect("list roots")
+            .len(),
+        1,
+        "no second ROOT minted on replay"
+    );
+}
+
+/// A WRONG PIN (valid founder sig, correct node pin) → 401, NO ROOT minted.
+#[tokio::test]
+async fn claim_with_wrong_pin_is_rejected() {
+    let node_key_id = "ciris-wrongpin2-node";
+    let founder_key_id = "ciris-wrongpin2-founder";
+    let engine = node(node_key_id).await;
+    register_self(&engine, node_key_id).await;
+    let (base, _h) = serve(Arc::clone(&engine), node_key_id).await; // armed with TEST_CLAIM_PIN
+    let client = reqwest::Client::new();
+
+    // A signed claim carrying the WRONG PIN (same length to exercise the
+    // byte-compare path, not just the length flag).
+    let (body, ed_b64, mldsa_b64) =
+        signed_claim_with_pin(node_key_id, founder_key_id, Some("WRNG-PIN0")).await;
+    let resp = client
+        .post(format!("{base}/v1/setup/root"))
+        .header("x-ciris-signing-key-id", founder_key_id)
+        .header("x-ciris-signature-ed25519", &ed_b64)
+        .header("x-ciris-signature-ml-dsa-65", &mldsa_b64)
+        .body(body)
+        .send()
+        .await
+        .expect("POST setup/root (wrong PIN)");
+    assert_eq!(resp.status(), 401, "a wrong PIN is rejected");
+    assert!(
+        store::list_by_role(&engine, WaRole::Root, 10)
+            .await
+            .expect("list roots")
+            .is_empty(),
+        "a wrong-PIN claim mints NO ROOT"
+    );
+    // The founder key must NOT have been admitted either.
+    assert!(
+        engine
+            .federation_directory()
+            .lookup_public_key(founder_key_id)
+            .await
+            .expect("lookup founder")
+            .is_none(),
+        "a wrong-PIN claim must NOT register the founder key"
+    );
+}
+
+/// A MISSING PIN (valid founder sig, correct node pin) → 401, NO ROOT minted.
+#[tokio::test]
+async fn claim_with_missing_pin_is_rejected() {
+    let node_key_id = "ciris-nopin-node";
+    let founder_key_id = "ciris-nopin-founder";
+    let engine = node(node_key_id).await;
+    register_self(&engine, node_key_id).await;
+    let (base, _h) = serve(Arc::clone(&engine), node_key_id).await; // armed with TEST_CLAIM_PIN
+    let client = reqwest::Client::new();
+
+    // No `claim_pin` field at all.
+    let (body, ed_b64, mldsa_b64) = signed_claim_with_pin(node_key_id, founder_key_id, None).await;
+    let resp = client
+        .post(format!("{base}/v1/setup/root"))
+        .header("x-ciris-signing-key-id", founder_key_id)
+        .header("x-ciris-signature-ed25519", &ed_b64)
+        .header("x-ciris-signature-ml-dsa-65", &mldsa_b64)
+        .body(body)
+        .send()
+        .await
+        .expect("POST setup/root (missing PIN)");
+    assert_eq!(resp.status(), 401, "a missing PIN is rejected");
+    assert!(
+        store::list_by_role(&engine, WaRole::Root, 10)
+            .await
+            .expect("list roots")
+            .is_empty(),
+        "a missing-PIN claim mints NO ROOT"
+    );
+}
+
+/// An UN-ARMED node (router built with `claim_pin: None`, e.g. already-claimed at
+/// boot) rejects every claim with 401 even with an otherwise-valid signed body —
+/// the PIN gate fails closed when no PIN is armed.
+#[tokio::test]
+async fn unarmed_node_rejects_claims() {
+    let node_key_id = "ciris-unarmed-node";
+    let founder_key_id = "ciris-unarmed-founder";
+    let engine = node(node_key_id).await;
+    register_self(&engine, node_key_id).await;
+    // No ROOT yet, but the router is NOT armed with a PIN.
+    let (base, _h) = serve_with_pin(Arc::clone(&engine), node_key_id, None).await;
+    let client = reqwest::Client::new();
+
+    let (body, ed_b64, mldsa_b64) =
+        signed_claim_with_pin(node_key_id, founder_key_id, Some(TEST_CLAIM_PIN)).await;
+    let resp = client
+        .post(format!("{base}/v1/setup/root"))
+        .header("x-ciris-signing-key-id", founder_key_id)
+        .header("x-ciris-signature-ed25519", &ed_b64)
+        .header("x-ciris-signature-ml-dsa-65", &mldsa_b64)
+        .body(body)
+        .send()
+        .await
+        .expect("POST setup/root (unarmed)");
+    assert_eq!(resp.status(), 401, "an un-armed node rejects all claims");
+    assert!(
+        store::list_by_role(&engine, WaRole::Root, 10)
+            .await
+            .expect("list roots")
+            .is_empty(),
+        "an un-armed-node claim mints NO ROOT"
+    );
+}
+
+/// Unit: `generate_claim_pin` produces an `XXXX-XXXX` Crockford-base32 PIN, and
+/// successive PINs differ (random source).
+#[test]
+fn generate_claim_pin_shape_and_randomness() {
+    let p1 = bootstrap::generate_claim_pin();
+    assert_eq!(p1.len(), 9, "8 chars + 1 dash");
+    assert_eq!(&p1[4..5], "-", "dash splits the two groups");
+    let groups: Vec<&str> = p1.split('-').collect();
+    assert_eq!(groups.len(), 2);
+    assert!(groups.iter().all(|g| g.len() == 4));
+    // Crockford alphabet only (no I/L/O/U; uppercase + digits).
+    const ALPHABET: &str = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+    assert!(p1
+        .chars()
+        .filter(|&c| c != '-')
+        .all(|c| ALPHABET.contains(c)));
+    // Overwhelmingly likely to differ (40 bits of entropy).
+    let p2 = bootstrap::generate_claim_pin();
+    assert_ne!(p1, p2, "successive PINs differ");
+}
+
 // ─── (d) auto_mint_root_if_needed elevates an admin-eligible identity ────────
 
 #[tokio::test]