@pithy-sh/auth 0.6.7 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -116,14 +116,9 @@ Apple only returns the user's name on the **first** authorization. Better Auth p
116
116
 
117
117
  ## When the credential will not read
118
118
 
119
- An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
120
- **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
121
-
122
- A sign-in attempt with Apple then answers `503` with the code `auth/provider_unavailable` and a
123
- message naming apple, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
124
- are different facts and never share an answer. The attempt is recorded in the audit trail as
125
- `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
126
- provisioning `auth-apple-credentials` for that environment, or turn the provider off in config.
119
+ An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
120
+
121
+ A sign-in attempt with Apple then answers `503` with the code `auth/provider_unavailable` and a message naming apple, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two are different facts and never share an answer. The attempt is recorded in the audit trail as `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by provisioning `auth-apple-credentials` for that environment, or turn the provider off in config.
127
122
 
128
123
  ## Checklist
129
124
 
@@ -74,14 +74,9 @@ Facebook is **not** in `trustedProviders`. Trusting the returned email is not th
74
74
 
75
75
  ## When the credential will not read
76
76
 
77
- An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
78
- **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
79
-
80
- A sign-in attempt with Facebook then answers `503` with the code `auth/provider_unavailable` and a
81
- message naming facebook, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
82
- are different facts and never share an answer. The attempt is recorded in the audit trail as
83
- `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
84
- provisioning `auth-facebook-credentials` for that environment, or turn the provider off in config.
77
+ An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
78
+
79
+ A sign-in attempt with Facebook then answers `503` with the code `auth/provider_unavailable` and a message naming facebook, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two are different facts and never share an answer. The attempt is recorded in the audit trail as `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by provisioning `auth-facebook-credentials` for that environment, or turn the provider off in config.
85
80
 
86
81
  ## Checklist
87
82
 
@@ -134,14 +134,9 @@ At no point does one account take an identity from another; one gives it up, aut
134
134
 
135
135
  ## When the credential will not read
136
136
 
137
- An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
138
- **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
139
-
140
- A sign-in attempt with GitHub then answers `503` with the code `auth/provider_unavailable` and a
141
- message naming github, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
142
- are different facts and never share an answer. The attempt is recorded in the audit trail as
143
- `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
144
- provisioning `auth-github-credentials` for that environment, or turn the provider off in config.
137
+ An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
138
+
139
+ A sign-in attempt with GitHub then answers `503` with the code `auth/provider_unavailable` and a message naming github, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two are different facts and never share an answer. The attempt is recorded in the audit trail as `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by provisioning `auth-github-credentials` for that environment, or turn the provider off in config.
145
140
 
146
141
  ## Checklist
147
142
 
@@ -96,14 +96,9 @@ A user who signed up with a magic link and later signs in with Google is linked
96
96
 
97
97
  ## When the credential will not read
98
98
 
99
- An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs
100
- **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
101
-
102
- A sign-in attempt with Google then answers `503` with the code `auth/provider_unavailable` and a
103
- message naming google, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two
104
- are different facts and never share an answer. The attempt is recorded in the audit trail as
105
- `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by
106
- provisioning `auth-google-credentials` for that environment, or turn the provider off in config.
99
+ An enabled provider whose secret is missing, or whose stored value no longer matches its schema, costs **that provider and nothing else**. Magic link, OTP, and every other provider keep signing people in.
100
+
101
+ A sign-in attempt with Google then answers `503` with the code `auth/provider_unavailable` and a message naming google, rather than the `404 PROVIDER_NOT_FOUND` a provider nobody enabled gets — the two are different facts and never share an answer. The attempt is recorded in the audit trail as `auth/provider_unavailable`, which is where an operator learns a sign-in method is down. Fix it by provisioning `auth-google-credentials` for that environment, or turn the provider off in config.
107
102
 
108
103
  ## Checklist
109
104
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/auth",
3
- "version": "0.6.7",
3
+ "version": "0.8.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -42,16 +42,16 @@
42
42
  "better-auth": "^1.7.1"
43
43
  },
44
44
  "peerDependencies": {
45
- "@pithy-sh/core": "^0.8.0",
46
- "@pithy-sh/email": "^0.3.10",
47
- "@pithy-sh/secrets": "^0.3.1",
48
- "@pithy-sh/turnstile": "^0.4.1",
45
+ "@pithy-sh/core": "^0.10.0",
46
+ "@pithy-sh/email": "^0.4.0",
47
+ "@pithy-sh/secrets": "^0.4.0",
48
+ "@pithy-sh/turnstile": "^0.4.3",
49
49
  "hono": "^4.13.2",
50
50
  "kysely": "^0.29.0",
51
51
  "zod": "^4.4.0"
52
52
  },
53
53
  "devDependencies": {
54
- "@cloudflare/vitest-plugin": "^1.0.0",
54
+ "@cloudflare/vitest-plugin": "^1.4.2",
55
55
  "@pithy-sh/cloudflare": "workspace:*",
56
56
  "@pithy-sh/core": "workspace:*",
57
57
  "@pithy-sh/email": "workspace:*",
@@ -63,11 +63,11 @@
63
63
  "hono": "^4.13.2",
64
64
  "kysely": "^0.29.0",
65
65
  "kysely-d1": "^0.4.0",
66
- "miniflare": "^4.20260722.1",
66
+ "miniflare": "5.20261012.0-beta",
67
67
  "tsdown": "^0.23.0",
68
68
  "typescript": "^7.0.2",
69
69
  "vitest": "^4.1.0",
70
- "wrangler": "^4.115.0",
70
+ "wrangler": "^4.151.0",
71
71
  "zod": "^4.4.0"
72
72
  }
73
73
  }
@@ -1,13 +1,13 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
- import { zValidator } from "@hono/zod-validator";
5
4
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
6
5
  import type { ControlPlaneContext } from "@pithy-sh/core/src/controlPlane/context";
7
6
  import { requireControlPlane } from "@pithy-sh/core/src/controlPlane/http/guard";
8
7
  import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
9
8
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
10
- import { validationHook } from "@pithy-sh/core/src/http/validation";
9
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
10
+ import { validate } from "@pithy-sh/core/src/http/validation";
11
11
  import type { Context, Hono } from "hono";
12
12
  import {
13
13
  type AdminSubList,
@@ -33,7 +33,7 @@ import {
33
33
  AUTH_USERS_READ_SCOPE,
34
34
  } from "./guards";
35
35
  import { getAuthInstance, resolveDb } from "./resolve";
36
- import type {
36
+ import {
37
37
  AdminDeviceRevokeResponse,
38
38
  AdminDevicesResponse,
39
39
  AdminRevokeResponse,
@@ -179,8 +179,14 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
179
179
 
180
180
  app.get(
181
181
  `${base}/admin/users`,
182
+ describeRoute({
183
+ summary: "Page through the users, newest first, optionally searching by email or name.",
184
+ verification: "control-plane",
185
+ scopes: [AUTH_USERS_READ_SCOPE],
186
+ responses: { 200: AdminUsersResponse },
187
+ }),
182
188
  requireControlPlane(AUTH_USERS_READ_SCOPE),
183
- zValidator("query", ListUsersQuery, validationHook),
189
+ validate("query", ListUsersQuery),
184
190
  async (c) => {
185
191
  const query = c.req.valid("query");
186
192
  const caller = controlPlaneCaller(c);
@@ -204,8 +210,14 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
204
210
 
205
211
  app.get(
206
212
  `${base}/admin/users/:userId`,
213
+ describeRoute({
214
+ summary: "Read one user with their sessions, devices and linked providers.",
215
+ verification: "control-plane",
216
+ scopes: [AUTH_USERS_READ_SCOPE],
217
+ responses: { 200: AdminUserResponse },
218
+ }),
207
219
  requireControlPlane(AUTH_USERS_READ_SCOPE),
208
- zValidator("param", UserIdParam, validationHook),
220
+ validate("param", UserIdParam),
209
221
  async (c) => {
210
222
  const { userId } = c.req.valid("param");
211
223
  const caller = controlPlaneCaller(c);
@@ -254,8 +266,14 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
254
266
 
255
267
  app.get(
256
268
  `${base}/admin/devices`,
269
+ describeRoute({
270
+ summary: "Page through the device registry, most recently seen first.",
271
+ verification: "control-plane",
272
+ scopes: [AUTH_DEVICES_READ_SCOPE],
273
+ responses: { 200: AdminDevicesResponse },
274
+ }),
257
275
  requireControlPlane(AUTH_DEVICES_READ_SCOPE),
258
- zValidator("query", ListDevicesQuery, validationHook),
276
+ validate("query", ListDevicesQuery),
259
277
  async (c) => {
260
278
  const query = c.req.valid("query");
261
279
  const caller = controlPlaneCaller(c);
@@ -278,8 +296,14 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
278
296
 
279
297
  app.post(
280
298
  `${base}/admin/sessions/revoke`,
299
+ describeRoute({
300
+ summary: "Revoke one session by its id.",
301
+ verification: "control-plane",
302
+ scopes: [AUTH_SESSIONS_REVOKE_SCOPE],
303
+ responses: { 200: AdminRevokeResponse },
304
+ }),
281
305
  requireControlPlane(AUTH_SESSIONS_REVOKE_SCOPE),
282
- zValidator("json", RevokeSessionBody, validationHook),
306
+ validate("json", RevokeSessionBody),
283
307
  async (c) => {
284
308
  const { sessionId } = c.req.valid("json");
285
309
  const caller = controlPlaneCaller(c);
@@ -309,8 +333,14 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
309
333
 
310
334
  app.post(
311
335
  `${base}/admin/users/:userId/sessions/revoke`,
336
+ describeRoute({
337
+ summary: "Sign one user out everywhere.",
338
+ verification: "control-plane",
339
+ scopes: [AUTH_USERS_LOGOUT_SCOPE],
340
+ responses: { 200: AdminRevokeResponse },
341
+ }),
312
342
  requireControlPlane(AUTH_USERS_LOGOUT_SCOPE),
313
- zValidator("param", UserIdParam, validationHook),
343
+ validate("param", UserIdParam),
314
344
  async (c) => {
315
345
  const { userId } = c.req.valid("param");
316
346
  const caller = controlPlaneCaller(c);
@@ -335,9 +365,15 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
335
365
 
336
366
  app.post(
337
367
  `${base}/admin/users/:userId/devices/revoke`,
368
+ describeRoute({
369
+ summary: "Sign out one of a user's devices and remove it from the registry.",
370
+ verification: "control-plane",
371
+ scopes: [AUTH_DEVICES_REVOKE_SCOPE],
372
+ responses: { 200: AdminDeviceRevokeResponse },
373
+ }),
338
374
  requireControlPlane(AUTH_DEVICES_REVOKE_SCOPE),
339
- zValidator("param", UserIdParam, validationHook),
340
- zValidator("json", RevokeDeviceBody, validationHook),
375
+ validate("param", UserIdParam),
376
+ validate("json", RevokeDeviceBody),
341
377
  async (c) => {
342
378
  const { userId } = c.req.valid("param");
343
379
  const { deviceId } = c.req.valid("json");
@@ -1,12 +1,14 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
- import { zValidator } from "@hono/zod-validator";
5
4
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
5
+ import { commandName, pithyCommand } from "@pithy-sh/core/src/cli/command";
6
6
  import { type AmbientEnv, ambientEnv, compositionEnvironment } from "@pithy-sh/core/src/env/ambient";
7
7
  import { isContinuousIntegration } from "@pithy-sh/core/src/env/ci";
8
8
  import { NotFoundError } from "@pithy-sh/core/src/error/pithyError";
9
- import { validationHook } from "@pithy-sh/core/src/http/validation";
9
+ import { describeRoute } from "@pithy-sh/core/src/http/routeSpec";
10
+ import { validate } from "@pithy-sh/core/src/http/validation";
11
+ import { LOCAL_ENVIRONMENT } from "@pithy-sh/core/src/naming/environment";
10
12
  import { DEV_LOGIN_CLAIM_PARAM, DEV_LOGIN_ROUTE } from "@pithy-sh/core/src/seed/devLogin";
11
13
  import type { SecretsStoreEnv } from "@pithy-sh/secrets/src/env/bindings";
12
14
  import type { Context, Hono } from "hono";
@@ -65,8 +67,19 @@ export function registerDevLoginRoute(
65
67
  if (isContinuousIntegration(env)) return;
66
68
  // The claim is read here rather than inside the handler: `c.req.valid` is typed off the chain it was
67
69
  // declared on, and a handler taking a bare `Context` has no validator to read from.
68
- app.get(DEV_LOGIN_ROUTE, zValidator("query", DevLoginQuery, validationHook), (c) =>
69
- serveDevLogin(c, wiring, c.req.valid("query")[DEV_LOGIN_CLAIM_PARAM]),
70
+ app.get(
71
+ DEV_LOGIN_ROUTE,
72
+ describeRoute({
73
+ summary: "Sign the browser in as the seeded dev user.",
74
+ description:
75
+ "Mounted only in a `dev` composition outside CI. It takes no credential: the signed claim `pithy seed` wrote into the URL is the whole of what it checks.",
76
+ verification: "public",
77
+ responses: {
78
+ 302: { description: "Signed in: sets the session cookie and redirects to `/`." },
79
+ },
80
+ }),
81
+ validate("query", DevLoginQuery),
82
+ (c) => serveDevLogin(c, wiring, c.req.valid("query")[DEV_LOGIN_CLAIM_PARAM]),
70
83
  );
71
84
  };
72
85
  }
@@ -86,7 +99,7 @@ export function registerDevLoginRoute(
86
99
  */
87
100
  function noSeededSession(): NotFoundError {
88
101
  return new NotFoundError({
89
- message: "No dev login has been seeded for this environment. Run pithy seed, then open this URL again.",
102
+ message: `No dev login has been seeded for this environment. Run ${pithyCommand("seed", { flags: { "--env": LOCAL_ENVIRONMENT } })}, then open this URL again.`,
90
103
  });
91
104
  }
92
105
 
@@ -162,7 +175,7 @@ async function serveDevLogin(
162
175
  createdAt: now,
163
176
  updatedAt: now,
164
177
  ipAddress: "127.0.0.1",
165
- userAgent: "pithy dev login",
178
+ userAgent: `${commandName("dev")} login`,
166
179
  deviceId: null,
167
180
  familyId: null,
168
181
  // A dev login is a real sign-in, so it is authenticated now — what the live hook stamps.
@@ -197,3 +197,57 @@ export const AdminDeviceRevokeResponse = z
197
197
  })
198
198
  .describe("How many sessions the device revocation ended, and whether the registry row went with them.");
199
199
  export type AdminDeviceRevokeResponse = z.output<typeof AdminDeviceRevokeResponse>;
200
+
201
+ /*
202
+ * The routes a signed-in person calls on their own account. These are not read across the management
203
+ * version boundary the admin schemas above are, but a client generated from the contract reads Workers on
204
+ * older releases too, so the same rule holds: a field added here later is `.optional()`.
205
+ */
206
+
207
+ /** `POST {base}/token/rotate`. */
208
+ export const TokenRotateResponse = z
209
+ .object({
210
+ accessToken: z
211
+ .string()
212
+ .describe("A fresh short-lived access token (a JWT) for the `Authorization: Bearer` header."),
213
+ refreshToken: z
214
+ .string()
215
+ .describe(
216
+ "The successor refresh credential: a new session token. The one presented is spent, and presenting it again past a short grace window revokes the whole family.",
217
+ ),
218
+ expiresAt: z.iso.datetime().describe("When the successor session lapses, ISO-8601."),
219
+ })
220
+ .describe("The rotated credential pair: a new access token and the session token that replaces the one presented.");
221
+ export type TokenRotateResponse = z.output<typeof TokenRotateResponse>;
222
+
223
+ /** One of the caller's own registered devices. */
224
+ export const MyDeviceView = z
225
+ .object({
226
+ id: z.string().describe("The client-generated device id it registered at sign-in."),
227
+ userId: z.string().describe("The owning user's id: always the caller's own."),
228
+ platform: DevicePlatform.describe("The platform the device registered as."),
229
+ name: z.string().nullable().describe("The device's human label, or null."),
230
+ model: z.string().nullable().describe("The hardware model, or null."),
231
+ osVersion: z.string().nullable().describe("The device OS version at last sign-in, or null."),
232
+ appVersion: z.string().nullable().describe("The client app version at last sign-in, or null."),
233
+ pushToken: z.string().nullable().describe("The APNs or FCM push token the device registered, or null."),
234
+ lastIp: z.string().nullable().describe("The client IP at the device's most recent sign-in, or null."),
235
+ lastSeenAt: z.iso.datetime().describe("When the device was last seen, ISO-8601."),
236
+ createdAt: z.iso.datetime().describe("When the device first registered, ISO-8601."),
237
+ })
238
+ .describe("One device registered to the caller's own account.");
239
+ export type MyDeviceView = z.output<typeof MyDeviceView>;
240
+
241
+ /** `GET {base}/devices`. */
242
+ export const MyDevicesResponse = z
243
+ .object({
244
+ devices: z.array(MyDeviceView).describe("Every device registered to the caller, most recently seen first."),
245
+ })
246
+ .describe("The caller's own registered devices.");
247
+ export type MyDevicesResponse = z.output<typeof MyDevicesResponse>;
248
+
249
+ /** `POST {base}/devices/revoke`. */
250
+ export const MyDeviceRevokeResponse = z
251
+ .object({ revoked: RevokedCount })
252
+ .describe("How many of the device's sessions the revocation signed out. The device's row goes with them.");
253
+ export type MyDeviceRevokeResponse = z.output<typeof MyDeviceRevokeResponse>;
@@ -1,11 +1,11 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
- import { zValidator } from "@hono/zod-validator";
5
4
  import type { PithyHonoEnv } from "@pithy-sh/core/src/capability/capability";
6
5
  import { NotFoundError, UnauthorizedError } from "@pithy-sh/core/src/error/pithyError";
6
+ import { describeRoute, type RouteResponse } from "@pithy-sh/core/src/http/routeSpec";
7
7
  import { requireSameOrigin } from "@pithy-sh/core/src/http/sameOrigin";
8
- import { validationHook } from "@pithy-sh/core/src/http/validation";
8
+ import { validate } from "@pithy-sh/core/src/http/validation";
9
9
  import { STORED_IMAGE_HEADERS, storedImageBytes } from "@pithy-sh/core/src/image/storedImage";
10
10
  import { TURNSTILE_LOGIN_ACTION } from "@pithy-sh/turnstile/src/config/config";
11
11
  import { turnstile } from "@pithy-sh/turnstile/src/http/middleware";
@@ -29,10 +29,21 @@ import { requireAuth } from "./middleware";
29
29
  import { requireFreshAuthentication } from "./providerFreshness";
30
30
  import { collapseProviderRefusal } from "./providerRefusal";
31
31
  import { getAuthInstance, resolveDb } from "./resolve";
32
+ import { MyDeviceRevokeResponse, MyDevicesResponse, TokenRotateResponse } from "./responses";
32
33
  import { RevokeDeviceBody } from "./schemas";
33
34
 
34
35
  type Ctx = Context<PithyHonoEnv>;
35
36
 
37
+ /**
38
+ * What a route answers when the answer is Better Auth's: the catch-all, and the two endpoints of its that
39
+ * are mounted ahead of it for a gate. Its wire is its own contract (`handleBetterAuth` says why), so the
40
+ * kit's contract points at it rather than restating it.
41
+ */
42
+ const BETTER_AUTH_ANSWER: RouteResponse = {
43
+ description: "Better Auth's own answer. See its endpoint reference.",
44
+ contentType: "application/json",
45
+ };
46
+
36
47
  function db(c: Ctx, wiring: AuthWiring) {
37
48
  return authDatabase(resolveDb(c.env, wiring.config.database));
38
49
  }
@@ -85,11 +96,40 @@ export function createAuthRoutes(wiring: AuthWiring): (app: Hono<PithyHonoEnv>)
85
96
  }
86
97
 
87
98
  // Rotate the refresh credential: mint a new session, revoke the presented one, return a fresh JWT.
88
- app.post(`${base}/token/rotate`, csrf, (c) => rotateToken(c, wiring));
99
+ app.post(
100
+ `${base}/token/rotate`,
101
+ describeRoute({
102
+ summary: "Trade the current refresh credential for a new access token and its successor.",
103
+ description:
104
+ "The presented session is spent. Presenting it again after a short grace window is read as theft, and revokes every session descended from the same sign-in.",
105
+ verification: ["bearer", "session"],
106
+ responses: { 200: TokenRotateResponse },
107
+ }),
108
+ csrf,
109
+ (c) => rotateToken(c, wiring),
110
+ );
89
111
  // Device management (bearer/session gated; the revoke is CSRF-guarded as a mutating route).
90
- app.get(`${base}/devices`, requireAuth(), (c) => listMyDevices(c, wiring));
91
- app.post(`${base}/devices/revoke`, requireAuth(), csrf, zValidator("json", RevokeDeviceBody, validationHook), (c) =>
92
- revokeMyDevice(c, wiring, c.req.valid("json")),
112
+ app.get(
113
+ `${base}/devices`,
114
+ describeRoute({
115
+ summary: "List the caller's own registered devices.",
116
+ verification: ["bearer", "session"],
117
+ responses: { 200: MyDevicesResponse },
118
+ }),
119
+ requireAuth(),
120
+ (c) => listMyDevices(c, wiring),
121
+ );
122
+ app.post(
123
+ `${base}/devices/revoke`,
124
+ describeRoute({
125
+ summary: "Sign out one of the caller's own devices and forget it.",
126
+ verification: ["bearer", "session"],
127
+ responses: { 200: MyDeviceRevokeResponse },
128
+ }),
129
+ requireAuth(),
130
+ csrf,
131
+ validate("json", RevokeDeviceBody),
132
+ (c) => revokeMyDevice(c, wiring, c.req.valid("json")),
93
133
  );
94
134
 
95
135
  // **Changing which providers can sign you in requires a recent authentication — both directions.**
@@ -97,18 +137,64 @@ export function createAuthRoutes(wiring: AuthWiring): (app: Hono<PithyHonoEnv>)
97
137
  // carries the argument: Better Auth guards the two unevenly, and its guard on the unlink side reads
98
138
  // `session.createdAt`, which `/token/rotate` resets. Neither takes a kit validator — the body is
99
139
  // Better Auth's, and `handleBetterAuth` hands it `c.req.raw`, which is the catch-all's own reason.
100
- app.post(`${base}/link-social`, requireFreshAuthentication("link"), (c) => handleBetterAuth(c, wiring));
101
- app.post(`${base}/unlink-account`, requireFreshAuthentication("unlink"), (c) => handleBetterAuth(c, wiring));
140
+ app.post(
141
+ `${base}/link-social`,
142
+ describeRoute({
143
+ summary: "Connect another sign-in provider to the caller's account.",
144
+ description:
145
+ "Better Auth's endpoint, behind a kit gate: the caller must have signed in within the last fifteen minutes, or it is refused with `auth/session_not_fresh`.",
146
+ verification: ["bearer", "session"],
147
+ responses: { 200: BETTER_AUTH_ANSWER },
148
+ }),
149
+ requireFreshAuthentication("link"),
150
+ (c) => handleBetterAuth(c, wiring),
151
+ );
152
+ app.post(
153
+ `${base}/unlink-account`,
154
+ describeRoute({
155
+ summary: "Disconnect a sign-in provider from the caller's account.",
156
+ description:
157
+ "Better Auth's endpoint, behind a kit gate: the caller must have signed in within the last fifteen minutes, or it is refused with `auth/session_not_fresh`.",
158
+ verification: ["bearer", "session"],
159
+ responses: { 200: BETTER_AUTH_ANSWER },
160
+ }),
161
+ requireFreshAuthentication("unlink"),
162
+ (c) => handleBetterAuth(c, wiring),
163
+ );
102
164
 
103
165
  // The caller's own stored picture, as bytes a browser can cache. No id in the path — see
104
166
  // `serveMyImage`, which is where the reason lives.
105
- app.get(`${base}${PROFILE_IMAGE_PATH}`, requireAuth(), (c) => serveMyImage(c, wiring));
167
+ app.get(
168
+ `${base}${PROFILE_IMAGE_PATH}`,
169
+ describeRoute({
170
+ summary: "Read the caller's own stored picture.",
171
+ description:
172
+ "A picture linked from a provider, or stored as a vector, is not served here and answers 404. The response is private and immutable: the URL a client is handed carries the picture's version.",
173
+ verification: ["bearer", "session"],
174
+ responses: {
175
+ 200: { description: "The caller's stored picture, as PNG, JPEG or WebP bytes.", contentType: "image/*" },
176
+ },
177
+ }),
178
+ requireAuth(),
179
+ (c) => serveMyImage(c, wiring),
180
+ );
106
181
 
107
182
  // The control-plane management surface. Registered here, before the catch-all below, or it is dead.
108
183
  registerAuthAdminRoutes(wiring)(app);
109
184
 
110
185
  // Better Auth owns the rest (sign-in, verify, callback, sign-out, /token, /jwks, revoke-sessions…).
111
- app.all(`${base}/*`, (c) => handleBetterAuth(c, wiring));
186
+ app.all(
187
+ `${base}/*`,
188
+ describeRoute({
189
+ summary: "Everything else under the auth path, answered by Better Auth.",
190
+ description:
191
+ "Sign-in, sign-up, verification, OAuth callbacks, sign-out, `/token`, `/jwks` and the rest of Better Auth's endpoints. Which credential an endpoint takes, if any, is its own decision.",
192
+ verification: ["public", "session", "bearer"],
193
+ methods: ["get", "post"],
194
+ responses: { 200: BETTER_AUTH_ANSWER },
195
+ }),
196
+ (c) => handleBetterAuth(c, wiring),
197
+ );
112
198
  };
113
199
  }
114
200
 
@@ -7,7 +7,7 @@ import { DevicePlatform } from "../data/device";
7
7
 
8
8
  /**
9
9
  * The request schemas for the auth routes Pithy owns. Validation happens at the HTTP boundary
10
- * (CLAUDE.md §Zod), declared on the route line with `zValidator(target, Schema, validationHook)` — so
10
+ * (CLAUDE.md §Zod), declared on the route line with `validate(target, Schema)` — so
11
11
  * reading `routes.ts` and `adminRoutes.ts` tells you what each route accepts without opening a handler.
12
12
  *
13
13
  * Only Pithy's own routes appear here. Everything under `basePath` that Better Auth owns validates
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
+ import { pithyCommand } from "@pithy-sh/core/src/cli/command";
4
5
  import { PithyError } from "@pithy-sh/core/src/error/pithyError";
5
6
  import { z } from "zod";
6
7
  import type {
@@ -179,7 +180,7 @@ export function providerUnavailable(provider: SocialProviderId): PithyError {
179
180
  code: "auth/provider_unavailable",
180
181
  status: 503,
181
182
  message: `Signing in with ${provider} is unavailable right now. Use a magic link instead.`,
182
- action: `Provision \`auth-${provider}-credentials\` for this environment with \`pithy secrets create\`, or set \`${provider}.enabled\` to false in pithy.config.ts.`,
183
+ action: `Provision \`auth-${provider}-credentials\` for this environment with \`${pithyCommand("secrets create", { args: [`auth-${provider}-credentials`] })}\`, or set \`${provider}.enabled\` to false in pithy.config.ts.`,
183
184
  detail: `provider ${provider} is enabled and its credential could not be resolved; the instance was built without it`,
184
185
  });
185
186
  }