feat(gl): sanctioned iCaptcha client flow + secure git lifecycle (#138)

* feat(gl): sanctioned iCaptcha client flow + secure git lifecycle

Builds the client side of the iCaptcha gate so a legitimate agent passes the
challenge transparently, with no manual headers and no GITLAWB_ICAPTCHA_PROOF
env var. Server enforcement is unchanged.

New crate `icaptcha-client` (blocking, shared by gl + the git helper):
- deterministic solvers for the computational challenge types (arithmetic,
  algebra, sequence) matching the iCaptcha generators; anagram/logic/LLM fall
  back to a solver hook / interactive prompt.
- obtain_proof(): POST /v1/challenge (requesterId = caller DID), solve, POST
  /v1/answer, handle escalation, return the signed proof. Optional bearer auth
  via GITLAWB_ICAPTCHA_API_KEY.

gl (crates/gl):
- http.rs: unify post/put/delete through one signed sender that, on a 403
  iCaptcha challenge (detected via x-icaptcha-url / x-icaptcha-level headers),
  solves it and retries the same signed request with the x-icaptcha-proof
  header (bounded retry absorbs the ~5 min proof TTL). Removes the env hack.
  Emits an actionable hint on 401 not_an_agent (old-CLI / unregistered).
- repo.rs: `repo info` checks status and returns a real 404 instead of a stub
  card with `?` fields; `repo info`/`clone` resolve the owner from the local
  identity or an explicit owner/name — never the node's own DID.
- doctor.rs: warn on gl-vs-node version drift; add an iCaptcha reachability
  check.

git-remote-gitlawb: same shared client — push stays signed (RFC 9421); on a 403
iCaptcha (safety net; push is signed-only, not gated) it solves and retries.
Clone/fetch unsigned; missing repo keeps its clear 404.

gitlawb-node: the 403 icaptcha_proof_required response now advertises the
service url + required level as JSON fields and x-icaptcha-url / x-icaptcha-level
headers (mirroring the human_detected pattern) so clients discover them instead
of scraping the message. The sub == authenticated-DID and expiry/level checks
are unchanged — enforcement is not weakened.

README: documents the full lifecycle (identity -> register -> repo create with
auto-iCaptcha -> push -> clone), the requesterId == DID rule, and proof TTL.

Tested: solver unit tests; full workspace green against Postgres (node still
rejects missing/expired/wrong-subject proofs).

* fix(icaptcha-client,gl): address PR #138 review feedback

Rebased onto main (resolving the git-remote-gitlawb/main.rs conflict from #119)
and addressed the review findings:

- [beardthelion P2 / jatmn P2 / CodeRabbit] Removed the dead iCaptcha retry loop
  from the push path. git_receive_pack never calls verify_request (only
  create/fork/register are iCaptcha-gated), so a push 403 never carries
  x-icaptcha-* headers and the loop could never solve. Taking main's push path
  (via #119) deletes it, which also resolves the pack-clone (retries no longer
  copy the whole pack) and the interactive-prompt-over-git-stream threads, and
  restores the sanitized info/refs error path. git-remote-gitlawb no longer
  depends on icaptcha-client.

- [beardthelion P1] Sanitize and length-bound iCaptcha error bodies before they
  reach the terminal. The origin is only as trusted as the node that advertised
  it, so its non-2xx bodies (and Failed{reason}) are attacker-influenceable; they
  went raw into bail! (CWE-150, the #137 class). Now bounded-read + C0/C1-stripped
  + capped, same shape as #137.

- [beardthelion P2] Do not trust or hand credentials to a node-chosen iCaptcha
  URL. x-icaptcha-url was used as the base with no scheme/host check and the API
  key was sent to it on the first hop (SSRF + key exfiltration). resolve_solver_url
  now honors an advertised URL only when https + host-allowlisted (public default
  or the operator's GITLAWB_ICAPTCHA_URL), else falls back to the trusted origin;
  the API key is attached only to the operator's own configured origin.

- [jatmn P2 / CodeRabbit] gl repo clone with a bare name now derives the short
  owner key via resolve_owner_did, matching the other commands' gitlawb://z.../name
  URL shape instead of the colon-bearing full DID.

Skipped (with reason): jatmn P3 (doctor GITLAWB_ICAPTCHA_URL) is resolved by the
P2 change — that env var is now read by the write path, so the doctor's probe is
accurate. CodeRabbit User-Agent-version nit lived in the push code reverted to
main. README push wording kept ("signed-only, no per-push challenge") — now
accurate since the retry path is gone; the API-key bullet was updated for the new
trust model.

Tests: added sanitize + resolve_solver_url unit tests; full workspace green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: kevincodex1

Cargo.lock

@@ -6,6 +6,7 @@ members = [
     "crates/gl",
     "crates/git-remote-gitlawb",
     "crates/gitlawb-attest",
+    "crates/icaptcha-client",
 ]
 
 [workspace.package]

Cargo.toml

@@ -185,6 +185,45 @@ git clone gitlawb://did:key:z6Mk.../my-repo
 
 For public-network use, make sure `GITLAWB_NODE` points to the node you want. The helper defaults to localhost for local development.
 
+### Full lifecycle against an iCaptcha-enforcing node
+
+Public nodes (e.g. `node.gitlawb.com`) require two things on writes:
+
+1. **RFC 9421 HTTP Signatures** — every write is signed by your identity key. `gl`
+   and the `git-remote-gitlawb` helper do this automatically. An old/unsigned CLI
+   fails with `401 not_an_agent`; `gl` will tell you to upgrade and register.
+2. **An iCaptcha proof** on the spam-gated writes (**repo create, fork, register**).
+   `gl` solves this for you: on the node's `403 icaptcha_proof_required` it reads the
+   `x-icaptcha-url` / `x-icaptcha-level` hints, requests a challenge, solves it
+   locally (arithmetic / algebra / sequence), and **retries the same signed request**
+   with the `x-icaptcha-proof` header — no manual steps, no env vars.
+
+```bash
+gl identity new                                   # create did:key identity
+gl register      --node https://node.gitlawb.com  # signed + auto-solves iCaptcha
+gl repo create memlawb --node https://node.gitlawb.com   # signed + auto-solves iCaptcha
+git push  origin2 main                            # origin2 = gitlawb://<your-did>/memlawb (signed)
+git clone gitlawb://<your-did>/memlawb            # public read, no proof needed
+gl doctor                                         # preflight: identity, node, version, iCaptcha
+```
+
+Notes:
+
+- **`requesterId` is always your DID.** The proof's `sub` claim must equal the
+  authenticated signer; `gl`/helper set this automatically and the node enforces
+  `sub == authenticated DID` (so a proof minted for another identity is rejected).
+- **Proofs are short-lived (~5 min TTL) and single-use.** If one expires between
+  solving and use, the client transparently solves a fresh one and retries.
+- **What needs what:** create / fork / register are signed **and** iCaptcha-gated;
+  `git push` is **signed-only** (owner signature is the gate — no per-push challenge);
+  reads (clone / fetch / `repo info`) need no proof. A non-existent repo returns a
+  clear `404`, never a placeholder.
+- **API-key iCaptcha deployments:** set `GITLAWB_ICAPTCHA_URL` to your iCaptcha
+  origin and `GITLAWB_ICAPTCHA_API_KEY` to its key. The client only talks to an
+  `https` origin whose host is allowlisted (that URL or the public default), and
+  sends the bearer token **only** to your configured origin — never to a URL a
+  node advertises — so a hostile node can't capture the key or redirect the solve.
+
 ---
 
 ## Architecture

README.md

@@ -23,8 +23,14 @@ pub enum AppError {
     #[allow(dead_code)]
     Forbidden(String),
 
-    #[error("icaptcha proof required: {0}")]
-    IcaptchaProofRequired(String),
+    #[error("icaptcha proof required: {message}")]
+    IcaptchaProofRequired {
+        message: String,
+        /// iCaptcha service base URL the client should solve against.
+        url: String,
+        /// Minimum proof level this node requires.
+        level: u32,
+    },
 
     #[error("invalid request: {0}")]
     BadRequest(String),
@@ -44,6 +50,34 @@ pub enum AppError {
 
 impl IntoResponse for AppError {
     fn into_response(self) -> Response {
+        // iCaptcha challenges carry structured discovery so clients don't have to
+        // scrape the message: the service URL and required level are returned as
+        // both JSON fields and `x-icaptcha-url` / `x-icaptcha-level` headers
+        // (mirroring the header-bearing `human_detected` response in auth/mod.rs).
+        if let AppError::IcaptchaProofRequired {
+            message,
+            url,
+            level,
+        } = &self
+        {
+            use axum::http::HeaderValue;
+            let body = Json(json!({
+                "error": "icaptcha_proof_required",
+                "message": message,
+                "icaptcha_url": url,
+                "required_level": level,
+            }));
+            let mut resp = (StatusCode::FORBIDDEN, body).into_response();
+            let headers = resp.headers_mut();
+            if let Ok(v) = HeaderValue::from_str(url) {
+                headers.insert("x-icaptcha-url", v);
+            }
+            if let Ok(v) = HeaderValue::from_str(&level.to_string()) {
+                headers.insert("x-icaptcha-level", v);
+            }
+            return resp;
+        }
+
         let (status, code, message) = match &self {
             AppError::RepoNotFound(r) => (
                 StatusCode::NOT_FOUND,
@@ -58,15 +92,8 @@ impl IntoResponse for AppError {
             AppError::NotFound(msg) => (StatusCode::NOT_FOUND, "not_found", msg.clone()),
             AppError::Unauthorized(msg) => (StatusCode::UNAUTHORIZED, "not_an_agent", msg.clone()),
             AppError::Forbidden(msg) => (StatusCode::FORBIDDEN, "forbidden", msg.clone()),
-            // 403, not 401: the caller IS an authenticated agent (credentials are
-            // valid) but is forbidden from this action without a valid, fresh
-            // iCaptcha proof. The distinct `icaptcha_proof_required` code — which
-            // clients branch on — keeps it separable from a plain `forbidden`.
-            AppError::IcaptchaProofRequired(msg) => (
-                StatusCode::FORBIDDEN,
-                "icaptcha_proof_required",
-                msg.clone(),
-            ),
+            // IcaptchaProofRequired is handled above (it carries extra headers/fields).
+            AppError::IcaptchaProofRequired { .. } => unreachable!("handled before this match"),
             AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, "bad_request", msg.clone()),
             AppError::TooManyRequests(msg) => {
                 (StatusCode::TOO_MANY_REQUESTS, "rate_limited", msg.clone())

crates/gitlawb-node/src/error.rs

@@ -237,9 +237,13 @@ impl ProofGuard {
         match self.0 {
             Some(p) => {
                 if !db.consume_proof_jti(&p.jti, p.exp).await? {
-                    return Err(AppError::IcaptchaProofRequired(
-                        "iCaptcha proof already used (replay); solve a fresh challenge".to_string(),
-                    ));
+                    let (url, level) = url_and_level();
+                    return Err(AppError::IcaptchaProofRequired {
+                        message: "iCaptcha proof already used (replay); solve a fresh challenge"
+                            .to_string(),
+                        url,
+                        level,
+                    });
                 }
                 Ok(Some(p))
             }
@@ -265,10 +269,23 @@ pub fn verify_request(headers: &HeaderMap, did: &str) -> Result<ProofGuard, AppE
 }
 
 fn reject_error(v: &Verifier, reason: &str) -> AppError {
-    AppError::IcaptchaProofRequired(format!(
-        "iCaptcha proof required ({reason}). Solve a challenge at {} for level >= {} and resend with the {} header.",
-        v.url, v.required_level, PROOF_HEADER
-    ))
+    AppError::IcaptchaProofRequired {
+        message: format!(
+            "iCaptcha proof required ({reason}). Solve a challenge at {} for level >= {} and resend with the {} header.",
+            v.url, v.required_level, PROOF_HEADER
+        ),
+        url: v.url.clone(),
+        level: v.required_level,
+    }
+}
+
+/// iCaptcha service url + required level for error responses, read from the
+/// initialized verifier (falls back to defaults if somehow uninitialized).
+fn url_and_level() -> (String, u32) {
+    VERIFIER
+        .get()
+        .map(|v| (v.url.clone(), v.required_level))
+        .unwrap_or_else(|| ("https://icaptcha.gitlawb.com".to_string(), 3))
 }
 
 /// Mode-aware decision. Pure and IO-free (no DB; clock injected via `now`) so it

crates/gitlawb-node/src/icaptcha.rs

@@ -12,6 +12,7 @@ path = "src/main.rs"
 
 [dependencies]
 gitlawb-core = { path = "../gitlawb-core" }
+icaptcha-client = { path = "../icaptcha-client" }
 tokio = { workspace = true }
 serde = { workspace = true }
 serde_json = { workspace = true }

crates/gl/Cargo.toml

@@ -174,6 +174,19 @@ pub async fn run(args: DoctorArgs) -> Result<()> {
                 "node",
                 format!("{} — v{version} ({short_did}…)", args.node),
             ));
+            // Capability drift: a node newer than this CLI may require features
+            // (RFC 9421 signing, iCaptcha) the CLI doesn't speak.
+            let gl_ver = env!("CARGO_PKG_VERSION");
+            if version != "?" && is_newer(version, gl_ver) {
+                checks.push(Check::warn(
+                    "gl version",
+                    format!(
+                        "node is v{version} but gl is v{gl_ver} — your CLI may be missing \
+                         features (signing / iCaptcha) this node requires"
+                    ),
+                    "upgrade gl: curl -sSf https://gitlawb.com/install.sh | sh",
+                ));
+            }
         }
         Ok(resp) => {
             checks.push(Check::fail(
@@ -191,6 +204,31 @@ pub async fn run(args: DoctorArgs) -> Result<()> {
         }
     }
 
+    // ── 4b. iCaptcha capability ───────────────────────────────────────────
+    // Gated writes (repo create / register / fork) auto-solve a challenge at the
+    // iCaptcha service; check it's reachable so the failure mode is obvious.
+    let icaptcha_url = std::env::var("GITLAWB_ICAPTCHA_URL")
+        .unwrap_or_else(|_| icaptcha_client::DEFAULT_URL.to_string());
+    match NodeClient::new(&icaptcha_url, None).get("/v1/pubkey").await {
+        Ok(resp) if resp.status().is_success() => {
+            checks.push(Check::pass("iCaptcha", format!("{icaptcha_url} reachable")));
+        }
+        Ok(resp) => {
+            checks.push(Check::warn(
+                "iCaptcha",
+                format!("{icaptcha_url} returned HTTP {}", resp.status()),
+                "gated writes (repo create / register) may fail until iCaptcha is reachable",
+            ));
+        }
+        Err(e) => {
+            checks.push(Check::warn(
+                "iCaptcha",
+                format!("{icaptcha_url} unreachable: {e}"),
+                "set GITLAWB_ICAPTCHA_URL or check connectivity — repo create / register solve a challenge there",
+            ));
+        }
+    }
+
     // ── 5. git-remote-gitlawb helper ──────────────────────────────────────
     // Use PATH lookup only — invoking the binary directly triggers git internals
     // that error with "fatal: not a git repository" outside of a git repo.