feat: add challenge expiry, well-known discovery, streaming deduction, address-based sessions

Kenbak · Kenbak · commit 168c9d63bb39 · 2026-03-28T11:22:08.000+05:30
- valid_until: 402 responses now include expiry timestamp (5 min default)
- /.well-known/payment: standardized discovery endpoint for agents
- POST /api/sessions/deduct: variable amount deduction for streaming metering
- POST /api/sessions/prepare: generate unique deposit address (no memo needed)
- Open endpoint now supports session_request_id for address-based deposits
- session_requests table with 30 min expiry and auto-cleanup
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -106,6 +106,10 @@ Privacy-preserving Zcash payment gateway. Non-custodial, shielded-only.
   - If human wants dashboard: register normally, hand API key to agent
   - Enables fully autonomous agent-to-agent commerce
   - Rate limited + UFVK validation before scanner activation
+- [x] **Challenge expiry (`valid_until`)** — 402 responses include expiry timestamp; verification rejects stale challenges (prevents agents paying outdated prices after ZEC rate changes)
+- [x] **`/.well-known/payment` discovery** — standardized endpoint for agents to auto-detect payment methods, currencies, protocols, session support, and facilitator URL
+- [x] **Streaming (pay-per-token)** — SSE metering on top of sessions; middleware deducts in batches (~100 tokens), sends `event: payment_required` when balance insufficient. Non-custodial (same session model, different metering)
+- [x] **Address-based session deposits** — generate unique deposit address per session (via diversifier), eliminating memo dependency. Future-proofs against NU7/Tachyon memo changes. Includes cleanup of abandoned prepare requests (30 min expiry)
 - [ ] **@cipherpay/wallet-mcp** — MCP server wrapping `zipher-cli` so AI agents can send ZEC
 - [ ] **Multi-recipient send** — enable batch payments from a single agent transaction
 
diff --git a/src/api/mod.rs b/src/api/mod.rs
@@ -114,8 +114,10 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
             // Session endpoints (agentic prepaid credit)
             .service(
                 web::scope("/sessions")
+                    .route("/prepare", web::post().to(sessions::prepare).wrap(Governor::new(&session_rate_limit)))
                     .route("/open", web::post().to(sessions::open).wrap(Governor::new(&session_rate_limit)))
                     .route("/validate", web::get().to(sessions::validate))
+                    .route("/deduct", web::post().to(sessions::deduct))
                     .route("/{id}", web::get().to(sessions::get_status))
                     .route("/{id}/close", web::post().to(sessions::close))
             )
@@ -127,6 +129,8 @@ pub fn configure(cfg: &mut web::ServiceConfig) {
             .route("/admin/webhooks", web::get().to(admin::webhooks))
             .route("/admin/system", web::get().to(admin::system)),
     );
+
+    cfg.route("/.well-known/payment", web::get().to(well_known_payment));
 }
 
 /// Public checkout endpoint for buyer-driven invoice creation.
@@ -465,6 +469,29 @@ async fn health() -> actix_web::HttpResponse {
     }))
 }
 
+async fn well_known_payment(
+    config: web::Data<crate::config::Config>,
+) -> actix_web::HttpResponse {
+    let network = if config.is_testnet() { "zcash:testnet" } else { "zcash:mainnet" };
+    actix_web::HttpResponse::Ok()
+        .insert_header(("Access-Control-Allow-Origin", "*"))
+        .insert_header(("Cache-Control", "public, max-age=3600"))
+        .json(serde_json::json!({
+            "version": "1.0",
+            "methods": ["zcash"],
+            "currencies": ["ZEC"],
+            "network": network,
+            "protocols": ["x402", "mpp"],
+            "capabilities": {
+                "sessions": true,
+                "streaming": true,
+                "replay_protection": true,
+            },
+            "facilitator": "https://api.cipherpay.app",
+            "documentation": "https://cipherpay.app/docs",
+        }))
+}
+
 /// List invoices: requires API key or session auth. Scoped to the authenticated merchant.
 async fn list_invoices(
     req: actix_web::HttpRequest,
diff --git a/src/api/sessions.rs b/src/api/sessions.rs
@@ -10,8 +10,11 @@ const SESSION_MEMO_PREFIX: &str = "zipher:session:";
 #[derive(Debug, Deserialize)]
 pub struct OpenRequest {
     pub txid: String,
-    pub merchant_id: String,
+    /// Required for memo-based flow; optional when using session_request_id.
+    pub merchant_id: Option<String>,
     pub refund_address: Option<String>,
+    /// If provided, uses address-based verification (no memo needed).
+    pub session_request_id: Option<String>,
 }
 
 pub async fn open(
@@ -40,8 +43,32 @@ pub async fn open(
         }));
     }
 
+    // Resolve merchant: either from session_request_id or merchant_id
+    let (merchant_id, expected_address) = if let Some(ref sr_id) = body.session_request_id {
+        match crate::sessions::get_session_request(pool.get_ref(), sr_id).await {
+            Ok(Some(sr)) => (sr.merchant_id, Some(sr.deposit_address)),
+            Ok(None) => {
+                return HttpResponse::BadRequest().json(serde_json::json!({
+                    "error": "Session request not found, already used, or expired"
+                }));
+            }
+            Err(e) => {
+                tracing::error!(error = %e, "Failed to lookup session request");
+                return HttpResponse::InternalServerError().json(serde_json::json!({
+                    "error": "Internal error"
+                }));
+            }
+        }
+    } else if let Some(ref mid) = body.merchant_id {
+        (mid.clone(), None)
+    } else {
+        return HttpResponse::BadRequest().json(serde_json::json!({
+            "error": "Either merchant_id or session_request_id is required"
+        }));
+    };
+
     let merchant = match crate::merchants::get_merchant_by_id(
-        pool.get_ref(), &body.merchant_id, &config.encryption_key
+        pool.get_ref(), &merchant_id, &config.encryption_key
     ).await {
         Ok(Some(m)) => m,
         _ => {
@@ -77,30 +104,49 @@ pub async fn open(
         }));
     }
 
-    let expected_memo = format!("{}{}", SESSION_MEMO_PREFIX, body.merchant_id);
-    let session_outputs: Vec<_> = outputs.iter()
-        .filter(|o| o.memo.trim() == expected_memo)
-        .collect();
-
-    if session_outputs.is_empty() {
-        return HttpResponse::BadRequest().json(serde_json::json!({
-            "error": format!("No output with session memo found. Expected memo: {}", expected_memo),
-        }));
-    }
-
-    let total_zatoshis: i64 = session_outputs.iter()
-        .map(|o| o.amount_zatoshis as i64)
-        .sum();
+    // Two verification paths: address-based (no memo) or memo-based (legacy)
+    let total_zatoshis: i64 = if let Some(ref addr) = expected_address {
+        // Address-based: sum all outputs (all decrypted outputs belong to this merchant,
+        // and the unique address ensures intent)
+        let total: i64 = outputs.iter().map(|o| o.amount_zatoshis as i64).sum();
+        if total == 0 {
+            return HttpResponse::BadRequest().json(serde_json::json!({
+                "error": "No outputs to the expected deposit address"
+            }));
+        }
+        tracing::info!(address = %addr, total_zatoshis = total, "Address-based session deposit verified");
+        total
+    } else {
+        // Memo-based: filter by session memo
+        let expected_memo = format!("{}{}", SESSION_MEMO_PREFIX, merchant_id);
+        let session_outputs: Vec<_> = outputs.iter()
+            .filter(|o| o.memo.trim() == expected_memo)
+            .collect();
+
+        if session_outputs.is_empty() {
+            return HttpResponse::BadRequest().json(serde_json::json!({
+                "error": format!("No output with session memo found. Expected memo: {}", expected_memo),
+            }));
+        }
+        session_outputs.iter().map(|o| o.amount_zatoshis as i64).sum()
+    };
 
     if total_zatoshis < 10_000 {
         return HttpResponse::BadRequest().json(serde_json::json!({
             "error": "Deposit too small — minimum 10,000 zatoshis (0.0001 ZEC)"
         }));
     }
 
+    // Mark session request as used (if address-based)
+    if let Some(ref sr_id) = body.session_request_id {
+        if let Err(e) = crate::sessions::mark_session_request_used(pool.get_ref(), sr_id).await {
+            tracing::warn!(error = %e, "Failed to mark session request as used");
+        }
+    }
+
     match crate::sessions::create_session(
         pool.get_ref(),
-        &body.merchant_id,
+        &merchant_id,
         &body.txid,
         total_zatoshis,
         body.refund_address.as_deref(),
@@ -294,6 +340,107 @@ pub async fn history(
     }
 }
 
+/// Prepare a session deposit: generates a unique payment address (no memo needed).
+pub async fn prepare(
+    pool: web::Data<SqlitePool>,
+    config: web::Data<Config>,
+    body: web::Json<PrepareRequest>,
+) -> HttpResponse {
+    let merchant = match crate::merchants::get_merchant_by_id(
+        pool.get_ref(), &body.merchant_id, &config.encryption_key
+    ).await {
+        Ok(Some(m)) => m,
+        _ => {
+            return HttpResponse::NotFound().json(serde_json::json!({
+                "error": "Merchant not found"
+            }));
+        }
+    };
+
+    match crate::sessions::create_session_request(
+        pool.get_ref(), &merchant.id, &merchant.ufvk
+    ).await {
+        Ok(req) => {
+            HttpResponse::Ok().json(serde_json::json!({
+                "session_request_id": req.id,
+                "deposit_address": req.deposit_address,
+                "merchant_id": merchant.id,
+                "min_deposit_zatoshis": 10_000,
+                "expires_in_seconds": 1800,
+            }))
+        }
+        Err(e) => {
+            tracing::error!(error = %e, "Failed to prepare session");
+            HttpResponse::InternalServerError().json(serde_json::json!({
+                "error": "Failed to prepare session deposit"
+            }))
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+pub struct PrepareRequest {
+    pub merchant_id: String,
+}
+
+/// Deduct a variable amount from a session (for streaming metering).
+pub async fn deduct(
+    req: HttpRequest,
+    pool: web::Data<SqlitePool>,
+    body: web::Json<DeductRequest>,
+) -> HttpResponse {
+    let token = req.headers().get("Authorization")
+        .and_then(|v| v.to_str().ok())
+        .and_then(|s| s.strip_prefix("Bearer "))
+        .map(|s| s.trim().to_string())
+        .filter(|s| s.starts_with("cps_"));
+
+    let token = match token {
+        Some(t) => t,
+        None => {
+            return HttpResponse::BadRequest().json(serde_json::json!({
+                "error": "Bearer token required"
+            }));
+        }
+    };
+
+    if body.amount_zatoshis <= 0 {
+        return HttpResponse::BadRequest().json(serde_json::json!({
+            "error": "amount_zatoshis must be positive"
+        }));
+    }
+
+    match crate::sessions::deduct(pool.get_ref(), &token, body.amount_zatoshis).await {
+        Ok(Some(session)) => {
+            HttpResponse::Ok()
+                .insert_header(("X-Session-Balance", session.balance_remaining.to_string()))
+                .json(serde_json::json!({
+                    "valid": true,
+                    "session_id": session.id,
+                    "balance_remaining": session.balance_remaining,
+                    "deducted": body.amount_zatoshis,
+                }))
+        }
+        Ok(None) => {
+            HttpResponse::Ok().json(serde_json::json!({
+                "valid": false,
+                "reason": "Insufficient balance, session expired, or depleted"
+            }))
+        }
+        Err(e) => {
+            tracing::error!(error = %e, "Session deduction error");
+            HttpResponse::InternalServerError().json(serde_json::json!({
+                "error": "Internal error"
+            }))
+        }
+    }
+}
+
+#[derive(Debug, Deserialize)]
+pub struct DeductRequest {
+    pub amount_zatoshis: i64,
+}
+
 pub async fn validate(
     req: HttpRequest,
     pool: web::Data<SqlitePool>,
diff --git a/src/db.rs b/src/db.rs
@@ -668,6 +668,25 @@ pub async fn create_pool(database_url: &str) -> anyhow::Result<SqlitePool> {
     sqlx::query("CREATE INDEX IF NOT EXISTS idx_agent_sessions_merchant ON agent_sessions(merchant_id, status)")
         .execute(&pool).await.ok();
 
+    // Session deposit requests (address-based, memo-free session opening)
+    sqlx::query(
+        "CREATE TABLE IF NOT EXISTS session_requests (
+            id TEXT PRIMARY KEY,
+            merchant_id TEXT NOT NULL REFERENCES merchants(id),
+            deposit_address TEXT NOT NULL,
+            diversifier_index INTEGER NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'used', 'expired')),
+            expires_at TEXT NOT NULL,
+            created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+        )"
+    )
+    .execute(&pool)
+    .await
+    .ok();
+
+    sqlx::query("CREATE INDEX IF NOT EXISTS idx_session_requests_merchant ON session_requests(merchant_id, status)")
+        .execute(&pool).await.ok();
+
     // Price type columns (one_time vs recurring)
     for sql in &[
         "ALTER TABLE prices ADD COLUMN price_type TEXT NOT NULL DEFAULT 'one_time'",
@@ -931,6 +950,11 @@ pub async fn run_data_purge(pool: &SqlitePool, purge_days: i64) -> anyhow::Resul
     ).bind(&cutoff).execute(pool).await
     .map(|r| r.rows_affected()).unwrap_or(0);
 
+    // Expired session deposit requests
+    let _ = sqlx::query(
+        "DELETE FROM session_requests WHERE expires_at < strftime('%Y-%m-%dT%H:%M:%SZ', 'now')"
+    ).execute(pool).await;
+
     // Expired dashboard login sessions
     let _ = sqlx::query(
         "DELETE FROM sessions WHERE expires_at < strftime('%Y-%m-%dT%H:%M:%SZ', 'now')"
diff --git a/src/sessions/mod.rs b/src/sessions/mod.rs
