Security (bank-level)
Controls aligned with patterns used by Stripe Dashboard and modern bank web apps. Everything listed here is live on the SDK portal BFF.
The portal is a BFF (tRPC) in front of the Perper API. Merchants never hold long-lived bearer tokens in JavaScript. Sessions, refresh cookies, and secret-reveal step-up tokens are issued only via Set-Cookie.
HttpOnly cookies + __Host- prefix
Production cookies use the browser `__Host-` prefix (Secure, Path=/, no Domain). Values are HttpOnly so XSS cannot exfiltrate tokens from document.cookie.
- `__Host-perper.session` — short access session (includes bearer for server-side API calls only).
- `__Host-perper.persistent` — 30-day refresh / PIN-challenge state.
- `__Host-perper.key` — ~5s secret-reveal step-up token (SameSite=Strict).
- `auth.session` returns public identity only (id, username, names, email) — never the bearer token.
Sliding session lifetime
Access session lasts 8 hours and slides on navigation / session poll (middleware + auth.session). Persistent cookie lasts 30 days. Logout clears all auth cookies including legacy names.
CSRF defense
Primary: SameSite=Lax cookies. Defense-in-depth: every tRPC mutation checks Origin/Referer against Host (and X-Forwarded-Host behind Contabo). Cross-site POSTs are rejected with FORBIDDEN.
Brute-force lockout
Login, PIN, and secret-key re-auth share a rate limiter: 5 failures inside 15 minutes lock that IP+subject for 15 minutes. Failed attempts also apply a short randomized delay (~180–400ms) to reduce timing oracles.
Anti-enumeration
Unknown username and wrong password return the same copy: “Invalid username or password.” Clients must not branch on exists vs mismatch.
Auth audit log
Structured JSON lines (`type: auth_audit`) are written to the process log for login/PIN/key success, failure, rate-limit, and logout. Subjects are truncated usernames/userIds — never passwords, PINs, or tokens.
HTTP security headers
Every response includes a bank baseline:
- Content-Security-Policy (self + required Next.js inline), frame-ancestors none, X-Frame-Options DENY
- Strict-Transport-Security (max-age=31536000; includeSubDomains), X-Content-Type-Options nosniff
- Referrer-Policy strict-origin-when-cross-origin, Permissions-Policy (camera/mic/geo/payment off)
- Cross-Origin-Opener-Policy same-origin, Cross-Origin-Resource-Policy same-site; authenticated routes send Cache-Control: no-store
Locale auth gate
Middleware protects `/app` (and `/en|cnr/app/...`) so English routes cannot bypass the merchant workspace. `/pay` is public; the page prompts sign-in before charging a Perper balance.
Hosted Pay hardening
Checkout uses the institutional white/red shell (same language as login). Amounts are sent to the API as decimal strings (`zodMoney`). Success and pay screens expose merchant/amount labels with a secure-checkout notice. Payments.
Project / webhook hygiene
Create-project validates apiUrl as public HTTPS (no localhost / RFC1918). UI is CG/EN localized; project tables show Active status chips; secrets are copyable with accessible buttons. Projects.
Accessibility & password managers
Copy controls are real buttons with aria-label and aria-live “Copied”. Login uses autocomplete=username / current-password; PIN uses one-time-code. Errors use role=alert and aria-invalid.
What merchants must still do
- Store the project secret only on your server (env / vault) — never in a mobile or web client bundle.
- Fulfill orders from the apiUrl callback, not only from the browser return URL.
- Use public HTTPS for apiUrl and resultUrl; keep TLS certificates valid.
- After a security upgrade, sign out once (or clear site cookies) so browsers pick up new `__Host-` cookie names.
- Verify redirect `hash` and apiUrl `hash` with HS256 JWT of the opaque `data` string using your project secret (see Webhooks docs). Webhooks.
Scope
These controls protect the SDK developer portal BFF. The Perper core ledger API has its own server-side controls. Rate limits are in-process today (single Contabo Node); multi-instance would require a shared store such as Redis. Payment callback verification lives under Webhooks. Authorised institutions reviewing Perper as a technology provider can use the ICT diligence pack at /partners/diligence.