fix(node): ANS-104 transport, three-outcome probe, verify endpoint (#26 split 2/4)

crates/gitlawb-node/src/auth/mod.rs

@@ -530,6 +530,11 @@ mod tests {
             push_limiter_trust: crate::rate_limit::TrustedProxy::None,
             sync_trigger_rate_limiter: RateLimiter::new(60, Duration::from_secs(3600)),
             peer_write_rate_limiter: RateLimiter::new(600, Duration::from_secs(3600)),
+            // F5 work-in-progress: a previous round added the field to
+            // `state::AppState` but not the test initializer. The field
+            // is unrelated to the F1 ANS-104 work and is initialized to
+            // a generous default so the test binary can compile.
+            arweave_verify_rate_limiter: RateLimiter::new(120, Duration::from_secs(60)),
             shutdown_tx: tokio::sync::watch::channel(false).0,
             git_read_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),
             git_write_semaphore: Arc::new(tokio::sync::Semaphore::new(64)),

crates/gitlawb-node/src/config.rs

@@ -134,6 +134,17 @@ pub struct Config {
     #[arg(long, env = "GITLAWB_IRYS_URL", default_value = "")]
     pub irys_url: String,
 
+    /// Arweave gateway URL for the public verify endpoint and the
+    /// three-outcome recovery probe. Defaults to `https://arweave.net`
+    /// because that is the protocol's public gateway. Set to a
+    /// private mirror in production if one is operated.
+    #[arg(
+        long,
+        env = "GITLAWB_ARWEAVE_GATEWAY_URL",
+        default_value = "https://arweave.net"
+    )]
+    pub arweave_gateway_url: String,
+
     /// Base L2 DID registry contract address (0x...)
     #[arg(long, env = "GITLAWB_CONTRACT_DID_REGISTRY", default_value = "")]
     pub contract_did_registry: String,
@@ -670,6 +681,19 @@ pub struct Config {
     #[arg(long, env = "GITLAWB_IPFS_RATE_LIMIT", default_value_t = 600)]
     pub ipfs_rate_limit: usize,
 
+    /// Per-IP requests-per-window cap on `GET
+    /// /api/v1/arweave/anchors/verify/{item_id}`.
+    ///
+    /// The verify endpoint is anonymous-callable and can issue one
+    /// (post round-3 refactor; two pre round-3) outbound HTTP
+    /// requests to the gateway per call. Unlike the comparable
+    /// public IPFS path, it had no IP admission limit prior to
+    /// the round-3 review, leaving the route open to anonymous
+    /// amplification. `0` disables the limit (NOT recommended in
+    /// production).
+    #[arg(long, env = "GITLAWB_ARWEAVE_VERIFY_RATE_LIMIT", default_value_t = 120)]
+    pub arweave_verify_rate_limit: usize,
+
     /// Rows the legacy provider-CID repair sweep reads per batch (U4, #173).
     ///
     /// The sweep walks every `pinned_cids` row on the node once, repairing rows that

crates/gitlawb-node/src/db/mod.rs

@@ -1123,6 +1123,29 @@ const MIGRATIONS: &[Migration] = &[
             "ALTER TABLE pin_repair_sweep ADD COLUMN IF NOT EXISTS discovery_cursor_id TEXT NOT NULL DEFAULT ''",
         ],
     },
+    Migration {
+        version: 27,
+        name: "arweave_anchors_irys_tx_id_index",
+        stmts: &[
+            // #26 split 2/4 (P2, reviewer round 2): backs the verify
+            // endpoint's `SELECT ... WHERE irys_tx_id = $1` at
+            // mod.rs:~3896. Without it every anonymous probe
+            // seq-scans the table (the existing indexes on
+            // `(repo, new_sha)` cannot serve it), so verify becomes
+            // O(rows) and the v2 transport's per-probe O(1) silently
+            // regresses.
+            //
+            // NON-UNIQUE on purpose: `record_arweave_anchor`
+            // generates a fresh UUID per call and a retry of the v2
+            // transport could legitimately write the same
+            // `irys_tx_id` twice; a UNIQUE constraint would fail on
+            // existing data and force a separate backfill decision.
+            // Promote to UNIQUE later only after auditing duplicates.
+            //
+            // NEW versioned migration (never appended to an applied block, INV-7).
+            "CREATE INDEX IF NOT EXISTS idx_arweave_anchors_irys_tx_id ON arweave_anchors(irys_tx_id)",
+        ],
+    },
 ];
 
 /// Max distinct source repos recorded per pinned object (F1, #173 jatmn round 8).
@@ -3874,6 +3897,44 @@ impl Db {
             })
             .collect())
     }
+
+    /// Look up a single Arweave anchor by its externally-routable
+    /// transaction id (the `irys_tx_id` column).
+    ///
+    /// Production callers — including the public verify endpoint
+    /// `GET /api/v1/arweave/anchors/verify/{item_id}` — pass the
+    /// gateway item id (the Irys response `id` for v1 anchors, the
+    /// ANS-104-derived `base64url(SHA256(signature))` for v2 anchors).
+    /// That value lives in `irys_tx_id`; the `id` column is an
+    /// internal UUID generated by [`Db::record_arweave_anchor`] and
+    /// is NOT routable from outside the node.
+    ///
+    /// Returns `None` if no row matches.
+    pub async fn get_arweave_anchor_by_item_id(
+        &self,
+        item_id: &str,
+    ) -> Result<Option<ArweaveAnchor>> {
+        let row = sqlx::query(
+            "SELECT id, repo, owner_did, ref_name, old_sha, new_sha, cid, irys_tx_id, arweave_url, node_did, anchored_at
+             FROM arweave_anchors WHERE irys_tx_id = $1",
+        )
+        .bind(item_id)
+        .fetch_optional(&self.pool)
+        .await?;
+        Ok(row.map(|r| ArweaveAnchor {
+            id: r.get("id"),
+            repo: r.get("repo"),
+            owner_did: r.get("owner_did"),
+            ref_name: r.get("ref_name"),
+            old_sha: r.get("old_sha"),
+            new_sha: r.get("new_sha"),
+            cid: r.get("cid"),
+            irys_tx_id: r.get("irys_tx_id"),
+            arweave_url: r.get("arweave_url"),
+            node_did: r.get("node_did"),
+            anchored_at: r.get("anchored_at"),
+        }))
+    }
 }
 
 // ── Row helpers ───────────────────────────────────────────────────────────────
@@ -5094,6 +5155,124 @@ mod migration_tests {
         assert_eq!(attempted_at_of(&db, "z6Mkfoo/failed").await, None);
         assert_eq!(attempted_at_of(&db, "z6Mkfoo/done").await, None);
     }
+
+    /// #26 split 2/4 (P2, reviewer round 2): the verify endpoint's
+    /// `SELECT ... WHERE irys_tx_id = $1` at mod.rs:~3896 is a
+    /// sequential scan unless `idx_arweave_anchors_irys_tx_id`
+    /// exists. Migration v27 is the only place that index is
+    /// created. This test pins the index's presence against a
+    /// future change that drops v27 from the array (a typo fix, a
+    /// misread of the review, an accidental revert) — without it
+    /// the suite stays green and the regression only shows up in
+    /// production EXPLAIN plans.
+    #[sqlx::test]
+    async fn migration_v27_creates_irys_tx_id_index(pool: sqlx::PgPool) {
+        let db = super::Db::for_testing(pool);
+        db.migrate().await.unwrap();
+        let row = sqlx::query(
+            "SELECT 1 AS present FROM pg_indexes
+             WHERE schemaname = 'public'
+               AND tablename = 'arweave_anchors'
+               AND indexname = 'idx_arweave_anchors_irys_tx_id'",
+        )
+        .fetch_optional(&db.pool)
+        .await
+        .unwrap();
+        assert!(
+            row.is_some(),
+            "idx_arweave_anchors_irys_tx_id is missing — migration v27 \
+             was not applied. The verify endpoint will seq-scan the table."
+        );
+    }
+
+    /// Round-3 P2 (reviewer): the presence test above only proves
+    /// the index EXISTS; a future "fix" could re-add it under a
+    /// non-equivalent name (wrong column, partial index) and the
+    /// presence test would still pass. The verify lookup query
+    /// would then seq-scan. This test pins the index is actually
+    /// USED by the verify lookup: with `enable_seqscan = off`,
+    /// the planner has no other option and the query must succeed;
+    /// with the default plan, the EXPLAIN output must name
+    /// `idx_arweave_anchors_irys_tx_id`. A bug in the index
+    /// definition (wrong column, INCLUDE-only, partial predicate
+    /// excluding the lookup value) flips this test RED.
+    #[sqlx::test]
+    async fn migration_v27_irys_tx_id_index_is_used_by_the_lookup(pool: sqlx::PgPool) {
+        let db = super::Db::for_testing(pool);
+        db.migrate().await.unwrap();
+
+        // Seed one row so the planner has data to estimate against.
+        // The actual value of `irys_tx_id` does not matter — the
+        // index lookup path is the same for any string.
+        sqlx::query(
+            r#"INSERT INTO arweave_anchors
+               (id, repo, owner_did, ref_name, old_sha, new_sha, cid, irys_tx_id,
+                arweave_url, node_did, anchored_at)
+               VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)"#,
+        )
+        .bind(uuid::Uuid::new_v4().to_string())
+        .bind("o/r")
+        .bind("o")
+        .bind("refs/heads/main")
+        .bind("0".repeat(40))
+        .bind("1".repeat(40))
+        .bind(Option::<String>::None)
+        .bind("seeded-irys-tx-for-explain")
+        .bind("https://arweave.net/x")
+        .bind("did:key:zN")
+        .bind(chrono::Utc::now().to_rfc3339())
+        .execute(&db.pool)
+        .await
+        .unwrap();
+
+        // Force the planner to use the index. If the index is
+        // missing or does not cover `irys_tx_id`, the planner
+        // has no other option and the query will fall back to
+        // an error (seqscan disabled, no index to use). This is
+        // the most direct proof the index is wired correctly.
+        sqlx::query("SET enable_seqscan = off")
+            .execute(&db.pool)
+            .await
+            .unwrap();
+
+        let row =
+            sqlx::query("SELECT id, repo, irys_tx_id FROM arweave_anchors WHERE irys_tx_id = $1")
+                .bind("seeded-irys-tx-for-explain")
+                .fetch_optional(&db.pool)
+                .await
+                .expect(
+                    "verify lookup failed with seqscan disabled — the index either \
+             does not exist, is on the wrong column, or is a partial index \
+             that excludes this row. The verify endpoint will seq-scan in \
+             production as a result.",
+                );
+        assert!(
+            row.is_some(),
+            "verify lookup returned no row for a seeded value; the index \
+             may be a covering index that does not return the row, or the \
+             planner path is broken"
+        );
+
+        // Reset and confirm the default EXPLAIN names the index.
+        sqlx::query("SET enable_seqscan = on")
+            .execute(&db.pool)
+            .await
+            .unwrap();
+        let plan: (String,) =
+            sqlx::query_as("EXPLAIN SELECT id FROM arweave_anchors WHERE irys_tx_id = $1")
+                .bind("seeded-irys-tx-for-explain")
+                .fetch_one(&db.pool)
+                .await
+                .expect("EXPLAIN failed; the verify query is broken");
+        let plan_lines: Vec<&str> = plan.0.lines().collect();
+        let plan_text = plan_lines.join(" | ");
+        assert!(
+            plan_text.contains("idx_arweave_anchors_irys_tx_id"),
+            "the default EXPLAIN did not use idx_arweave_anchors_irys_tx_id. \
+             Plan: {plan_text}. The index is present but the planner chose \
+             another path; the verify endpoint will seq-scan in production."
+        );
+    }
 }
 
 #[cfg(test)]
@@ -8552,3 +8731,114 @@ mod cid_candidate_order_tests {
         );
     }
 }
+
+#[cfg(test)]
+mod arweave_anchor_lookup_tests {
+    //! The production writer at `Db::record_arweave_anchor` generates
+    //! a fresh UUID for the internal `id` column and stores the
+    //! externally-routable transaction id in `irys_tx_id`. The
+    //! public verify endpoint looks anchors up by the
+    //! externally-routable id, so `get_arweave_anchor_by_item_id`
+    //! must filter on `irys_tx_id` — the prior `WHERE id = $1` form
+    //! would always 404 on real anchors (the internal UUID never
+    //! matches the gateway item id) and only passed the older
+    //! fixtures because they seeded `id = item_id`.
+    //!
+    //! The fixture deliberately uses distinct values for `id` (a
+    //! fresh UUID generated by `record_arweave_anchor`) and
+    //! `irys_tx_id` (the Irys response `id`, or the ANS-104 derived
+    //! id) so the test exercises the production writer path, not
+    //! a masked self-round-trip.
+
+    use crate::db::Db;
+    use crate::db::RecordAnchorInput;
+    use sqlx::PgPool;
+
+    async fn _db(pool: PgPool) -> Db {
+        let db = Db::for_testing(pool);
+        db.run_migrations().await.unwrap();
+        db
+    }
+
+    #[sqlx::test]
+    async fn record_then_lookup_round_trips_via_irys_tx_id(pool: PgPool) {
+        let db = _db(pool).await;
+
+        // The production writer's signature: external item id lives
+        // in `irys_tx_id`, the internal UUID is generated.
+        let item_id = "abc-external-43-char-base58-7xGpIoHUQ8j9GhD3Y2mKzP1NsVtXwRcFe";
+        let old_sha = "0".repeat(40);
+        let new_sha = "1".repeat(40);
+        let arweave_url = format!("https://arweave.net/{item_id}");
+        db.record_arweave_anchor(&RecordAnchorInput {
+            repo: "alice/repo",
+            owner_did: "did:key:z6owner",
+            ref_name: "refs/heads/main",
+            old_sha: &old_sha,
+            new_sha: &new_sha,
+            cid: None,
+            irys_tx_id: item_id,
+            arweave_url: &arweave_url,
+            node_did: "did:key:z6node",
+        })
+        .await
+        .unwrap();
+
+        // The reader filters on `irys_tx_id`, not `id`. The lookup
+        // MUST return the row.
+        let row = db
+            .get_arweave_anchor_by_item_id(item_id)
+            .await
+            .unwrap()
+            .expect("the row is reachable by the externally-routable id");
+        assert_eq!(row.irys_tx_id, item_id);
+        assert_eq!(row.repo, "alice/repo");
+        assert_eq!(row.node_did, "did:key:z6node");
+        // The internal `id` is a UUID — distinct from the item id.
+        assert_ne!(row.id, item_id);
+        assert_eq!(row.id.len(), 36, "id is a 36-char UUID");
+    }
+
+    #[sqlx::test]
+    async fn lookup_with_internal_uuid_returns_none(pool: PgPool) {
+        let db = _db(pool).await;
+        let item_id = "real-tx-id-base58-43-chars-7xGpIoHUQ8j9GhD3Y2mKzP1N";
+        let old_sha = "0".repeat(40);
+        let new_sha = "1".repeat(40);
+        let arweave_url = format!("https://arweave.net/{item_id}");
+        db.record_arweave_anchor(&RecordAnchorInput {
+            repo: "alice/repo",
+            owner_did: "did:key:z6owner",
+            ref_name: "refs/heads/main",
+            old_sha: &old_sha,
+            new_sha: &new_sha,
+            cid: None,
+            irys_tx_id: item_id,
+            arweave_url: &arweave_url,
+            node_did: "did:key:z6node",
+        })
+        .await
+        .unwrap();
+
+        // The row's internal `id` is a UUID. Looking it up via
+        // `get_arweave_anchor_by_item_id` MUST return `None` — the
+        // prior `WHERE id = $1` filter would have spuriously
+        // returned the row, which is the production bug.
+        let row = db
+            .get_arweave_anchor_by_item_id(
+                &db.list_arweave_anchors(None, 10)
+                    .await
+                    .unwrap()
+                    .first()
+                    .expect("row exists")
+                    .id,
+            )
+            .await
+            .unwrap();
+        assert!(
+            row.is_none(),
+            "the internal UUID is NOT a valid externally-routable item id; \
+             the lookup must filter on irys_tx_id, not id"
+        );
+    }
+}