lecodes-sdk 0.19.0

package/src/scene/material.ts

@@ -0,0 +1,188 @@
+// Materials as data — the `material:` grammar of scene files and the `defineMaterial` document
+// behind `*.material.ts` assets (docs/scene-materials-plan.md).
+//
+//   // materials/holo-glass.material.ts
+//   export default defineMaterial({
+//     shader: asset('../assets/shaders/lens.mat'),
+//     params: { tint: '#1d2b26', opacity: 0.22, mask: asset('../assets/weapons/reticle.png') },
+//   })
+//
+//   // range.scene.ts
+//   import holoGlass from './materials/holo-glass.material'
+//   lens: { mesh: { kind: 'plane' }, material: holoGlass },
+//
+// One grammar serves the inline form (`material: { lit: {…} }` / `{ shader, params }` on a node),
+// the asset form (the handle) and GLB-part overrides. A handle is ONE shared GPU material: every
+// node using the asset renders the same instance, and editing the asset changes all of them
+// (Unity's rule — two looks are two assets).
+//
+// Parameter values need no shader metadata at runtime: a string is a colour when it starts with
+// `#`, otherwise it is a texture URL (`asset('./x.png')` compiles to one) — the same lowering
+// `Material.set` already applies to colours.
+
+import type { ColorInput } from "../core/color"
+import { Material, type LitMaterialOptions, type UnlitMaterialOptions } from "../gl/Material"
+import { Texture } from "../gl/Texture"
+import type { Node } from "../gl/Node"
+import { EDIT_FLAG } from "./grammar"
+
+/** A shader parameter value as scene files write it: number, boolean, `#colour`, texture URL
+ *  (`asset('./x.png')`), or a numeric vector. */
+export type MaterialParamValue = number | boolean | string | number[]
+
+type WithMapUrl<T> = Omit<T, "map"> & {
+  /** Base-colour texture — a `Texture`, a `Canvas`, or `asset('./x.png')` (a URL string). */
+  map?: LitMaterialOptions["map"] | string
+}
+
+export type LitMaterialDef = WithMapUrl<LitMaterialOptions>
+export type UnlitMaterialDef = WithMapUrl<UnlitMaterialOptions>
+
+/** A custom Filament shader (`asset('./x.mat')` — compiled by the platform / `lecodes shaders`)
+ *  plus its parameter values. */
+export type ShaderMaterialDef = {
+  shader: string
+  params?: Record<string, MaterialParamValue>
+}
+
+export type MaterialDef =
+  | { lit: LitMaterialDef }
+  | { unlit: UnlitMaterialDef }
+  | { shadow: ColorInput }
+  | ShaderMaterialDef
+  /** A material asset (`import m from './x.material'`) — one shared instance. */
+  | MaterialHandle
+  /** A code-level Material instance — valid at runtime; the editor shows it read-only. */
+  | Material
+
+/** The data forms of MaterialDef (everything but a live instance / handle). */
+export type MaterialData = Exclude<MaterialDef, MaterialHandle | Material>
+
+const isTextureUrl = (v: unknown): v is string => typeof v === "string" && !v.startsWith("#")
+
+/** Push one parameter into a live material. Textures load asynchronously — the returned promise
+ *  settles once the value is applied (immediately for scalars). */
+export const applyMaterialParam = (material: Material, name: string, value: MaterialParamValue | null): Promise<void> => {
+  if (isTextureUrl(value)) {
+    return Texture.load(value).then((tex) => { material.set(name, tex) }, (e) => {
+      console.warn(`[material] "${name}": ${e instanceof Error ? e.message : String(e)}`)
+    })
+  }
+  material.set(name, value as never)
+  return Promise.resolve()
+}
+
+/** Build a live Material from a data def. Resolves once every texture it names has loaded. */
+export const createMaterialFromData = async (def: MaterialData): Promise<Material> => {
+  if ("shader" in def) {
+    const m = await Material.load(def.shader)
+    await Promise.all(Object.entries(def.params ?? {}).map(([ k, v ]) => applyMaterialParam(m, k, v)))
+    return m
+  }
+  if ("shadow" in def) return Material.shadow(def.shadow)
+  const lit = "lit" in def
+  const opts = lit ? def.lit : def.unlit
+  const { map, ...rest } = opts
+  const m = lit ? Material.lit(rest as LitMaterialOptions) : Material.unlit(rest as UnlitMaterialOptions)
+  if (isTextureUrl(map)) m.map = await Texture.load(map)
+  else if (map !== undefined) m.map = map as LitMaterialOptions["map"] as Texture | null
+  return m
+}
+
+/**
+ * A material asset: the default export of a `*.material.ts` file. `load()` yields ONE shared
+ * `Material` (cached); scene files hand the handle to `material:` and the loader resolves it.
+ * The editor edits the asset live through `setParam` / `reset` — every node the handle was
+ * applied to follows (`_users`).
+ */
+export class MaterialHandle {
+  def: MaterialData
+  private _instance: Material | null = null
+  private _loading: Promise<Material> | null = null
+  /** Every (node, slot) this handle was applied to through a scene — the editor re-assigns them
+   *  when the asset's shader changes. */
+  readonly _users = new Set<{ node: Node, slot: number }>()
+
+  constructor(def: MaterialData) {
+    this.def = def
+  }
+
+  /** The shared material instance (built on first use). */
+  load(): Promise<Material> {
+    if (this._instance) return Promise.resolve(this._instance)
+    this._loading ??= createMaterialFromData(this.def).then((m) => { this._instance = m; return m })
+    return this._loading
+  }
+
+  /** The live instance, if built yet. */
+  get material(): Material | null { return this._instance }
+
+  /** Editor: assign this material to `node`'s `slot`, remembering the user. */
+  async _applyTo(node: Node, slot: number): Promise<Material> {
+    const m = await this.load()
+    node.setMaterial(m, slot)
+    this._users.add({ node, slot })
+    return m
+  }
+
+  /** Editor: one parameter value, applied live to the shared instance (a texture loads in). */
+  setParam(name: string, value: MaterialParamValue | null): void {
+    const def = this.def
+    if ("shader" in def) {
+      def.params ??= {}
+      if (value === null) delete def.params[name]
+      else def.params[name] = value
+    } else if ("lit" in def || "unlit" in def) {
+      const opts = ("lit" in def ? def.lit : def.unlit) as Record<string, unknown>
+      if (value === null) delete opts[name]
+      else opts[name] = value
+    }
+    const m = this._instance
+    if (!m) return
+    if (!("shader" in def) && name === "color") { m.color = value as string; return }
+    if (!("shader" in def) && name === "map") {
+      if (isTextureUrl(value)) void Texture.load(value).then((t) => { m.map = t })
+      else m.map = null
+      return
+    }
+    void applyMaterialParam(m, name, value)
+  }
+
+  /** Editor: replace the whole definition (a shader/kind switch) — rebuilds the instance and
+   *  re-assigns every user. */
+  async reset(def: MaterialData): Promise<Material> {
+    this.def = def
+    this._instance = null
+    this._loading = null
+    const m = await this.load()
+    for (const u of this._users) u.node.setMaterial(m, u.slot)
+    return m
+  }
+}
+
+/** Resolve any `material:` value to a live Material (a handle's shared instance, a data def's
+ *  fresh one, a code instance as is). */
+export const resolveMaterialDef = (def: MaterialDef): Promise<Material> => {
+  if (def instanceof Material) return Promise.resolve(def)
+  if (def instanceof MaterialHandle) return def.load()
+  return createMaterialFromData(def)
+}
+
+/** Resolve and assign a `material:` value to one slot of a node (tracking handle users). */
+export const assignMaterialDef = async (node: Node, slot: number, def: MaterialDef): Promise<Material> => {
+  if (def instanceof MaterialHandle) return def._applyTo(node, slot)
+  const m = await resolveMaterialDef(def)
+  node.setMaterial(m, slot)
+  return m
+}
+
+/**
+ * Define a material as data — the default export of a `*.material.ts` file. Import it into scene
+ * files (`material: handle`) or code (`const m = await handle.load()`).
+ */
+export const defineMaterial = (def: MaterialData): MaterialHandle => {
+  const handle = new MaterialHandle(def)
+  const g = globalThis as unknown as { [EDIT_FLAG]?: boolean, __lecodesMaterialHandles?: MaterialHandle[] }
+  if (g[EDIT_FLAG]) (g.__lecodesMaterialHandles ??= []).push(handle)
+  return handle
+}

package/src/server/auth/appConfig.ts

@@ -0,0 +1,12 @@
+/**
+ * The project's `app.json` subset the server runtime reads (name, auth providers).
+ *
+ * This module is a placeholder the COMPILER REPLACES: `compileServerBundle({ app })` puts a module with the
+ * real values at this same path in chisel's file map (project files win over SDK files), so every SDK module
+ * that imports `app` gets the project's config as a plain dependency — no globals, no evaluation-order games.
+ * Outside a compiled bundle (tests, tooling) `globalThis.__lecodesApp` can stand in.
+ */
+export type AuthProvider = "email" | "google" | "apple" | "yandex" | "vk"
+export type AppConfig = { name?: string, auth?: { providers?: AuthProvider[] } }
+
+export const app: AppConfig = {}

package/src/server/auth/global.ts

@@ -0,0 +1,80 @@
+/**
+ * The `auth` server global (docs/backend-plan.md §3.4) — the BUNDLE side. State (`auth.user`,
+ * `auth.session`) is read from the current request, which the host resolved before the endpoint ran;
+ * operations (`auth.email.*`, `auth.oauth.url`, `signIn/signOut`, `sessions`) forward to the host's
+ * `AuthOps` on `globalThis.__lecodesAuth` (a seam: the compiled bundle carries its own SDK copy). Nothing
+ * here touches the db or a secret; `auth.model.*` are pure schema factories.
+ */
+
+import { currentRequest, type RequestContext } from "../context"
+import type { Model, Query } from "../db/types"
+import { ApiError } from "../errors"
+import { authSessionModel, authUserModel, type AuthProvider, type SessionFields, type UserFields } from "./models"
+import type { AuthOps, AuthState, AuthUser, OAuthCredential } from "./types"
+
+const seam = globalThis as unknown as { __lecodesAuth?: AuthOps }
+const ops = (): AuthOps => {
+  const o = seam.__lecodesAuth
+  if (!o) throw new Error("auth: not available — the host did not install the auth runtime (globalThis.__lecodesAuth)")
+  return o
+}
+const ctx = (): RequestContext => {
+  const c = currentRequest()
+  if (!c) throw new Error("auth: no current request — auth.* is only available while handling an endpoint or a channel join")
+  return c
+}
+const state = (): AuthState => {
+  const c = ctx()
+  const s = c.auth as AuthState | undefined
+  if (!s) throw new Error("auth: this project has no database — sessions need a defineDb() (auth.model.* are optional, Session is added for you)")
+  return s
+}
+
+/** The schema of the two built-in models, for typing `auth.sessions` (developer extras aren't visible here). */
+type AuthSchema = { User: Model<UserFields>, Session: Model<SessionFields> }
+
+export const auth = {
+  /** The signed-in user (built-in fields; custom ones via `db.user`) or `null`. Request-scoped. */
+  get user(): AuthUser | null { return state().user },
+  /** The device session — exists from the first request, before any login. */
+  get session(): { readonly id: number } { return { id: state().sessionId } },
+  /**
+   * The signed-in user, or `throw new ApiError(401)`; with `match`, every given field must equal the user's
+   * (`{ role: "admin" }`, `{ plan: "pro" }`) or it's a 403.
+   */
+  requireUser(match?: Record<string, unknown>): AuthUser {
+    const u = state().user
+    if (!u) throw new ApiError(401, "Sign in required")
+    if (match) for (const [k, v] of Object.entries(match)) if ((u as Record<string, unknown>)[k] !== v) throw new ApiError(403, "Forbidden")
+    return u
+  },
+  email: {
+    /** Emails a 6-digit code to `email` (always resolves — no "email exists" oracle; rate-limited). Needs `"email"` in app.json providers. */
+    sendCode: (email: string): Promise<void> => ops().email.sendCode(ctx(), email),
+    /** The only email sign-in: checks the code sent to this device session, finds/creates the `User`, binds the session. */
+    verify: (email: string, code: string): Promise<AuthUser> => ops().email.verify(ctx(), email, code),
+  },
+  oauth: {
+    /** A one-time sign-in URL for the platform's OAuth broker (`"google" | "apple" | "yandex" | "vk"`), bound to this device session — open it in the browser. */
+    url: (provider: Exclude<AuthProvider, "email">): Promise<string> => ops().oauth.url(ctx(), provider),
+    /**
+     * Sign in with a credential a NATIVE provider SDK produced in the app (client `OAuth.signIn(provider)`):
+     * the platform verifies it with the provider, finds/links/creates the `User`, binds this session. The
+     * in-app counterpart of the browser broker — same accounts either way.
+     */
+    signIn: (provider: Exclude<AuthProvider, "email">, credential: OAuthCredential): Promise<AuthUser> => ops().oauth.signIn(ctx(), provider, credential),
+  },
+  /** Escape hatch for developer-verified identities (Telegram initData, SSO): binds this session to `userId`. */
+  signIn: (userId: number): Promise<AuthUser> => ops().signIn(ctx(), userId),
+  /** Unbinds the user; the device stays a guest with the same `session.id` (token rotated). */
+  signOut: (): Promise<void> => ops().signOut(ctx()),
+  /** The current user's sessions ("my devices"): a `db.session` query — `await`, `.select()`, `.where(...).updateMany({ revoked: true })`. */
+  get sessions(): Query<AuthSchema, "Session"> { return ops().sessions(ctx()) },
+  /** Schema-time factories — see ./models.ts. */
+  model: {
+    user: authUserModel,
+    session: authSessionModel,
+  },
+}
+
+export type { AuthUser }

package/src/server/auth/host.ts

@@ -0,0 +1,318 @@
+/**
+ * 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.
+ *
+ * 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`.
+ */
+
+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"
+
+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[]
+  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
+}
+
+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 CACHE_TTL_MS = 60_000
+const SEEN_UPDATE_MS = 60_000
+
+const enc = new TextEncoder()
+const b64url = (bytes: ArrayBuffer | Uint8Array): string => {
+  const u = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+  let s = ""
+  for (const b of u) s += String.fromCharCode(b)
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
+}
+const hex = (bytes: ArrayBuffer): string => [...new Uint8Array(bytes)].map(b => b.toString(16).padStart(2, "0")).join("")
+export const sha256 = async (text: string): Promise<string> => hex(await crypto.subtle.digest("SHA-256", enc.encode(text)))
+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)))
+}
+/** 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 EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+const normalizeEmail = (email: unknown): string => {
+  const e = typeof email === "string" ? email.trim().toLowerCase() : ""
+  if (!e || e.length > 254 || !EMAIL_RE.test(e)) throw new ApiError(400, "Invalid email")
+  return e
+}
+
+/** Built-in user shape from a row (custom scalar fields ride along at runtime). */
+const toUser = (row: any): AuthUser => row as AuthUser
+
+export type AuthHost = {
+  /** Resolve the bearer token of `ctx` into `ctx.auth` (minting a guest session when needed). No db → leaves it undefined. */
+  resolve(ctx: RequestContext): Promise<void>
+  ops: AuthOps
+  /** Install `ops` for the bundle's `auth` global (`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.
+   */
+  oauthComplete(provider: Exclude<AuthProvider, "email">, nonce: string, profile: OAuthProfile): Promise<{ userId: number }>
+  /** Test hook / diagnostics: forget cached sessions and users. */
+  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 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() }
+
+  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 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()")
+    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 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() })
+    ctx.auth = state
+    ctx.sessionToken = token
+    return state
+  }
+  const rotate = async (ctx: RequestContext): Promise<void> => {
+    const s = stateOf(ctx)
+    const token = randomToken()
+    await db.session.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 s = stateOf(ctx)
+    await db.session.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
+    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) }
+        return
+      }
+      const row = await db.session.where({ tokenHash: await sha256(token) }).select(sessionSelect()).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) }
+        return
+      }
+    }
+    await mint(ctx)
+  }
+
+  // ── 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")
+    const s = stateOf(ctx)
+    const email = normalizeEmail(rawEmail)
+    const t = now()
+    const recent = (sends.get(email) ?? []).filter(x => t - x < 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)
+    const appName = cfg.appName || "the app"
+    if (cfg.mail) {
+      try { await cfg.mail({ to: email, code, appName }) }
+      catch (e) { log("warn", `[auth] could not send the sign-in code to ${email}: ${(e as Error).message}`) }
+    }
+    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!
+  }
+
+  // ── 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 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 }
+    }
+    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 }
+  }
+
+  // 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 }))!
+  }
+
+  const ops: AuthOps = {
+    email: { sendCode, verify },
+    oauth: { url: oauthUrl, signIn: oauthSignIn },
+    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 }))!
+    },
+    signOut: async (ctx) => { requireDb(); await bind(ctx, null, { rotate: true }) },
+    sessions: (ctx) => {
+      requireDb()
+      const s = stateOf(ctx)
+      return s.userId !== null && hasUser ? db.session.where({ user: { id: s.userId } }) : db.session.where({ id: s.sessionId })
+    },
+  }
+
+  return {
+    resolve, ops, oauthComplete, clearCache,
+    install: () => { (globalThis as any).__lecodesAuth = ops },
+  }
+}