Sign-in, Sessions and API Keys

How people, respondents and programs prove who they are in Sondely today, and how the TypeScript app does it. Read from the code on 5 November 2026: sondely/backend/app/api/auth/routes.py, backend/app/utils/auth.py, backend/app/utils/permissions.py, backend/app/core/security.py, backend/app/core/redis.py, backend/app/middleware/rate_limit.py, backend/app/api/api_keys/routes.py, backend/app/main.py, and the frontend in frontend/src. The target copies TourCockpit's src/lib/auth/* and src/lib/api/auth.ts at commit f952d0eea. Every route named here is in the API Route Map by its number (A1 to A17, K1 to K3); the tables are on Data Model.

How a request is identified today

Every protected route depends on get_current_user in backend/app/utils/auth.py. It reads one bearer token and tries three things in order. Nothing else is checked: no scope, no organization, no revocation list.

The organization on an API key is stored on the user object as _api_key_org_id (backend/app/utils/auth.py, line 68) and is read nowhere else in the backend. The JWT's scope claim (set to respondent by auto-enroll) is read nowhere either.

Sign-in methods today

Tokens and sessions today

Because the frontend sends only the 30-minute JWT and every 401 clears localStorage and redirects to /auth/signin, a person is signed out mid-task after 30 minutes regardless of the 24-hour session (inferred from the clients' 401 handlers, not observed).

The key prefix carries only 4 random hex characters (65,536 values) and the lookup is find_one by prefix: two live keys that share a prefix cannot both work, because only one document comes back to be verified (inferred from code, not run).

Target design

Credentials

All three stores hold a SHA-256 hash of the token and are looked up by that hash, as TourCockpit does with hashToken (src/lib/auth/tokens.ts) and hashApiKey (src/lib/api/auth.ts). The guard for each route comes from its registry Rbac (public, self, grant, member, admin, owner, test), defined on the API Route Map.

Roles

Passwords

• Argon2id through @node-rs/argon2, with TourCockpit's parameters (19 MiB, 2 passes, 1 lane), copied as is from src/lib/auth/password.ts.
• bcrypt accepted once, then rehashed. TourCockpit's verifyPassword only reads argon2 digests. Sondely's copy adds one branch: a digest starting $2a$, $2b$ or $2y$ is checked with bcryptjs (pure JavaScript, so the musl image needs no build tools); on success the password is hashed with argon2id and stored in the same transaction. needsRehash already returns true for any digest that is not argon2id. A test signs in with a real passlib digest from a Python fixture and asserts the stored digest starts $argon2id$ afterwards.
• The unknown-email branch spends the same work as a real check (verifyAgainstDummy), which closes today's timing oracle on A2.
• Policy from src/lib/auth/password-policy.ts: minimum 6 (today's rule, kept so no existing password is refused), maximum 256, the common-password and own-email checks.

Sessions in Postgres

• TourCockpit's Session model: tokenHash, expiresAt, lastSeenAt, sliding expiry with an absolute ceiling (src/lib/auth/session.ts, src/lib/auth/config.ts). TourCockpit's windows are 90 days sliding and 180 absolute; Sondely's are set in its own config (proposed: 30 days sliding, 90 absolute, since owners hold respondent data).
• Bearer contract at cutover. A1, A2, A8 and A14 keep returning access_token, session_token and token_type: bearer. Both fields carry the same opaque session token. The frontend never decodes the token (no JWT parsing anywhere in frontend/src), so this changes nothing on screen and ends the 30-minute sign-outs. JWTs and Redis go away; everyone signs in again once at cutover, which falls inside the write freeze.
• A15 deletes the session row. A6 (reset) and any password change call destroyAllSessions.
• Then the httpOnly cookie, when the screens move to Next: a cookie named for Sondely in place of tp_session, httpOnly, Secure in production, SameSite=Lax, host-only. 17 files in frontend/src read access_token from localStorage today; each stops when its screen moves. The bearer path for browsers is removed when the last screen has moved; bearer stays for API keys and grants.
• Custom domains. A host-only cookie means a person signs in on the domain they use. Google and Apple keep one registered redirect URI on the canonical host, so the callback hands back to the tenant domain with a short-lived signed payload (src/lib/auth/signed-payload.ts, the way src/lib/auth/google-return.ts does it) that the tenant host exchanges for its own cookie. Tokens never travel in a URL again.

One-time codes on the magic-link storage

TourCockpit's MagicLinkToken (tokenHash, kind with no default, expiresAt, consumedAt) holds every single-use secret:

A3 stays a GET for the link in old emails, and consumes the token; A8 keeps today's behaviour (a new email becomes an account, an email-only account is promoted).

Google and Apple

• Google is ported from src/lib/auth/google.ts and src/app/api/auth/google/callback/route.ts, keeping Sondely's return_to validation (canonical hosts plus organization custom domains) and the rate limit TourCockpit puts on the callback.
• Where Google sign-in starts and returns (fixed 9 November 2026, after "Continue with Google" answered 422 on platform.sondely.com). Behind the Container Apps ingress the app sees its own address, http://localhost:8000, so the address the browser used is read from the Host header, with the scheme from X-Forwarded-Proto when TRUST_PROXY is true. A start on any host other than APP_BASE_URL's (a custom domain, the *.azurecontainerapps.io address) is redirected to the canonical host first, because Google returns there and the binding cookie must be set there; hosts are compared, never full origins, so a missing forwarded scheme cannot loop. Without an explicit return_to, sign-in returns to the app: no custom-domain page exchanges the handoff yet, so returning to a custom domain would leave the person signed out. A handoff exchanged without an Origin header is bound to the public host. Tests: tests/integration/review-oauth.test.ts. The Google client lists https://platform.sondely.com/api/v1/auth/google/callback and the dev equivalent as redirect URIs (added by Chip on 9 November 2026).
• Apple is written new (TourCockpit has none): a form_post callback, the client secret as an ES256 JWT as today, and the id_token verified against Apple's published keys (issuer, audience, expiry, nonce) before any claim is read. The name arrives only on the first authorization and is saved then. Relay addresses (privaterelay.appleid.com) are treated as the account's email.
• Linking by email only when the provider says the email is verified. When a provider or a code proves an email whose account was never verified, any password on that account is cleared and its sessions are ended, so someone who registered with another person's email before them loses that access.

API keys

The new prefix is a decision below; the scope check lives in the registry guard, so a route with no key scope refuses every key.

Respondent grants

A grant replaces the auto-enroll token. Model RespondentGrant: id, tokenHash, organizationId, surveyId, email, userId (when the email has an email-only user), expiresAt (4 hours, as today), revokedAt, createdAt.

The take page already holds the token in memory and sends it on the session calls; A14 is the one call that must start sending it (frontend/src/pages/SurveyTakePage.tsx, line 113 posts without a bearer today).

Rate limiting

TourCockpit's limiter (src/lib/auth/rate-limit.ts) is a fixed window in memory, written for one replica. Sondely runs up to three, so its copy keeps the same interface over a shared store: a RateLimitBucket table with one upsert per hit, or an in-memory limiter behind a single-replica setting (a decision below).

Every refusal is 429 RATE_LIMITED with Retry-After, class retry.

CORS

Today backend/app/main.py passes allow_origins=["http://localhost:6291", "http://127.0.0.1:6291", "*"] with allow_credentials=True, allow_headers=["*"] and expose_headers=["*", ...]. Starlette then echoes the caller's origin back with credentials allowed. The cors_origins setting in config.py is not used. Because the token sits in localStorage rather than a cookie, a hostile page cannot ride the session today; it would the day the cookie arrives.

After: the app is one origin per host (Next serves the screens and the API, custom domains included), so /api/v1 sends no CORS headers to browsers by default. An explicit allowlist from configuration covers anything that must call from another origin; * is never combined with credentials. API keys are server-to-server and need no CORS.

Security holes today and how the new design closes each

The first four are the ones named in Sondely as an Agent, step 0, which Chip has accepted for now. The rest were found reading the code for this page and have no decision yet.

Open decisions

Legacy ip_live_ keys

Every existing key is stored as a bcrypt hash keyed by a 12-character prefix, so it cannot be turned into the new SHA-256 hash without the key itself. Keys are also unscoped today, so any carried-over key needs an organization and a scope assigned.

Either way new keys get a new prefix (proposed sd_live_) so the two kinds are told apart at a glance.

"/me with no memberships means admin"

In code:

• backend/app/api/auth/routes.py, lines 870 to 871, in A16: is_admin = any(r["role"] in ("OWNER", "ADMIN") for r in roles) or len(roles) == 0. The comment says "Admin if OWNER/ADMIN in any org, or new user with no memberships".
• backend/app/api/dashboard/routes.py, lines 35 to 38, in D1: the admin dashboard is shown to admins and owners "OR new users with no memberships"; the respondent dashboard only to users whose every role is RESPONDENT.
• frontend/src/contexts/AuthContext.tsx, lines 31 to 32, reads is_admin as is; AdminRoute in frontend/src/App.tsx (lines 69 to 93) sends anyone without it to /dashboard.

What it does: a person who signs up at sondely.com belongs to no organization, so they get the admin screens and can create their first one (O1 accepts any signed-in user). It is a screen rule only: every server route still checks the role in the organization concerned, so it grants no data. Its side effect is that anyone with no membership, for example a person who signed in by code only to see their own results, lands on an empty admin dashboard instead of the respondent one.

Smaller ones