@pithy-sh/auth 0.1.0

package/src/http/responses.ts

@@ -0,0 +1,199 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { Locale } from "@pithy-sh/core/src/i18n/locale";
+import { z } from "zod";
+import { DevicePlatform } from "../data/device";
+
+/**
+ * What the auth admin routes return, as Zod objects a management client can validate against.
+ *
+ * `schemas.ts` bounds what a caller may send; this file states what it gets back. Both halves are
+ * runtime values for the same reason: a management client reading a customer's Worker is crossing a
+ * trust boundary, its own rules require it to validate that response before rendering it, and a
+ * TypeScript interface is erased before it can help. Every client that had only an interface
+ * hand-wrote a mirror of these, and the mirror drifted the first time a field landed here.
+ *
+ * **No codecs, and no transform anywhere in this file.** These describe JSON on the wire, so parsing
+ * one hands back exactly what went in — which is what lets `responses.test.ts` compare a parsed value
+ * with the projection's output and fail on a field either side forgot. A `SQLiteDate` here would
+ * decode an ISO string into a `Date` and make that comparison meaningless.
+ *
+ * The projections that fill these live in `views.ts`, which documents *why* a credential is absent
+ * from each. This file is the shape; that file is the argument.
+ *
+ * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
+ * version boundary — a management client validates a response with this schema against a customer's
+ * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
+ * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
+ * say*, which is a different fact from `null`.
+ */
+
+/** Where a page resumes, or the end of the list. */
+const NextCursor = z
+  .string()
+  .nullable()
+  .describe("Where the next page resumes. Null at the end of the list. Opaque — pass it back verbatim.");
+
+/** How many sessions a revocation actually ended. */
+const RevokedCount = z
+  .number()
+  .int()
+  .min(0)
+  .describe("How many sessions were revoked. Zero is a success: revoking nothing is the idempotent case.");
+
+/** A user as a management client may see them. */
+export const AdminUserView = z
+  .object({
+    id: z.string().describe("The user's id, as `pithy_auth_users.id` stores it."),
+    email: z.string().describe("The user's email address. Personal data, and the point of a support pane."),
+    name: z.string().describe("The display name from the provider profile or sign-up."),
+    emailVerified: z.boolean().describe("Whether the address has been verified."),
+    image: z.string().nullable().describe("The avatar URL from a social profile, or null."),
+    // `Locale`, not a bare string: it is a plain schema with checks and no transform, so parsing a
+    // response still hands back exactly what went in — which is what `responses.test.ts` compares.
+    locale: Locale.nullable()
+      .optional()
+      .describe(
+        "The reader's chosen language as a BCP-47 tag; null when they have never chosen one, and absent when the Worker that answered predates the field (#450).",
+      ),
+    createdAt: z.iso.datetime().describe("When the user was created, ISO-8601."),
+    updatedAt: z.iso.datetime().describe("When the row was last written, ISO-8601."),
+  })
+  .describe("One user as a management client sees them. The table holds no credential, so nothing is withheld.");
+export type AdminUserView = z.output<typeof AdminUserView>;
+
+/** A session as a management client may see it — the token is not part of the contract. */
+export const AdminSessionView = z
+  .object({
+    id: z.string().describe("The session's id — the handle `POST /admin/sessions/revoke` accepts. Not the token."),
+    deviceId: z.string().nullable().describe("The device this session was created on, or null."),
+    ipAddress: z.string().nullable().describe("Where the sign-in came from, or null. The field that catches a theft."),
+    userAgent: z.string().nullable().describe("The client user-agent at sign-in, or null."),
+    createdAt: z.iso.datetime().describe("When the session began, ISO-8601."),
+    updatedAt: z.iso.datetime().describe("When it was last refreshed, ISO-8601."),
+    expiresAt: z.iso.datetime().describe("When it lapses, ISO-8601."),
+  })
+  .describe("One session as a management client sees it — without the token, which is the credential itself.");
+export type AdminSessionView = z.output<typeof AdminSessionView>;
+
+/** A registered device as a management client may see it — the push token is not part of the contract. */
+export const AdminDeviceView = z
+  .object({
+    id: z.string().describe("The client-generated device id it registered at sign-in."),
+    userId: z.string().describe("The owning user's id."),
+    platform: DevicePlatform.describe("The platform the device registered as."),
+    name: z.string().nullable().describe("The device's human label, or null."),
+    model: z.string().nullable().describe("The hardware model, or null."),
+    osVersion: z.string().nullable().describe("The device OS version at last sign-in, or null."),
+    appVersion: z.string().nullable().describe("The client app version at last sign-in, or null."),
+    lastIp: z.string().nullable().describe("Where the device was last seen, or null."),
+    lastSeenAt: z.iso.datetime().describe("When it was last seen, ISO-8601."),
+    createdAt: z.iso.datetime().describe("When it first registered, ISO-8601."),
+  })
+  .describe("One registered device as a management client sees it — without the push token, which is a credential.");
+export type AdminDeviceView = z.output<typeof AdminDeviceView>;
+
+/** `GET {base}/admin/users`. */
+export const AdminUsersResponse = z
+  .object({
+    users: z.array(AdminUserView).describe("The page, newest first."),
+    nextCursor: NextCursor,
+  })
+  .describe("A page of the user list.");
+export type AdminUsersResponse = z.output<typeof AdminUsersResponse>;
+
+/** `GET {base}/admin/users/:userId`. */
+/**
+ * A sub-read of the user pane that could not be made (#380).
+ *
+ * The pane fans out over three independent tables and this route used to `Promise.all` them: one D1 read
+ * failing took the whole page down, so a support agent looking at a locked-out account saw a 500 instead
+ * of the user and whichever lists did read.
+ *
+ * It carries **no rows and no reason**. No rows, because an empty array means *this user has none* and a
+ * pane rendering "no active sessions" over a list nobody read is telling a support agent something that
+ * was never established. No reason, because what a D1 read throws names a query and a table, and this
+ * response crosses a trust boundary to a management client.
+ */
+const ListUnavailable = z
+  .object({ state: z.literal("unavailable").describe("The list could not be read on this request.") })
+  .describe("Nothing was established about this list. Deliberately empty — there is nothing here to render as 'none'.");
+
+/** A bounded sub-list, behind its state: the rows and the truncation flag are unreachable without narrowing. */
+const boundedList = <T extends z.ZodTypeAny>(items: T, what: string) =>
+  z
+    .discriminatedUnion("state", [
+      z
+        .object({
+          state: z.literal("read").describe("The list was read."),
+          items: z.array(items).describe(`${what} Empty means this user has none.`),
+          truncated: z
+            .boolean()
+            .describe(
+              "True when more rows exist than the bound allowed. A pane must say so rather than imply a total.",
+            ),
+        })
+        .describe("The rows, and whether the bound cut them short."),
+      ListUnavailable,
+    ])
+    .describe(`${what} Behind a state, so an unread list cannot be rendered as an empty one.`);
+
+/** An unbounded sub-list, behind the same state. No truncation flag: this read has no bound to exceed. */
+const wholeList = <T extends z.ZodTypeAny>(items: T, what: string) =>
+  z
+    .discriminatedUnion("state", [
+      z
+        .object({
+          state: z.literal("read").describe("The list was read."),
+          items: z.array(items).describe(`${what} Empty means this user has none.`),
+        })
+        .describe("The rows, in full."),
+      ListUnavailable,
+    ])
+    .describe(`${what} Behind a state, so an unread list cannot be rendered as an empty one.`);
+
+export const AdminUserResponse = z
+  .object({
+    user: AdminUserView.describe("The user."),
+    providers: wholeList(
+      z.string(),
+      "The OAuth providers linked to this account, as slugs. Read by a query that selects only `providerId`, so no provider token is ever loaded.",
+    ),
+    sessions: boundedList(AdminSessionView, "Their live sessions, newest first, bounded."),
+    devices: boundedList(AdminDeviceView, "Their registered devices, most recently seen first, bounded."),
+  })
+  .describe(
+    "One user with their live sessions, registered devices, and linked providers. The user is the subject and its absence is a 404; the three lists are contributors, and one that will not read costs its own list and not the page (#380).",
+  );
+export type AdminUserResponse = z.output<typeof AdminUserResponse>;
+
+/** `GET {base}/admin/devices`. */
+export const AdminDevicesResponse = z
+  .object({
+    devices: z.array(AdminDeviceView).describe("The page, most recently seen first."),
+    nextCursor: NextCursor,
+  })
+  .describe("A page of the device registry.");
+export type AdminDevicesResponse = z.output<typeof AdminDevicesResponse>;
+
+/**
+ * `POST {base}/admin/sessions/revoke` and `POST {base}/admin/users/:userId/sessions/revoke`.
+ *
+ * A count and nothing else, deliberately. Both routes are idempotent — revoking a session that has
+ * already gone is a success — and neither caller holds a read scope, so the response must not say
+ * whose session it was. The owning user reaches the audit trail instead.
+ */
+export const AdminRevokeResponse = z
+  .object({ revoked: RevokedCount })
+  .describe("How many sessions the revocation ended.");
+export type AdminRevokeResponse = z.output<typeof AdminRevokeResponse>;
+
+/** `POST {base}/admin/users/:userId/devices/revoke`. */
+export const AdminDeviceRevokeResponse = z
+  .object({
+    revoked: RevokedCount,
+    removed: z.boolean().describe("Whether a device row was deleted. False when the user had no such device."),
+  })
+  .describe("How many sessions the device revocation ended, and whether the registry row went with them.");
+export type AdminDeviceRevokeResponse = z.output<typeof AdminDeviceRevokeResponse>;

package/src/http/routes.ts

@@ -0,0 +1,325 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { zValidator } from "@hono/zod-validator";
+import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
+import { UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
+import { requireSameOrigin } from "@pithy-sh/core/src/http/sameOrigin";
+import { validationHook } from "@pithy-sh/core/src/http/validation";
+import { TURNSTILE_LOGIN_ACTION } from "@pithy-sh/turnstile/src/config/config";
+import { turnstile } from "@pithy-sh/turnstile/src/http/middleware";
+import type { Context, Hono } from "hono";
+import { correlation, emitDenied, emitDeviceRevoked, emitTokenRefresh, emitTokenReuseDetected } from "../audit/emit";
+import type { AuthWiring } from "../capability";
+import { authDatabase } from "../data/tables";
+import { deleteDevice, deviceSessionTokens, listDevices } from "../device/registry";
+import {
+  consumeSession,
+  findConsumedToken,
+  pruneConsumedTokens,
+  recordConsumedToken,
+  revokeFamily,
+} from "../token/rotation";
+import { registerAuthAdminRoutes } from "./adminRoutes";
+import { apiErrorToPithy } from "./errors";
+import { requireAuth } from "./middleware";
+import { getAuthInstance, resolveDb } from "./resolve";
+import { RevokeDeviceBody } from "./schemas";
+
+type Ctx = Context<PithyHonoEnv>;
+
+function db(c: Ctx, wiring: AuthWiring) {
+  return authDatabase(resolveDb(c.env, wiring.config.database));
+}
+
+/**
+ * Register the auth routes onto the backend's Hono app.
+ *
+ * Order matters: turnstile gates the human-initiated send routes (only when composed), Pithy's own
+ * routes are registered before the catch-all so they win, and Better Auth owns everything else under
+ * `basePath`. A handler that returns a Response ends the chain, so the specific routes never fall
+ * through to the catch-all. (The tier-1 edge rate limiter is contributed as capability *middleware*, so
+ * it runs before session resolution — see `capability.ts`.)
+ *
+ * What each Pithy-owned route accepts, declared on its route line (schemas in `./schemas`):
+ *
+ * | Route                      | Verification    | Input                       |
+ * | -------------------------- | --------------- | --------------------------- |
+ * | `POST /token/rotate`       | bearer/session  | none — the credential only  |
+ * | `GET  /devices`            | bearer/session  | none                        |
+ * | `POST /devices/revoke`     | bearer/session  | json `RevokeDeviceBody`     |
+ * | `*    /admin/*`            | control-plane   | see `./adminRoutes`         |
+ *
+ * The catch-all takes NO validator, deliberately: `handleBetterAuth` hands Better Auth `c.req.raw`,
+ * and reading the body first would consume the stream. Better Auth validates its own endpoints and
+ * answers its own refusals; what it rejects reaches a caller in its shape, not ours.
+ *
+ * **The admin routes must be registered before the catch-all, and it is not a style preference.**
+ * `handleBetterAuth` returns a Response, which ends the chain — so a route registered after
+ * `app.all(`${base}/*`)` is mounted, is visible in `app.routes`, and never runs. A management call to
+ * `/auth/admin/users` would instead reach Better Auth, which knows no such endpoint, and the failure
+ * would look like a 404 from the wrong layer. `routeContract.test.ts` proves the ordering with a real
+ * request rather than by inspecting the route table, because the route table cannot see this.
+ */
+export function createAuthRoutes(wiring: AuthWiring): (app: Hono<PithyHonoEnv>) => void {
+  return (app) => {
+    const base = wiring.config.basePath;
+    // The CSRF origin guard for our own mutating routes (Better Auth guards its own endpoints). The
+    // same gate an adopter's routes wear: this capability publishes it bound to the origins it
+    // resolved, and reads it back here rather than binding a second copy of the same decision.
+    const csrf = requireSameOrigin();
+
+    // Auto-gate the magic-link and OTP send routes with the humanity check, when turnstile is composed.
+    // The action is `@pithy-sh/turnstile`'s constant, never a literal: the widget is solved for the same
+    // string through the client projection, and a second copy of it could only be caught in production —
+    // where the two disagreeing refuses every sign-in. #377, and `TURNSTILE_LOGIN_ACTION`'s docblock.
+    if (wiring.turnstile) {
+      const guard = turnstile({ mode: wiring.turnstile.mode, action: TURNSTILE_LOGIN_ACTION });
+      app.use(`${base}/sign-in/magic-link`, guard);
+      app.use(`${base}/email-otp/send-verification-otp`, guard);
+    }
+
+    // Rotate the refresh credential: mint a new session, revoke the presented one, return a fresh JWT.
+    app.post(`${base}/token/rotate`, csrf, (c) => rotateToken(c, wiring));
+    // Device management (bearer/session gated; the revoke is CSRF-guarded as a mutating route).
+    app.get(`${base}/devices`, requireAuth(), (c) => listMyDevices(c, wiring));
+    app.post(`${base}/devices/revoke`, requireAuth(), csrf, zValidator("json", RevokeDeviceBody, validationHook), (c) =>
+      revokeMyDevice(c, wiring, c.req.valid("json")),
+    );
+
+    // The control-plane management surface. Registered here, before the catch-all below, or it is dead.
+    registerAuthAdminRoutes(wiring)(app);
+
+    // Better Auth owns the rest (sign-in, verify, callback, sign-out, /token, /jwks, revoke-sessions…).
+    app.all(`${base}/*`, (c) => handleBetterAuth(c, wiring));
+  };
+}
+
+/** The statuses that mean somebody was turned away, rather than that something is broken. */
+const DENIED_STATUSES = new Set([400, 401, 403]);
+
+/**
+ * Whether a refused request on this path was an attempt to authenticate.
+ *
+ * **The audit action is `auth/signin`, so the path has to earn it.** `emitDenied` records
+ * `auth/signin outcome=denied actorType=anonymous`, which is the row a brute-force alert counts — and
+ * the catch-all under `basePath` carries far more than sign-in. Recording every 4xx there would write
+ * a *failed sign-in* for a logged-out tab polling `/update-user` with a stale cookie, and would let an
+ * unauthenticated loop against `/list-sessions` bury real credential-stuffing under noise wearing the
+ * same anonymous shape.
+ *
+ * So: the routes where presenting something and being refused *is* the failed attempt — starting a
+ * sign-in, completing one at an OAuth callback, and asking for the credential that starts one.
+ */
+function isSignInAttempt(path: string): boolean {
+  return (
+    path.includes("/sign-in/") ||
+    path.includes("/callback/") ||
+    path.includes("/magic-link/") ||
+    path.includes("/email-otp/")
+  );
+}
+
+/**
+ * Record a Better Auth refusal on the audit trail.
+ *
+ * **Read off the Response, because a refusal never arrives as a throw.** `onAPIError: { throw: true }`
+ * reads as though an endpoint's `APIError` reaches this module, and it does not: better-auth's
+ * `onError` re-raises it (`better-auth/dist/api/index.mjs:193`) directly into better-call's own catch
+ * (`better-call@1.4.0`, `dist/router.mjs:83-89`), which renders an `APIError` as a Response and returns
+ * it. The throw is swallowed one frame later by the library that asked for it.
+ *
+ * So the `emitDenied` call this replaces — gated on catching an `APIError` — had never run once. No
+ * failed one-time code, no bad magic link, no refused OAuth callback has ever reached
+ * `pithy_audit_events`, which is the largest class of security event this capability has (#449).
+ *
+ * **The body is cloned, never consumed.** The Response is handed back to the caller untouched: Better
+ * Auth's own flat shape is a contract adopters read through `createAuthClient`, and the browser client
+ * reads it too, so nothing here rewrites it.
+ */
+async function auditRefusal(c: Ctx, response: Response): Promise<void> {
+  if (!DENIED_STATUSES.has(response.status)) return;
+  if (!isSignInAttempt(new URL(c.req.raw.url).pathname)) return;
+
+  let body: unknown;
+  try {
+    body = await response.clone().json();
+  } catch {
+    // A body that will not parse still refused somebody, but names no reason worth a row.
+    return;
+  }
+  const code = (body as { code?: unknown } | null)?.code;
+
+  // Record only the Better-Auth error *code* (e.g. INVALID_OTP) — never the message, which can
+  // carry the submitted email or other request context (no PII in the audit trail).
+  await emitDenied(c.var.emit, {
+    ...correlation(c.req.raw.headers),
+    detail: typeof code === "string" ? code : undefined,
+  });
+}
+
+/**
+ * Delegate to Better Auth's fetch handler, and record what it refused.
+ *
+ * **The answer is returned exactly as Better Auth wrote it.** Re-homing its flat `{ message, code }`
+ * into the kit envelope was tried and taken back out: `packages/auth/README.md` documents
+ * `createAuthClient` from `better-auth/client` as a first-class client surface (#271), and
+ * `@better-fetch/fetch` builds its error as `{ ...parsedBody, status }` — so rewriting the body would
+ * make `error.code` `undefined` for every adopter on the documented path. The wire is Better Auth's
+ * contract. `readFailure` in `../client/api` learns to read it instead (#449).
+ *
+ * The `catch` covers what better-call genuinely hands on: a non-`APIError` throw from an endpoint
+ * (`router.mjs:88`), and a throw from a plugin's `onRequest` hook, which runs outside the router's own
+ * try. A failure building the instance does **not** come this way — `getAuthInstance` is called before
+ * it, and what that throws is already a `PithyError` for `pithyErrorHandler` to render.
+ */
+async function handleBetterAuth(c: Ctx, wiring: AuthWiring): Promise<Response> {
+  const instance = await getAuthInstance(c, wiring);
+  let response: Response;
+  try {
+    response = await instance.handler(c.req.raw);
+  } catch (error) {
+    throw apiErrorToPithy(error);
+  }
+  await auditRefusal(c, response);
+  return response;
+}
+
+/** The raw bearer token presented on the Authorization header, or undefined when none/malformed. */
+function bearerToken(headers: Headers): string | undefined {
+  const match = headers.get("authorization")?.match(/^Bearer\s+(.+)$/i);
+  return match?.[1]?.trim() || undefined;
+}
+
+/**
+ * Grace window after a token is consumed during which a replay is treated as a benign concurrent or
+ * retried rotation — denied, but WITHOUT revoking the family — rather than compromise. It absorbs a
+ * client that fires or retries the same rotation twice (a network race) so a legitimate double-submit
+ * never signs the user out everywhere. A replay past the window is a genuine reuse and revokes.
+ */
+const ROTATION_REUSE_GRACE_MS = 30_000;
+
+/**
+ * Rotate the refresh credential. Validates the presented session, mints a fresh one (preserving the
+ * device binding and refresh-token family), atomically revokes the old one, and returns a new access
+ * token + refresh token. This is the "refresh credential rotates on use" primitive Better Auth does not
+ * provide natively.
+ *
+ * Two hardenings over a naive rotate (#59):
+ *  - **Reuse detection.** A presented token that no longer resolves to a live session but was previously
+ *    consumed is a replayed refresh token — the compromise signal for rotated refresh tokens
+ *    (RFC 6819 §5.2.2.3). The whole family is revoked and the attempt denied. (Covers the bearer refresh
+ *    flow — the mobile refresh credential; a cookie session presented after rotation already fails closed.)
+ *  - **Race safety.** The old session is consumed by a conditional delete that exactly one concurrent
+ *    rotation wins; the loser rolls back its freshly-minted successor. One presented token, one successor.
+ */
+async function rotateToken(c: Ctx, wiring: AuthWiring): Promise<Response> {
+  const instance = await getAuthInstance(c, wiring);
+  const headers = c.req.raw.headers;
+  const database = db(c, wiring);
+  const ctx = await instance.$context;
+  const current = await instance.api.getSession({ headers });
+
+  if (!current) {
+    // The presented token resolves to no live session. If it was consumed by an earlier rotation, it is
+    // a replay: compromise past the grace window (revoke the family), or a benign concurrent/retried
+    // rotation within it (deny only). Otherwise the token is simply invalid or expired.
+    const presented = bearerToken(headers);
+    const consumed = presented ? await findConsumedToken(database, presented) : null;
+    if (consumed) {
+      if (Date.now() - consumed.rotatedAt.getTime() >= ROTATION_REUSE_GRACE_MS) {
+        await revokeFamily(database, consumed.familyId, (token) => ctx.internalAdapter.deleteSession(token));
+        await emitTokenReuseDetected(c.var.emit, {
+          userId: consumed.userId,
+          familyId: consumed.familyId,
+          ...correlation(headers),
+        });
+        throw new UnauthorizedError({
+          message: "This credential has been revoked.",
+          action: "Sign in again to obtain a new session.",
+        });
+      }
+      // Within the grace window: a superseded token from a race/retry. Deny, but leave the family — the
+      // successor the winning rotation issued must keep working.
+      throw new UnauthorizedError({
+        message: "Authentication required.",
+        action: "Retry with your current session or bearer token.",
+      });
+    }
+    throw new UnauthorizedError({
+      message: "Authentication required.",
+      action: "Present a valid session or bearer token to rotate.",
+    });
+  }
+
+  const ip = headers.get("cf-connecting-ip") ?? undefined;
+  const userAgent = headers.get("user-agent") ?? undefined;
+  const session = current.session as { token: string; deviceId?: string | null; familyId?: string | null };
+  const deviceId = session.deviceId ?? undefined;
+  // Carry the family forward across the rotation; a session that never had one starts a family now.
+  const familyId = session.familyId ?? crypto.randomUUID();
+
+  // Mint the successor session and its access token BEFORE consuming the old one, so a transient signing
+  // failure leaves the presented refresh token still valid (the successor simply expires unused) rather
+  // than stranding the caller with no working credential.
+  const next = await ctx.internalAdapter.createSession(current.user.id, undefined, {
+    ipAddress: ip,
+    userAgent,
+    familyId,
+    ...(deviceId ? { deviceId } : {}),
+  });
+  const access = await instance.api.getToken({ headers: new Headers({ authorization: `Bearer ${next.token}` }) });
+
+  // Atomically consume the presented session. Of N concurrent rotations, exactly one wins the delete;
+  // the losers roll back the successor they minted, so one presented token never yields two successors.
+  const consumed = await consumeSession(database, session.token);
+  if (!consumed.won) {
+    await ctx.internalAdapter.deleteSession(next.token);
+    throw new UnauthorizedError({
+      message: "Authentication required.",
+      action: "Retry with your current session or bearer token.",
+    });
+  }
+
+  // Record the consumed token so a later replay is caught as reuse (the family is already carried forward).
+  await recordConsumedToken(database, {
+    token: session.token,
+    familyId,
+    userId: current.user.id,
+    rotatedAt: new Date(),
+  });
+  await emitTokenRefresh(c.var.emit, { userId: current.user.id, sessionId: next.id, ip, userAgent });
+
+  // Bound the ledger: a token consumed longer ago than a full session lifetime can no longer match any
+  // live session. Best-effort — a cleanup failure must never fail the rotation it rode in on.
+  try {
+    await pruneConsumedTokens(database, new Date(Date.now() - wiring.config.sessionExpiresIn * 1000));
+  } catch {
+    // Retention pruning is non-critical maintenance.
+  }
+
+  return c.json({ accessToken: access.token, refreshToken: next.token, expiresAt: next.expiresAt });
+}
+
+/** List the authenticated user's registered devices. */
+async function listMyDevices(c: Ctx, wiring: AuthWiring): Promise<Response> {
+  const userId = c.var.auth?.userId;
+  if (!userId) throw new UnauthorizedError({ message: "Authentication required." });
+  return c.json({ devices: await listDevices(db(c, wiring), userId) });
+}
+
+/** Revoke one of the authenticated user's devices: sign out its sessions, then drop the device row. */
+async function revokeMyDevice(c: Ctx, wiring: AuthWiring, body: RevokeDeviceBody): Promise<Response> {
+  const userId = c.var.auth?.userId;
+  if (!userId) throw new UnauthorizedError({ message: "Authentication required." });
+  const deviceId = body.deviceId;
+  const database = db(c, wiring);
+  const tokens = await deviceSessionTokens(database, userId, deviceId);
+  const ctx = await (await getAuthInstance(c, wiring)).$context;
+  for (const token of tokens) {
+    await ctx.internalAdapter.deleteSession(token);
+  }
+  await deleteDevice(database, userId, deviceId);
+  await emitDeviceRevoked(c.var.emit, { userId, ...correlation(c.req.raw.headers) });
+  return c.json({ revoked: tokens.length });
+}

package/src/http/schemas.ts

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
+import { z } from "zod";
+import { DevicePlatform } from "../data/device";
+
+/**
+ * The request schemas for the auth routes Pithy owns. Validation happens at the HTTP boundary
+ * (CLAUDE.md §Zod), declared on the route line with `zValidator(target, Schema, validationHook)` — so
+ * reading `routes.ts` and `adminRoutes.ts` tells you what each route accepts without opening a handler.
+ *
+ * Only Pithy's own routes appear here. Everything under `basePath` that Better Auth owns validates
+ * itself, behind a catch-all that must hand it an unread request body.
+ *
+ * Every schema below the first is a bound on something a **management client** chose. Verified is not
+ * the same as trusted: a control-plane credential proves who is calling, not that their pagination is
+ * sane, and a client with a bug asks for a million user rows exactly as easily as a hostile one does.
+ */
+
+/**
+ * The body of `POST /devices/revoke` and of the admin `POST /admin/users/:userId/devices/revoke`.
+ * `deviceId` is client-minted (it arrives as the `x-pithy-device-id` header at sign-in), so it is
+ * bounded rather than shape-checked: a well-formed id that matches no row must still reach the handler,
+ * which answers `{ revoked: 0 }`.
+ */
+export const RevokeDeviceBody = z
+  .object({
+    deviceId: z
+      .string()
+      .min(1)
+      .max(256)
+      .describe("The id of the device to revoke — the client-generated id it registered at sign-in."),
+  })
+  .describe("The body identifying which device to revoke — the caller's own, or an admin-named user's.");
+export type RevokeDeviceBody = z.output<typeof RevokeDeviceBody>;
+
+/**
+ * The user id in the path of every single-user admin route.
+ *
+ * Bounded rather than `.uuid()`: Better Auth's id generator is configurable and its default is not a
+ * UUID, so a UUID shape here would 404 — as a 400 — every user in a project that changed it. The schema
+ * constrains the string; the handler still does the lookup and raises its own `core/not_found`.
+ */
+export const UserIdParam = z
+  .object({
+    userId: z.string().min(1).max(255).describe("The user's id, as `pithy_auth_users.id` stores it."),
+  })
+  .describe("The path parameters of every admin route that names one user.");
+export type UserIdParam = z.output<typeof UserIdParam>;
+
+/** How many rows a paged admin listing returns, when the caller names a number. */
+const PageLimit = z.coerce
+  .number()
+  .int()
+  .min(1)
+  .max(MAX_PAGE_SIZE)
+  .optional()
+  .describe("How many rows to return. Bounded, because a verified client can still have a bug.");
+
+/** Where a paged admin listing resumes. */
+const PageCursorParam = z
+  .string()
+  .max(512)
+  .optional()
+  .describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page.");
+
+/** The user listing query. */
+export const ListUsersQuery = z
+  .object({
+    search: z
+      .string()
+      .min(1)
+      .max(200)
+      .optional()
+      .describe(
+        "Free text matched against email and display name. `%` and `_` are escaped rather than treated as wildcards, so an address containing an underscore matches itself and nothing else.",
+      ),
+    cursor: PageCursorParam,
+    limit: PageLimit,
+  })
+  .describe("The user listing query: what to search for, how many to return, and where to resume.");
+export type ListUsersQuery = z.output<typeof ListUsersQuery>;
+
+/** The device-registry listing query. */
+export const ListDevicesQuery = z
+  .object({
+    userId: z
+      .string()
+      .min(1)
+      .max(255)
+      .optional()
+      .describe("Narrow to one user's devices. Absent walks the whole fleet, most-recently-seen first."),
+    platform: DevicePlatform.optional().describe("Narrow to one platform."),
+    cursor: PageCursorParam,
+    limit: PageLimit,
+  })
+  .describe("The device-registry query: what to filter by, how many to return, and where to resume.");
+export type ListDevicesQuery = z.output<typeof ListDevicesQuery>;
+
+/**
+ * The body of `POST /admin/sessions/revoke`.
+ *
+ * A session **id**, never a session token. The token is the live credential — a management client that
+ * could name one would be holding the thing it is revoking, and a route that accepted one would be an
+ * oracle for whether a captured token is still valid. The id is the row's public handle, which is what
+ * the read routes project.
+ */
+export const RevokeSessionBody = z
+  .object({
+    sessionId: z
+      .string()
+      .min(1)
+      .max(255)
+      .describe("The session's id, as the admin read routes report it. Not the session token."),
+  })
+  .describe("The body identifying which single session to revoke.");
+export type RevokeSessionBody = z.output<typeof RevokeSessionBody>;