dogfood: auth() returns a loosely-typed session (user is Record<string, unknown>)

[vivek7405]

Problem

auth() returns a session whose user is typed as Record<string, unknown>. Custom fields set in the session callback — e.g. session.user.id, session.user.username — therefore have type unknown, so reading them requires a cast at every call site:

const session = await auth();
const userId = Number((session.user as { id?: number }).id); // forced cast

An AI writing route handlers/pages has to guess the field names and cast; TypeScript won't catch a typo (session.user.usrname). The real shape is already defined imperatively in the session/jwt callbacks (crisp does session.user.id = token.uid), but that shape isn't reflected back into auth()'s return type. This came up at nearly every gated route in the crisp rewrite.

Design / approach

Let an app declare its session/user shape and have auth() return it typed. Options (either, or both):

• Module augmentation (NextAuth/Auth.js-style): declare module '@webjsdev/server' { interface Session { user: { id: number; username: string; ... } } }, which auth()'s return type picks up.
• Generic: createAuth<TUser>({...}) whose auth() returns { user: TUser } | null.

Document the pattern in the auth recipe so agents use it by default.

Acceptance criteria

• An app can declare its session-user shape so auth() returns it typed (no cast for session.user.id).
• A wrong/misspelled field on session.user is a TypeScript error.
• The auth doc shows the augmentation/generic pattern.

[vivek7405]

Implementation notes (for the agent picking this up)

Where

• packages/server/src/auth.js — createAuth, the auth() return type, and the Session / User shapes.
• packages/server/src/session.js — Remix-style session types (if the user shape flows through here).
• Doc: docs/app/docs/auth/page.ts (auth recipe).

Do

• Let an app declare its session/user shape and have auth() return it typed. Either (or both): NextAuth-style module augmentation (declare module '@webjsdev/server' { interface Session { user: {...} } }), or a generic createAuth<TUser>() whose auth() returns { user: TUser } | null.
• Reflect the fields the session/jwt callbacks actually set (e.g. crisp sets session.user.id = token.uid).
• Document the pattern in the auth recipe so agents adopt it by default.

Don't

• Don't change any RUNTIME behavior — this is purely a TS-types DX change (types are erased at runtime; no-build is unaffected).
• Don't break existing untyped code: keep Record<string, unknown> (or equivalent) as the un-augmented default; typing is opt-in.

Verify

• An app augments Session → auth().user.id is typed (no cast); a misspelled field is a tsc/webjs typecheck error. This is enforced by typecheck, NOT webjs check.