fix: harden widget SSO JWT token verification

docs/widget-sso.md

@@ -22,22 +22,34 @@ Secrets are **never auto-created** — merely probing an org id cannot materiali
 | Claim | Value | Why |
 | --- | --- | --- |
 | `aud` | **Your workspace id** (from the widget config) | Pins the token to exactly one workspace. A token minted for workspace A is rejected at workspace B even if both secrets leaked. |
-| `userId` | Your stable id for this user | Used as the contact's `externalId` and to dedupe the SSO user. |
+| `sub` | Your stable id for this user | Used as the contact's `externalId` and to dedupe the SSO user. |
 | `email` | User's email | Required; the SSO session and contact are keyed on it. |
 | `name` | Display name | Required. |
+| `exp` | UNIX timestamp; keep it short (≤ 5 minutes is plenty) | **Required and enforced.** Tokens without `exp` are rejected. |
 
 `aud` must be a **single string** — an array or a missing/`iss`-only token is rejected.
 
+`sub` replaced the legacy `userId` claim. `userId` is still **accepted as a fallback** while customers migrate, but a token carrying **both** `sub` and `userId` with different values is rejected as a conflict. The `userId` fallback is scheduled for removal **after 2026-12-31** — mint `sub` in new integrations today.
+
+### Enforced at verification time
+
+Beyond the signature and the required claims, `verifyJwt` enforces (all failures map to `INVALID_JWT`):
+
+- **`exp` required** — a token without it is rejected after the signature verifies.
+- **Total lifetime capped**: `exp - iat` (or `exp - now` when `iat` is absent) may not exceed the workspace cap — **24 hours by default**, overridable per workspace via `organization.jwt_max_token_lifetime_minutes` (contact support to tighten it; shortening the cap is the only supported direction). A token claiming `exp = now + 30 days` is rejected even though the signature is valid. Keep minting short-lived tokens (≤ 5 minutes); the cap only bounds the worst case for a leaked token.
+- **`iat` not in the future** — more than 30s ahead of Feeblo's clock is rejected.
+- **30s clock-skew leeway** for `exp`/`nbf`/`iat` checks, so a slightly-skewed issuer clock does not break sign-ins.
+
 ### Recommended claims
 
 | Claim | Value | Why |
 | --- | --- | --- |
-| `exp` | UNIX timestamp; keep it short (≤ 5 minutes is plenty) | Not required, but **strongly recommended**: if present it is validated (an expired token is rejected), it bounds the 24h rotation grace window, and it limits how long a leaked token stays valid. |
+| `iss` | Your app URL (e.g. `https://app.example.com`) | Not verified yet — the issuer is stored unverified. Setting it now means the workspace can be migrated to issuer verification (planned to be promoted to required) without a second token change. Until then it is informational only. |
 
 ### Optional claims
 
 - `avatar` — profile image URL.
-- Custom attribute values and nested `companies` (see `packages/domain/src/contact/utils.ts` `parsePersonAttributes` for the exact shape; attribute definitions are configured per workspace).
+- Custom attribute values and nested `companies` (see `packages/domain/src/contact/utils.ts` `parsePersonAttributes` for the exact shape; attribute definitions are configured per workspace). Attribute values must be **JSON scalars** (string, number, boolean, null); arrays and nested objects are **ignored** — they are never persisted or rendered.
 
 ## Example (Node.js, `jose`)
 
@@ -48,21 +60,23 @@ const workspaceId = process.env.FEEBLO_WORKSPACE_ID; // from the widget config
 const secret = process.env.FEEBLO_SSO_SECRET; // from Settings → Security (64-char hex)
 
 const token = await new SignJWT({
-  userId: user.id,
+  sub: user.id,
   email: user.email,
   name: user.name,
   // custom attributes: { email: { value: user.plan } } …
 })
   .setProtectedHeader({ alg: "HS256" })
   .setAudience(workspaceId) // REQUIRED — binds to the workspace
-  .setExpirationTime("5m") // strongly recommended, optional
+  .setIssuer("https://app.example.com") // recommended — issuer verification coming
+  .setIssuedAt() // recommended — required for the lifetime cap to use real mint time
+  .setExpirationTime("5m") // REQUIRED
   .sign(new Uint8Array(Buffer.from(secret, "hex")));
 ```
 
 ## Rotation & revocation
 
 - **Rotate** (Settings → Security): the current secret is revoked and a new one becomes active. Tokens signed with the previous secret keep verifying for a **24-hour grace period**, so rotate at a low-traffic moment and mint tokens with short `exp` values.
-- **Revoke immediately**: the secret is dropped right away; tokens signed with it stop working immediately.
+- **Revoke immediately**: the secret is dropped right away (its tokens stop verifying immediately), and a new secret is generated. The grace period still applies to the immediately-revoked secret.
 - Only the active secret plus the most recent grace-period secret are ever accepted. Expired revoked secrets are pruned.
 
 ## Error codes
@@ -72,22 +86,24 @@ The SSO endpoint maps failures to better-auth errors via the `jwt-auto-login` pl
 | Code | Meaning |
 | --- | --- |
 | `ORGANIZATION_HAS_NO_JWT_SECRET` | No secret generated yet; generate one in Settings → Security. |
-| `INVALID_JWT` | Signature invalid, wrong `aud`, an expired `exp` (when present), or wrong/leaked secret. |
-| `SSO_TOKEN_MISSING_EMAIL_OR_NAME` | Required `email`/`name` (or `userId`) missing. |
+| `INVALID_JWT` | Signature invalid, wrong/missing `aud`, missing `exp`, expired `exp` (beyond leeway), `iat` too far in the future, token lifetime beyond the workspace cap, conflicting `sub`/`userId`, or wrong/leaked secret. |
+| `SSO_TOKEN_MISSING_EMAIL_OR_NAME` | Required `email`/`name` (or `sub`) missing. |
 | `FAILED_TO_CREATE_SSO_USER` / `FAILED_TO_CREATE_SSO_CONTACT` | Persistence failure while upserting the user/contact. |
 | `SSO_RATE_LIMITED` | Too many SSO attempts within the rate-limit window (429): unauthenticated attempts are limited by trusted client IP, and verified sign-ins are limited by workspace. |
 | `SSO_RATE_LIMIT_UNAVAILABLE` | The SSO rate limiter is unavailable (503). |
 
 ## Security notes
 
 - **`aud` binding is required, not optional.** The per-workspace secret already prevents cross-workspace forgery; `aud` is defense-in-depth that keeps the tenant binding intact even if a verification path ever runs against a pool of secrets or a stateless edge verifier derives the workspace from the token.
-- Mint tokens **on-demand, per request**, with a short `exp` — never long-lived API keys. (Enforced `exp` is not part of the contract, so treat it as your own mitigation for leaked tokens.)
+- Mint tokens **on-demand, per request**, with a short `exp` — never long-lived API keys. `exp` and the lifetime cap are enforced server-side, so a leaked token now ages out on a fixed schedule no matter what the minting side does.
 - The signing secret is a tenant credential: keep it in server-side config only, never ship it to the browser.
 - SSO sessions are restricted to the workspace (`restrictedToOrganizationId`) and cannot be used to access the dashboard.
+- Prefer passing the SSO token in a fragment (`data-feeblo-link` widget flow) over a query string: query strings leak into logs, history and the `Referer` header, and a token in a URL is replayable until it expires.
 
 ## Tests
 
 The contract is locked by tests:
 
-- `packages/domain/src/jwt-secret/verification.test.ts` — claim-level rules (wrong/missing `aud`, `exp` optional but expired tokens rejected when `exp` is present, wrong secret).
-- `packages/domain/src/widget/sso.test.ts` — end-to-end `createSsoSession` against a real database (valid token creates a restricted user; mismatched `aud`, missing `aud`, expired token, foreign secret, and no-secret cases all behave as documented).
+- `packages/domain/src/jwt-secret/verification.test.ts` — claim-level rules (wrong/missing `aud`, missing `exp`, expired `exp`, future `iat`, clock-skew leeway, 24h lifetime cap, per-workspace cap override, wrong secret).
+- `packages/domain/src/widget/sso.test.ts` — end-to-end `createSsoSession` against a real database (valid token creates a restricted user; mismatched `aud`, missing `aud`, missing `exp`, expired token, overlifetime token, per-org cap, foreign secret, and no-secret cases all behave as documented).
+- `packages/domain/src/contact/utils.test.ts` / `jwt-parsing.test.ts` — `sub`/`userId` resolution and conflict rejection, scalar-only custom attribute values.

packages/db/src/migrations/20260823045922_jwt_max_token_lifetime/migration.sql

@@ -0,0 +1 @@
+ALTER TABLE "organization" ADD COLUMN "jwt_max_token_lifetime_minutes" integer;