Skip to content

Security: Hennit-Dave/rota

Security

docs/SECURITY.md

Security

The brief's eight-threat list (Requirement 4), each with its mitigation and where it is tested or proven. All eight are complete; the sections linked below have the full write-up, and "Proving tests" under each names the exact test files.

# Threat Mitigation, in short Proven in
1 Staff calling Manager-only endpoints directly One permission table (server/src/teams/permissions.ts), role read from the database on every request, never from the token Threat 1: shifts.integration.test.ts ("THE BRIEF": delete-shift as Staff is 403, nothing deleted), team-security.integration.test.ts, permissions.unit.test.ts
2 Reading another team's data by changing an ID Team ID only from the validated route param; membership checked on that team's own shard; unknown team and someone else's team both answer identical 404 Threat 2: team-security.integration.test.ts ("TEAM ISOLATION", two users on different shards), shifts.integration.test.ts
3 A stolen access token 15-minute token carries no role or team; every authenticated request re-checks the session on shard A's primary, so logout stops it on the very next request Threat 3: session-check.integration.test.ts, tokens.unit.test.ts, middleware.unit.test.ts
4 A stolen refresh token, and reuse Rotation on every use; presenting an already-used token revokes the whole family before the 401 is sent Threat 4: refresh.integration.test.ts (rotation, reuse), concurrency.slow.test.ts (concurrent refresh and revocation race, 15 repeats), logout.integration.test.ts
5 Credential stuffing and brute-force login Fixed-window rate limits in Valkey (never in memory) on login, register and refresh, by IP and by email; Argon2id, a dummy hash on unknown emails so timing doesn't reveal accounts Rate limiting and Passwords: ratelimit unit tests, recovery.integration.test.ts
6 Secrets extracted from the app bundle One EXPO_PUBLIC_ variable exists and it is not a secret (table below); every other secret is a server env var only Threat 6: app/src/publicEnv.test.ts (allowlist), app/src/api/config.test.ts. Still pending: the bundle search itself (unzip the APK, search for sk_, secret, password, _KEY) runs on the first preview (release) build and is recorded then — not yet done
7 Theft or reuse of an invitation link Single use, hashed, 7-day expiry, tied to one email address (or Staff-only and un-addressed for a bearer link); one identical 404 for every unusable link Threat 7: invites.integration.test.ts, invite-links.integration.test.ts
8 Theft, reuse, enumeration and takeover of reset and magic-link tokens Single use, hashed, short expiry, constant-time no-enumeration answer, a redeemed magic link on an unverified address clears the password and revokes every session Threat 8: recovery.integration.test.ts, recovery.unit.test.ts

Stripe webhook forgery/replay and the deploy credential model are real security controls too, but not part of this numbered list — see "Stripe webhook signature verification" and "Deploy-provider credentials" below.

Permissions: the one table (threat 1)

One module, server/src/teams/permissions.ts, decides every permission; this table mirrors it and permissions.unit.test.ts checks the two against a hand-written copy. Anything not in the table is refused. Rows without a route yet are for later slices.

Action Owner Manager Staff Route today
team.view, members.list yes yes yes GET /teams/:teamId, GET /teams/:teamId/members
shifts.view yes yes yes GET /teams/:teamId/shifts, GET /teams/:teamId/shifts/:shiftId, GET /teams/:teamId/activity
shifts.edit yes yes no POST /teams/:teamId/shifts, PATCH and DELETE /teams/:teamId/shifts/:shiftId
swaps.request yes yes yes GET and POST /teams/:teamId/swaps, GET /teams/:teamId/swaps/:swapId, POST …/:swapId/cancel (the requester only)
swaps.approve yes yes no POST /teams/:teamId/swaps/:swapId/approve and /reject (never by a person who is part of the swap, except an Owner who is the only approver)
preferences.edit (own) yes yes yes later
invite.staff yes yes no later
invite.manager yes no no later
billing.manage yes no no later

Nobody is invited as Owner, and the database allows only one Owner per team (partial unique index).

Threat 1: Staff calling Manager-only endpoints directly

What it is. A Staff member skips the app and calls an Owner/Manager endpoint (a shift delete, an invite, billing) with their own valid token.

How it is handled.

  • The app hides buttons, but the server decides. Every team route runs requireTeamRole(action) after the token and session check.
  • The role is read from the database on every request (the team shard's primary), never from the token, which carries no role. A demotion applies to the very next request.
  • A member whose role may not do the action gets 403 forbidden; the real reason (role_staff_cannot_shifts.edit) is in the server log only.

The brief's test. "Staff calls delete-shift and is rejected": DELETE /teams/:teamId/shifts/:shiftId with a Staff token answers 403 forbidden, and the shift and its history row are still there afterwards (shifts.integration.test.ts, "THE BRIEF"). Staff may view the schedule but every write (create, edit, delete) is refused with nothing written. Swaps (slice S1). A Staff member who calls approve or reject directly, as the requester or the other person or anyone else, gets 403 and the request, both shifts and the feed are untouched (swaps.integration.test.ts, "THE SECURITY TEST"). A person who is part of a swap cannot decide it ("A PARTY CANNOT DECIDE THEIR OWN SWAP"; rules.unit.test.ts). What remains. billing.manage and the settings routes get their routes in later slices on the same middleware.

Proving tests. shifts.integration.test.ts: "THE BRIEF", "a Staff member can view the schedule but cannot publish or change a shift", "ROLE FROM THE SERVER" (a demoted Manager is refused on the next request with the same token). team-security.integration.test.ts: "ROLE ENFORCEMENT" (Staff 403, Manager and Owner 200, Staff still allowed to view), "ROLE FROM THE SERVER, NOT THE TOKEN" (demote a Manager, the same token gets 403). permissions.unit.test.ts: the table. The test route is checked to be absent from the production app in teams.integration.test.ts.

Threat 2: reading another team's data by changing an ID

What it is. A user changes the team ID in a request to see a team they are not in.

How it is handled.

  • The team comes from the validated route parameter (a canonical UUID), never from the body or the token. The membership is looked up on that team's shard for the caller's user ID; no membership means the request stops.
  • 404, not 403. A team the caller is not in answers exactly like a team that does not exist (same status, same body apart from the request ID), so a response never confirms that another team's resource exists. 403 is only for a member with too little power.
  • Team data is tied to the team's shard; there is no cross-team query on a request path.
  • A removed member loses access on the next request (membership is read from the primary every time), even if the directory still lists them (ADR 0013: the directory is a hint, access never consults it).

What remains. Team routes added later must use requireTeamRole and filter every query by team_id; a route that skips it is the risk. The shift routes follow it: a shift ID from another team is a 404 under my team's path, and the assignee of a shift must be a member of this team.

Proving tests. team-security.integration.test.ts: "TEAM ISOLATION" (users from team X and team Y, on different shards, shown by SQL and the shard function: 404 on the team and its members, byte-identical to an unknown ID, in both directions), the Staff variant, and "a removed member loses access on the next request". shifts.integration.test.ts: the same isolation for the shift routes (a member of team X gets the same 404 on list, create, update and delete for team Y as for an unknown team, across shards) and "a shift ID from ANOTHER team is not found under MY team's path". Mutation-checked (shift delete without the team_id scope fails them): making the middleware answer 403 for a stranger, or skipping the role check, fails them.

Deactivated members (ADR 0029)

What it is. A reduction at period end makes some members inactive. A deactivated membership keeps its row (memberships.deactivated_at) so history and the ledger stay intact, but the person must lose every kind of access to the team at once.

The control. The team middleware answers 404 not_a_member for a deactivated membership, exactly as for a stranger, so no team route can be reached by ID. The member list and the team list skip them, shift assignment and the swap approver, caller and both-people locks require deactivated_at IS NULL, and a seat is an active member. The Owner can never be chosen. Only the Owner schedules a reduction, and the server validates the chosen people against the members as they are at that moment, under the team row lock. Tests: server/src/billing/reductions.integration.test.ts ("A DEACTIVATED MEMBER", "WHO MAY", "SCHEDULING").

What remains. Nothing sets deactivated_at until the renewal slice applies a reduction. Any NEW query on memberships must filter deactivated_at IS NULL; a reviewer should look for it.

Threat 7: theft or reuse of an invitation link

What it is. An invitation link is a credential that lets someone join a team in a role. It travels by email, so it can be forwarded, read by a scanner, or found in a database dump.

How it is handled (ADR 0015).

  • The link is https://rota.davebuilds.design/invite/<teamId>.<secret>. The secret is 32 random bytes (base64url, 43 characters); only its SHA-256 is stored. The team ID is a routing hint only.
  • Single use, consumed by one conditional update (accepted_at IS NULL AND revoked_at IS NULL AND expires_at > now()), so two simultaneous acceptances give one membership.
  • Tied to one email address. Accepting needs a signed-in account whose address equals the invited address (403 invite_wrong_account otherwise, nothing granted). So a forwarded or leaked link alone does not let anyone else join.
  • Expires after 7 days from creation or resend. A resend gives a new secret and kills the old link at once; a revoke kills it too.
  • One answer for every unusable link: unknown, malformed, wrong team ID, expired, used and revoked all give the identical 404 invite_unavailable, so a response never reveals which. The one exception is the account that already accepted this exact link and still has the membership: it gets the same success again (a retry after a lost response, or a double submit), and nothing is written. Everyone else, including a different signed-in account, still gets the identical 404. The preview mirrors this (ADR 0017): the same account, with a valid session, gets 200 { status: 'already_member', team, role } instead of the 404, so the app can take them to their team; every other caller of a spent link, signed in or not, gets the identical 404.
  • Opening a link consumes nothing: the preview is a POST (the token never sits in an access log) and changes no row; only an explicit accept does.
  • The role comes only from the invitation row. Nobody can be invited as Owner (validation, the permission table, and a database CHECK). A Manager can invite Staff only.
  • Never in logs: the logger cannot carry a token, a link or an address. The raw secret exists only in the link and in the email job's stored payload until the email is sent or skipped, then the body is scrubbed from the row.

Accepted gaps (written down on purpose).

  • A pre-registered address blocks the invitation until the real owner takes the account over. Signup verification is deferred, so anyone can register someone else's address. The invite can only be accepted by the account that holds that address; password reset or a magic link (slice 2b, below) is how the real owner takes such an account over. Accepting an invite deliberately does not clear the password or revoke sessions (ADR 0015; security.md amended).
  • The raw token sits in the work row's payload until the job finishes, and stays on a row that ended failed (a human may retry it). Because acceptance is tied to the invited address and the token lasts 7 days, that alone does not let a reader join the team.
  • The invite email goes out from a verified domain with a team name and inviter name that people type themselves, so an Owner could write a misleading team name. Names are escaped and single-line; team creation is rate limited.
  • The link host is GitHub Pages (site/, ADR 0019). Proven on a real device (2026-11-06, preview build): Android reports the domain verified, and a cold-started tap on a real invite link opens the app directly to the "You're invited" screen rather than the browser. The landing page shown without the app is static, shows no token and sends no referrer, but the host's own request logs still see the path.
  • In the app (ADR 0017): the token lives only in the route (memory) and as route params to login and signup; it is never stored, logged, put in a query key or shown. When Sentry is initialised for the app, route params and /invite/ URLs must be scrubbed from breadcrumbs. Done (ADR 0039): every breadcrumb goes through scrubBreadcrumb, which removes the token after /invite/, /magic/ and /reset/ and every query string; tested in app/src/observability/observability.test.ts. Opening a link only previews; accepting is an explicit tap, sent once (a latch), never queued offline.
  • Proof limits: adb proofs put the link in the emulator's system log (the adb daemon logs the shell command), so device logs are never attached to a PR. Test data only.

Proving tests. invites.integration.test.ts: "create" (hash only, the secret never in the invitations row), "unavailable is ONE answer", "accept" (role from the invitation, nothing cleared, session intact), "accept needs a signed-in account...", "two simultaneous accepts", "a join that fails halfway", "preview consumes nothing", "preview mirrors accept", "REDACTION". invites-limits.integration.test.ts. tokens.unit.test.ts.

Invite links (ADR 0025, issue #37). A link is the other half of "invite by email or link": a Staff invitation not tied to an email address, usable once by whoever holds it. What changes against the email threat above, and what does not:

  • A bearer credential. Anyone who sees the link first can use it first. It is bounded: Staff only (a Manager is invited by email, where the address is the second factor; the API, the permission table and a database CHECK all refuse a Manager link), single use (the same conditional UPDATE as an email invitation, so five simultaneous acceptances give one membership), 48 hours (INVITE_LINK_EXPIRY_HOURS, chosen), revocable by an Owner or Manager, and capped at 10 pending per team (INVITE_LINK_MAX_PENDING, counted under a lock on the team row).
  • Same token design. <teamId>.<secret>, 32 random bytes, only the SHA-256 stored, the link shown once in the creation answer and nowhere else. The same 404 invite_unavailable for unknown, malformed, wrong-team, expired, used and revoked links, in preview and in accept.
  • No address, so no match and no verification. Any signed-in account may accept it. Accepting does not verify an email address (a link proves nothing about one), so an unverified account stays unverified.
  • An existing member is never touched. Opening a link as someone already on the team answers already_member with the role they hold, does not consume the link, and never changes a role. The account that already used a link gets the same success again (a lost answer is safe to retry).
  • Race losers. A loser's directory row is taken back if they are not a member, so the directory is not left pointing at a team they are not in (best effort; the orphan sweep, issue #33, covers a failure).
  • Creating sends no email, so it has its own limits (invite_link_user, invite_link_team) and never uses the app-wide email cap.
  • Proving tests. invite-links.integration.test.ts: the single-use race, the identical answer for every unusable link, Staff only (API and CHECK), the existing-member case, no address verification, the cap under concurrency, the limits, and the production app serving the route.
  • Weakness, written down. Nothing says who a link was meant for; the activity record shows who accepted it. If a link leaks before it is used, whoever uses it first gets in as Staff, until the Owner or Manager revokes it (visible in the pending list) or it expires.

Threat 8: reset and magic-link tokens — theft, reuse, enumeration and takeover

What it is. A reset or magic-link token is a credential that sets a password or starts a session. It travels by email, so it can be forwarded, read by a scanner, or found in a database dump; and the request that asks for it can be used to find out which addresses have accounts.

How it is handled (ADR 0020).

  • The token is 32 random bytes (base64url); only its SHA-256 is stored in auth_tokens on shard A. Single use, consumed by one conditional update (used_at IS NULL AND expires_at > now()), so two simultaneous redemptions give one winner. Magic link 10 minutes, reset 1 hour (config). A newer request replaces an older unused token of the same purpose; a successful reset kills every other outstanding token of that user.
  • One answer for every dead link (unknown, malformed, used, replaced, expired): 404 link_unavailable.
  • Opening a link consumes nothing. The link opens an app screen; only the screen's POST redeems it, so an email scanner fetching the link changes nothing. The app never stores, logs or caches the token.
  • No enumeration. A request answers 202 { ok: true } whether or not the address has an account, and in the same time: the token is made after the answer is sent (measured 135 ms against 134 ms; before, 1020 ms against 152 ms). The per-address and per-IP limits count unknown addresses too, so a 429 reveals nothing, and the daily email cap is counted only for emails that would really be made.
  • Takeover blocked. Redeeming a magic link for an unverified address verifies it, clears the existing password and revokes every session in the same transaction (whoever registered it first may not own it); a reset also verifies the address. A verified account loses nothing when it redeems a magic link.
  • A reset ends every session (all families revoked under the same lock as refresh, reason password_reset) and does not sign anyone in.
  • Rate limits (magic_request_ip 30 and magic_request_email 5 per 15 minutes, magic_redeem_ip 30 per 15 minutes, the same for reset, reset_submit_ip), fail closed with 503 when Valkey is down, and a blocked attempt never reaches an Argon2 run. Daily cap: 30 emails per UTC day, shared with nothing else but Resend's 100 (invites keep 50).
  • Never in logs: the logger cannot carry a token or an address; the tests check the captured logs. The raw token exists only in the link inside the frozen email payload until the email job has sent or skipped it, then the body is scrubbed.

Accepted gaps (written down on purpose).

  • Recovery can be starved. Someone who knows real addresses can use up the 30 daily emails, or an address's 5 requests per 15 minutes, and delay a real person (ADR 0020).
  • A request replaces the link a person was about to use. The newest email is the one that works.
  • An email can be lost after the answer if the process dies or the database refuses between the answer and the commit; the person asks again and the failure is logged.
  • The host's request logs see the token in the URL path (ADR 0019). The landing page shows and sends nothing.
  • When Sentry is initialised for the app, route params and /magic/ and /reset/ URLs must be scrubbed from breadcrumbs, as for /invite/. Done (ADR 0039), by the same shared list, for all three.

Proving tests. recovery.integration.test.ts (security.md tests 11, 16, 17 and 18) and recovery.unit.test.ts; the app's authActions, authFailure, validation, recoveryApi and linkToken tests.

Threat 3: a stolen access token

What it is. Someone obtains a valid access token (a leaked log, a shared device, a proxy) and sends it as Authorization: Bearer.

How it is handled.

  • The token lives 15 minutes (ADR 0005). It carries only the user and the session (sub, sid): no role and no team, so stealing it gains no permission the server doesn't re-check on every request.
  • Every authenticated request re-checks the session on shard A's primary (isSessionActive): the family exists, belongs to the token's user, is not revoked and is inside its absolute expiry. So logout, logout-all and a detected refresh-token theft stop a stolen access token on its very next request, not 15 minutes later.
  • HS256 is fixed. alg: none, any other algorithm, a wrong key, a wrong issuer or audience, and an expired token are all refused, with one public answer (401 unauthenticated, WWW-Authenticate: Bearer); the real reason is only in the server log.
  • Token-bearing responses are Cache-Control: no-store. Tokens are never logged: the logger accepts a fixed list of fields and cannot be handed a header or a body.

What remains. Until the session is revoked or the token expires, a stolen access token works, and nothing tells the owner. The cost of the check is one primary read per request, which the k6 report must measure.

Proving tests. session-check.integration.test.ts (revocation stops the same token on its next request; expired family; family of another user; none, HS512, wrong secret; roles ignored), tokens.unit.test.ts (every verification failure), middleware.unit.test.ts, refresh.integration.test.ts ("redaction": no token in any log line), logout.integration.test.ts.

Threat 4: a stolen refresh token, and reuse

What it is. Someone copies a refresh token (the long-lived credential) and uses it to mint new access tokens.

How it is handled.

  • A refresh token is 32 random bytes. Only its SHA-256 is stored; the token itself never is. A session is a family of tokens, one family per device login.
  • Rotation: every refresh consumes the presented token and issues a replacement, in one transaction that locks the family row (FOR UPDATE) and consumes the token with one conditional update. Two simultaneous uses of one token give exactly one winner.
  • Reuse detection: presenting a token that was already used revokes the whole family and commits that revocation before the 401 goes out (the outcome is returned from the transaction, never thrown inside it). The newest refresh token and the family's access tokens stop working; the user's other devices are untouched.
  • Logout revokes one family; logout-all revokes every family of the user. Both take the same lock as refresh, and logout-all locks families in id order, so a refresh in flight either commits first and is then revoked, or runs after and sees the revocation.
  • Limits: 30 days idle, 90 days absolute per family (ADR 0005); refresh is rate limited by IP (refresh_ip, below).
  • Failure answers are identical for unknown, idle-expired, expired, revoked and reused tokens. The reason (refresh_reuse_detected, ...) is in the log only; reuse also writes a refresh_reuse_detected security event naming the user and family.

Accepted trade-offs.

  • No grace window. A refresh whose response is lost looks like reuse on the next refresh and forces a new login. The app keeps one refresh in flight to make this rare.
  • A thief who refreshes first and keeps rotating while the owner is offline holds a session until the owner returns and presents the now-old token (detected then, and the family dies). Used tokens are kept until their family expires so reuse can be seen; a purge job is a follow-up (issue #20).
  • A login that starts while logout-all is running makes a new family that logout-all does not cover.
  • If the database can't start the transaction in time, the answer is a retryable 503; nothing was consumed.

Proving tests (numbers are security.md / data.md acceptance tests). refresh.integration.test.ts: rotation (5), reuse (6). concurrency.slow.test.ts: concurrent refresh (7), atomic consumption, revocation race (8) deterministic in both orders and repeated 15 times, no deadlock between logout, logout-all and refresh. logout.integration.test.ts: logout ends one device, logout-all ends all (9).

Rate limiting (threat 5: credential stuffing and brute force)

Held in Valkey, never in memory (ADR 0007). Fixed windows, keyed by a hash of the IP or the email.

Rule Limit Window Env override (max / window seconds)
login_ip 30 15 minutes RATE_LIMIT_LOGIN_IP_MAX / _WINDOW_SECONDS
login_email 5 15 minutes RATE_LIMIT_LOGIN_EMAIL_MAX / _WINDOW_SECONDS
register_ip 10 1 hour RATE_LIMIT_REGISTER_IP_MAX / _WINDOW_SECONDS
refresh_ip 60 15 minutes RATE_LIMIT_REFRESH_IP_MAX / _WINDOW_SECONDS
team_create_user 5 1 hour RATE_LIMIT_TEAM_CREATE_USER_MAX / _WINDOW_SECONDS (per user ID; approved 2026-10-23)
invite_send_user 10 1 hour RATE_LIMIT_INVITE_SEND_USER_MAX / _WINDOW_SECONDS (create and resend; approved 2026-10-23)
invite_send_team 20 24 hours RATE_LIMIT_INVITE_SEND_TEAM_MAX / _WINDOW_SECONDS (per team; counted after the membership check; approved 2026-10-23)
invite_link_user 10 1 hour RATE_LIMIT_INVITE_LINK_USER_MAX / _WINDOW_SECONDS (creating an invite link; mirrors invite_send_user; approved 2026-10-28; chosen, not measured; ADR 0025)
invite_link_team 20 24 hours RATE_LIMIT_INVITE_LINK_TEAM_MAX / _WINDOW_SECONDS (per team, counted after the membership check; mirrors invite_send_team; approved 2026-10-28; chosen, not measured; ADR 0025)
invite_send_global 50 UTC day INVITE_GLOBAL_DAILY_CAP (app-wide; counted only for requests that passed every other check; resets at 00:00 UTC; approved 2026-10-23)
invite_preview_ip 30 15 minutes RATE_LIMIT_INVITE_PREVIEW_IP_MAX / _WINDOW_SECONDS
invite_accept_ip 30 15 minutes RATE_LIMIT_INVITE_ACCEPT_IP_MAX / _WINDOW_SECONDS
invite_accept_user 10 1 hour RATE_LIMIT_INVITE_ACCEPT_USER_MAX / _WINDOW_SECONDS
billing_user 10 1 hour RATE_LIMIT_BILLING_USER_MAX / _WINDOW_SECONDS (per user ID, creating or cancelling a payment attempt only; approved by Dave 2026-10-29; chosen, not measured; ADR 0027)
swap_request_user 10 1 hour RATE_LIMIT_SWAP_REQUEST_USER_MAX / _WINDOW_SECONDS (per user ID, creating a swap request only; approved 2026-10-27; chosen, not measured; ADR 0023)
feed_user 120 1 minute RATE_LIMIT_FEED_USER_MAX / _WINDOW_SECONDS (per user ID; approved 2026-10-26; chosen, not measured: the load test, with 200 distinct users, checks it; ADR 0022)
settings_read_user 120 1 minute RATE_LIMIT_SETTINGS_READ_USER_MAX / _WINDOW_SECONDS (per user ID; proposed in the settings PR, awaiting approval; chosen, not measured: it mirrors the feed, every foreground refetch is one read; ADR 0024)
settings_write_user 30 1 minute RATE_LIMIT_SETTINGS_WRITE_USER_MAX / _WINDOW_SECONDS (per user ID; proposed, awaiting approval; chosen, not measured; ADR 0024)
devices_write_user 30 1 minute RATE_LIMIT_DEVICES_WRITE_USER_MAX / _WINDOW_SECONDS (per user ID, registering or removing a push device; approved by Dave 2026-11-03; chosen, not measured; ADR 0032)

The app-wide invite cap exists because Resend's free plan sends 100 emails per UTC day in total, shared with password reset and magic link (slice 2b) and any proof sends (ADR 0015). A limit keyed by the team or the whole app runs after the membership and role check, so a stranger cannot spend another team's budget (security.md).

  • A blocked request is 429 rate_limited with a Retry-After header, and never reaches password verification.
  • If Valkey is unreachable or rejects the write, these routes answer 503 service_unavailable (fail closed). That includes the swap request and the activity feed (the feed decided 2026-10-26, issue #11, ADR 0022): it returns no rows rather than serving unprotected; test "with Valkey down the feed fails CLOSED".
  • They work again on their own when Valkey is back, with no restart. A connection that went silently dead (a laptop sleep, a NAT that forgot the mapping) is replaced after the first command timeout, so the limited routes answer 503 only while Valkey is really unreachable (ADR 0018, issue #39). An error reply such as OOM under noeviction is not a timeout and changes nothing: it still fails closed, and noeviction is never altered.
  • The IP is the TCP peer address. X-Forwarded-For is not trusted until the host's proxy setup is verified.
  • A set-but-invalid override (not a positive integer) stops the server from starting.

Push notifications (ADR 0032)

  • A device belongs to the signed-in user. PUT /devices and POST /devices/unregister are user routes: Zod, access token and session check, a per-user rate limit, then the handler. The user comes from the session, never the request. Unregister removes only the caller's own token; someone else's token, or an unknown one, changes nothing. A token that was another user's moves to whoever registers it, so a phone handed over stops notifying the first person. The database refuses anything that is not an Expo token.
  • Every decision is the server's (AGENTS.md rule 3). Who is told, in which role, with which switches and quiet hours, is read when the job runs from the primary: billing pushes go to the Owner of the team and nobody else, and an Owner who was replaced or deactivated gets nothing. Nothing the phone sends decides any of it.
  • What the phone receives: a version, a type, a moment, a team id and, for a shift or a swap, that one id (ADR 0033). No path, no amount, no free text from a user, no secret. The app maps a known shape to a screen and ignores everything else, and the screen loads its data through the normal authorised API, so a forged notification can point the app somewhere but never show anything the person could not already see. No push carries a money figure (AGENTS.md rule 2).
  • No secret in the app or the worker. The Firebase service-account key is uploaded to Expo (EAS credentials), never committed and never in the repo; google-services.json is gitignored (ADR 0011). The worker holds no Expo or Firebase secret. Device tokens are never logged, never in an error text, and never in PR text or evidence; logs carry row ids and device ids.
  • Known gap: enhanced push security is not enabled (Dave, 2026-11-03). Expo's send endpoint requires no authentication, so anyone who learns a device's push token can make that phone show a notification (it cannot make the app do anything: a tap only opens a screen from a fixed list). Tokens are held only in the database and never leave the server. Turn it on before submission if time allows (ADR 0032).
  • Known gap: lock-screen text. A notification's title and body can be read on a locked phone. They carry the team's name and the fact that a renewal failed, no amount and nothing about people. A phone that was signed out involuntarily stays registered until another person signs in on it or Expo reports it unregistered (ADR 0032).
  • Shift and swap pushes (ADR 0033): who is told is decided on the server inside the change's own transaction and checked again when the job runs (the recipient must still be an active member of the team, so someone who left or was deactivated at a reduction gets nothing); a person is never notified of their own action; the words are generic (no shift title, time or name) because a notification is readable on a locked phone. A forged notification can open a shift or swap screen, which loads through the normal authorised API (a shift or swap of another team is a 404).
  • A push is a notification, not a guarantee: at-least-once processing, an accepted ticket does not prove delivery, and Expo has no SLA.

Request IDs and logging

  • Every response carries X-Request-Id. An incoming one is accepted only if it is a canonical UUID; otherwise a new one is made.
  • One JSON log line per request: request ID, user ID (when authenticated), route template, status, duration, error code, database route. UTC ISO 8601 timestamps.
  • The logger only accepts a fixed list of fields and primitive values. It cannot be handed a request body, a header, an email, a password or a token, so none of them can reach a log line. Error text passes through the shared redaction.

Sentry (ADR 0039). Errors only — no tracing, profiling, logs, metrics or session replay — on the API, the worker and the app, into two EU-region Sentry projects (rota-server, rota-app). One shared redaction list (shared/sentry-scrub.ts, copied byte for byte into both server/src/observability/sentryScrub.ts and app/src/observability/sentryScrub.ts, a parity test in each) strips everything the SDK would otherwise collect by default (user identity beyond an ID, cookies, headers, request/response bodies, query strings, local-variable values) before an event leaves the process, and scrubs /invite/, /magic/ and /reset/ tokens from app breadcrumbs (the same list threats 7 and 8 rely on). A gate gives one event per error per 5 minutes, 50 a day per server process, 20 per app session. Every event carries the placeholder IP 0.0.0.0 (Sentry infers a user's city and country from the real one even with IP storage turned off — checked against Sentry's own events, not assumed). Tags on each event: request_id, team_id, route, role, job fields — the same request ID the structured log line carries, which is how "what happened to this user's payment at 3:14pm" is answered from the two together. Tests: sentryScrub.unit.test.ts (both packages), sentry.unit.test.ts, app/src/observability/observability.test.ts. Full write-up: docs/ARCHITECTURE.md section 5r.

Passwords (threat 5, with rate limiting)

  • Stored as Argon2id (19 MiB, 2 iterations, parallelism 1) on shard A, in credentials.password_hash. Never returned, never logged. Library and benchmark: ADR 0006.
  • Policy (NIST SP 800-63B-4, ADR 0005): minimum 15 and maximum 128 characters, counted as Unicode code points; NFC-normalised; no composition rules; over-long passwords are rejected, never truncated. A blocklist check exists but its list is empty: NIST SHALL not yet met, no list with a confirmed data licence (ADR 0005; tracked in AGENTS.md, "Later proofs").
  • Login never says which of email or password was wrong: one 401 invalid_credentials, and an unknown email still runs one Argon2 verification against a dummy hash so timing does not reveal accounts.
  • Accepted trade-off: 409 email_in_use at sign-up reveals that an address has an account. Sign-up verification is deferred, so there is no way to answer identically. The route is rate limited. Squatting risk: anyone can register someone else's address (unverified) and hold the account until the real owner redeems a magic link or a reset (below), which verifies the address and ends the squatter's password and sessions.

Signing secret

AUTH_JWT_SECRET is base64 of at least 32 random bytes (RFC 7518 section 3.2). Generate: openssl rand -base64 32. The server refuses to start without it, and never logs it. It is a server environment variable only: it is never in the repo, the app bundle or any EXPO_PUBLIC_ variable.

Rotating it (on a schedule you choose, or at once if it may have leaked):

  1. Generate a new value: openssl rand -base64 32.
  2. Set it as AUTH_JWT_SECRET in the host's environment (and your local .env), then restart the API. There is a single key and no key ID, so the switch is immediate: every access token signed with the old key is refused (401) from the first request on the new process.
  3. The effect on users is small and by design: access tokens last 15 minutes and the app answers a 401 with one refresh. Refresh tokens are random values stored as hashes and do not depend on this secret, so sessions survive a rotation.
  4. If the old secret leaked, step 2 is not enough on its own to be sure: someone holding it could have signed tokens, but each token must name a real, live (user, session) pair, and the session check refuses any other. Ending every live session is the stronger response: an operator runs, on shard A, UPDATE refresh_token_families SET revoked_at = now(), revoked_reason = 'secret_rotation' WHERE revoked_at IS NULL; (not run by any code; everyone then signs in again).
  5. Rotation is not exercised by an automated test yet. A second verifier, or a rotation without logging out in-flight tokens, would need a key ID and two accepted keys (ADR 0005, Revisit when).

Threat 6: secrets extracted from the app bundle

What it is. Anyone can download the APK, unzip it and search it. Anything inside is public: a payment key in an EXPO_PUBLIC_ variable would let a stranger issue refunds (brief, Requirement 4).

How it is handled.

  • One EXPO_PUBLIC_ variable exists, and it is not a secret (table below). A unit test (app/src/publicEnv.test.ts) fails if any other EXPO_PUBLIC_ name appears anywhere in the app, or if an allowed name looks secret-shaped, or if one is missing from this file or .env.example. A new variable therefore cannot be added without writing its justification here first.
  • Restricted access after a failed renewal (ADR 0031). One guard, requireWritable, on every team route that writes and is not billing (shifts, swaps, invitations): 403 team_read_only once the current period's renewal failed, its grace period ended and it is unpaid. It runs after authentication and the membership check, so it can never tell a stranger that a team exists or is overdue (same 404). It reads the primary on every request (a payment confirmed a second ago lifts it). Reads, sign-in, account recovery and the Owner's billing routes keep working. A unit test walks the real routers and fails if a write route lacks the guard. Renewal events are accepted only with our team_id, renewal_id and attempt in the metadata, only from a verified signature, and only the attempt that is charging can fail; a payment that does not match the frozen amount, currency, version or period is recorded and sent to human review. Tests: renewal.integration.test.ts, teams/writeGuard.unit.test.ts.
  • What we store about a card (ADR 0030): Stripe's Customer and PaymentMethod ids, the brand, the last four digits, the expiry, and the consent wording with its date. Never a card number or CVC (Stripe holds the card). The app sees only finished strings ("Visa ending 4242"), never a Stripe id. The worker holds the Stripe test key for reads and never the webhook signing secret; it refuses to start with a non-test key.
  • The app holds no key, no signing secret and no provider credential. The server holds every secret as an environment variable (.env.example lists names only). The app has no payment logic at all (AGENTS.md rule 2).
  • Tokens are stored only in expo-secure-store, never AsyncStorage, never the query cache, never a log. Android's cloud and device-transfer backup rules shipped with expo-secure-store exclude its data, so tokens are not copied off the device by backup.
  • android/ is generated and gitignored; the Sentry source-map upload token will be an EAS build secret, never a public variable.
  • google-services.json (Firebase client config for push) holds the Firebase project identifiers and a Google API key. Those values are shipped inside every APK by design, so they are not secret. It is still kept out of the repository (ADR 0011) so a public repo does not trigger secret-scanning alerts or trip the brief's _KEY history search. The Firebase service-account private key is the real secret: it is uploaded to EAS credentials and never enters the repo or the app.

EXPO_PUBLIC_ variables (the complete list).

Variable Value Why it is safe to expose
EXPO_PUBLIC_API_URL The API's address, for example https://api.example.com (locally http://10.0.2.2:<port>) It is only an address, and anyone with the APK or a network trace can read it anyway. It grants nothing: the server authenticates every request and decides every permission, and never trusts the client (AGENTS.md rule 3). The app refuses to start talking to anything that is not https, except the local development server in a development build (app/src/api/config.ts, tested).
EXPO_PUBLIC_SENTRY_DSN The address and public key of the rota-app Sentry project (EU data storage), for example https://<key>@o<org>.ingest.de.sentry.io/<project> Checked against Sentry's own page (docs.sentry.io/concepts/key-terms/dsn-explainer, read 2026-11-04): "DSNs are safe to keep public because they only allow submission of new events and related event data; they do not allow read access to any information." It is a different project, and a different key, from the server's DSN, so it cannot reach the server's events. The residual risk, stated on the same page: anyone who reads it from the app can send events with whatever content they like, which could use up the shared 5,000-error quota. The controls are Sentry's IP blocking and rotating (or revoking) the key in the project's Client Keys settings; the app's own limit of 20 events a session does not stop someone who is not using the app. Nothing it can send can read, change or delete anything.
EXPO_PUBLIC_SENTRY_ENVIRONMENT A label such as development or production, shown on each event It is a word, not an address or a key.

The Sentry DSN joined this table in the Sentry slice (ADR 0039), with the claim checked against Sentry's own page (see its row). The Sentry auth token (source-map upload) is a different thing and is never public: it is an EAS build secret (eas env:set --visibility secret), never EXPO_PUBLIC_, never in the repo; Dave creates and sets it himself. Not yet confirmed done.

What remains. A debug build loads its JavaScript from the development server and does not contain the bundle, so the bundle search (unzip the APK and search for sk_, secret, password, _KEY) is run on the first preview (release) build and recorded then.

Proving tests. app/src/publicEnv.test.ts (allowlist), app/src/api/config.test.ts (https only), app/src/auth/signOut.test.ts and app/src/api/client.test.ts (token handling).

Stripe webhook signature verification (forged or replayed events)

What it is. Someone sends a fake Stripe event to the webhook endpoint, or replays a real one, to make the server think a payment succeeded (or failed) when it didn't.

How it is handled. Signature verified on the raw body before anything is parsed or logged (a bad, missing or tampered signature is 400 and records nothing); live-mode events are refused outright; the inbox is unique by Stripe's event ID, so a replay writes nothing; a valid signature is never treated as proof of payment on its own — the job matches amount, currency, team, session and status against the frozen operation we created (ADR 0027). A saved card (ADR 0030) is recorded the same way: a setup event is matched to the setup we froze (team, session, still open, setup mode), the SetupIntent is READ from Stripe by the job and must have succeeded, for off-session use, as a card, with the session's Customer and our metadata, in test mode; anything else is recorded for review and saves nothing.

Proven against a real Stripe event end to end: deployment-gate check 1, PR #77 (checkout.session.completed and payment_intent.succeeded, both 200 OK, verified, durably recorded, processed by the deployed worker).

Proving tests. server/src/billing/activation.integration.test.ts, server/src/billing/cardSetup.integration.test.ts.

Deploy-provider credentials, and the Northflank incident (ADR 0040)

What happened. Northflank, the deployment provider (ADR 0040), disclosed a security incident beginning 30 October 2026 (status "Monitoring" as of 2 November): an attacker targeted secrets held in Northflank's own control plane, and customers were told to assume their environment variables had been decrypted. Northflank says it was contained within an hour and rotated its own keys. Dave has screenshots of the disclosure.

Checked before accepting the risk. Rota's Northflank account held no secrets at the time of the incident: the Secrets page was empty, and the audit log showed only two project-setup events from 16 October, before any credential existed. The deploy wasn't created until after the incident. The residual risk is also bounded by what Rota exposes: Stripe test mode only, demo data only, every dependency on a free plan. Dave accepted the risk on this basis.

Mitigation: every deploy credential is new, least-privilege where the provider allows it, and separately rotatable from local dev — a different threat model from "one .env for everything," because a single leaked deploy secret never also compromises what a developer uses locally, and each provider's credential can be rotated on its own:

  • Stripe: a restricted test-mode key (rota-deploy-api), Checkout Sessions/Payment Intents (Write), Setup Intents/Payment Methods (Read) only. A separate webhook signing secret from the local one.
  • Resend: a sending-only key, restricted to the rota.davebuilds.design sending domain.
  • Neon: a new role per shard (rota_deploy_api), separate from Dave's own role — full project access (the Neon Console's own default; it offers no narrower one), so this is separation for rotation, not least privilege.
  • Valkey (Aiven): a new ACL user (rota_deploy), +@all -@admin with the @dangerous commands individually denied and CONFIG denied outright (ADR 0040 has the detail on why -@admin alone wasn't enough).
  • AUTH_JWT_SECRET: a value only the deployed API holds, deliberately different from local dev's — proven the hard way when the k6 load test's first seed attempt signed tokens with the local secret and got 401s against the deployed API from every one of 200 users (load-tests/REPORT.md). Rotated once already (2026-11-06, after the k6 run used a temporary K6_DEPLOY_AUTH_JWT_SECRET to mint tokens the deployed API would accept) with no code change needed: there is a single key and no key ID, so every token signed with the old key is refused from the first request on the restarted process (see "Signing secret" above for what rotation costs users).
  • GitHub: Northflank's GitHub App access is limited to this one repository.
  • All of the above are rotated again after submission, or sooner if Northflank's root-cause report warrants it.

What remains. The Neon deploy role is not least-privilege (no narrower role exists today); revisit if Neon offers one. Full detail, options considered and the Stripe webhook API-version proof: docs/decisions/0040-northflank-deployment.md.

There aren't any published security advisories