paybondpaybond
Sign in

Operational surfaces

Admin console, compliance audit exports, disputes, reconciliation, and key-rotation tooling.

Operational surfaces

Paybond exposes several operational surfaces — the admin console, compliance audit exports, dispute workflows, Stripe reconciliation, and signal recovery — all gated by session auth and tenant scope.

This page summarizes them for platform implementers and integrators. The authoritative runbooks live under docs/operations/.

Admin console (apps/admin)

  • Next.js App Router. Browser code never talks to Harbor or Signal directly; every data load goes through a server route under /app/api/* that re-validates the session's tenant binding.
  • Session cookies (paybond_access, paybond_refresh) are httpOnly; silent refresh runs in middleware for /console/* routes except /console/login.
  • The marketing surface (apps/admin/app/page.tsx, mega-menu) is unauthenticated; it must not render tenant-scoped data.
  • In production, put the console behind Cloudflare on a dedicated hostname such as console.paybond.ai.

Compliance audit exports (V1-009)

  • Tenant-scoped ZIP bundles produced by the Gateway, signed with a dedicated manifest key. See Gateway API — audit exports and docs/operations/audit-export-compliance.md.
  • Each bundle includes a manifest.json anchored to the Harbor ledger tip at build time, so the auditor can verify bundle ↔ ledger correspondence.
  • Downloads use a dedicated JWT (aud = paybond-audit-export-download). The session Bearer is not accepted for bundle downloads.

Dispute workbench (V1-005)

  • Gateway-owned case rows under /v1/disputes/cases/*; timeline, evidence refs, internal notes.
  • Harbor transitions the intent to disputed (from funded or evidence_submitted) to freeze settlement.
  • Operators resolve through Harbor (release / refund) or record resolved_split / escalated_external outcomes.
  • An arbitration handoff JSON packet can be exported for external reviewers (rate-limited; honor Retry-After).

Stripe reconciliation

  • Gateway surfaces /v1/stripe/reconcile, /v1/stripe/webhook-health, /v1/stripe/webhook-failures for operators with tenant_admin or audited support.
  • When PAYBOND_SETTLEMENT_MODE=stripe_connect, set PAYBOND_HARBOR_RECOVERY_STRIPE_RECONCILE=1 to let the Harbor recovery tick call Stripe retrieve PaymentIntent for non-terminal rows and update stripe_last_status (no capture / cancel / refund).
  • Do not hand-edit Postgres or sled to "fix" a drifted intent; escalate with ledger excerpts and Stripe ids instead (see runbook §1).
  • Stripe webhooks should terminate at the public Gateway origin only; Harbor stays private on the service network.

Signal controlled rebuild

  • Indexer inserts are idempotent, so restarts never double-count.
  • Lowering the checkpoint alone does not re-apply counters.
  • Controlled rebuild for a single tenant (destructive): set PAYBOND_SIGNAL_ALLOW_DESTRUCTIVE_RESET=true and PAYBOND_SIGNAL_RESET_MODE=full_tenant_signal on the indexer; the tenant's Signal tables are truncated and the ledger is replayed from the beginning on the next startup.
  • Shared-SaaS pacing, lag budgets, and replay approval rules live in docs/operations/signal-shared-saas-guardrails-v1.md.

Secrets & key rotation

  • Session HMAC, Harbor ledger signing, Signal receipt/artifact keys, audit-export manifest key, and Stripe webhook secret are all managed out-of-band in encrypted provider-managed secret stores (for example Fly secrets and Supabase-managed credentials in production).
  • Rotation is additive: new keys come online, old keys remain in the verifier allow-list until their last-use window closes.
  • Runbook: docs/security/secrets-and-key-rotation-v1.md.

Backup and DR