Skip to content

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

  1. Store the project secret only on your server (env / vault) — never in a mobile or web client bundle.
  2. Fulfill orders from the apiUrl callback, not only from the browser return URL.
  3. Use public HTTPS for apiUrl and resultUrl; keep TLS certificates valid.
  4. After a security upgrade, sign out once (or clear site cookies) so browsers pick up new `__Host-` cookie names.
  5. 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.

ICT diligence pack (institutions)

Webhooks · Authentication · Errors · Changelog