feat(0.14.0): rate limits + approval-gated leases

Two related capabilities in one release.

Rate limits
- AppRoles gain three optional caps (per-minute/hour/day) settable via
  the UI or POST/PUT /v1/auth/approle. Per-secret minute caps come from
  metadata.rate_limit_per_minute. Both apply independently; the most
  restrictive wins.
- Fixed-window counters keyed on Math.floor(now/window_ms), in-memory.
  Hard ceilings 10K/min, 100K/hour, 1M/day.
- 429 with Retry-After when hit. Root tokens and user JWTs exempt.
- New audit actions: proxy.blocked.rate_limit.

Approval-gated leases (unified model)
- metadata.requires_approval=true gates a secret. Agents must call
  gatehouse_request_access(path, ttl, justification) and wait for a
  human approval before gatehouse_proxy or gatehouse_lease succeeds.
- The approved lease IS the access window. Revoke once, atomic kill.
  No second checkout lease; each value-reveal audits as lease.access
  against the approval lease_id.
- Status drives lifecycle: pending -> approved/denied/expired. revoked
  boolean stays orthogonal.
- Auto-approve via metadata.auto_approve_from_ip (CIDR list) plus
  optional auto_approve_ttl_seconds.
- Webhook on lease.request_created (GATEHOUSE_APPROVAL_WEBHOOK_URL).
  Optional HMAC-SHA256 signing over `${timestamp}.${body}` with
  X-Gatehouse-Timestamp and X-Gatehouse-Signature headers when
  GATEHOUSE_APPROVAL_WEBHOOK_SECRET is set; 5-minute replay window.
- AppRole delete clears that identity's pending leases.

Shared
- enforceProxyGates() helper consumed by REST proxy and MCP proxy so
  the three gates (AppRole rate limit, per-secret rate limit, approval)
  stay consistent across surfaces.
- AuthContext gains role_id (extracted from JWT payload in middleware).
- New MCP tool gatehouse_request_access; gatehouse_status now returns
  pending_leases.
- New SSE events lease_request_created and lease_status_changed,
  identity-scoped server-side.

UI
- Leases page: Active / Pending Approval tabs. Approve / Deny actions
  with justification preview. Sidebar pending badge updated via SSE.
- AppRole modals: three rate-limit inputs. List row gets a small
  rate-limited badge when any limit is set.
- Secrets tree: approval chip on gated secrets. Detail panel: banner
  + Active Approved Leases section.

Migration
- Schema-only. Six nullable columns on leases (status defaulting to
  'approved' so every existing row stays valid) and three on app_roles.
  New index idx_leases_pending.

Tests: 497 pass (up from 459). New: test/rateLimits.test.ts,
test/leaseApproval.test.ts, test/leaseWebhook.test.ts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bshandley

CHANGELOG.md

@@ -5,6 +5,36 @@ release notes (built from conventional-commit subjects between tags) carry the
 fine-grained per-commit log. This file summarises each release at a higher
 level.
 
+## [0.14.0] - 2026-05-12
+
+### Features
+
+- **Rate limits on proxy calls.** AppRoles gain three optional limits (per-minute, per-hour, per-day) settable from the UI or `POST/PUT /v1/auth/approle` body. Secrets accept a per-secret `metadata.rate_limit_per_minute`. Both apply independently; the most restrictive wins. Hitting either returns `429` with `Retry-After`. Root tokens and user JWTs are exempt. Counters are fixed-window and in-memory. Limit ceilings: 10K/min, 100K/hour, 1M/day.
+- **Approval-gated leases.** Mark a secret with `metadata.requires_approval=true` and agents must call `gatehouse_request_access(path, ttl, justification)` and wait for a human approval before `gatehouse_proxy` or `gatehouse_lease` will succeed. The approved lease IS the access window: revoking it kills access atomically. Status drives lifecycle (`pending` → `approved`/`denied`/`expired`). Auto-approve for trusted networks via `metadata.auto_approve_from_ip` (comma-separated CIDRs) plus optional `metadata.auto_approve_ttl_seconds`.
+- **Approval webhook.** Set `GATEHOUSE_APPROVAL_WEBHOOK_URL` to fire a POST on every `lease.request_created`. Payload includes `approve_url` and `ui_url` so the receiver can deep-link a Slack/Discord/PagerDuty bridge to the approval. Optional `GATEHOUSE_APPROVAL_WEBHOOK_SECRET` enables HMAC-SHA256 signing over `${timestamp}.${body}` with `X-Gatehouse-Timestamp` and `X-Gatehouse-Signature` headers (5-minute replay window). When unset, no signature headers (URL-secrecy mode).
+- **New MCP tool `gatehouse_request_access`.** Agents call this to ask for approval. `gatehouse_status` now returns `pending_leases` so agents can poll for status changes.
+- **UI: Leases page redesigned.** Tabs for Active and Pending Approval. Approve/Deny actions with justification preview. Sidebar Leases nav gains a pending-count badge driven by SSE. AppRole modals gain a Rate Limits group. Approval-gated secrets get a `🔒 approval` chip in the tree and a banner in the detail panel.
+- **SSE: `lease_request_created` and `lease_status_changed` events.** Live-update the pending tab and the sidebar badge without polling. Identity-scoped server-side (non-admins only see events for leases they own).
+
+### New metadata keys
+
+- `requires_approval` (`"true"` to gate the secret)
+- `auto_approve_from_ip` (comma-separated CIDRs)
+- `auto_approve_ttl_seconds` (default 300)
+- `rate_limit_per_minute` (positive integer; per-secret cap)
+
+### New AppRole columns
+
+- `rate_limit_per_minute`, `rate_limit_per_hour`, `rate_limit_per_day` (all nullable; NULL means no limit)
+
+### New audit actions
+
+`lease.request_created`, `lease.approved`, `lease.denied`, `lease.request_expired`, `lease.auto_approved`, `lease.access`, `proxy.blocked.rate_limit`, `proxy.blocked.approval`.
+
+### Migration
+
+Schema-only; safe on a live v0.13.2 database. Six nullable columns added to `leases` (with `status` defaulting to `'approved'` so every existing row stays valid) and three nullable columns to `app_roles`. New index `idx_leases_pending`. Existing proxy and lease behaviour is unchanged for secrets without the new metadata.
+
 ## [0.13.2] - 2026-05-10
 
 ### Documentation

README.md

@@ -27,6 +27,8 @@ For everything else (leasing, dynamic secrets, SSH certificates, audit logging)
 - **Key rotation.** Rotate the master key and re-wrap all DEKs in one API call, zero downtime.
 - **Web UI.** Dark-themed control panel with command palette (Cmd/Ctrl+K) for managing secrets, leases, agents, patterns, and audit logs.
 - **SSO.** Optional OpenID Connect single sign-on for human admins. Works with PocketID, Authentik, Keycloak, Google, and any other OIDC provider. Strict link-by-verified-email account model; configure once in Settings.
+- **Rate limits.** Per-AppRole (minute/hour/day) and per-secret (minute) on proxy traffic. Bound damage from a runaway agent or an expensive upstream. 429 with `Retry-After` when hit; root and user JWTs exempt.
+- **Approval-gated leases.** Mark a secret `requires_approval=true` and agents must call `gatehouse_request_access` and wait for a human. The approved lease IS the access window: revoke once, atomic kill. Optional signed webhook (HMAC + timestamp) for Slack/Discord/paging bridges. Trusted networks can auto-approve via CIDR allowlist.
 - **Homelab-first.** Single Docker container. Runs on a Raspberry Pi, Proxmox LXC, or Jetson Orin Nano. AGPL-3.0.
 
 ## Screenshots

src/api/auth.ts

@@ -7,6 +7,8 @@ import { safeEqual } from "../auth/middleware";
 import { verifyTotp, verifyRecoveryCode } from "../auth/totp";
 import { ipMatchesAllowlist, validateCIDRs } from "../auth/cidr";
 import { generateLoginParams, buildAuthUrl, exchangeAndVerify, fetchUserinfo } from "../auth/oidc";
+import { validateAppRoleLimits } from "../rateLimits/rateLimitValidation";
+import type { LeaseManager } from "../lease/manager";
 
 // Simple in-memory rate limiter: 5 failed attempts per IP per 60s window
 const failedAttempts = new Map<string, { count: number; resetAt: number }>();
@@ -55,7 +57,7 @@ function recordFailure(ip: string) {
   }
 }
 
-export function authRouter(db: Database, config: GatehouseConfig, audit: AuditLog) {
+export function authRouter(db: Database, config: GatehouseConfig, audit: AuditLog, leases?: LeaseManager) {
   const router = new Hono();
   const secret = new TextEncoder().encode(config.jwtSecret);
 
@@ -616,7 +618,7 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
     }
 
     const roles = db
-      .query("SELECT role_id, display_name, policies, suspended, created_at, last_used, ip_allowlist FROM app_roles ORDER BY created_at DESC")
+      .query("SELECT role_id, display_name, policies, suspended, created_at, last_used, ip_allowlist, rate_limit_per_minute, rate_limit_per_hour, rate_limit_per_day FROM app_roles ORDER BY created_at DESC")
       .all() as any[];
 
     return c.json({
@@ -628,6 +630,9 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
         created_at: r.created_at,
         last_used: r.last_used,
         ip_allowlist: r.ip_allowlist ? JSON.parse(r.ip_allowlist) : [],
+        rate_limit_per_minute: r.rate_limit_per_minute,
+        rate_limit_per_hour: r.rate_limit_per_hour,
+        rate_limit_per_day: r.rate_limit_per_day,
       })),
     });
   });
@@ -644,7 +649,14 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
       return c.json({ error: "AppRole not found", request_id: c.get("requestId") }, 404);
     }
 
-    let body: { display_name?: string; policies?: string[]; ip_allowlist?: string[] };
+    let body: {
+      display_name?: string;
+      policies?: string[];
+      ip_allowlist?: string[];
+      rate_limit_per_minute?: unknown;
+      rate_limit_per_hour?: unknown;
+      rate_limit_per_day?: unknown;
+    };
     try {
       body = await c.req.json();
     } catch {
@@ -672,19 +684,55 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
       allowlistJson = cleaned.length > 0 ? JSON.stringify(cleaned) : null;
     }
 
-    if (allowlistJson !== undefined) {
+    // Rate limits: only update if any field was provided. Missing-field semantics
+    // are "leave unchanged"; explicit null sets the column to NULL (no limit).
+    const hasLimitFields =
+      body.rate_limit_per_minute !== undefined ||
+      body.rate_limit_per_hour !== undefined ||
+      body.rate_limit_per_day !== undefined;
+    let limits: { per_minute: number | null; per_hour: number | null; per_day: number | null } | undefined;
+    if (hasLimitFields) {
+      const v = validateAppRoleLimits({
+        rate_limit_per_minute: body.rate_limit_per_minute,
+        rate_limit_per_hour: body.rate_limit_per_hour,
+        rate_limit_per_day: body.rate_limit_per_day,
+      });
+      if (!v.ok) {
+        return c.json({ error: v.error, request_id: c.get("requestId") }, 400);
+      }
+      limits = v.limits;
+    }
+
+    if (allowlistJson !== undefined && limits) {
+      db.query(
+        "UPDATE app_roles SET display_name = ?, policies = ?, ip_allowlist = ?, rate_limit_per_minute = ?, rate_limit_per_hour = ?, rate_limit_per_day = ? WHERE role_id = ?"
+      ).run(displayName, JSON.stringify(policies), allowlistJson, limits.per_minute, limits.per_hour, limits.per_day, roleId);
+    } else if (allowlistJson !== undefined) {
       db.query("UPDATE app_roles SET display_name = ?, policies = ?, ip_allowlist = ? WHERE role_id = ?")
         .run(displayName, JSON.stringify(policies), allowlistJson, roleId);
+    } else if (limits) {
+      db.query(
+        "UPDATE app_roles SET display_name = ?, policies = ?, rate_limit_per_minute = ?, rate_limit_per_hour = ?, rate_limit_per_day = ? WHERE role_id = ?"
+      ).run(displayName, JSON.stringify(policies), limits.per_minute, limits.per_hour, limits.per_day, roleId);
     } else {
       db.query("UPDATE app_roles SET display_name = ?, policies = ? WHERE role_id = ?")
         .run(displayName, JSON.stringify(policies), roleId);
     }
 
+    const updated = db
+      .query(
+        "SELECT rate_limit_per_minute, rate_limit_per_hour, rate_limit_per_day FROM app_roles WHERE role_id = ?"
+      )
+      .get(roleId) as any;
+
     return c.json({
       role_id: roleId,
       display_name: displayName,
       policies,
       ip_allowlist: allowlistJson ? JSON.parse(allowlistJson) : [],
+      rate_limit_per_minute: updated?.rate_limit_per_minute ?? null,
+      rate_limit_per_hour: updated?.rate_limit_per_hour ?? null,
+      rate_limit_per_day: updated?.rate_limit_per_day ?? null,
     });
   });
 
@@ -725,11 +773,20 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
     }
 
     const roleId = c.req.param("roleId");
-    const role = db.query("SELECT role_id FROM app_roles WHERE role_id = ?").get(roleId);
+    const role = db.query("SELECT role_id, display_name FROM app_roles WHERE role_id = ?").get(roleId) as { role_id: string; display_name: string } | null;
     if (!role) {
       return c.json({ error: "AppRole not found", request_id: c.get("requestId") }, 404);
     }
 
+    // Cancel any pending lease requests this AppRole has in flight so they
+    // don't haunt the approval queue after the role is gone. Approved leases
+    // are left alone (they keep their existing revoked-or-expiring lifecycle
+    // and stay visible in audit).
+    if (leases) {
+      const identity = `approle:${role.display_name}`;
+      leases.deletePendingForIdentity(identity);
+    }
+
     db.query("DELETE FROM app_roles WHERE role_id = ?").run(roleId);
     return c.json({ deleted: true });
   });
@@ -1066,7 +1123,14 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
       return c.json({ error: "Admin access required", request_id: c.get("requestId") }, 403);
     }
 
-    let body: { display_name: string; policies: string[]; ip_allowlist?: string[] };
+    let body: {
+      display_name: string;
+      policies: string[];
+      ip_allowlist?: string[];
+      rate_limit_per_minute?: unknown;
+      rate_limit_per_hour?: unknown;
+      rate_limit_per_day?: unknown;
+    };
     try {
       body = await c.req.json();
     } catch {
@@ -1093,13 +1157,31 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
       allowlistJson = cleaned.length > 0 ? JSON.stringify(cleaned) : null;
     }
 
+    const limitsResult = validateAppRoleLimits({
+      rate_limit_per_minute: body.rate_limit_per_minute,
+      rate_limit_per_hour: body.rate_limit_per_hour,
+      rate_limit_per_day: body.rate_limit_per_day,
+    });
+    if (!limitsResult.ok) {
+      return c.json({ error: limitsResult.error, request_id: c.get("requestId") }, 400);
+    }
+
     const role_id = `role-${crypto.randomUUID()}`;
     const secret_id = crypto.randomUUID();
     const secret_hash = await Bun.password.hash(secret_id);
 
     db.query(
-      "INSERT INTO app_roles (role_id, secret_hash, display_name, policies, ip_allowlist) VALUES (?, ?, ?, ?, ?)"
-    ).run(role_id, secret_hash, display_name, JSON.stringify(policies), allowlistJson);
+      "INSERT INTO app_roles (role_id, secret_hash, display_name, policies, ip_allowlist, rate_limit_per_minute, rate_limit_per_hour, rate_limit_per_day) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+    ).run(
+      role_id,
+      secret_hash,
+      display_name,
+      JSON.stringify(policies),
+      allowlistJson,
+      limitsResult.limits.per_minute,
+      limitsResult.limits.per_hour,
+      limitsResult.limits.per_day
+    );
 
     return c.json(
       {
@@ -1108,6 +1190,9 @@ h1{font-size:18px;margin:0 0 12px}p{color:#9ca3af;margin:0 0 24px}a{color:#6c63f
         display_name,
         policies,
         ip_allowlist: allowlistJson ? JSON.parse(allowlistJson) : [],
+        rate_limit_per_minute: limitsResult.limits.per_minute,
+        rate_limit_per_hour: limitsResult.limits.per_hour,
+        rate_limit_per_day: limitsResult.limits.per_day,
         warning: "Save the secret_id now, it cannot be retrieved later",
       },
       201