slauthjs 0.0.0-stage → 2.0.0

package/src/index.d.ts

@@ -0,0 +1,364 @@
+/** A key-value store: the only thing slauth needs from your database. */
+export interface Store {
+  get(key: string): Promise<any>
+  /** ttl is in seconds. */
+  put(key: string, value: unknown, options?: { ttl?: number }): Promise<void>
+  delete(key: string): Promise<void>
+  /** Optional: keys starting with `prefix`, in order. Only needed for auth.users.list(). */
+  list?(prefix: string, options?: { limit?: number; cursor?: string | null }): Promise<{ items: { key: string; value: any }[]; cursor: string | null }>
+}
+
+export type EmailKind = 'sign-in' | 'email-change' | 'invite'
+
+/** Sends slauth's emails. `subject`, `text` and `html` are ready to use. */
+export interface EmailSender {
+  send(message: { to: string; kind: EmailKind; code?: string; link?: string; appName: string; subject: string; text: string; html: string }): Promise<void>
+}
+
+/** What the browser, auth.user() and your event handlers see. */
+export interface SlauthUser {
+  id: string
+  email: string
+  name: string | null
+  image: string | null
+  /** Set on the server (auth.users.update); checked by requireUser(request, { role }). */
+  roles: string[]
+  /** Yours to fill on the server; sent to the browser. */
+  metadata: Record<string, unknown>
+  createdAt: number
+}
+
+/** The whole record, for server code only. */
+export interface StoredUser extends SlauthUser {
+  /** Never sent to the browser. */
+  privateMetadata: Record<string, unknown>
+  updatedAt: number
+  bannedAt: number | null
+}
+
+export interface Profile {
+  id: string
+  email?: string | null
+  emailVerified?: boolean
+  name?: string | null
+  image?: string | null
+}
+
+/** A "Sign in with …" provider; make one with the helpers in 'slauthjs/providers'. */
+export interface Provider {
+  id: string
+  name: string
+  clientId: string
+  clientSecret?: string
+  authorization: string
+  token: string
+  scope?: string
+  params?: Record<string, string>
+  pkce?: boolean
+  tokenAuth?: 'post' | 'basic'
+  /** Count the provider's email as verified even when it doesn't say so. Only for providers you trust. */
+  trustEmail?: boolean
+  /** Save the provider's access and refresh tokens, for auth.accounts.list(). */
+  keepTokens?: boolean
+  profile(tokens: Record<string, any>, fetch: typeof globalThis.fetch): Promise<Profile>
+}
+
+export interface SignInContext {
+  method: 'email' | 'link' | 'password' | 'passkey' | 'oauth' | 'access' | 'session' | 'email-change'
+  provider?: string
+  profile?: Profile
+  user?: SlauthUser
+}
+
+export interface SlauthEvents {
+  signUp?(event: { user: SlauthUser; method: string; request?: Request }): unknown
+  signIn?(event: { user: SlauthUser; method: string; request: Request }): unknown
+  signOut?(event: { user: SlauthUser; request: Request }): unknown
+  userUpdated?(event: { user: SlauthUser }): unknown
+  userDeleted?(event: { user: SlauthUser }): unknown
+}
+
+export interface SlauthConfig {
+  /** A random string of 16+ characters. Make one with: openssl rand -base64 32 */
+  secret: string
+  /** Where users, sessions and passkeys live: memory(), d1(env.DB), kv(env.KV), sqlite(db), or your own. */
+  store: Store
+  /** How codes are emailed. Defaults to printing them to the console. */
+  email?: EmailSender
+  /** Your own wording for the emails. Return null to keep slauth's. */
+  emails?: (kind: EmailKind, data: { code?: string; link?: string; appName: string; minutes?: number; orgName?: string; inviter?: string }) => { subject: string; text: string; html: string } | null | Promise<{ subject: string; text: string; html: string } | null>
+  /** Shown in emails and as the passkey's site name. */
+  appName?: string
+  /** Who may sign in: a list of emails ("@family.com" for a whole domain) or a function. Everyone, if left out. */
+  allow?: string[] | ((email: string, context: SignInContext) => boolean | Promise<boolean>)
+  /** Where the routes live. Default "/auth". */
+  basePath?: string
+  /** Your site's address for links in emails and provider callbacks, e.g. "https://myapp.dev". Default: the request's origin. */
+  baseUrl?: string
+  /** The page with your sign-in box; provider errors and two-factor steps come back here. Default: the page the person started on. */
+  signInPage?: string
+  /** Session cookie name. Default "slauth_session". */
+  cookie?: string
+  /** Sessions last this many days after the last visit. Default 30. */
+  sessionDays?: number
+  /** Adding a passkey or password, changing email, turning on two-factor or deleting the account need a sign-in this recent. Default 15; false to skip. */
+  freshMinutes?: number | false
+  /** Origins allowed to post to the routes (and to use passkeys). Default: the request's own origin. */
+  origins?: string | string[]
+  /** Passkey settings, or false to turn passkeys off. */
+  passkeys?:
+    | false
+    | {
+        /** The site passkeys belong to, e.g. "myapp.dev" (works for every subdomain). Default: the request's hostname. */
+        rpId?: string
+        rpName?: string
+        origin?: string | string[]
+        userVerification?: 'required' | 'preferred' | 'discouraged'
+      }
+  /** "Sign in with …": github(), google(), oidc() and friends from 'slauthjs/providers'. */
+  providers?: Provider[]
+  /** Put a one-tap sign-in link in the code email too. */
+  magicLinks?: boolean
+  /** Let people sign in with a password (after proving their email once). */
+  passwords?: boolean | { minLength?: number; iterations?: number; validate?: (password: string) => string | null | Promise<string | null> }
+  /** Let people turn on an authenticator app (TOTP) with recovery codes. */
+  twoFactor?: boolean | { issuer?: string }
+  /** Short-lived JWTs for your other services, checked with /auth/jwks.json. */
+  tokens?: boolean | { minutes?: number; issuer?: string; audience?: string; claims?: (user: SlauthUser) => Record<string, unknown> | Promise<Record<string, unknown>> }
+  /** Teams with members, roles and email invitations. */
+  organizations?: boolean | { allowCreate?: boolean | ((user: SlauthUser) => boolean | Promise<boolean>); invitePage?: string }
+  /** Per-IP limits on code, password and two-factor routes; false to turn off. */
+  rateLimit?: false | { limits?: Record<string, [requests: number, seconds: number]>; ip?: (request: Request) => string | null }
+  /** Let people delete their own account at POST /auth/user/delete. Default true. */
+  allowDeletion?: boolean
+  /** Things to do when people sign up, sign in, and so on. */
+  on?: SlauthEvents
+  /** For providers' HTTP calls; handy in tests. */
+  fetch?: typeof globalThis.fetch
+  /** Also accept people signed in by Cloudflare Access. */
+  access?: { team: string; aud: string | string[]; devUser?: string; fetch?: typeof fetch }
+  /** Turn on the PIN app lock. true = off by default for each person; or set their default. */
+  lock?: true | { default?: Policy; cookie?: string }
+}
+
+export interface SessionInfo {
+  id: string
+  createdAt: number
+  lastActiveAt: number
+  method: string | null
+  userAgent: string | null
+  ip: string | null
+  impersonatorId: string | null
+}
+
+export interface LinkedAccount {
+  provider: string
+  accountId: string
+  userId: string
+  email: string | null
+  name: string | null
+  createdAt: number
+  updatedAt: number
+  tokens?: Record<string, any> & { savedAt: number }
+}
+
+export type OrgRole = 'owner' | 'admin' | 'member' | (string & {})
+
+export interface Org {
+  id: string
+  name: string
+  metadata: Record<string, unknown>
+  createdAt: number
+  createdBy: string | null
+}
+
+export interface OrgMember {
+  userId: string
+  role: OrgRole
+  joinedAt: number
+}
+
+export interface OrgInvite {
+  id: string
+  orgId: string
+  email: string
+  role: OrgRole
+  invitedBy: string | null
+  createdAt: number
+  expiresAt: number
+}
+
+export interface TokenClaims extends Record<string, unknown> {
+  sub: string
+  email: string
+  name: string | null
+  roles: string[]
+  iat: number
+  exp: number
+}
+
+export interface Slauth {
+  /** Answers every request under basePath (404 for anything else). */
+  handle(request: Request): Promise<Response>
+  /** The signed-in person, or null. Ignores the app lock. Reads the cookie, a bearer session token, or (with tokens on) a JWT. */
+  user(request: Request): Promise<SlauthUser | null>
+  /** The signed-in, unlocked person (with one of these roles), or a 401/403 Response to return as it is. */
+  requireUser(request: Request, options?: { role?: string | string[] }): Promise<SlauthUser | Response>
+  /** The user and their session (null for Access or a JWT), or null. */
+  session(request: Request): Promise<{ user: SlauthUser; session: { id: string; userId: string; createdAt: number; method: string | null; impersonatorId: string | null } | null } | null>
+  store: Store
+
+  users: {
+    get(id: string): Promise<StoredUser | null>
+    byEmail(email: string): Promise<StoredUser | null>
+    /** Needs a store with list() (all the built-in ones have it). */
+    list(options?: { limit?: number; cursor?: string | null }): Promise<{ users: StoredUser[]; cursor: string | null }>
+    create(user: { email: string; name?: string | null; image?: string | null; roles?: string[]; metadata?: Record<string, unknown>; privateMetadata?: Record<string, unknown> }): Promise<StoredUser>
+    update(id: string, patch: Partial<Pick<StoredUser, 'email' | 'name' | 'image' | 'roles' | 'metadata' | 'privateMetadata'>>): Promise<StoredUser | null>
+    /** Removes the user and their sessions, passkeys, providers, password, two-factor and memberships. */
+    delete(id: string): Promise<boolean>
+    ban(id: string): Promise<StoredUser | null>
+    unban(id: string): Promise<StoredUser | null>
+  }
+
+  sessions: {
+    list(userId: string): Promise<SessionInfo[]>
+    revoke(userId: string, sessionId: string): Promise<boolean>
+    revokeAll(userId: string): Promise<void>
+    /** Signs someone in without asking: your own sign-in methods, tests, or impersonation. */
+    create(userId: string, request: Request, options?: { method?: string; impersonatorId?: string | null }): Promise<{ cookie: string; token: string }>
+  }
+
+  accounts: {
+    list(userId: string): Promise<LinkedAccount[]>
+  }
+
+  /** Null unless `passwords` is on. */
+  passwords: null | {
+    set(userId: string, password: string): Promise<void>
+    remove(userId: string): Promise<void>
+    has(userId: string): Promise<boolean>
+    hash(password: string): Promise<string>
+  }
+
+  /** Null unless `twoFactor` is on. */
+  twoFactor: null | {
+    enabled(userId: string): Promise<boolean>
+    /** For support: when someone has lost their phone and their recovery codes. */
+    disable(userId: string): Promise<void>
+  }
+
+  /** Null unless `organizations` is on. */
+  orgs: null | {
+    create(org: { name: string; metadata?: Record<string, unknown> }, ownerId?: string): Promise<Org>
+    get(orgId: string): Promise<Org | null>
+    update(orgId: string, patch: { name?: string; metadata?: Record<string, unknown> }): Promise<Org | null>
+    delete(orgId: string): Promise<void>
+    forUser(userId: string): Promise<(Org & { role: OrgRole })[]>
+    members(orgId: string): Promise<OrgMember[]>
+    role(orgId: string, userId: string): Promise<OrgRole | null>
+    addMember(orgId: string, userId: string, role?: OrgRole): Promise<boolean>
+    setRole(orgId: string, userId: string, role: OrgRole): Promise<boolean>
+    removeMember(orgId: string, userId: string): Promise<boolean>
+    /** Saves an invitation (it doesn't email it; POST /auth/orgs/<id>/invite does both). */
+    invite(orgId: string, email: string, role?: OrgRole, invitedBy?: string | null): Promise<OrgInvite>
+    revokeInvite(inviteId: string): Promise<boolean>
+    /** The signed-in member (with one of these org roles), or a 401/403 Response to return as it is. */
+    require(request: Request, orgId: string, options?: { role?: OrgRole | OrgRole[] }): Promise<(SlauthUser & { orgRole: OrgRole }) | Response>
+  }
+
+  /** Needs `tokens` on. */
+  createToken(user: SlauthUser, extra?: Record<string, unknown>): Promise<{ token: string; expiresAt: number }>
+  /** The claims of a token slauth signed that hasn't expired, or null. Needs `tokens` on. */
+  verifyToken(token: string): Promise<TokenClaims | null>
+}
+
+export function slauth(config: SlauthConfig): Slauth
+export function memory(): Store
+export function consoleEmail(): EmailSender
+export function hashPassword(password: string, iterations?: number): Promise<string>
+export function verifyPassword(password: string, hash: string): Promise<boolean>
+/** The TOTP code for a base32 secret at a 30-second step (default: now). */
+export function totp(secret: string, step?: number): Promise<string>
+
+/** What createAccess and createLock work with. */
+export interface User {
+  /** Lower-cased email from the Access sign-in. */
+  email: string
+  /** Stable, opaque id: the same in every app for the same email. */
+  userId: string
+}
+
+export interface AccessOptions {
+  /** "yourteam" or "yourteam.cloudflareaccess.com". */
+  teamDomain: string
+  /** The Application Audience (AUD) tag of the Access application(s). */
+  audience: string | string[]
+  /** Optional second check after the Access policy. */
+  allowedEmails?: string[]
+  /** email -> userId, to keep someone's data when their email changes. */
+  aliases?: Record<string, string>
+  /** Local development only: treat every request as this email. Never set in production. */
+  devUser?: string
+  fetch?: typeof fetch
+}
+
+export function createAccess(options: AccessOptions): {
+  /** The signed-in person, or null when the request did not come through Access. */
+  getUser(request: Request): Promise<User | null>
+}
+
+export function userIdFor(email: string): Promise<string>
+
+export type Policy = 'always' | 'daily' | 'weekly' | 'never'
+export const POLICIES: readonly Policy[]
+
+export interface LockDoc {
+  pinHash?: string
+  salt?: string
+  sessionKey: string
+  failures: number
+  lockedUntil: number
+  policy?: Policy
+}
+
+export interface LockStore {
+  get(userId: string): Promise<LockDoc | null>
+  put(userId: string, doc: LockDoc): Promise<void>
+}
+
+export interface LockReply {
+  status: number
+  body: Record<string, unknown>
+  /** A Set-Cookie header value, when the reply changes the unlock. */
+  cookie?: string
+}
+
+export interface LockOptions {
+  /** Cookie name; keep an app's old one so nobody is signed out twice. Default "slauth_lock". */
+  cookie?: string
+  /** For people who haven't chosen yet. Default "weekly". */
+  defaultPolicy?: Policy
+}
+
+export function createLock(
+  store: LockStore,
+  options?: LockOptions,
+): {
+  /**
+   * Routes: GET session, POST login | setup | logout | pin | policy.
+   * Returns null for any other route.
+   */
+  handle(
+    route: string,
+    method: string,
+    readBody: () => Promise<any>,
+    user: User,
+    cookieHeader: string | null | undefined,
+    secure: boolean,
+  ): Promise<LockReply | null>
+  isUnlocked(user: User, cookieHeader: string | null | undefined): Promise<boolean>
+}
+
+export function validPin(pin: unknown): pin is string
+export function validPolicy(policy: unknown): policy is Policy

package/src/index.js

@@ -0,0 +1,9 @@
+export { slauth } from './core.js'
+export { memory } from './stores/memory.js'
+export { consoleEmail } from './email/console.js'
+// The Cloudflare Access check and the PIN lock, usable on their own too.
+export { createAccess, userIdFor } from './access.js'
+export { createLock, validPin, validPolicy, POLICIES } from './lock.js'
+// Building blocks for your own tools and tests.
+export { hashPassword, verifyPassword } from './password.js'
+export { totp } from './two-factor.js'

package/src/lock.js

@@ -0,0 +1,225 @@
+/**
+ * The app lock: a 4-digit PIN that each person can ask an app to check again now and
+ * then, on top of the Access sign-in. Access says *who* you are; the lock guards an
+ * unlocked phone or iPad from whoever picks it up.
+ *
+ * Each person picks how often, per app:
+ *   always   every visit (the unlock ends when the browser closes, at most 12 hours)
+ *   daily    once a day
+ *   weekly   once a week
+ *   never    no PIN; the Access sign-in is enough
+ *
+ * Grown out of the Planda / LedgerFox PIN pad, and compatible with its stored hashes:
+ * a salted PBKDF2 hash, 5 free tries then a lock of 5 minutes doubling to an hour, and a
+ * signed HttpOnly cookie. The signing key is random and per person; changing the PIN
+ * replaces it, which locks that person's other devices.
+ */
+
+import { base64Url, randomToken, readCookie, safeEqual } from './util.js'
+
+const DAY = 24 * 60 * 60
+export const POLICIES = /** @type {const} */ (['always', 'daily', 'weekly', 'never'])
+const TTL_SECONDS = { always: DAY / 2, daily: DAY, weekly: 7 * DAY }
+const FREE_ATTEMPTS = 5
+const PBKDF2_ITERATIONS = 100_000
+
+export function validPin(pin) {
+  return typeof pin === 'string' && /^\d{4}$/.test(pin)
+}
+
+export function validPolicy(policy) {
+  return POLICIES.includes(policy)
+}
+
+/**
+ * @typedef {'always' | 'daily' | 'weekly' | 'never'} Policy
+ * @typedef {{ pinHash?: string, salt?: string, sessionKey: string, failures: number, lockedUntil: number, policy?: Policy }} LockDoc
+ * @typedef {{ get(userId: string): Promise<LockDoc | null>, put(userId: string, doc: LockDoc): Promise<void> }} LockStore
+ * @typedef {{ email: string, userId: string }} User
+ * @typedef {{ status: number, body: object, cookie?: string }} LockReply
+ */
+
+/**
+ * @param {LockStore} store  where each person's lock document lives
+ * @param {{ cookie?: string, defaultPolicy?: Policy }} [options]
+ *   cookie         the cookie name (keep an app's old one so nobody is signed out twice)
+ *   defaultPolicy  for people who haven't chosen yet; "weekly" unless set
+ */
+export function createLock(store, { cookie: cookieName = 'slauth_lock', defaultPolicy = 'weekly' } = {}) {
+  if (!validPolicy(defaultPolicy)) throw new Error(`slauth: unknown policy "${defaultPolicy}".`)
+
+  async function load(userId) {
+    const doc = await store.get(userId)
+    if (doc && typeof doc.sessionKey === 'string') return doc
+    const fresh = { sessionKey: randomToken(), failures: 0, lockedUntil: 0 }
+    await store.put(userId, fresh)
+    return fresh
+  }
+
+  const policyOf = (doc) => (validPolicy(doc.policy) ? doc.policy : defaultPolicy)
+  const pinIsSet = (doc) => Boolean(doc.pinHash && doc.salt)
+  const matches = async (doc, pin) => pinIsSet(doc) && safeEqual(await hashPin(pin, doc.salt), doc.pinHash)
+
+  async function unlockCookie(userId, doc, secure) {
+    const issued = String(Math.floor(Date.now() / 1000))
+    const value = `${issued}.${await sign(`${userId}.${issued}`, doc.sessionKey)}`
+    // "always" is a browser-session cookie; the others last as long as the longest policy,
+    // and the policy in force decides on each request whether the unlock still counts.
+    return cookie(cookieName, value, policyOf(doc) === 'always' ? null : TTL_SECONDS.weekly, secure)
+  }
+
+  /**
+   * True when this person may use the app right now: they chose "never", or they
+   * unlocked recently enough for their policy.
+   * @param {User} user
+   * @param {string | null | undefined} cookieHeader
+   */
+  async function isUnlocked(user, cookieHeader) {
+    const doc = await load(user.userId)
+    const policy = policyOf(doc)
+    if (policy === 'never') return true
+    if (!pinIsSet(doc)) return false
+
+    const [issued, signature] = (readCookie(cookieHeader, cookieName) ?? '').split('.')
+    const issuedAt = Number(issued)
+    if (!signature || !Number.isFinite(issuedAt)) return false
+    const age = Date.now() / 1000 - issuedAt
+    if (age < -60 || age > TTL_SECONDS[policy]) return false
+    // The user id is part of what's signed, so one person's cookie never unlocks another's.
+    return safeEqual(signature, await sign(`${user.userId}.${issued}`, doc.sessionKey))
+  }
+
+  async function savePin(userId, doc, pin, policy, secure) {
+    const salt = randomToken()
+    const next = { ...doc, pinHash: await hashPin(pin, salt), salt, sessionKey: randomToken(), failures: 0, lockedUntil: 0, policy }
+    await store.put(userId, next)
+    return unlockCookie(userId, next, secure)
+  }
+
+  /** @returns {Promise<LockReply>} */
+  async function login(user, guess, secure) {
+    if (!validPin(guess)) return { status: 400, body: { error: 'The PIN is 4 digits.' } }
+    const doc = await load(user.userId)
+    const now = Date.now()
+    if (!pinIsSet(doc)) return { status: 409, body: { error: 'No PIN has been created yet.', reason: 'no-pin' } }
+    if (doc.lockedUntil > now) {
+      return { status: 429, body: { error: 'Too many tries.', reason: 'locked', retryAt: doc.lockedUntil } }
+    }
+
+    if (await matches(doc, guess)) {
+      if (doc.failures !== 0 || doc.lockedUntil !== 0) await store.put(user.userId, { ...doc, failures: 0, lockedUntil: 0 })
+      return { status: 200, body: { ok: true }, cookie: await unlockCookie(user.userId, doc, secure) }
+    }
+
+    const failures = doc.failures + 1
+    const over = failures - FREE_ATTEMPTS
+    const lockedUntil = over >= 0 ? now + Math.min(60, 5 * 2 ** over) * 60_000 : 0
+    await store.put(user.userId, { ...doc, failures, lockedUntil })
+    return lockedUntil
+      ? { status: 429, body: { error: 'Too many tries.', reason: 'locked', retryAt: lockedUntil } }
+      : { status: 401, body: { error: 'Wrong PIN.', reason: 'wrong', attemptsLeft: FREE_ATTEMPTS - failures } }
+  }
+
+  /** First time in this app: choose a PIN (and optionally how often to ask for it). */
+  async function setup(user, pin, policy, secure) {
+    if (!validPin(pin)) return { status: 400, body: { error: 'The PIN is 4 digits.' } }
+    if (policy !== undefined && !validPolicy(policy)) return { status: 400, body: { error: 'Unknown lock setting.' } }
+    const doc = await load(user.userId)
+    if (pinIsSet(doc)) return { status: 409, body: { error: 'A PIN already exists.' } }
+    return { status: 200, body: { ok: true }, cookie: await savePin(user.userId, doc, pin, policy ?? policyOf(doc), secure) }
+  }
+
+  /** Change PIN from Settings. Not counted toward the lockout; locks this person's other devices. */
+  async function change(user, current, next, secure) {
+    if (!validPin(current) || !validPin(next)) return { status: 400, body: { error: 'PINs are 4 digits.' } }
+    const doc = await load(user.userId)
+    if (!(await matches(doc, current))) return { status: 403, body: { error: 'The current PIN is wrong.' } }
+    return { status: 200, body: { ok: true }, cookie: await savePin(user.userId, doc, next, policyOf(doc), secure) }
+  }
+
+  /**
+   * Change how often the PIN is asked for. With a PIN set, the current PIN is needed,
+   * so a borrowed unlocked device can't switch the lock off.
+   */
+  async function setPolicy(user, policy, pin, secure) {
+    if (!validPolicy(policy)) return { status: 400, body: { error: 'Unknown lock setting.' } }
+    const doc = await load(user.userId)
+    if (pinIsSet(doc)) {
+      if (!validPin(pin) || !(await matches(doc, pin))) return { status: 403, body: { error: 'The current PIN is wrong.' } }
+    } else if (policy !== 'never') {
+      return { status: 409, body: { error: 'Create a PIN first.', reason: 'no-pin' } }
+    }
+    const next = { ...doc, policy }
+    await store.put(user.userId, next)
+    const reply = { status: 200, body: { ok: true, policy } }
+    return pinIsSet(next) ? { ...reply, cookie: await unlockCookie(user.userId, next, secure) } : reply
+  }
+
+  /**
+   * The lock routes. `route` is the part after the app's prefix (e.g. "session" for
+   * /api/lock/session). Returns null for any other route.
+   * @param {string} route
+   * @param {string} method
+   * @param {() => Promise<any>} readBody
+   * @param {User} user  from Access
+   * @param {string | null | undefined} cookieHeader
+   * @param {boolean} secure  https, so the cookie gets the Secure flag
+   * @returns {Promise<LockReply | null>}
+   */
+  async function handle(route, method, readBody, user, cookieHeader, secure) {
+    if (route === 'session' && method === 'GET') {
+      const doc = await load(user.userId)
+      const policy = policyOf(doc)
+      return {
+        status: 200,
+        body: { email: user.email, policy, required: policy !== 'never', pinSet: pinIsSet(doc), unlocked: await isUnlocked(user, cookieHeader) },
+      }
+    }
+    if (route === 'login' && method === 'POST') return login(user, (await readBody())?.pin, secure)
+    if (route === 'setup' && method === 'POST') {
+      const body = await readBody()
+      if (body?.policy === 'never' && body?.pin === undefined) return setPolicy(user, 'never', undefined, secure)
+      return setup(user, body?.pin, body?.policy, secure)
+    }
+    if (route === 'logout' && method === 'POST') return { status: 200, body: { ok: true }, cookie: cookie(cookieName, '', 0, secure) }
+    if (route === 'pin' && method === 'POST') {
+      if (!(await isUnlocked(user, cookieHeader))) return { status: 401, body: { error: 'Please enter your PIN.' } }
+      const body = await readBody()
+      return change(user, body?.current, body?.next, secure)
+    }
+    if (route === 'policy' && method === 'POST') {
+      if (!(await isUnlocked(user, cookieHeader))) return { status: 401, body: { error: 'Please enter your PIN.' } }
+      const body = await readBody()
+      return setPolicy(user, body?.policy, body?.pin, secure)
+    }
+    return null
+  }
+
+  return { handle, isUnlocked }
+}
+
+function cookie(name, value, maxAge, secure) {
+  const age = maxAge === null ? '' : `; Max-Age=${maxAge}`
+  return `${name}=${value}; Path=/; HttpOnly; SameSite=Strict${age}${secure ? '; Secure' : ''}`
+}
+
+
+async function hashPin(pin, salt) {
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey('raw', encoder.encode(pin), 'PBKDF2', false, ['deriveBits'])
+  const bits = await crypto.subtle.deriveBits(
+    { name: 'PBKDF2', hash: 'SHA-256', salt: encoder.encode(salt), iterations: PBKDF2_ITERATIONS },
+    key,
+    256,
+  )
+  return base64Url(bits)
+}
+
+async function sign(payload, secret) {
+  const encoder = new TextEncoder()
+  const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign'])
+  return base64Url(await crypto.subtle.sign('HMAC', key, encoder.encode(payload)))
+}
+
+
+

package/src/node.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+export function toNodeHandler(auth: { handle(request: Request): Promise<Response> }): (req: IncomingMessage, res: ServerResponse, next?: (error?: unknown) => void) => Promise<void>
+export function toRequest(req: IncomingMessage): Promise<Request>

package/src/node.js

@@ -0,0 +1,67 @@
+/**
+ * Plain Node (node:http, Express, Connect): turns `auth.handle` into `(req, res, next)`.
+ *
+ *   import { toNodeHandler } from 'slauthjs/node'
+ *   app.use('/auth', toNodeHandler(auth))            // Express
+ *   const user = await auth.user(toRequest(req))     // in your own routes
+ *
+ * Everything else (Workers, Bun, Deno, Next.js, Astro, Hono) speaks Request/Response
+ * already and can call auth.handle(request) directly.
+ */
+
+/** @param {{ handle(request: Request): Promise<Response> }} auth */
+export function toNodeHandler(auth) {
+  return async (req, res, next) => {
+    try {
+      const response = await auth.handle(await toRequest(req))
+      res.statusCode = response.status
+      for (const [key, value] of response.headers) {
+        if (key.toLowerCase() === 'set-cookie') continue
+        res.setHeader(key, value)
+      }
+      const cookies = response.headers.getSetCookie?.() ?? []
+      if (cookies.length) res.setHeader('Set-Cookie', cookies)
+      res.end(Buffer.from(await response.arrayBuffer()))
+    } catch (error) {
+      if (next) next(error)
+      else {
+        res.statusCode = 500
+        res.end()
+      }
+    }
+  }
+}
+
+/**
+ * A Web Request from a Node IncomingMessage (body included).
+ * @param {import('node:http').IncomingMessage & { originalUrl?: string, body?: unknown }} req
+ */
+export async function toRequest(req) {
+  const proto = req.headers['x-forwarded-proto']?.toString().split(',')[0] ?? (req.socket?.encrypted ? 'https' : 'http')
+  const host = req.headers['x-forwarded-host']?.toString() ?? req.headers.host ?? 'localhost'
+  // Under app.use('/auth', ...) Express strips the prefix from req.url; originalUrl keeps it.
+  const url = new URL(req.originalUrl ?? req.url ?? '/', `${proto}://${host}`)
+
+  const headers = new Headers()
+  for (const [key, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue
+    for (const v of [value].flat()) headers.append(key, v)
+  }
+
+  let body
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    // Express's json() may already have read the body.
+    if (req.body !== undefined && typeof req.body === 'object' && !Buffer.isBuffer(req.body)) body = JSON.stringify(req.body)
+    else {
+      const chunks = []
+      let size = 0
+      for await (const chunk of req) {
+        size += chunk.length
+        if (size > 1_000_000) throw new Error('slauth: request body too large.')
+        chunks.push(chunk)
+      }
+      body = Buffer.concat(chunks)
+    }
+  }
+  return new Request(url, { method: req.method, headers, body })
+}