@pithy-sh/auth 0.1.0

package/src/data/betterAuth.ts

@@ -0,0 +1,210 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { JsonDate, SQLiteBoolean } from "@pithy-sh/core/src/data/codecs";
+import { Locale } from "@pithy-sh/core/src/i18n/locale";
+import { z } from "zod";
+
+/**
+ * The Better-Auth-managed tables, one Zod object per table.
+ *
+ * Better Auth owns the reads and writes to these via its Kysely adapter (which wraps our shared
+ * Kysely + `CamelCasePlugin`, so it issues camelCase identifiers that map to the snake_case
+ * `pithy_auth_*` columns our migration creates). These schemas are the table definitions of record:
+ * they back the migration, document the model, and decode any direct read Pithy does. Columns are
+ * column-exact to Better Auth 1.6.19's generated SQLite schema. Dates are ISO-8601 text
+ * (`BetterAuthDate`), booleans are `0|1` (`SQLiteBoolean`) — matching Better Auth's on-disk
+ * representation, not Pithy's ms-epoch house default. `z.input` is the SQLite row; `z.output` the
+ * app shape.
+ */
+
+/**
+ * Date codec for Better-Auth columns. On SQLite/D1 Better Auth's adapter serializes `date` fields with
+ * `Date#toISOString()` — ISO-8601 **text**, not the ms-epoch number Pithy's house `SQLiteDate` assumes.
+ * That on-disk shape is exactly core's `JsonDate` (Date ↔ ISO-8601 string), so this is an alias, named
+ * for its use so the right codec is obvious at each Better-Auth column (`SQLiteDate` would mis-decode).
+ */
+const BetterAuthDate = JsonDate;
+
+/** `pithy_auth_users` — one end user. Text/UUID id (anti-enumeration); email is unique. */
+export const User = z
+  .object({
+    id: z.string().describe("Primary key. A random/UUID text id (not auto-increment) so users cannot be enumerated."),
+    name: z.string().describe("The user's display name, supplied by the provider profile or at sign-up."),
+    email: z
+      .string()
+      .describe("The user's email address. Unique across all users; the identity key for passwordless sign-in."),
+    emailVerified: SQLiteBoolean.describe(
+      "Whether the email has been verified. Stored as `0|1`; magic-link/OTP sign-in sets it true.",
+    ),
+    image: z.string().nullable().describe("URL of the user's avatar from a social profile, or null."),
+    locale: Locale.nullable().describe(
+      "The reader's chosen language as a BCP-47 tag, or null when they have never chosen. Null is not the default locale: it means negotiate from `Accept-Language`, so an unchosen reader follows their device. A stored tag outranks the header.",
+    ),
+    createdAt: BetterAuthDate.describe(
+      "When the user record was created. ISO-8601 text in SQLite; a `Date` in app code.",
+    ),
+    updatedAt: BetterAuthDate.describe(
+      "When the user record was last updated. ISO-8601 text in SQLite; a `Date` in app code.",
+    ),
+  })
+  .describe("A user in `pithy_auth_users` — the canonical identity every session and account hangs off.");
+export type User = z.output<typeof User>;
+
+/** `pithy_auth_sessions` — one active session (the long-lived, bearer/cookie credential). */
+export const Session = z
+  .object({
+    id: z.string().describe("Primary key. A random/UUID text id."),
+    expiresAt: BetterAuthDate.describe(
+      "When the session expires. Slides forward on use within `updateAge`. ISO-8601 text in SQLite.",
+    ),
+    token: z
+      .string()
+      .describe(
+        "The opaque session token. Unique; presented as the cookie value or `Authorization: Bearer`. The refresh credential.",
+      ),
+    createdAt: BetterAuthDate.describe("When the session was created. ISO-8601 text in SQLite."),
+    updatedAt: BetterAuthDate.describe("When the session was last refreshed. ISO-8601 text in SQLite."),
+    ipAddress: z
+      .string()
+      .nullable()
+      .describe(
+        "The client IP at sign-in, for the device registry and `new sign-in from…` security signals. Nullable.",
+      ),
+    userAgent: z.string().nullable().describe("The client user-agent at sign-in. Nullable."),
+    userId: z.string().describe("The owning user's id. Foreign key to `pithy_auth_users(id)`, ON DELETE CASCADE."),
+    deviceId: z
+      .string()
+      .nullable()
+      .describe(
+        "The id of the `pithy_auth_devices` row this session is bound to (per-device sessions), or null for a device-less web login.",
+      ),
+    familyId: z
+      .string()
+      .nullable()
+      .describe(
+        "The refresh-token family this session belongs to, carried across rotations so a replayed refresh token can revoke the whole chain. Server-set; null for a session created before rotation or one never rotated.",
+      ),
+  })
+  .describe("A session in `pithy_auth_sessions` — a signed-in credential, optionally bound to a device.");
+export type Session = z.output<typeof Session>;
+
+/** `pithy_auth_accounts` — a credential/identity link for a user (one row per social provider). */
+export const Account = z
+  .object({
+    id: z.string().describe("Primary key. A random/UUID text id."),
+    issuer: z
+      .string()
+      .describe(
+        "Who asserted this identity, as the identity provider names itself: an OIDC issuer URL (`https://accounts.google.com`), `local:oauth:<id>` for an OAuth provider that publishes none, or `local:credential` for a password. With `accountId` it is the account's identity and carries a unique index — a provider slug is a name this project chose, so two providers pointed at one directory could assert the same `accountId` and land on two rows.",
+      ),
+    accountId: z.string().describe("The provider's stable id for this user (e.g. the Google `sub` claim)."),
+    providerId: z
+      .string()
+      .describe("The provider slug, e.g. `google`. Identifies which OAuth/credential provider this row links."),
+    userId: z.string().describe("The owning user's id. Foreign key to `pithy_auth_users(id)`, ON DELETE CASCADE."),
+    accessToken: z
+      .string()
+      .nullable()
+      .describe("The provider OAuth access token, if granted. Never returned to clients. Nullable."),
+    refreshToken: z
+      .string()
+      .nullable()
+      .describe(
+        "The provider OAuth refresh token, if granted (`accessType: offline`). Never returned to clients. Nullable.",
+      ),
+    idToken: z
+      .string()
+      .nullable()
+      .describe("The provider OIDC id token from the last sign-in. Never returned to clients. Nullable."),
+    accessTokenExpiresAt: BetterAuthDate.nullable().describe(
+      "When the provider access token expires. ISO-8601 text in SQLite. Nullable.",
+    ),
+    refreshTokenExpiresAt: BetterAuthDate.nullable().describe(
+      "When the provider refresh token expires. ISO-8601 text in SQLite. Nullable.",
+    ),
+    scope: z.string().nullable().describe("The OAuth scopes granted, space-delimited. Nullable."),
+    password: z
+      .string()
+      .nullable()
+      .describe("Unused — Pithy is passwordless-only, so this Better-Auth column is always null."),
+    createdAt: BetterAuthDate.describe("When the account link was created. ISO-8601 text in SQLite."),
+    updatedAt: BetterAuthDate.describe("When the account link was last updated. ISO-8601 text in SQLite."),
+  })
+  .describe("An account link in `pithy_auth_accounts` — a user's connection to a social/OAuth provider.");
+export type Account = z.output<typeof Account>;
+
+/** `pithy_auth_verifications` — short-lived tokens: magic-link, OTP, and OAuth PKCE/state. */
+export const Verification = z
+  .object({
+    id: z.string().describe("Primary key. A random/UUID text id."),
+    identifier: z
+      .string()
+      .describe(
+        "What the value verifies — a namespaced email for OTP/magic-link, or the OAuth `state` for PKCE. Indexed.",
+      ),
+    value: z
+      .string()
+      .describe("The token, code, or serialized PKCE/state payload. Consumed atomically on first verify (single-use)."),
+    expiresAt: BetterAuthDate.describe(
+      "When the verification expires (5 min for magic-link/OTP, ~10 min for OAuth state). ISO-8601 text in SQLite.",
+    ),
+    createdAt: BetterAuthDate.describe("When the verification was created. ISO-8601 text in SQLite."),
+    updatedAt: BetterAuthDate.describe("When the verification was last updated. ISO-8601 text in SQLite."),
+  })
+  .describe(
+    "A verification record in `pithy_auth_verifications` — the store behind magic-link, OTP, and OAuth PKCE state.",
+  );
+export type Verification = z.output<typeof Verification>;
+
+/** `pithy_auth_jwks` — the JWKS keypairs that sign and verify short-lived JWT access tokens. */
+export const Jwks = z
+  .object({
+    id: z.string().describe("Primary key. A random/UUID text id, used as the JWT `kid`."),
+    publicKey: z
+      .string()
+      .describe("The public key (JWK), published at `/jwks` so resource servers verify access tokens locally."),
+    privateKey: z
+      .string()
+      .describe(
+        "The private signing key, encrypted at rest with the Better-Auth secret (sourced from `@pithy-sh/secrets`). Never published.",
+      ),
+    createdAt: BetterAuthDate.describe("When the keypair was created. ISO-8601 text in SQLite."),
+    expiresAt: BetterAuthDate.nullable().describe(
+      "When the keypair is retired. Retired keys stay published through their grace window so in-flight tokens still verify. Nullable.",
+    ),
+    alg: z
+      .string()
+      .nullable()
+      .describe(
+        "The signing algorithm this keypair is for (`EdDSA`, `RS256`), published in the key's JWKS entry so a verifier picks the right one without guessing. Nullable because Better Auth declares it optional and a key minted before 1.7 has none — the plugin falls back to `EdDSA`, which is what those keys are.",
+      ),
+    crv: z
+      .string()
+      .nullable()
+      .describe(
+        "The elliptic curve for an EC or OKP key (`Ed25519`, `P-256`), and null for RSA, which has no curve. Published beside `alg` for the same reason.",
+      ),
+  })
+  .describe(
+    "A signing keypair in `pithy_auth_jwks` — rotation keeps prior public keys published so issued tokens keep verifying.",
+  );
+export type Jwks = z.output<typeof Jwks>;
+
+/** `pithy_auth_rate_limit` — Better Auth's database-backed rate-limit counters (per key, durable across isolates). */
+export const RateLimit = z
+  .object({
+    id: z.string().describe("Primary key. A random/UUID text id."),
+    key: z.string().describe("The rate-limit bucket key (path + client IP). Unique."),
+    count: z.number().int().describe("The number of requests counted in the current window."),
+    lastRequest: z
+      .number()
+      .int()
+      .describe(
+        "The ms-epoch timestamp of the most recent request in the window. A raw number, written by Better Auth's limiter.",
+      ),
+  })
+  .describe(
+    "A rate-limit counter in `pithy_auth_rate_limit` — durable per-isolate-safe throttling for the auth send/sign-in routes.",
+  );
+export type RateLimit = z.output<typeof RateLimit>;

package/src/data/device.ts

@@ -0,0 +1,57 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * `pithy_auth_devices` — the device registry, a Pithy-specific table with no Better-Auth equivalent.
+ *
+ * One row per user-device, keyed on a client-generated stable id so the same physical device maps to
+ * one row across re-logins. Sessions link back via `pithy_auth_sessions.device_id`. This table is
+ * written by Pithy code (the `session.create` hook and the device routes) through our shared Kysely,
+ * so it keeps Pithy's house ms-epoch `SQLiteDate` — unlike the Better-Auth tables.
+ */
+
+/** The platform a device runs. `web` covers any browser; mobile carries richer metadata. */
+export const DevicePlatform = z
+  .enum(["ios", "android", "web"])
+  .describe("The device platform: `ios`, `android`, or `web`.");
+export type DevicePlatform = z.output<typeof DevicePlatform>;
+
+/** One registered device. */
+export const Device = z
+  .object({
+    id: z
+      .string()
+      .min(1)
+      .max(128)
+      .describe(
+        "Primary key. A client-generated stable id (UUID) so one physical device maps to one row across re-logins. Bounded because it arrives verbatim from the `x-pithy-device-id` header and becomes both a stored key and the tiebreak inside the device listing's keyset cursor — an unbounded id is an unbounded write, and it would also let one device push that cursor past the length the same route accepts on the way back in, making the registry unpageable past that row. Same reasoning as the control-plane `jti` bound.",
+      ),
+    userId: z
+      .string()
+      .describe("The owning user's id. Foreign key to `pithy_auth_users(id)`, ON DELETE CASCADE. Indexed."),
+    platform: DevicePlatform.describe("The device platform, captured from login metadata."),
+    name: z
+      .string()
+      .nullable()
+      .describe("A human label for the device (OS device name), shown in device-management UI. Nullable."),
+    model: z.string().nullable().describe("The hardware model, for device-management UI and support. Nullable."),
+    osVersion: z.string().nullable().describe("The device OS version at last sign-in. Nullable."),
+    appVersion: z.string().nullable().describe("The client app version at last sign-in. Nullable."),
+    pushToken: z
+      .string()
+      .nullable()
+      .describe("The APNs/FCM push token, stored for the future push capability and updatable. Nullable."),
+    lastIp: z
+      .string()
+      .nullable()
+      .describe("The client IP at the most recent sign-in, for `new sign-in from…` security signals. Nullable."),
+    lastSeenAt: SQLiteDate.describe(
+      "When this device was last seen (most recent sign-in). Ms-epoch in SQLite; a `Date` in app code.",
+    ),
+    createdAt: SQLiteDate.describe("When this device was first registered. Ms-epoch in SQLite; a `Date` in app code."),
+  })
+  .describe("A registered device in `pithy_auth_devices` — per-device sessions, security signals, and push routing.");
+export type Device = z.output<typeof Device>;

package/src/data/kitFields.ts

@@ -0,0 +1,69 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Locale } from "@pithy-sh/core/src/i18n/locale";
+
+/**
+ * The columns Pithy adds to Better Auth's own tables, declared **once**.
+ *
+ * Better Auth owns every read and write to `pithy_auth_users` and `pithy_auth_sessions` through its
+ * Kysely adapter, and it writes only the fields its options declare. So a column that exists in the
+ * migration and in the `User` Zod object and *not* here is null forever and absent from every user
+ * object the instance returns — a migration and a schema field that silently did nothing.
+ *
+ * ## Why one module rather than two agreeing declarations
+ *
+ * These have to appear in two places: `makeAuth`'s live options (`../instance/auth.ts`) and the
+ * schema baseline `pluginSchemaDelta` subtracts each adopter plugin's schema from
+ * (`../migrations/pluginTables.ts`). Both were written out by hand, with a comment in each saying it
+ * "must match" the other and a test claiming to hold them together. The test did not: it compared the
+ * baseline against the `User` schema and never imported `makeAuth` at all, so reverting the live
+ * declaration left the whole suite green while Better Auth silently stopped writing the column (#441).
+ *
+ * `docs/CONVENTIONS.md` is explicit that removing an invariant beats watching it. There is one object
+ * now, imported by both, and the two cannot disagree because there is no second thing to disagree
+ * with. That is also why the consequence is worth restating rather than diluting: leave a kit column
+ * out of the baseline and `pluginSchemaDelta` reports it as something an adopter's plugin brought, so
+ * a plugin that also declares a user `locale` emits `ALTER TABLE … ADD COLUMN locale` against a table
+ * that already has one — a duplicate-column failure part-way through a migration D1 cannot roll back,
+ * because it has no transactional DDL.
+ */
+
+/**
+ * The extra `pithy_auth_users` columns.
+ *
+ * **`locale` is `input: true`, deliberately, and that is the whole point of the column.** Every other
+ * extra field the kit declares is server-set — {@link KIT_SESSION_FIELDS} is `input: false` because a
+ * client that could name its own device or token family could name somebody else's. A locale is the
+ * opposite: it is the reader's own preference, and the flow it exists for is a signed-in reader
+ * switching language and having the choice follow them to their next device. Refusing client input
+ * would leave an admin route as the only way to store a preference, which is not a thing a reader has.
+ *
+ * **What makes that safe is the validator, not the type.** `type: "string"` alone would let a caller
+ * write any string into a column every read passes through `User.parse` — so one `updateUser` with a
+ * megabyte of junk would poison that row, and the admin listing that reads a page of rows would then
+ * throw for every operator rather than only for the author. Better Auth runs `validator.input` on the
+ * supplied value and answers 400 on a failure (`parseInputData`), so the same schema that guards the
+ * read guards the write, one hop earlier.
+ *
+ * **And it is `Locale.nullable()`, not `Locale`.** The column is nullable, the `User` field is
+ * nullable, `AdminUserView` is nullable, and every one of those says the same thing: null is "this
+ * reader has not chosen", which is what makes the server fall back to `Accept-Language`. A validator
+ * that accepted a tag but refused `null` would let a reader pick a language and never take it back —
+ * `updateUser({ locale: null })` answering 400 for the one state the schema calls ordinary.
+ */
+export const KIT_USER_FIELDS = {
+  locale: { type: "string", required: false, input: true, validator: { input: Locale.nullable() } },
+} as const;
+
+/**
+ * The extra `pithy_auth_sessions` columns — the bound device, and the refresh-token family carried
+ * across rotations.
+ *
+ * `input: false` on both: these are server-set facts about a session, and a client able to name its own
+ * device id or token family could name somebody else's.
+ */
+export const KIT_SESSION_FIELDS = {
+  deviceId: { type: "string", required: false, input: false },
+  familyId: { type: "string", required: false, input: false },
+} as const;

package/src/data/rotatedToken.ts

@@ -0,0 +1,40 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * `pithy_auth_rotated_tokens` — the reuse-detection ledger, a Pithy-specific table with no
+ * Better-Auth equivalent.
+ *
+ * One row per refresh token that has been consumed by a rotation. On `/auth/token/rotate` the
+ * presented session token is deleted and recorded here; presenting it again (after it no longer
+ * resolves to a live session) is a replayed refresh credential — the canonical compromise signal for
+ * rotated refresh tokens (OAuth refresh rotation, RFC 6819 §5.2.2.3). The row carries the `familyId`
+ * so the whole token family can be revoked on reuse. Written by Pithy code through our shared Kysely,
+ * so it keeps Pithy's house ms-epoch `SQLiteDate` — unlike the Better-Auth tables.
+ */
+export const RotatedToken = z
+  .object({
+    token: z
+      .string()
+      .describe(
+        "Primary key. The consumed session token, recorded when a rotation revoked it. Presenting it again is reuse.",
+      ),
+    familyId: z
+      .string()
+      .describe(
+        "The refresh-token family this token belonged to. The unit revoked when reuse is detected — every session sharing it is signed out. Indexed.",
+      ),
+    userId: z
+      .string()
+      .describe("The owning user's id, for attributing the reuse audit event to the compromised account."),
+    rotatedAt: SQLiteDate.describe(
+      "When the token was consumed by a rotation. Ms-epoch in SQLite; a `Date` in app code. Drives retention pruning.",
+    ),
+  })
+  .describe(
+    "A consumed refresh token in `pithy_auth_rotated_tokens` — the ledger that powers refresh-token reuse detection and family revocation.",
+  );
+export type RotatedToken = z.output<typeof RotatedToken>;

package/src/data/tables.ts

@@ -0,0 +1,38 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { createDatabase, type DatabaseSchema } from "@pithy-sh/core/src/data/db";
+import type { Kysely } from "kysely";
+import { Account, Jwks, RateLimit, Session, User, Verification } from "./betterAuth";
+import { Device } from "./device";
+import { RotatedToken } from "./rotatedToken";
+
+/**
+ * The auth capability's table map: camelCase keys, so `CamelCasePlugin` emits the snake_case
+ * `pithy_auth_*` SQL. One source of truth shared by the capability wiring, the Better-Auth instance
+ * (whose Kysely adapter wraps this same Kysely), the device registry, and the migration.
+ *
+ * The first six tables are Better-Auth-managed; `pithyAuthDevices` and `pithyAuthRotatedTokens` are
+ * ours. Setting Better Auth's `modelName` to these exact camelCase keys lets the one `CamelCasePlugin`
+ * own the camelCase ↔ snake_case boundary uniformly for both Better Auth's queries and our migration DDL.
+ */
+export const authTables = {
+  pithyAuthUsers: User,
+  pithyAuthSessions: Session,
+  pithyAuthAccounts: Account,
+  pithyAuthVerifications: Verification,
+  pithyAuthJwks: Jwks,
+  pithyAuthRateLimit: RateLimit,
+  pithyAuthDevices: Device,
+  pithyAuthRotatedTokens: RotatedToken,
+};
+export type AuthTables = typeof authTables;
+
+/** The typed Kysely view over the auth tables — shared by the Better-Auth adapter and the device registry. */
+export type AuthDatabase = Kysely<DatabaseSchema<AuthTables>>;
+
+/** Build the auth Kysely over a D1 binding. Carries `CamelCasePlugin`, so query code stays camelCase. */
+export function authDatabase(d1: D1Database): AuthDatabase {
+  return createDatabase(d1, authTables);
+}

package/src/device/registry.ts

@@ -0,0 +1,139 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Device, DevicePlatform } from "../data/device";
+import type { AuthDatabase } from "../data/tables";
+
+/**
+ * The device registry: parse optional device metadata off a sign-in request, upsert the
+ * `pithy_auth_devices` row, and resolve a device's sessions for revocation. All writes go through our
+ * shared Kysely + codecs (ms-epoch dates) — distinct from the Better-Auth-managed tables.
+ */
+
+/** Request headers a client may send at sign-in to register/identify its device. */
+export const DEVICE_HEADERS = {
+  id: "x-pithy-device-id",
+  platform: "x-pithy-platform",
+  name: "x-pithy-device-name",
+  model: "x-pithy-device-model",
+  osVersion: "x-pithy-os-version",
+  appVersion: "x-pithy-app-version",
+  pushToken: "x-pithy-push-token",
+} as const;
+
+/**
+ * Device metadata captured at sign-in. `id` is required; everything else is best-effort. `platform` is
+ * `null` when the header was absent — distinct from a supplied value — so a sparse re-login never
+ * overwrites a known platform with a default.
+ */
+export interface DeviceMeta {
+  id: string;
+  platform: DevicePlatform | null;
+  name: string | null;
+  model: string | null;
+  osVersion: string | null;
+  appVersion: string | null;
+  pushToken: string | null;
+}
+
+function header(headers: Headers, name: string): string | null {
+  const value = headers.get(name)?.trim();
+  return value ? value : null;
+}
+
+/**
+ * Parse device metadata from request headers. Returns `undefined` when no `x-pithy-device-id` is
+ * present — a device-less login (a plain web session). `platform` is `null` when its header is absent
+ * or unrecognized; the default `web` is applied only on first registration, never on a sparse update.
+ */
+export function parseDeviceMeta(headers: Headers): DeviceMeta | undefined {
+  const id = header(headers, DEVICE_HEADERS.id);
+  if (!id) return undefined;
+  const platform = DevicePlatform.safeParse(header(headers, DEVICE_HEADERS.platform));
+  return {
+    id,
+    platform: platform.success ? platform.data : null,
+    name: header(headers, DEVICE_HEADERS.name),
+    model: header(headers, DEVICE_HEADERS.model),
+    osVersion: header(headers, DEVICE_HEADERS.osVersion),
+    appVersion: header(headers, DEVICE_HEADERS.appVersion),
+    pushToken: header(headers, DEVICE_HEADERS.pushToken),
+  };
+}
+
+/**
+ * Register-or-update a device for a user. Idempotent on the composite `(userId, id)` key: a re-login
+ * from the same device refreshes `lastSeenAt`/`lastIp` and any newly-supplied metadata, but never
+ * overwrites existing metadata with a sparse login and never resets `createdAt`.
+ */
+export async function registerDevice(
+  db: AuthDatabase,
+  meta: DeviceMeta,
+  context: { userId: string; lastIp: string | null; now: Date },
+): Promise<void> {
+  const record = Device.encode({
+    id: meta.id,
+    userId: context.userId,
+    // `web` is the default only at first registration; an update preserves the stored platform unless
+    // the client supplied a fresh one (handled in `refreshed` below).
+    platform: meta.platform ?? "web",
+    name: meta.name,
+    model: meta.model,
+    osVersion: meta.osVersion,
+    appVersion: meta.appVersion,
+    pushToken: meta.pushToken,
+    lastIp: context.lastIp,
+    lastSeenAt: context.now,
+    createdAt: context.now,
+  });
+  // Only refresh fields the client actually supplied this time, so a metadata-light re-login keeps
+  // earlier richer detail.
+  const refreshed: Record<string, unknown> = {
+    lastSeenAt: record.lastSeenAt,
+    lastIp: record.lastIp,
+  };
+  if (meta.platform !== null) refreshed.platform = record.platform;
+  if (meta.name !== null) refreshed.name = record.name;
+  if (meta.model !== null) refreshed.model = record.model;
+  if (meta.osVersion !== null) refreshed.osVersion = record.osVersion;
+  if (meta.appVersion !== null) refreshed.appVersion = record.appVersion;
+  if (meta.pushToken !== null) refreshed.pushToken = record.pushToken;
+
+  await db
+    .insertInto("pithyAuthDevices")
+    .values(record)
+    .onConflict((oc) => oc.columns(["userId", "id"]).doUpdateSet(refreshed))
+    .execute();
+}
+
+/** List a user's registered devices, most-recently-seen first. */
+export async function listDevices(db: AuthDatabase, userId: string): Promise<Device[]> {
+  const rows = await db
+    .selectFrom("pithyAuthDevices")
+    .selectAll()
+    .where("userId", "=", userId)
+    .orderBy("lastSeenAt", "desc")
+    .execute();
+  return rows.map((row) => Device.parse(row));
+}
+
+/** Resolve the session tokens bound to one of a user's devices — the set a device-revoke must sign out. */
+export async function deviceSessionTokens(db: AuthDatabase, userId: string, deviceId: string): Promise<string[]> {
+  const rows = await db
+    .selectFrom("pithyAuthSessions")
+    .select("token")
+    .where("userId", "=", userId)
+    .where("deviceId", "=", deviceId)
+    .execute();
+  return rows.map((row) => row.token);
+}
+
+/** Delete a user's device row (after its sessions are revoked). Returns true if a row was removed. */
+export async function deleteDevice(db: AuthDatabase, userId: string, deviceId: string): Promise<boolean> {
+  const result = await db
+    .deleteFrom("pithyAuthDevices")
+    .where("userId", "=", userId)
+    .where("id", "=", deviceId)
+    .executeTakeFirst();
+  return (result.numDeletedRows ?? 0n) > 0n;
+}

package/src/email/send.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { EmailCapability } from "@pithy-sh/email/src/capability";
+import type { AuthEmailMessage, SendAuthEmail } from "../instance/auth";
+
+/**
+ * The email-delivery seam. Auth never assembles the email infrastructure — it calls the `enqueue` the
+ * email capability exposes (already bound to the request env by the caller), passing only the
+ * high-level input. The email capability owns the `DB`/`EMAIL_SENDER` bindings, the from-identity, and
+ * the theme. Delivery is the email Workflow's job; auth only enqueues.
+ */
+
+/** An env-bound enqueue — the email capability's `enqueue`, partially applied with the request env. */
+export type EnqueueEmail = (input: Parameters<EmailCapability["enqueue"]>[1]) => Promise<unknown>;
+
+/**
+ * The language to write to this person in, resolved per message.
+ *
+ * A thunk over the address rather than a value, because the answer is a database read and most of
+ * what it is asked about is a sign-in that may not have an account yet. See {@link makeSendAuthEmail}.
+ */
+export type ResolveRecipientLocale = (email: string) => Promise<string | null>;
+
+/**
+ * Build the `sendEmail` the auth instance calls from its magic-link / OTP hooks.
+ *
+ * ## The locale
+ *
+ * A sign-in email is the first thing a project sends and the one it cannot afford to send in a
+ * language the reader does not have, because there is no password to fall back to: somebody who cannot
+ * find the button in an unfamiliar alphabet cannot get in at all. So `localeFor` is asked per message
+ * and the answer rides onto the job, where the send Workflow reads it back hours later.
+ *
+ * It resolves in two steps and the order matters. **A stored `pithy_auth_users.locale` wins**, because
+ * a person who has chosen a language has said something durable about themselves, and the device they
+ * happen to be signing in from tonight has not. Where there is no row — a first-time sign-up, which is
+ * exactly when a magic link matters most — the resolver falls back to the language this request
+ * negotiated, which is the only thing anyone knows about the reader yet. Null means neither answered,
+ * and null renders the kit's English rather than asserting English was chosen.
+ *
+ * Optional so that a composition without it (and every existing test harness) behaves as it did.
+ */
+export function makeSendAuthEmail(
+  enqueue: EnqueueEmail,
+  expiresMinutes: number,
+  localeFor?: ResolveRecipientLocale,
+): SendAuthEmail {
+  return async (message: AuthEmailMessage): Promise<void> => {
+    const locale = (await localeFor?.(message.to)) ?? undefined;
+    if (message.template === "magicLink") {
+      await enqueue({
+        to: message.to,
+        template: "magicLink",
+        payload: { url: message.url, expiresMinutes },
+        ...(locale ? { locale } : {}),
+      });
+      return;
+    }
+    await enqueue({
+      to: message.to,
+      template: "otp",
+      payload: { code: message.code, expiresMinutes },
+      ...(locale ? { locale } : {}),
+    });
+  };
+}