feat(widget): scope sessions by audience (upstream batch D)

[theRealBithive]

What changes in the running service

Upstream QuackbackIO#547 (99fb7a1d2), cherry-picked with -x. Every session now carries
the audience it was minted for — dashboard, widget or portal — and only a
dashboard session can satisfy a team or permission gate.

The bug it closes: a widget-minted session shared one credential universe with
dashboard sessions, so the identify-time staff guard was the only thing stopping
a widget token from passing requireAuth and requireWorkspaceRole. A
principal promoted to staff after identify kept its seven-day widget session,
and the promoted role then passed those gates.

• Migration 0280_widget_session_scope adds session.scope, backfills it, and
  installs a trigger that re-stamps a session when its widget provenance lands.
• /api/widget/identify mints scope=widget and never reuses a dashboard
  session; the lazy anonymous sign-in is tagged through a Better Auth hook.
• The one-time-token handoff promotes the session to portal before the cookie.
• Bare requireAuth() / getOptionalAuth() present a widget or portal session's
  principal as an ordinary user with no permissions.
• Stream tokens bind the audience, and a token that names none is refused.
• The import/export API and the onboarding administrator gates refuse a
  non-dashboard session.

After deploying, some sessions end. The backfill is deliberately
conservative: a false positive costs a re-login, a false negative leaves a widget
token dashboard-capable.

One deliberate divergence from upstream, on request

Upstream's toSessionScope answers dashboard for any value it does not
recognise. That makes the most privileged audience the fallback: a session whose
scope column was written by a replica that predates the column, or written
wrongly, comes back with full team authority. Here it answers with the least
authority an audience can carry instead.

What an operator notices: a session carrying an audience nothing wrote loses
staff authority until the next sign-in. Nothing else changes — every gate in the
product asks === 'dashboard', so the new fallback behaves exactly like the two
audiences that already existed, and there is no path in the product that writes
a fourth value. portal rather than a new member of the union, because the type
travels into the client bootstrap payload and into the signed stream token.

mintStreamToken loses its scope default for the same reason: upstream
defaults it to dashboard, so a caller that forgets the argument mints the most
privileged token. There is one caller and it passes the audience it
authenticated, so the compiler holds it instead.

Migration numbering has re-converged

0280 keeps upstream's number and its when. Our journal ends at idx 256 /
0279_better_auth_17 and so does upstream's — the two files we renumbered and
the one we skipped cancel out. First pick since #29 that needed no renumbering.

615e4da2b is skipped

It fixes the bug this fork already fixed in #14 (d20bda577) eight days earlier
and more completely: same root cause, plus the swallowed rejection beside it,
with diff coverage and a mutation score. Upstream's version carries one thing
ours did not — it validates each page, not only that pages is an array — and
that check is adopted here on its own terms rather than as a re-import (R13).

The contract

Confirmed before the tests were written; the list is verbatim in
lib/server/functions/__tests__/auth-scope.test.ts and every test names its
number.

#	Guarantee	Held in
R1	A session is stamped with the audience it was minted for	auth/__tests__/session-scope-on-create.test.ts, session-scope-backfill.db.test.ts
R2	Only a dashboard session satisfies a team or permission gate	auth-scope.test.ts, workspace-utils.redirect.test.ts, upload/__tests__/image.test.ts, chat/__tests__/stream.test.ts, oauth-callback-audience.test.ts
R3	A principal promoted after the widget minted its session gains no dashboard authority on it	auth-scope.test.ts, widget-auth.test.ts
R4	A widget identify never reuses a dashboard session	widget/__tests__/identify-session-audience.test.ts
R5	The lazy anonymous sign-in gets a widget session	session-scope-on-create.test.ts
R6	The handoff promotes to portal before the cookie is set	auth.widget-handoff-promotion.test.ts, routes/__tests__/auth.widget-handoff.test.ts
R7	A bare auth helper presents a non-dashboard principal as an ordinary user	auth-scope.test.ts, resolve-portal-access.test.ts
R8	A stream token carries its audience; one naming none is refused	realtime/__tests__/stream-token.test.ts, conversation-stream-token.fn.test.ts
R9	Import/export and the onboarding admin gates refuse a non-dashboard session	workspace-api-access.test.ts, onboarding-admin-promotion.fn.test.ts, oauth-callback-audience.test.ts
R10	Re-running the migration changes nothing, and each kind of session lands on the right audience	session-scope-backfill.db.test.ts
R11	A session minted by an old replica is re-stamped when its provenance row lands	session-scope-backfill.db.test.ts
R12	An unrecognised audience carries no dashboard authority	auth-scope.test.ts, roles.test.ts, oauth-callback-audience.test.ts
R13	A cached inbox entry is patched only when it really is a page of posts	mutations/__tests__/inbox-list-cache.test.ts

Three of those needed more than assertions.

• R5 could not be reached at all. Upstream's rule is an arrow function inside
  the betterAuth({ … }) literal, and nothing in the repository executes a hook
  body there — measured, no statement between lines 540 and 660 of
  auth/index.ts is covered by any of the 43 suites in that directory. It moves
  into auth/session-scope.ts and is passed by reference, the way
  guardBetterAuthUserCreation already is; the new suite asserts both the rule
  and that the options object really carries it.
• R10 and R11 are claims about rows, and the checks next to them are not.
  replay-safety.test.ts reads the SQL; lineage-double-apply.db.test.ts
  re-applies every safe migration and compares catalogues. So the backfill and
  the trigger get a real-Postgres suite that seeds each kind of session, forces
  the column back to its default, and runs the migration's own DO block —
  taken from the file rather than restated, since a copy would agree with itself.
• R6 is an ordering, and the suite beside it exercises a hand-kept mirror of
  the route rather than the route — a mirror can agree with a test while
  disagreeing with the code it mirrors. The mirror keeps the branch cases, and
  the production handler is now captured from createServerFn and driven, with
  the promotion and the Set-Cookie forward recorded in one ordered log. The
  source-text check stays alongside it: the two fail for different reasons, one
  surviving a refactor of the test double and the other a rewording of the
  source.

One thing to decide, not changed here

The handoff's promotion to portal is best-effort — upstream wraps it in a
try/catch that logs and carries on, so a failed update still installs the
cookie. It is currently harmless: the session being promoted was minted by
widget identify, which already writes scope: 'widget', so a failed promotion
leaves it non-dashboard and every gate still refuses it. Worth knowing rather
than fixing blind.

Gates

Every number below was measured on this branch, not carried over.

Gate	Result
Diff coverage	PASS — 59 of 59 added lines executed, 0 never executed, across 21 judged files
Mutation	PASS — 5 graded files, 201 mutants, 93.53%, 13 excused as equivalent, 0 unjustified survivors (1m51s)
bun run typecheck	0 errors
bun run lint	0 errors (48 pre-existing warnings)
bun scripts/i18n-check.ts	PASS
bunx tsc --noEmit -p scripts/tsconfig.json	0 errors
bun run --cwd packages/db typecheck	0 errors
bun run db:check-drift	"No drift: migrations and TS schema are in sync."
CONTRACT.md	regenerated; the diff is the scanned count and nothing else
Prettier	clean on every changed and new file

The first coverage figure came from a full four-shard run; the three holes it
named were real rather than shard flake, and the last commit closes them.

Fifteen touched files are named by the mutation gate as not graded, and stay
that way. That is the gate working as designed rather than a gap being
skipped: an entry in mutation-manifest.json asserts that the listed suites pin
the whole file, and these are files this change passes through rather than
files it is about — conversation.ts is 1,749 lines and this batch touches one
of them. The exception worth naming is functions/auth-helpers.ts, which is
where the R12 flip actually lands: its wiring is held behaviourally by
auth-scope.test.ts, and the decision it wires up is graded at 98.11% in
roles.ts. Grading the file itself would mean writing tests for its
cookie-sniffing and settings-read halves, which this change never touches, and
widening a repository-wide gate as a side effect of a pick.

Six suites went red in the local four-shard run and none of them belong to this
branch. Five are the 11x entry in SELF-IMPROVE.md — settings.test.ts,
email-inbound-route.test.ts, archive.test.ts, module-state.test.ts and
singletons-not-shared.test.ts each hit a 20-to-36-second timeout under
parallel load — and all five pass when the six are re-run together on their own.
The sixth, sns-signature.test.ts, fails for an environmental reason with
nothing to do with the change: this Fedora host's OpenSSL policy refuses
RSA-SHA1, so signing the fixture throws invalid digest. CI's runner does not
have that policy.

🤖 Generated with Claude Code