/fastify-better-auth-bridge

Fastify Better Auth Bridge

When to Use

Load this skill for: the user asks to "bridge Better Auth into Fastify", "fix Fastify session resolution", "forward auth cookies", "patch IDCS org context", or "decorate Fastify request auth".

Prefer this skill only for its named domain. For broader OCI architecture triage, start with oci/best-practices as the router.

Wire Better Auth session resolution into Fastify 5 via the onRequest hook. Use this when Better Auth already exists but Fastify lacks the framework bridge.

Do NOT load this skill when

• The problem is callback URL configuration, trusted origins, or provider bootstrap order
• The problem is IDCS group mapping or org_members provisioning rules
• The goal is to build a parallel session system alongside Better Auth

NEVER

• Never build a parallel session layer when cookie header forwarding is all that's needed — the symptom (no session) and the fix (forward cookies) are separated by two layers, making it easy to misdiagnose.
• Never enforce RBAC policy inside the bridge onRequest hook — the bridge resolves identity, route guards enforce access. Mixing them makes both untestable.
• Never share mutable array decorator defaults in Fastify 5 — arrays on the prototype are shared across all requests; use a Symbol-backed getter/setter per-request.
• Never skip the Web Request bridge — auth.api.getSession() requires a native Web API Request, not a Fastify request object. Passing the wrong type silently returns no session.
• Never assume reply.send(undefined) is safe in Fastify 5 — it throws.

The Non-Obvious Parts

Why cookie forwarding breaks silently

Missing cookie headers make login and session resolution fail in completely different places — the login succeeds (sets cookie in browser) but the next request has no session. There's no error; the session is simply null. The bridge and the login flow look unrelated. Always verify cookies are included in the Web Request you build.

Why Fastify 5 decorator arrays share state

fastify.decorateRequest('permissions', []) — the [] is a prototype default shared across all requests. First request mutates it; second request sees the previous request's permissions. Use a Symbol-keyed getter/setter that allocates a fresh array per request.

Why IDCS users have no active org

IDCS-provisioned users are created via group sync, not Better Auth's organization-switch flow. Their session has no activeOrganizationId. Downstream code expecting org context will silently receive undefined. Patch by querying org_members when activeOrganizationId is absent.

Required Bridge Shape

Step 1: Web Request bridge Build from protocol + hostname + URL + method + full incoming headers. The headers must include cookie — that's the only way auth.api.getSession() can resolve a session.

Step 2: Decorate request state once Standardize: request.user, request.session, request.permissions, request.apiKeyContext. Use Symbol-backed getter/setter for any field that holds an array or mutable object.

Step 3: Path exclusions Skip session resolution only for: health, metrics, Better Auth handler routes. Normalize query strings and trailing slashes before matching — inconsistent normalization creates auth misses on some routes only.

Step 4: Resolve session, then continue as anonymous on error If auth.api.getSession() throws: log it, continue with request.user = null. Never reject the request at bridge level — that's the route guard's job.

Step 5: Patch org context If request.session.activeOrganizationId is absent, query org_members by user ID and set the org context downstream. Only do this when org context is genuinely absent — not as a default fallback on every request.

Diagnostic Script

node scripts/check-fastify-auth-bridge.js /path/to/auth-plugin.ts
# Defaults to apps/api/src/plugins/auth.ts if no argument given

Arguments

$ARGUMENTS: Optional path to the Fastify auth plugin file to inspect. Empty = use repo-default path (apps/api/src/plugins/auth.ts).