Functional Weave
Code in Rust

auth.oauth-sign-in@1.0.0

README.md

4,262 bytes · view raw

# auth.oauth-sign-in

Sign users in with an OpenID Connect issuer (Google, Microsoft Entra ID,
Auth0, Okta, Keycloak) or with GitHub, using the OAuth 2.0 authorisation-code
flow with PKCE (RFC 7636, S256), and keep them signed in with a session
cookie signed by `SESSION_SECRET`. No database is needed for either cookie.

`AUTH_PROVIDER` picks the provider:

- **oidc** finds the issuer's endpoints by discovery
  (`OIDC_ISSUER/.well-known/openid-configuration`), checks the document is
  for that issuer, and asks for `OIDC_SCOPES` (`openid email profile` unless
  you say). A confidential client sends `OIDC_CLIENT_SECRET`
  (client_secret_post); a public client leaves it unset and relies on PKCE.
  The user comes from the id_token's claims: its issuer, audience, nonce and
  expiry are checked. Its signature is not, because it came straight from the
  token endpoint over TLS (OpenID Connect Core 1.0, section 3.1.3.7); never
  pass this function an id_token you received any other way.
- **github** uses a GitHub OAuth app (`GITHUB_CLIENT_ID`,
  `GITHUB_CLIENT_SECRET`) with PKCE, then reads `/user` and the primary
  verified address from `/user/emails`. GitHub reports a bad code with status
  200 and an `error` field; that is thrown like any other refusal.

## Wiring it up

```ts
// app/login/route.ts (Next.js)
import { beginSignIn } from "#fune/auth.oauth-sign-in@^1";

export async function GET() {
  const start = await beginSignIn("https://app.example.com/callback", "/dashboard");
  return new Response(null, { status: 302, headers: { location: start.url, "set-cookie": start.setCookie } });
}

// app/callback/route.ts
import { completeSignIn, createSession, sessionCookie } from "#fune/auth.oauth-sign-in@^1";
import { cookies } from "next/headers";

export async function GET(request: Request) {
  const signIn = (await cookies()).get("fune_signin")?.value ?? "";
  const user = await completeSignIn(request.url, signIn);
  // find or create the account by (user.provider, user.subject) here
  const headers = new Headers({ location: user.returnTo ?? "/" });
  headers.append("set-cookie", sessionCookie(createSession(user)));
  headers.append("set-cookie", "fune_signin=; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=0");
  return new Response(null, { status: 302, headers });
}

// anywhere: who is this?
const me = readSession((await cookies()).get("fune_session")?.value ?? null);
```

In Express it is the same three calls: `res.cookie`/`res.append('Set-Cookie', ...)`
for the headers, `req.protocol + '://' + req.get('host') + req.originalUrl`
for the callback URL. Signing out is `sessionCookie("", 0)`.

## What it checks, and what it leaves to you

- The sign-in cookie holds the state, the PKCE verifier, the nonce, the
  callback URL and `returnTo`, signed and valid for ten minutes. The callback
  must carry the same state, and must come back to the provider that began
  it. `returnTo` must be a path on your site, so it cannot become an open
  redirect.
- A session is the user's provider, subject, email and name, signed, with an
  expiry. It is readable by whoever holds it, so put nothing secret in it.
  It cannot be revoked one at a time: rotating `SESSION_SECRET` signs
  everyone out. If you need per-session revocation, store a session id in
  your database and keep it in the session's subject lookup.
- Key accounts on `provider` and `subject`, never on the email: emails
  change, and an unverified one (`emailVerified: false`) proves nothing.
- It does not fetch userinfo, refresh tokens, or call the provider's APIs on
  the user's behalf, and it does not do CSRF protection for your own forms
  (SameSite=Lax on the session cookie helps; it is not a token).

## Where the contract tests come from

The exchanges follow the providers' documentation: Google's published
discovery document and token response, Keycloak's endpoint layout, GitHub's
OAuth app flow (including its `bad_verification_code` error body) and its
`/user` and `/user/emails` shapes. Every client id and secret in them is a
fake. The PKCE challenges and the cookie signatures in the expected results
were computed independently with Node's crypto module. Before going live,
sign in once against the real provider from a staging deployment.