workos-auth/docs-tests: Document WorkOS auth and add readUserId tests

[x0ba]

Stack Context

This 3-PR stack migrates FlightLog from Clerk to WorkOS AuthKit while preserving cookie sessions for the dashboard and Bearer tokens for the SDK/API.

Stack: workos-auth/core (#51) → workos-auth/ui-shell (#52) → workos-auth/docs-tests

Why?

Env var names and API token docs need to match the new WorkOS auth model before merge. Unit tests for readUserId lock in cookie-vs-bearer precedence without requiring live JWT verification in CI.

What?

• Update .env.example and README for WorkOS env vars and WORKOS_ACCESS_TOKEN
• Rename auth-redirect test description (behavior unchanged)
• Add readUserId unit tests for session vs bearer precedence

Test plan

• bun run check
• bun run lint (src/ + README)
• bunx vitest run src/lib/server/auth.test.ts src/lib/auth-redirect.test.ts
• Integration tests require local Postgres (bun run db:up)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
flightlog	Error		May 29, 2026 8:24pm

[x0ba]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• workos-auth/docs-tests: Document WorkOS auth and add readUserId tests #53 👈 (View in Graphite)
• workos-auth/ui-shell: Add account dropdown to auth corner #52
• workos-auth/core: Replace Clerk with WorkOS AuthKit #51
• staging

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR completes the WorkOS AuthKit migration by updating .env.example and README.md to reflect the new environment variables and token model, and adds unit tests for the readUserId session-vs-bearer precedence logic introduced in the earlier stack PRs.

• Env/docs: Replaces all CLERK_* references with WORKOS_* vars and documents the cookie password generation command and redirect URI registration requirement.
• Tests: Three new readUserId unit tests cover cookie-session preference over bearer, bearer fallback when no session exists, and the unauthenticated (undefined) case — all assertions match the actual ??-chain implementation in auth.ts.
• Test rename: The auth-redirect test description is updated to drop the Clerk-specific label; no behavioral change.

Confidence Score: 5/5

Safe to merge — changes are documentation updates and additive unit tests with no production code modifications.

All three test assertions correctly reflect the actual ??-chain in readUserId, the env var and README updates are accurate, and no existing logic is touched.

No files require special attention.

Important Files Changed

Filename	Overview
src/lib/server/auth.test.ts	Adds three unit tests for readUserId covering cookie-session precedence, bearer fallback, and unauthenticated case; all assertions correctly reflect the ?? chain in the implementation
src/lib/auth-redirect.test.ts	Single description rename to drop Clerk-specific wording; no logic changes
README.md	Replaces all Clerk references with WorkOS equivalents and documents cookie-password generation and bearer-token acquisition; content is accurate
.env.example	Swaps Clerk env vars for the four required WorkOS vars with a sensible default redirect URI

Sequence Diagram

sequenceDiagram
    participant Client
    participant SvelteKit as SvelteKit Hooks
    participant Auth as auth.ts
    participant WorkOS as WorkOS API

    Note over Client,WorkOS: Cookie session (dashboard)
    Client->>SvelteKit: Request with session cookie
    SvelteKit->>Auth: readUserId(event)
    Auth-->>SvelteKit: event.locals.auth.user.id

    Note over Client,WorkOS: Bearer token (SDK / API)
    Client->>SvelteKit: Request with Authorization: Bearer token
    SvelteKit->>Auth: authenticateBearer(event)
    Auth->>WorkOS: jwtVerify(token, JWKS)
    WorkOS-->>Auth: payload.sub
    Auth-->>SvelteKit: event.locals.bearerUserId
    SvelteKit->>Auth: readUserId(event)
    Auth-->>SvelteKit: bearerUserId (cookie absent → fallback)

    Note over Client,WorkOS: Unauthenticated
    Client->>SvelteKit: Request (no auth)
    SvelteKit->>Auth: readUserId(event)
    Auth-->>SvelteKit: undefined
    SvelteKit-->>Client: 401 / redirect /sign-in

Loading

_{Reviews (1): Last reviewed commit: "Document WorkOS auth setup and add readU..." | Re-trigger Greptile}