feat: subscription transparency + /security page

Five related changes, all driven by the same goal: make paying customers
see exactly what they're paying for, and make our privacy story honest
enough to hold up against a line-by-line audit.

### Past-due grace countdown (backend + frontend)

`GET /api/nodes/plan` now returns `grace_days_remaining`,
`grace_expires_at`, and `grace_window_days`. The dashboard past-due
banner renders a live "N days left" countdown while in grace and flips
to a deeper-red "Grace period expired" variant once caps tighten.
Previously the ToS promised 7 days but the UI was silent — the first
signal a user got was cameras going dark.

Banner picks up `role="status"` + `aria-live="polite"` so screen
readers announce state changes.

### subscription.updated clears past-due on a paid plan

If a customer upgraded to fix a past-due state, `effective_plan_for_caps`
kept returning "free_org" until the next paymentAttempt.updated webhook
trickled in — their newly-paid plan stayed capped at free-tier limits
for as long as Clerk took to re-deliver. Now any subscription.* event
landing on pro/business clears `payment_past_due` + `payment_past_due_at`
immediately (Clerk wouldn't mark the subscription active without the
card having gone through).

### Custom 429 handler

Replaces slowapi's bare `{"detail": "429 ..."}` with a structured body
(`error`, `message`, `limit`, `retry_after_seconds`) and a proper
`Retry-After: 60` header. Off-the-shelf HTTP clients now back off
correctly without special-casing.

### /docs#api-rate-limits

New sidebar entry + full section documenting every REST rate limit,
MCP per-key budgets, SSE subscriber caps, payload caps, and pagination
bounds. Also fixes the outdated "429 MCP only" claim in the Error
Format subsection — 429 applies to REST routes too, now with docs.

### /security page

New public page at `/security` (linked from the footer) covering the
privacy architecture: what lives on-device vs in cloud, AES-256-GCM
encryption posture (now including recordings — see the paired CloudNode
commit), motion detection running locally via FFmpeg scene-change
(not any cloud ML service), third-party list, law-enforcement policy,
and the deletion cascade. Every claim cites the implementing file so
"open source you can verify" isn't just marketing.

All 226 backend tests pass; frontend builds clean.

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

Author: Sbussiso

backend/app/api/nodes.py

@@ -11,6 +11,7 @@
 from app.core.auth import AuthUser, require_admin, require_active_billing, get_current_user
 from app.core.limiter import limiter
 from app.core.plans import (
+    PAYMENT_GRACE_DAYS,
     enforce_camera_cap,
     get_plan_limits,
     get_plan_limits_for_org,
@@ -506,13 +507,43 @@ async def get_plan_info(
     user: AuthUser = Depends(get_current_user),
     db: Session = Depends(get_db),
 ):
-    """Return the org's current plan, usage, and limits."""
+    """Return the org's current plan, usage, limits, and (when past-due) the
+    remaining grace window. The countdown lets the dashboard show a clear
+    "X days until suspension" banner instead of the static "7 days" copy the
+    ToS guarantees but operators can't see live.
+    """
     from app.models.models import Setting
+    from datetime import datetime, timedelta, timezone
 
     limits = get_plan_limits(user.plan)
     current_nodes = db.query(CameraNode).filter_by(org_id=user.org_id).count()
     current_cameras = db.query(Camera).filter_by(org_id=user.org_id).count()
     payment_past_due = Setting.get(db, user.org_id, "payment_past_due", "false") == "true"
+
+    # Compute grace window when past-due. The ToS promises PAYMENT_GRACE_DAYS
+    # from payment_past_due_at; after that, effective_plan_for_caps tightens
+    # everyone to free_org. We expose the remaining days + expiry timestamp
+    # so the dashboard banner can warn users before it bites.
+    grace_days_remaining: int | None = None
+    grace_expires_at: str | None = None
+    if payment_past_due:
+        past_due_at_str = Setting.get(db, user.org_id, "payment_past_due_at", "")
+        if past_due_at_str:
+            try:
+                past_due_at = datetime.fromisoformat(past_due_at_str.replace("Z", "+00:00"))
+                if past_due_at.tzinfo is None:
+                    past_due_at = past_due_at.replace(tzinfo=timezone.utc)
+                expires_at = past_due_at + timedelta(days=PAYMENT_GRACE_DAYS)
+                remaining = expires_at - datetime.now(tz=timezone.utc)
+                # Negative remaining means grace already expired — surface as
+                # 0 so the UI shows "suspended" rather than a negative number.
+                grace_days_remaining = max(0, remaining.days)
+                grace_expires_at = expires_at.isoformat()
+            except (ValueError, TypeError):
+                # Unparseable timestamp — leave fields None, same posture as
+                # effective_plan_for_caps (keep nominal plan until resolved).
+                pass
+
     return {
         "plan": user.plan,
         "plan_name": get_plan_display_name(user.plan),
@@ -523,6 +554,9 @@ async def get_plan_info(
             "cameras": current_cameras,
         },
         "payment_past_due": payment_past_due,
+        "grace_days_remaining": grace_days_remaining,
+        "grace_expires_at": grace_expires_at,
+        "grace_window_days": PAYMENT_GRACE_DAYS,
     }
 
 

backend/app/api/webhooks.py

@@ -21,6 +21,12 @@
     "business": 20,
 }
 
+# Paid plan slugs. Seeing a subscription.updated with one of these means the
+# payment card is active (Clerk wouldn't mark the subscription live otherwise),
+# so we can clear any past-due flag we were holding. Kept local to this module
+# rather than imported from plans.py to keep webhook semantics self-contained.
+PAID_PLAN_SLUGS_WEBHOOK = frozenset({"pro", "business"})
+
 
 def set_org_member_limit(org_id: str, limit: int):
     """Update the Clerk org's max allowed memberships."""
@@ -70,6 +76,17 @@ async def clerk_webhook(request: Request, db: Session = Depends(get_db)):
             set_org_member_limit(org_id, limit)
             # Persist plan in DB so API-key-authenticated endpoints can look it up
             Setting.set(db, org_id, "org_plan", plan_slug)
+            # If the subscription is now on a paid plan, clear any lingering
+            # past-due flag. Clerk only emits subscription.active/updated once
+            # the payment has actually gone through, so seeing this event with
+            # a paid plan means the card is good again — the org should get
+            # their paid caps back immediately, not after the next
+            # paymentAttempt.updated trickles in. Without this clear, an org
+            # that upgrades *during* the grace window stays capped at free
+            # because effective_plan_for_caps still sees past_due=true.
+            if plan_slug in PAID_PLAN_SLUGS_WEBHOOK:
+                Setting.set(db, org_id, "payment_past_due", "false")
+                Setting.set(db, org_id, "payment_past_due_at", "")
             # Re-evaluate camera cap — a plan change (up or down) may flip
             # rows in either direction. Flushing the Setting first ensures
             # `resolve_org_plan` inside enforce_camera_cap reads the new value.

backend/app/main.py

@@ -9,9 +9,9 @@
 from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse
-from slowapi import _rate_limit_exceeded_handler
 from slowapi.errors import RateLimitExceeded
 from slowapi.middleware import SlowAPIMiddleware
+from fastapi.responses import JSONResponse
 from app.core.config import settings
 from app.core.database import Base, engine, SessionLocal
 from app.core.limiter import limiter
@@ -70,7 +70,37 @@ async def lifespan(app):
 )
 
 app.state.limiter = limiter
-app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+
+async def rate_limit_exceeded_handler(request: Request, exc: RateLimitExceeded) -> JSONResponse:
+    """Custom 429 response — gives the client everything it needs to retry.
+
+    The slowapi default emits a bare `{"detail": "429 ..."}` string with no
+    Retry-After header, which leaves integrators guessing at the backoff
+    window and which limit they hit. We return:
+      - a stable JSON shape matching the rest of the API's error envelope
+      - the exact limit string (e.g. "60 per 1 minute") so callers know what
+        bucket they tripped
+      - a `Retry-After: 60` header, per RFC 9110, so off-the-shelf HTTP
+        clients back off without special handling
+    60s is a safe upper bound because our tightest rate windows are minute-
+    scoped; callers that honour Retry-After will idle through the window and
+    succeed on the next attempt.
+    """
+    limit_str = str(exc.detail) if getattr(exc, "detail", None) else "rate limit exceeded"
+    body = {
+        "error": "rate_limit_exceeded",
+        "message": (
+            "Too many requests. Back off and retry after the Retry-After window. "
+            "See /docs#api-rate-limits for per-route limits."
+        ),
+        "limit": limit_str,
+        "retry_after_seconds": 60,
+    }
+    return JSONResponse(status_code=429, content=body, headers={"Retry-After": "60"})
+
+
+app.add_exception_handler(RateLimitExceeded, rate_limit_exceeded_handler)
 app.add_middleware(SlowAPIMiddleware)
 
 # Get frontend URL from environment (set in fly.toml or .env)

frontend/src/App.jsx

@@ -18,6 +18,7 @@ const PricingPage = lazy(() => import("./pages/PricingPage.jsx"))
 const McpPage = lazy(() => import("./pages/McpPage.jsx"))
 const SentinelPage = lazy(() => import("./pages/SentinelPage.jsx"))
 const LegalPage = lazy(() => import("./pages/LegalPage.jsx"))
+const SecurityPage = lazy(() => import("./pages/SecurityPage.jsx"))
 
 function RequireOrg({ children }) {
   const { organization, isLoaded } = useOrganization()
@@ -98,6 +99,7 @@ function App() {
           <Route path="/pricing" element={<PricingPage />} />
           <Route path="/sentinel" element={<SentinelPage />} />
           <Route path="/legal/:page" element={<LegalPage />} />
+          <Route path="/security" element={<SecurityPage />} />
         </Route>
 
         {/* Auth routes (public but use Clerk components) */}

frontend/src/components/LandingFooter.jsx

@@ -38,6 +38,7 @@ function LandingFooter() {
 
             <div className="landing-footer-col">
               <h5>Legal</h5>
+              <Link to="/security">Security</Link>
               <Link to="/legal/terms">Terms of Service</Link>
               <Link to="/legal/privacy">Privacy Policy</Link>
               <a href="https://github.com/SourceBox-LLC/OpenSentry-Command/blob/master/LICENSE" target="_blank" rel="noopener noreferrer">

frontend/src/index.css

@@ -1401,6 +1401,120 @@ body {
     text-decoration: underline;
 }
 
+.payment-past-due-banner.payment-past-due-expired {
+    background: rgba(220, 38, 38, 0.18);
+    border-color: rgba(220, 38, 38, 0.55);
+    color: #fecaca;
+}
+
+/* Security Page */
+.security-page {
+    min-height: 100vh;
+    color: var(--text-primary);
+}
+
+.security-hero {
+    padding: 4rem 1.5rem 2.5rem;
+    text-align: center;
+    background: linear-gradient(180deg, rgba(59, 130, 246, 0.08), transparent);
+    border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+}
+
+.security-title {
+    font-size: clamp(1.875rem, 4vw, 2.75rem);
+    margin: 0 0 0.75rem;
+    line-height: 1.15;
+    letter-spacing: -0.02em;
+}
+
+.security-subtitle {
+    max-width: 42rem;
+    margin: 0 auto;
+    color: var(--text-secondary);
+    font-size: 1.05rem;
+    line-height: 1.55;
+}
+
+.security-body {
+    max-width: 880px;
+    padding: 2.5rem 1.5rem 5rem;
+}
+
+.security-section {
+    margin-bottom: 3rem;
+}
+
+.security-section h2 {
+    font-size: 1.5rem;
+    margin-bottom: 1rem;
+    padding-bottom: 0.5rem;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+.security-section h3 {
+    font-size: 1.05rem;
+    margin-top: 1.5rem;
+    margin-bottom: 0.5rem;
+    color: var(--text-primary);
+}
+
+.security-section p {
+    color: var(--text-secondary);
+    line-height: 1.65;
+    margin-bottom: 1rem;
+}
+
+.security-section code {
+    background: rgba(255, 255, 255, 0.06);
+    padding: 0.1rem 0.35rem;
+    border-radius: 4px;
+    font-size: 0.9em;
+}
+
+.security-bullets {
+    list-style: disc;
+    padding-left: 1.25rem;
+    color: var(--text-secondary);
+    line-height: 1.65;
+}
+
+.security-bullets li {
+    margin-bottom: 0.6rem;
+}
+
+.security-bullets li strong {
+    color: var(--text-primary);
+}
+
+.security-dataflow {
+    overflow-x: auto;
+    margin: 1rem 0 1.5rem;
+}
+
+.security-dataflow table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.9rem;
+}
+
+.security-dataflow th,
+.security-dataflow td {
+    padding: 0.65rem 0.75rem;
+    text-align: left;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+    vertical-align: top;
+}
+
+.security-dataflow th {
+    color: var(--text-primary);
+    font-weight: 600;
+    border-bottom-color: rgba(255, 255, 255, 0.15);
+}
+
+.security-dataflow td {
+    color: var(--text-secondary);
+}
+
 /* Legal Pages */
 .legal-container {
     max-width: 800px;

frontend/src/pages/DashboardPage.jsx

@@ -149,18 +149,52 @@ function DashboardPage() {
     <div className="dashboard-container">
       <HeartbeatBanner />
 
-      {isAdmin && planInfo?.payment_past_due && (
-        <div className="payment-past-due-banner">
-          <span>
-            Your payment is past due. Cameras beyond your free-tier limit will be
-            suspended after a 7-day grace period — update your payment method to
-            keep streaming.
-          </span>
-          <Link to="/pricing" className="btn btn-primary btn-small">
-            Manage Billing
-          </Link>
-        </div>
-      )}
+      {isAdmin && planInfo?.payment_past_due && (() => {
+        // Grace countdown: backend returns grace_days_remaining + grace_expires_at.
+        // When the timestamp parses cleanly we show the live number; otherwise
+        // fall back to the ToS-guaranteed window (grace_window_days) so the
+        // copy still reads correctly for older backends that haven't shipped
+        // the countdown fields yet.
+        const daysLeft = planInfo.grace_days_remaining
+        const windowDays = planInfo.grace_window_days ?? 7
+        let copy
+        if (daysLeft === 0) {
+          copy = (
+            <>
+              <strong>Grace period expired.</strong> Cameras beyond the free-tier
+              limit are now suspended. Update your payment method to restore them.
+            </>
+          )
+        } else if (typeof daysLeft === "number") {
+          copy = (
+            <>
+              <strong>Payment past due — {daysLeft} day{daysLeft === 1 ? "" : "s"} left.</strong>
+              {" "}After that, cameras beyond the free-tier limit will be suspended.
+              Update your payment method now to avoid interruption.
+            </>
+          )
+        } else {
+          copy = (
+            <>
+              Your payment is past due. Cameras beyond your free-tier limit will be
+              suspended after a {windowDays}-day grace period — update your payment method to
+              keep streaming.
+            </>
+          )
+        }
+        return (
+          <div
+            className={`payment-past-due-banner${daysLeft === 0 ? " payment-past-due-expired" : ""}`}
+            role="status"
+            aria-live="polite"
+          >
+            <span>{copy}</span>
+            <Link to="/pricing" className="btn btn-primary btn-small">
+              Manage Billing
+            </Link>
+          </div>
+        )
+      })()}
 
       {planInfo && planInfo.features?.includes("admin") && (
         <div className={`pro-status-bar pro-status-${planInfo.plan}`}>