lecodes-sdk 2.0.3 → 2.0.5

package/src/server/auth/host.ts

@@ -1,55 +1,68 @@
 /**
- * The HOST side of auth (docs/backend-plan.md §3.4): sessions + tokens, the email-code flow, OAuth
- * binding. Runs where the runner imports `sdk/server` (the project worker), against the project's own
- * db handle (`server.dbs[0]` — `User`/`Session` are ordinary models, see ./models.ts). Installed on
- * `globalThis.__lecodesAuth` for the bundle's `auth` global (./global.ts); `resolve(ctx)` runs before
- * every endpoint / channel join so `auth.user` / `auth.session` are plain synchronous reads.
+ * The HOST side of auth: sessions + tokens, passwords, the email-code flow. Runs where
+ * the runner imports `sdk/server` (the project worker), over the three collections of a db made with
+ * `defineDb({...}).withAuth({ model })` (`db.$auth`: the project's user model, and the platform's
+ * `Session` and `Identity` — ./models.ts). Installed on `globalThis.__lecodesAuth` for the bundle's
+ * `db.auth` (./api.ts); `resolve(ctx)` runs before every endpoint / channel join and leaves the
+ * session and the ID of its user on the request.
+ *
+ * The user's row is the project's: this file creates one (empty, or with what a sign-up handed over)
+ * the first time someone signs in, and never reads or writes its fields. What a provider told about the
+ * person is kept on the `Identity`.
  *
  * Tokens: 32 random bytes (base64url) held by the client transport; only `sha256(token)` is stored.
  * A request without a valid token gets a fresh guest session and the token travels back in the
- * envelope (`session`); sign-in/out ROTATE the token the same way. OAuth binds without rotation (the
- * browser completes the flow, the app can't receive a new token) — see `oauthComplete`.
+ * envelope (`session`); sign-in/out ROTATE the token the same way.
+ *
+ * Identities: every sign-in method is an `Identity` row `(provider, subject)` of a user — `email:<address>`
+ * or `login:<name>` (its `hash` = the password). The one rule that keeps passwords honest: proving an
+ * email (a code) on an identity that was never verified DROPS its password — a password set before the
+ * address was confirmed proves nothing (pre-account-takeover guard).
+ *
+ * Sign-in through a provider (Google, Apple, …) is not here: a project that verifies a person some
+ * other way binds the device itself with `db.auth.signIn(userId)`.
  */
 
+import { randomBytes, scrypt as scryptCb, timingSafeEqual } from "node:crypto"
 import type { RequestContext } from "../context"
 import type { AuthBinding } from "../db/types"
 import { ApiError } from "../errors"
-import type { AuthProvider } from "./models"
-import type { AuthOps, AuthState, AuthUser, OAuthCredential, OAuthProfile } from "./types"
+import type { IdentityProvider } from "./models"
+import type { AuthOps, AuthState } from "./types"
 
 export type AuthMail = { to: string, code: string, appName: string }
 
 export type AuthHostConfig = {
-  /** The project's db (`server.dbs[0]`, any `defineDb` handle); `null` = no database → `auth.*` throws a clear error. */
-  db: { readonly $auth: AuthBinding, readonly $schema: string } | null
-  /** HMAC key for OAuth nonces (runner-wide secret). */
-  secret: string
-  /** `app.json` `auth.providers` (the compiler embeds them; the runner reads them off the manifest). */
-  providers: AuthProvider[]
+  /** The project's db with sign-in (`defineDb(...).withAuth(...)`); `null`, or a db without it = no auth:
+   *  requests carry no session and `db.auth` does not exist. */
+  db: { readonly $auth: AuthBinding | null } | null
+  /** The app's name in the sign-in mail (`app.json`). */
   appName?: string
-  /** `<publicUrl>/p/<key>` — OAuth start links are minted under it; absent = OAuth unavailable. */
-  publicBase?: string
-  /** Nonce scope (the runner's project key): a nonce minted for one project can't bind a session of another. */
-  scope?: string
   /** Sends the sign-in code (the platform mailer). Absent = codes are only echoed to the console. */
   mail?: (msg: AuthMail) => Promise<void>
   /** Echo every code to the server console (the draft slot: the developer is the only user). */
   echoCodes?: boolean
-  /** Verifies a NATIVE-SDK credential with the provider (runner-side, knows the platform's app ids) → profile.
-   *  Absent = `auth.oauth.signIn` is unavailable. Throw `ApiError` for a bad credential. */
-  verifyOAuth?: (provider: Exclude<AuthProvider, "email">, credential: OAuthCredential) => Promise<OAuthProfile>
   /** Server console sink (default console). */
   log?: (level: "warn" | "info", text: string) => void
   now?: () => number
+  /**
+   * LOCAL DEVELOPMENT ONLY (`lecodes dev`): a code `signInWithCode` accepts for ANY email without a prior
+   * `sendCode` — the test sign-in. The platform never sets it; the host that does must be the developer's own machine.
+   */
+  devCode?: string
 }
 
 const CODE_TTL_MS = 10 * 60_000
 const CODE_MAX_ATTEMPTS = 5
 const SEND_MIN_GAP_MS = 30_000
 const SEND_MAX_PER_10MIN = 3
-const NONCE_TTL_MS = 10 * 60_000
+const PASSWORD_MIN = 8
+const PASSWORD_MAX = 128
+const PASSWORD_FAILS_PER_LOGIN = 10
+const PASSWORD_FAILS_PER_IP = 50
 const CACHE_TTL_MS = 60_000
 const SEEN_UPDATE_MS = 60_000
+const SCRYPT_N = 16384
 
 const enc = new TextEncoder()
 const b64url = (bytes: ArrayBuffer | Uint8Array): string => {
@@ -63,20 +76,24 @@ export const sha256 = async (text: string): Promise<string> => hex(await crypto.
 const randomToken = (): string => b64url(crypto.getRandomValues(new Uint8Array(32)))
 const randomCode = (): string => String(crypto.getRandomValues(new Uint32Array(1))[0] % 1_000_000).padStart(6, "0")
 
-const hmac = async (secret: string, text: string): Promise<string> => {
-  const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"])
-  return b64url(await crypto.subtle.sign("HMAC", key, enc.encode(text)))
+// ── passwords: scrypt (node:crypto — runs under Bun and Node alike), `scrypt$N$salt$hash` ──
+const scrypt = (password: string, salt: Buffer, n: number): Promise<Buffer> =>
+  new Promise((res, rej) => scryptCb(password.normalize("NFKC"), salt, 32, { N: n, r: 8, p: 1, maxmem: 64 * 1024 * 1024 }, (e, k) => (e ? rej(e) : res(k as Buffer))))
+export const hashPassword = async (password: string): Promise<string> => {
+  const salt = randomBytes(16)
+  return `scrypt$${SCRYPT_N}$${salt.toString("base64url")}$${(await scrypt(password, salt, SCRYPT_N)).toString("base64url")}`
+}
+export const verifyPassword = async (password: string, stored: string): Promise<boolean> => {
+  const [algo, n, salt, hash] = stored.split("$")
+  if (algo !== "scrypt" || !n || !salt || !hash) return false
+  const expected = Buffer.from(hash, "base64url")
+  const actual = await scrypt(password, Buffer.from(salt, "base64url"), Number(n))
+  return actual.length === expected.length && timingSafeEqual(actual, expected)
 }
-/** OAuth nonce: `<sessionId>.<expiresAt>.<hmac>` — stateless, bound to a session (and a `scope`: the project), short-lived. */
-export const signNonce = async (secret: string, sessionId: number, expiresAt: number, scope = ""): Promise<string> =>
-  `${sessionId}.${expiresAt}.${await hmac(secret, `${scope}|${sessionId}.${expiresAt}`)}`
-export const verifyNonce = async (secret: string, nonce: string, now = Date.now(), scope = ""): Promise<{ sessionId: number } | null> => {
-  const [sid, exp, sig] = nonce.split(".")
-  const sessionId = Number(sid), expiresAt = Number(exp)
-  if (!Number.isInteger(sessionId) || !Number.isFinite(expiresAt) || !sig) return null
-  if (expiresAt < now) return null
-  if (sig !== await hmac(secret, `${scope}|${sid}.${exp}`)) return null
-  return { sessionId }
+const checkPassword = (password: unknown): string => {
+  if (typeof password !== "string" || password.length < PASSWORD_MIN) throw new ApiError(400, `Password must be at least ${PASSWORD_MIN} characters`)
+  if (password.length > PASSWORD_MAX) throw new ApiError(400, `Password must be at most ${PASSWORD_MAX} characters`)
+  return password
 }
 
 const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
@@ -86,66 +103,71 @@ const normalizeEmail = (email: unknown): string => {
   return e
 }
 
-/** Built-in user shape from a row (custom scalar fields ride along at runtime). */
-const toUser = (row: any): AuthUser => row as AuthUser
+const LOGIN_RE = /^[\p{L}\p{N}_.-]{3,32}$/u
+/** What a person signs in by: an address (it has an `@`) or a name — the `email` / `login` identity. */
+const parseLogin = (login: unknown): { provider: "email" | "login", subject: string } => {
+  const l = typeof login === "string" ? login.trim() : ""
+  if (l.includes("@")) return { provider: "email", subject: normalizeEmail(l) }
+  if (!LOGIN_RE.test(l)) throw new ApiError(400, "Login must be 3–32 letters, digits, dots, dashes or underscores")
+  return { provider: "login", subject: l.toLowerCase() }
+}
+
+const identityKey = (provider: IdentityProvider, subject: string) => `${provider}:${subject}`
+
+/** A sliding-window counter per key (in-worker; the persistent limits live on the rows). */
+const window = (map: Map<string, number[]>, key: string, now: number, span: number): number[] => {
+  const list = (map.get(key) ?? []).filter(x => now - x < span)
+  map.set(key, list)
+  return list
+}
 
 export type AuthHost = {
-  /** Resolve the bearer token of `ctx` into `ctx.auth` (minting a guest session when needed). No db → leaves it undefined. */
+  /** Does the project's db have sign-in? Without it nothing is resolved and `db.auth` does not exist. */
+  readonly enabled: boolean
+  /** Resolve the bearer token of `ctx` into `ctx.auth` (minting a guest session when needed). */
   resolve(ctx: RequestContext): Promise<void>
   ops: AuthOps
-  /** Install `ops` for the bundle's `auth` global (`globalThis.__lecodesAuth`). */
+  /** Install `ops` for the bundle's `db.auth` (`globalThis.__lecodesAuth`). */
   install(): void
   /**
-   * OAuth callback: bind the session named by `nonce` to the user identified by `profile` (existing
-   * `<provider>Id`, else a verified-email match, else a new user). Runs in the worker; the runner's
-   * broker route calls it with what the provider returned.
+   * LOCAL DEVELOPMENT ONLY (needs `devCode`): a fresh session already signed in as `email` (the user and its
+   * verified email identity are created when missing). The token is what a test host seeds the app's transport
+   * with (`localStorage["lecodes.session:<url>"]`) so a scenario starts past the sign-in screen.
    */
-  oauthComplete(provider: Exclude<AuthProvider, "email">, nonce: string, profile: OAuthProfile): Promise<{ userId: number }>
-  /** Test hook / diagnostics: forget cached sessions and users. */
+  devSignIn(email: string): Promise<{ token: string, userId: number }>
+  /** Test hook / diagnostics: forget cached sessions. */
   clearCache(): void
 }
 
 export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
-  const db = cfg.db as any
-  const binding = cfg.db?.$auth ?? null
-  const hasUser = !!binding?.user
+  const tables = cfg.db?.$auth ?? null
+  const users = tables?.user, sessions = tables?.session, identities = tables?.identity
   const now = cfg.now ?? (() => Date.now())
   const log = cfg.log ?? ((level, text) => (level === "warn" ? console.warn(text) : console.info(text)))
-  const providers = new Set(cfg.providers)
 
-  // token → session (60 s), user id → user row (60 s). Cleared on every mutation — correctness over reuse.
-  const sessionCache = new Map<string, { sessionId: number, userId: number | null, at: number, seenAt: number }>()
-  const userCache = new Map<number, { user: AuthUser | null, at: number }>()
-  const clearCache = () => { sessionCache.clear(); userCache.clear() }
+  // token → session (60 s). Cleared on every mutation — correctness over reuse.
+  const sessionCache = new Map<string, { sessionId: number, userId: number | null, at: number }>()
+  const clearCache = () => { sessionCache.clear() }
 
-  const requireDb = () => {
-    if (!db) throw new Error("auth: this project has no database — sessions need a defineDb()")
-    return db
-  }
-  const requireUserModel = (what: string) => {
-    if (!hasUser) throw new Error(`${what} needs a user model: export const User = auth.model.user({...}) in your schema`)
+  const requireAuth = () => {
+    if (!tables) throw new Error("db.auth: this project's database has no sign-in — defineDb({...}).withAuth({ model: \"<your user model>\" })")
   }
   const stateOf = (ctx: RequestContext): AuthState => {
     const s = ctx.auth as AuthState | undefined
-    if (!s) throw new Error("auth: this project has no database — sessions need a defineDb()")
+    if (!s) throw new Error("db.auth: the request carries no session")
     return s
   }
-
-  const sessionSelect = () => (hasUser ? { id: true, revoked: true, lastSeenAt: true, user: { id: true } } : { id: true, revoked: true, lastSeenAt: true })
-  const loadUser = async (userId: number | null): Promise<AuthUser | null> => {
-    if (userId === null || !hasUser) return null
-    const c = userCache.get(userId)
-    if (c && now() - c.at < CACHE_TTL_MS) return c.user
-    const row = await db.user.where({ id: userId }).first()
-    const user = row ? toUser(row) : null
-    userCache.set(userId, { user, at: now() })
-    return user
+  const requireSignedIn = (ctx: RequestContext): number => {
+    const id = stateOf(ctx).userId
+    if (id === null) throw new ApiError(401, "Sign in required")
+    return id
   }
+
   const mint = async (ctx: RequestContext): Promise<AuthState> => {
     const token = randomToken()
-    const { id } = await db.session.insert({ tokenHash: await sha256(token) })
-    const state: AuthState = { sessionId: id, userId: null, user: null, issuedToken: token }
-    sessionCache.set(token, { sessionId: id, userId: null, at: now(), seenAt: now() })
+    const { id } = await sessions.insert({ tokenHash: await sha256(token) })
+    const state: AuthState = { sessionId: id, userId: null, issuedToken: token }
+    sessionCache.set(token, { sessionId: id, userId: null, at: now() })
     ctx.auth = state
     ctx.sessionToken = token
     return state
@@ -153,59 +175,122 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
   const rotate = async (ctx: RequestContext): Promise<void> => {
     const s = stateOf(ctx)
     const token = randomToken()
-    await db.session.update(s.sessionId, { tokenHash: await sha256(token) })
+    await sessions.update(s.sessionId, { tokenHash: await sha256(token) })
     clearCache()
     s.issuedToken = token
     ctx.sessionToken = token
   }
-  const bind = async (ctx: RequestContext, userId: number | null, opts: { rotate: boolean }): Promise<AuthUser | null> => {
+  const bind = async (ctx: RequestContext, userId: number | null, opts: { rotate: boolean }): Promise<void> => {
     const s = stateOf(ctx)
-    await db.session.update(s.sessionId, { user: userId === null ? null : { $connect: { id: userId } } })
+    await sessions.update(s.sessionId, { user: userId === null ? null : { $connect: { id: userId } } })
     clearCache()
     s.userId = userId
-    s.user = await loadUser(userId)
     if (opts.rotate) await rotate(ctx)
-    return s.user
   }
 
   const resolve = async (ctx: RequestContext): Promise<void> => {
-    if (!db) return
+    if (!tables) return
     const token = ctx.sessionToken
     if (token) {
       const c = sessionCache.get(token)
       if (c && now() - c.at < CACHE_TTL_MS) {
-        ctx.auth = { sessionId: c.sessionId, userId: c.userId, user: await loadUser(c.userId) }
+        ctx.auth = { sessionId: c.sessionId, userId: c.userId }
         return
       }
-      const row = await db.session.where({ tokenHash: await sha256(token) }).select(sessionSelect()).first()
+      const row = await sessions.where({ tokenHash: await sha256(token) }).select({ id: true, revoked: true, lastSeenAt: true, user: { id: true } }).first()
       if (row && !row.revoked) {
-        const userId: number | null = hasUser && row.user ? row.user.id : null
-        if (now() - (row.lastSeenAt ?? 0) > SEEN_UPDATE_MS) db.session.update(row.id, { lastSeenAt: now() }).then(undefined, () => {})
-        sessionCache.set(token, { sessionId: row.id, userId, at: now(), seenAt: now() })
-        ctx.auth = { sessionId: row.id, userId, user: await loadUser(userId) }
+        const userId: number | null = row.user ? row.user.id : null
+        if (now() - (row.lastSeenAt ?? 0) > SEEN_UPDATE_MS) sessions.update(row.id, { lastSeenAt: now() }).then(undefined, () => {})
+        sessionCache.set(token, { sessionId: row.id, userId, at: now() })
+        ctx.auth = { sessionId: row.id, userId }
         return
       }
     }
     await mint(ctx)
   }
 
+  // ── identities ──
+  type IdentityRow = { id: number, hash: string | null, verifiedAt: number | null, user: { id: number } }
+  const findIdentity = (provider: IdentityProvider, subject: string): Promise<IdentityRow | null> =>
+    identities.where({ key: identityKey(provider, subject) }).select({ id: true, hash: true, verifiedAt: true, user: { id: true } }).first()
+  const createIdentity = (userId: number, provider: IdentityProvider, subject: string, extra: Record<string, unknown> = {}) =>
+    identities.insert({ user: { id: userId }, provider, subject, key: identityKey(provider, subject), ...extra })
+  /** The project's row of a new person: empty (every field has a default — `withAuth` checked), or what a sign-up handed over. */
+  const createUser = async (data?: Record<string, unknown>): Promise<number> => (await users.insert(data ?? {})).id
+  /**
+   * The email was just proven for `userId` (a code): mark the `email` identity
+   * verified — and drop a password that was set BEFORE the address was confirmed (it proved nothing).
+   * `create` = make the identity when missing.
+   */
+  const proveEmail = async (userId: number, email: string, create: boolean): Promise<void> => {
+    const ident = await findIdentity("email", email)
+    if (ident) {
+      if (ident.user.id !== userId) throw new ApiError(409, "This email belongs to another account")
+      if (!ident.verifiedAt) await identities.update(ident.id, { verifiedAt: now(), hash: null })
+    } else if (create) {
+      await createIdentity(userId, "email", email, { verifiedAt: now() })
+    }
+  }
+
+  // ── passwords ──
+  const passwordFails = new Map<string, number[]>()
+  const signUpWithPassword = async (ctx: RequestContext, rawLogin: string, rawPassword: string, data?: Record<string, unknown>): Promise<void> => {
+    requireAuth()
+    const { provider, subject } = parseLogin(rawLogin)
+    const password = checkPassword(rawPassword)
+    if (await findIdentity(provider, subject)) throw new ApiError(409, provider === "email" ? "An account with this email already exists" : "This login is taken")
+    const userId = await createUser(data)
+    await createIdentity(userId, provider, subject, { hash: await hashPassword(password) })
+    await bind(ctx, userId, { rotate: true })
+  }
+  const signInWithPassword = async (ctx: RequestContext, rawLogin: string, rawPassword: string): Promise<void> => {
+    requireAuth()
+    // a login that could not exist fails like a wrong password — one message, nothing to learn from it
+    let who: { provider: "email" | "login", subject: string } | null = null
+    try { who = parseLogin(rawLogin) } catch { /* below */ }
+    const t = now()
+    const byLogin = window(passwordFails, `l:${who ? identityKey(who.provider, who.subject) : ""}`, t, 10 * 60_000)
+    const byIp = ctx.ip ? window(passwordFails, `ip:${ctx.ip}`, t, 10 * 60_000) : []
+    if (byLogin.length >= PASSWORD_FAILS_PER_LOGIN || byIp.length >= PASSWORD_FAILS_PER_IP) throw new ApiError(429, "Too many attempts — try again later")
+    const ident = who ? await findIdentity(who.provider, who.subject) : null
+    const ok = !!ident?.hash && typeof rawPassword === "string" && await verifyPassword(rawPassword, ident.hash)
+    if (!ok) {
+      byLogin.push(t); byIp.push(t)
+      throw new ApiError(401, "Invalid login or password")
+    }
+    await bind(ctx, ident!.user.id, { rotate: true })
+  }
+  const setPassword = async (ctx: RequestContext, rawPassword: string): Promise<void> => {
+    requireAuth()
+    const userId = requireSignedIn(ctx)
+    const password = checkPassword(rawPassword)
+    // the password belongs to what the person types to sign in: their email and / or their login
+    const mine: { id: number, provider: string }[] = await identities.where({ user: { id: userId } }).select({ id: true, provider: true })
+    const typed = mine.filter(i => i.provider === "email" || i.provider === "login")
+    if (!typed.length) throw new ApiError(400, "Your account has no email or login to sign in with a password — sign in with a code first")
+    const hash = await hashPassword(password)
+    for (const i of typed) await identities.update(i.id, { hash })
+    // a password change signs every OTHER device out
+    const s = stateOf(ctx)
+    await sessions.where({ user: { id: userId }, id: { $ne: s.sessionId } }).updateMany({ revoked: true })
+    clearCache()
+  }
+
   // ── email codes ──
   const sends = new Map<string, number[]>()   // email → send timestamps (per worker; attempts persist on the row)
   const codeHash = (sessionId: number, code: string) => sha256(`${sessionId}:${code}`)
 
   const sendCode = async (ctx: RequestContext, rawEmail: string): Promise<void> => {
-    requireDb()
-    if (!providers.has("email")) throw new Error(`auth.email is not enabled — add "email" to auth.providers in app.json`)
-    requireUserModel("auth.email")
+    requireAuth()
     const s = stateOf(ctx)
     const email = normalizeEmail(rawEmail)
     const t = now()
-    const recent = (sends.get(email) ?? []).filter(x => t - x < 10 * 60_000)
+    const recent = window(sends, email, t, 10 * 60_000)
     if (recent.length && t - recent[recent.length - 1] < SEND_MIN_GAP_MS) throw new ApiError(429, `Try again in ${Math.ceil((SEND_MIN_GAP_MS - (t - recent[recent.length - 1])) / 1000)} s`)
     if (recent.length >= SEND_MAX_PER_10MIN) throw new ApiError(429, "Too many codes requested — try again later")
     const code = randomCode()
-    await db.session.update(s.sessionId, { pendingEmail: email, codeHash: await codeHash(s.sessionId, code), codeExpires: t + CODE_TTL_MS, codeAttempts: 0 })
-    recent.push(t); sends.set(email, recent)
+    await sessions.update(s.sessionId, { pendingEmail: email, codeHash: await codeHash(s.sessionId, code), codeExpires: t + CODE_TTL_MS, codeAttempts: 0 })
+    recent.push(t)
     const appName = cfg.appName || "the app"
     if (cfg.mail) {
       try { await cfg.mail({ to: email, code, appName }) }
@@ -214,105 +299,90 @@ export const createAuthHost = (cfg: AuthHostConfig): AuthHost => {
     if (!cfg.mail || cfg.echoCodes) log("info", `[auth] sign-in code for ${email}: ${code}${cfg.mail ? "" : " (no mailer configured — the code was not emailed)"}`)
   }
 
-  const verify = async (ctx: RequestContext, rawEmail: string, code: string): Promise<AuthUser> => {
-    requireDb()
-    requireUserModel("auth.email")
-    const s = stateOf(ctx)
-    const email = normalizeEmail(rawEmail)
-    const row = await db.session.where({ id: s.sessionId }).select({ pendingEmail: true, codeHash: true, codeExpires: true, codeAttempts: true }).first()
-    if (!row?.codeHash || row.pendingEmail !== email || !row.codeExpires || row.codeExpires < now()) throw new ApiError(400, "Code expired — request a new one")
-    if (row.codeAttempts >= CODE_MAX_ATTEMPTS) throw new ApiError(429, "Too many attempts — request a new code")
-    if (typeof code !== "string" || await codeHash(s.sessionId, code.trim()) !== row.codeHash) {
-      await db.session.update(s.sessionId, { codeAttempts: { $increment: 1 } })
-      throw new ApiError(400, "Invalid code")
-    }
-    const existing = await db.user.where({ email }).first()
-    const userId: number = existing ? existing.id : (await db.user.insert({ email })).id
-    await db.session.update(s.sessionId, { pendingEmail: null, codeHash: null, codeExpires: null, codeAttempts: 0 })
-    const user = await bind(ctx, userId, { rotate: true })
-    return user!
+  /** The user an email belongs to, made when nobody has it yet; the address is proven either way. */
+  const userOfProvenEmail = async (email: string): Promise<number> => {
+    const ident = await findIdentity("email", email)
+    const userId = ident ? ident.user.id : await createUser()
+    await proveEmail(userId, email, true)
+    return userId
   }
 
-  // ── oauth ──
-  const oauthUrl = async (ctx: RequestContext, provider: Exclude<AuthProvider, "email">): Promise<string> => {
-    requireDb()
-    if (!providers.has(provider)) throw new Error(`auth.oauth: "${provider}" is not enabled — add it to auth.providers in app.json`)
-    requireUserModel("auth.oauth")
-    if (!cfg.publicBase) throw new Error("auth.oauth: not available in this environment (no public runner URL)")
+  const signInWithCode = async (ctx: RequestContext, rawEmail: string, code: string): Promise<void> => {
+    requireAuth()
     const s = stateOf(ctx)
-    const nonce = await signNonce(cfg.secret, s.sessionId, now() + NONCE_TTL_MS, cfg.scope)
-    return `${cfg.publicBase}/auth/${provider}/start?s=${encodeURIComponent(nonce)}`
-  }
-
-  /** The user a provider identity maps to: by `<provider>Id`, else a verified-email match (linked), else created. */
-  const userForProfile = async (provider: Exclude<AuthProvider, "email">, profile: OAuthProfile): Promise<number> => {
-    const idField = `${provider}Id`
-    if (!profile.sub) throw new ApiError(502, `${provider} returned no account id`)
-    let user = await db.user.where({ [idField]: profile.sub }).first()
-    if (!user && profile.email && profile.emailVerified !== false) {
-      const byEmail = await db.user.where({ email: profile.email.toLowerCase() }).first()
-      if (byEmail) { await db.user.update(byEmail.id, { [idField]: profile.sub }); user = { ...byEmail, [idField]: profile.sub } }
-    }
-    if (!user) {
-      const data: Record<string, unknown> = { [idField]: profile.sub }
-      if (profile.email && profile.emailVerified !== false) data.email = profile.email.toLowerCase()
-      if (profile.name) data.name = profile.name
-      if (profile.avatar) data.avatar = profile.avatar
-      const { id } = await db.user.insert(data)
-      user = { id }
+    const email = normalizeEmail(rawEmail)
+    // the local dev code skips the sent-code check entirely (no sendCode needed) — never set on the platform
+    const isDevCode = !!cfg.devCode && typeof code === "string" && code.trim() === cfg.devCode
+    if (!isDevCode) {
+      const row = await sessions.where({ id: s.sessionId }).select({ pendingEmail: true, codeHash: true, codeExpires: true, codeAttempts: true }).first()
+      if (!row?.codeHash || row.pendingEmail !== email || !row.codeExpires || row.codeExpires < now()) throw new ApiError(400, "Code expired — request a new one")
+      if (row.codeAttempts >= CODE_MAX_ATTEMPTS) throw new ApiError(429, "Too many attempts — request a new code")
+      if (typeof code !== "string" || await codeHash(s.sessionId, code.trim()) !== row.codeHash) {
+        await sessions.update(s.sessionId, { codeAttempts: { $increment: 1 } })
+        throw new ApiError(400, "Invalid code")
+      }
     }
-    return user.id
-  }
-
-  const oauthComplete = async (provider: Exclude<AuthProvider, "email">, nonce: string, profile: OAuthProfile): Promise<{ userId: number }> => {
-    requireDb()
-    requireUserModel("auth.oauth")
-    const n = await verifyNonce(cfg.secret, nonce, now(), cfg.scope)
-    if (!n) throw new ApiError(400, "This sign-in link has expired — start again from the app")
-    const session = await db.session.where({ id: n.sessionId }).select({ id: true, revoked: true, user: { id: true } }).first()
-    if (!session || session.revoked) throw new ApiError(400, "This sign-in link is no longer valid — start again from the app")
-    const userId = await userForProfile(provider, profile)
-    // A session already signed in as someone else is not re-bound by a stray link (fixation guard).
-    if (session.user && session.user.id !== userId) throw new ApiError(409, "This device is already signed in as another user — sign out first")
-    if (!session.user) await db.session.update(session.id, { user: { $connect: { id: userId } } })
-    clearCache()
-    return { userId }
+    const userId = await userOfProvenEmail(email)
+    await sessions.update(s.sessionId, { pendingEmail: null, codeHash: null, codeExpires: null, codeAttempts: 0 })
+    await bind(ctx, userId, { rotate: true })
   }
 
-  // Native-SDK credential (client plugin OAuth.signIn) → verified with the provider → bound to THIS session, rotated
-  // like any in-band sign-in (the same client receives the new token).
-  const oauthSignIn = async (ctx: RequestContext, provider: Exclude<AuthProvider, "email">, credential: OAuthCredential): Promise<AuthUser> => {
-    requireDb()
-    if (!providers.has(provider)) throw new Error(`auth.oauth: "${provider}" is not enabled — add it to auth.providers in app.json`)
-    requireUserModel("auth.oauth")
-    if (!cfg.verifyOAuth) throw new Error("auth.oauth.signIn: not available in this environment (no provider verification configured)")
-    if (!credential || typeof credential !== "object" || (typeof credential.accessToken !== "string" && typeof credential.idToken !== "string")) throw new ApiError(400, "A provider credential (accessToken or idToken) is required")
-    const profile = await cfg.verifyOAuth(provider, credential)
-    // Apple only sends the name on the first sign-in — the app forwards what the sheet returned
-    if (!profile.name && typeof credential.name === "string" && credential.name.trim()) profile.name = credential.name.trim()
-    const userId = await userForProfile(provider, profile)
-    return (await bind(ctx, userId, { rotate: true }))!
-  }
+  /**
+   * A query of the platform's model handed to project code: every write through it drops the cached
+   * sessions, so a device revoked by `db.auth.sessions.where(...).updateMany({ revoked: true })` is out
+   * at its next request, not when the cache expires.
+   */
+  const WRITES = new Set(["update", "updateMany", "delete", "deleteMany"])
+  const guarded = (q: any): any => new Proxy(q, {
+    get: (target, prop) => {
+      const value = target[prop]
+      if (typeof value !== "function" || prop === "then") return value
+      return (...args: unknown[]) => {
+        const out = value.apply(target, args)
+        if (!out || typeof out !== "object") return out
+        if (!WRITES.has(prop as string)) return typeof out.where === "function" ? guarded(out) : out
+        return { ...out, then: (ok?: any, fail?: any) => out.then((v: unknown) => { clearCache(); return v }).then(ok, fail) }
+      }
+    },
+  })
 
   const ops: AuthOps = {
-    email: { sendCode, verify },
-    oauth: { url: oauthUrl, signIn: oauthSignIn },
+    signUpWithPassword, signInWithPassword, setPassword,
+    sendCode, signInWithCode,
     signIn: async (ctx, userId) => {
-      requireDb(); requireUserModel("auth.signIn")
-      const row = await db.user.where({ id: userId }).first()
-      if (!row) throw new ApiError(404, "No such user")
-      return (await bind(ctx, userId, { rotate: true }))!
+      requireAuth()
+      if (!await users.where({ id: userId }).select({ id: true }).first()) throw new ApiError(404, "No such user")
+      await bind(ctx, userId, { rotate: true })
     },
-    signOut: async (ctx) => { requireDb(); await bind(ctx, null, { rotate: true }) },
+    signOut: async (ctx) => { requireAuth(); await bind(ctx, null, { rotate: true }) },
     sessions: (ctx) => {
-      requireDb()
+      requireAuth()
       const s = stateOf(ctx)
-      return s.userId !== null && hasUser ? db.session.where({ user: { id: s.userId } }) : db.session.where({ id: s.sessionId })
+      const q = s.userId !== null ? sessions.where({ user: { id: s.userId } }) : sessions.where({ id: s.sessionId })
+      return guarded(q.select({ id: true, createdAt: true, lastSeenAt: true, revoked: true }))
     },
+    identities: (ctx) => {
+      requireAuth()
+      const s = stateOf(ctx)
+      // the hash stays out of the projection; a guest sees an empty list
+      return identities.where({ user: { id: s.userId ?? 0 } })
+        .select({ id: true, provider: true, subject: true, verifiedAt: true, createdAt: true })
+    },
+  }
+
+  const devSignIn = async (rawEmail: string): Promise<{ token: string, userId: number }> => {
+    if (!cfg.devCode) throw new Error("auth.devSignIn: local development only (no devCode configured)")
+    requireAuth()
+    const userId = await userOfProvenEmail(normalizeEmail(rawEmail))
+    const token = randomToken()
+    await sessions.insert({ tokenHash: await sha256(token), user: { id: userId } })
+    clearCache()
+    return { token, userId }
   }
 
   return {
-    resolve, ops, oauthComplete, clearCache,
+    enabled: !!tables,
+    resolve, ops, devSignIn, clearCache,
     install: () => { (globalThis as any).__lecodesAuth = ops },
   }
 }