@pithy-sh/auth 0.13.0 → 0.14.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.
package/README.md CHANGED
@@ -62,7 +62,7 @@ So: **do not "improve" this by matching more addresses, and do not make the refu
62
62
 
63
63
  ## Account lifecycle
64
64
 
65
- An account can be suspended or deleted, and the kit refuses it at every door. An operator suspends and reinstates one through `POST /auth/admin/users/:userId/suspend` and `/reinstate`, under `auth:users:suspend`, with a reason the trail keeps. They delete one through `DELETE /auth/admin/users/:userId` — soft by default, restorable through `POST …/restore` until the purge window closes, or `mode: "hard"` to purge now — under `auth:users:delete`, and export everything the kit holds about one person through `GET …/export`, under `auth:users:export`. A person deletes their own account with `DELETE /auth/account { confirm: true }`, which is what the App Store and Google Play require of an app with accounts. A purge Workflow, hosted by your own Worker, erases a deleted account from every capability that holds it, one step per capability; the four that keep a person's rows — payments, email, audit and the control plane's legal holds — say why, and the export says it with them. A legal hold on the account stops its purge until it is released, and when the Worker's `retention` block declares class ages, the daily pass soft-deletes an account inactive past them through this same lifecycle. Auth's own routes, sign-in and token refresh answer `auth/account_suspended` or `auth/account_deleted` (403); another capability's `requireAuth()` answers 401, and the client's next refresh gets the code. The admin user reads say where each account stands — `state`, `suspendedUntil` and `purgeAfter` — read the way enforcement reads them. [`docs/account-lifecycle.md`](docs/account-lifecycle.md) has the two states, the record, the scopes, the routes, the purge and the Workflow classes to export for it, the mail, the hooks, the screens, and the purge contribution a capability declares for its own rows.
65
+ An account can be suspended or deleted, and the kit refuses it at every door. An operator suspends and reinstates one through `POST /auth/admin/users/:userId/suspend` and `/reinstate`, under `auth:users:suspend`, with a reason the trail keeps. They delete one through `DELETE /auth/admin/users/:userId` — soft by default, restorable through `POST …/restore` until the purge window closes, or `mode: "hard"` to purge now — under `auth:users:delete`, and export everything the kit holds about one person through `POST …/export` with the reason in the body, under `auth:users:export`. A person deletes their own account with `DELETE /auth/account { confirm: true }`, which is what the App Store and Google Play require of an app with accounts. A purge Workflow, hosted by your own Worker, erases a deleted account from every capability that holds it, one step per capability; the four that keep a person's rows — payments, email, audit and the control plane's legal holds — say why, and the export says it with them. A legal hold on the account stops its purge until it is released, and when the Worker's `retention` block declares class ages, the daily pass soft-deletes an account inactive past them through this same lifecycle. Auth's own routes, sign-in and token refresh answer `auth/account_suspended` or `auth/account_deleted` (403); another capability's `requireAuth()` answers 401, and the client's next refresh gets the code. The admin user reads say where each account stands — `state`, `suspendedUntil` and `purgeAfter` — read the way enforcement reads them. [`docs/account-lifecycle.md`](docs/account-lifecycle.md) has the two states, the record, the scopes, the routes, the purge and the Workflow classes to export for it, the mail, the hooks, the screens, and the purge contribution a capability declares for its own rows.
66
66
 
67
67
  **Every purge can be proved.** The purge records an audit event per step and on completion, and names the step it stopped at when it gives up. `GET /control-plane/erasure/user/:userId`, under `erasure:read`, attests one account's erasure from that record: when it was deleted, by which kind of actor and why, soft or hard, each step erased or kept with its reason, the purge's state, and the audit event behind each step by id and chain position. `GET /control-plane/erasure?since&until` counts every purge in a period and names each failed or overdue one. Nothing about the person crosses but the id. [`docs/CONTROL-PLANE.md` §12](../../docs/CONTROL-PLANE.md#erasure) has the shape.
68
68
 
@@ -1 +1 @@
1
- {"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AA8ThD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA6gB7F"}
1
+ {"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAgUhD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA4hB7F"}
@@ -15,7 +15,7 @@ import { auditedLifecycleCall, recordLifecycleRefusal } from "../lifecycle/audit
15
15
  import { AUTH_PURGE_BINDING } from "../purge/specs.js";
16
16
  import { startPurgeInstance } from "../purge/start.js";
17
17
  import { AdminDeviceRevokeResponse, AdminDevicesResponse, AdminRevokeResponse, AdminUserDeleteResponse, AdminUserExportResponse, AdminUserReinstateResponse, AdminUserResponse, AdminUserRestoreResponse, AdminUserSuspendResponse, AdminUsersResponse, AdminVerificationsResponse } from "./responses.js";
18
- import { DeleteUserBody, ExportUserQuery, ListDevicesQuery, ListUsersQuery, ListVerificationsQuery, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SuspendUserBody, UserIdParam } from "./schemas.js";
18
+ import { DeleteUserBody, ExportUserBody, ListDevicesQuery, ListUsersQuery, ListVerificationsQuery, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SearchUsersBody, SuspendUserBody, UserIdParam } from "./schemas.js";
19
19
  import { deletionView, deviceView, exportView, reinstatementView, restorationView, sessionView, suspensionView, userView, verificationView } from "./views.js";
20
20
  import { purgeExports } from "@pithy-sh/core/src/capability/purge";
21
21
  import { InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
@@ -30,6 +30,7 @@ import { workflowBindingFor } from "@pithy-sh/core/src/workflow/dispatch";
30
30
  * revocations an incident costs.
31
31
  *
32
32
  * GET {base}/admin/users auth:users:read query: ListUsersQuery
33
+ * POST {base}/admin/users/search auth:users:read json: SearchUsersBody
33
34
  * GET {base}/admin/users/:userId auth:users:read param: UserIdParam
34
35
  * GET {base}/admin/devices auth:devices:read query: ListDevicesQuery
35
36
  * GET {base}/admin/verifications auth:verifications:read query: ListVerificationsQuery
@@ -40,7 +41,7 @@ import { workflowBindingFor } from "@pithy-sh/core/src/workflow/dispatch";
40
41
  * POST {base}/admin/users/:userId/reinstate auth:users:suspend param + json: ReinstateUserBody
41
42
  * DELETE {base}/admin/users/:userId auth:users:delete param + json: DeleteUserBody
42
43
  * POST {base}/admin/users/:userId/restore auth:users:delete param + json: RestoreUserBody
43
- * GET {base}/admin/users/:userId/export auth:users:export param + query: ExportUserQuery
44
+ * POST {base}/admin/users/:userId/export auth:users:export param + json: ExportUserBody
44
45
  *
45
46
  * ## Registered before the catch-all, or dead
46
47
  *
@@ -81,11 +82,11 @@ function db(c, wiring) {
81
82
  return authDatabase(resolveDb(c.env, wiring.config.database));
82
83
  }
83
84
  /**
84
- * One of the user pane's sub-reads, guarded and projected in one step (#380).
85
+ * One of the user pane's sub-reads, guarded and projected in one step.
85
86
  *
86
87
  * **`try`/`catch` inside an `async` function, never `.catch()`.** The read is *called* inside the `try`,
87
88
  * so a seam that throws before it returns a promise is caught too — a rejected promise is not the only
88
- * way a D1 read fails, and a `.catch()` guard has been escaped by exactly that before (#371).
89
+ * way a D1 read fails, and a `.catch()` guard is escaped by exactly that.
89
90
  *
90
91
  * **The guard takes no binding.** The state is the whole of what travels; what the read threw names a
91
92
  * query and a table, and this response goes to a management client across a trust boundary.
@@ -175,7 +176,7 @@ function lifecycleCall(c, wiring, caller, userId, reason) {
175
176
  };
176
177
  }
177
178
  /**
178
- * A lifecycle route's body validator, which audits the bodies it refuses (#621). Every call is on the trail,
179
+ * A lifecycle route's body validator, which audits the bodies it refuses. Every call is on the trail,
179
180
  * a refusal included, and a body the validator turns away never reaches `auditedLifecycleCall`. So it is
180
181
  * recorded here, as `denied` under the route's own action, with whatever reason the body carried — cut to the
181
182
  * reason's own limit, so a refused essay is not stored whole — and the 400 is thrown as before.
@@ -221,7 +222,7 @@ async function endSessions(c, wiring, caller, userId, cause) {
221
222
  return revoked;
222
223
  }
223
224
  /**
224
- * Start the purge of one account now (#622): `started` when this Worker binds the purge Workflow and it took the
225
+ * Start the purge of one account now: `started` when this Worker binds the purge Workflow and it took the
225
226
  * instance — or already held it — and `pending` when it binds none or the start failed; the account is due
226
227
  * either way, and the daily pass starts it. A failed start is not this call's failure: the deletion is already
227
228
  * written, and a 500 over it would invite a retry that finds the account deleted and says nothing new.
@@ -263,13 +264,8 @@ function scheduledOrDue(result) {
263
264
  function registerAuthAdminRoutes(wiring) {
264
265
  return (app) => {
265
266
  const base = wiring.config.basePath;
266
- app.get(`${base}/admin/users`, describeRoute({
267
- summary: "Page through the users, newest first, optionally searching by email or name and narrowing by standing, verification or signup window.",
268
- verification: "control-plane",
269
- scopes: [AUTH_USERS_READ_SCOPE],
270
- responses: { 200: AdminUsersResponse }
271
- }), requireControlPlane(AUTH_USERS_READ_SCOPE), validate("query", ListUsersQuery), async (c) => {
272
- const query = c.req.valid("query");
267
+ /** One page of users, audited as a listing: whether it was a search and how much came back, never the term. */
268
+ const pageOfUsers = async (c, query) => {
273
269
  const caller = controlPlaneCaller(c);
274
270
  const now = /* @__PURE__ */ new Date();
275
271
  const page = await listUsers(db(c, wiring), {
@@ -283,7 +279,7 @@ function registerAuthAdminRoutes(wiring) {
283
279
  resourceType: "user",
284
280
  ...context(c),
285
281
  metadata: {
286
- searched: query.search !== void 0,
282
+ searched: "search" in query,
287
283
  returned: page.items.length,
288
284
  filters: {
289
285
  state: query.state ?? null,
@@ -297,7 +293,20 @@ function registerAuthAdminRoutes(wiring) {
297
293
  users: page.items.map((user) => userView(user, now)),
298
294
  nextCursor: page.nextCursor
299
295
  });
300
- });
296
+ };
297
+ app.get(`${base}/admin/users`, describeRoute({
298
+ summary: "Page through the users, newest first, narrowing by standing, verification or signup window. A search by address or name is `POST /admin/users/search`.",
299
+ verification: "control-plane",
300
+ scopes: [AUTH_USERS_READ_SCOPE],
301
+ responses: { 200: AdminUsersResponse }
302
+ }), requireControlPlane(AUTH_USERS_READ_SCOPE), validate("query", ListUsersQuery), async (c) => pageOfUsers(c, c.req.valid("query")));
303
+ app.post(`${base}/admin/users/search`, describeRoute({
304
+ summary: "Search the users by email or name, newest first, with the listing's filters, paged on its cursor.",
305
+ description: "The term travels in the body, because a query string is written to every request log between the client and the Worker and a search term is usually somebody's address. Answers the listing's envelope. Audited as a listing that searched, never with the term. Read-only.",
306
+ verification: "control-plane",
307
+ scopes: [AUTH_USERS_READ_SCOPE],
308
+ responses: { 200: AdminUsersResponse }
309
+ }), requireControlPlane(AUTH_USERS_READ_SCOPE), validate("json", SearchUsersBody), async (c) => pageOfUsers(c, c.req.valid("json")));
301
310
  app.get(`${base}/admin/users/:userId`, describeRoute({
302
311
  summary: "Read one user with their sessions, devices and linked providers.",
303
312
  verification: "control-plane",
@@ -579,15 +588,15 @@ function registerAuthAdminRoutes(wiring) {
579
588
  }), (outcome) => !outcome.changed);
580
589
  return c.json(restorationView(userId, result));
581
590
  });
582
- app.get(`${base}/admin/users/:userId/export`, describeRoute({
591
+ app.post(`${base}/admin/users/:userId/export`, describeRoute({
583
592
  summary: "Export everything the kit holds about one user, from every composed capability, as one document.",
584
- description: "The answer to an access request. One entry per composed capability that declares a purge contribution, in the order the purge erases them. Audited as a disclosure, with the reason.",
593
+ description: "The answer to an access request. One entry per composed capability that declares a purge contribution, in the order the purge erases them. Audited as a disclosure, with the reason, which travels in the body because a reason often names the person who asked and a URL is written to every request log. Changes nothing.",
585
594
  verification: "control-plane",
586
595
  scopes: [AUTH_USERS_EXPORT_SCOPE],
587
596
  responses: { 200: AdminUserExportResponse }
588
- }), requireControlPlane(AUTH_USERS_EXPORT_SCOPE), validate("param", UserIdParam), validate("query", ExportUserQuery), async (c) => {
597
+ }), requireControlPlane(AUTH_USERS_EXPORT_SCOPE), validate("param", UserIdParam), validate("json", ExportUserBody), async (c) => {
589
598
  const { userId } = c.req.valid("param");
590
- const { reason } = c.req.valid("query");
599
+ const { reason } = c.req.valid("json");
591
600
  const caller = controlPlaneCaller(c);
592
601
  const call = lifecycleCall(c, wiring, caller, userId, reason);
593
602
  const exportedAt = /* @__PURE__ */ new Date();
@@ -1 +1 @@
1
- {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAA0C,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAyC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAwC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,iBAAiB,EAUjE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAqGzE"}
1
+ {"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/http/guards.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAClG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAAqC,CAAC;AAE1E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;GAGG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAA0C,CAAC;AAEpF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,iBAAyC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAAwC,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAuC,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,EAAE,iBAA6C,CAAC;AAE1F;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,SAAS,iBAAiB,EAUjE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,qBAAqB,EAAE,CA+GzE"}
@@ -145,7 +145,16 @@ function authAdminRoutes(basePath) {
145
145
  path: `${basePath}/admin/users`,
146
146
  scope: AUTH_USERS_READ_SCOPE,
147
147
  kind: "reads",
148
- summary: "Find a user. Lists everyone newest first, or searches email and display name."
148
+ summary: "List the users newest first, narrowed by standing, verification or signup window."
149
+ },
150
+ {
151
+ method: "POST",
152
+ operation: "users.search",
153
+ path: `${basePath}/admin/users/search`,
154
+ scope: AUTH_USERS_READ_SCOPE,
155
+ kind: "reads",
156
+ readInBody: true,
157
+ summary: "Find a user by email or display name, the term in the body so it never reaches a request log."
149
158
  },
150
159
  {
151
160
  method: "GET",
@@ -228,11 +237,12 @@ function authAdminRoutes(basePath) {
228
237
  summary: "Every sign-in link and code sent over a window: used, expired or still waiting, and the mail that carried it."
229
238
  },
230
239
  {
231
- method: "GET",
240
+ method: "POST",
232
241
  operation: "users.export",
233
242
  path: `${basePath}/admin/users/:userId/export`,
234
243
  scope: AUTH_USERS_EXPORT_SCOPE,
235
244
  kind: "reads",
245
+ readInBody: true,
236
246
  summary: "Everything the kit holds about one user, from every capability — the answer to an access request."
237
247
  }
238
248
  ];
@@ -49,7 +49,7 @@ export declare const AdminDeviceView: z.ZodObject<{
49
49
  createdAt: z.ZodISODateTime;
50
50
  }, z.core.$strip>;
51
51
  export type AdminDeviceView = z.output<typeof AdminDeviceView>;
52
- /** `GET {base}/admin/users`. */
52
+ /** `GET {base}/admin/users` and `POST {base}/admin/users/search`. */
53
53
  export declare const AdminUsersResponse: z.ZodObject<{
54
54
  users: z.ZodArray<z.ZodObject<{
55
55
  id: z.ZodString;
@@ -156,7 +156,7 @@ export declare const AdminDevicesResponse: z.ZodObject<{
156
156
  }, z.core.$strip>;
157
157
  export type AdminDevicesResponse = z.output<typeof AdminDevicesResponse>;
158
158
  /**
159
- * One sign-in link or code from the verification ledger (#829), as a management client sees it.
159
+ * One sign-in link or code from the verification ledger, as a management client sees it.
160
160
  *
161
161
  * Never the token and never the address: the ledger holds neither. The mail is named by its job id, which is how
162
162
  * a reader holding `email:jobs:read` joins this to a bounce, a deferral or a suppression.
@@ -192,7 +192,7 @@ export declare const VerificationTypeCounts: z.ZodObject<{
192
192
  }, z.core.$strip>;
193
193
  export type VerificationTypeCounts = z.output<typeof VerificationTypeCounts>;
194
194
  /**
195
- * `GET {base}/admin/verifications` (#829): the window it covered, the counts by type and state over all of it,
195
+ * `GET {base}/admin/verifications`: the window it covered, the counts by type and state over all of it,
196
196
  * and a page of its rows, newest issue first.
197
197
  *
198
198
  * The counts cover every row in the window whatever the page or the filters say, and every type, with zeros —
@@ -251,7 +251,7 @@ export declare const AdminDeviceRevokeResponse: z.ZodObject<{
251
251
  }, z.core.$strip>;
252
252
  export type AdminDeviceRevokeResponse = z.output<typeof AdminDeviceRevokeResponse>;
253
253
  /**
254
- * `POST {base}/admin/users/:userId/suspend` (#621).
254
+ * `POST {base}/admin/users/:userId/suspend`.
255
255
  *
256
256
  * The suspension the account is now under, how many sessions ended with it, and whether the person was told.
257
257
  * Not the reason: the caller wrote it, the trail keeps it, and echoing it back would put it in one more place
@@ -271,7 +271,7 @@ export declare const AdminUserSuspendResponse: z.ZodObject<{
271
271
  }, z.core.$strip>;
272
272
  export type AdminUserSuspendResponse = z.output<typeof AdminUserSuspendResponse>;
273
273
  /**
274
- * `POST {base}/admin/users/:userId/reinstate` (#621).
274
+ * `POST {base}/admin/users/:userId/reinstate`.
275
275
  *
276
276
  * No session count: a reinstatement restores none. The person signs in again.
277
277
  */
@@ -286,7 +286,7 @@ export declare const AdminUserReinstateResponse: z.ZodObject<{
286
286
  }, z.core.$strip>;
287
287
  export type AdminUserReinstateResponse = z.output<typeof AdminUserReinstateResponse>;
288
288
  /**
289
- * `DELETE {base}/admin/users/:userId` (#622).
289
+ * `DELETE {base}/admin/users/:userId`.
290
290
  *
291
291
  * What the deletion left in force, how many sessions ended with it, whether the person was told, and what
292
292
  * became of the purge. Not the reason: the caller wrote it and the trail keeps it.
@@ -315,7 +315,7 @@ export declare const AdminUserDeleteResponse: z.ZodObject<{
315
315
  }, z.core.$strip>;
316
316
  export type AdminUserDeleteResponse = z.output<typeof AdminUserDeleteResponse>;
317
317
  /**
318
- * `POST {base}/admin/users/:userId/restore` (#622). No session count: a restoration restores none.
318
+ * `POST {base}/admin/users/:userId/restore`. No session count: a restoration restores none.
319
319
  */
320
320
  export declare const AdminUserRestoreResponse: z.ZodObject<{
321
321
  userId: z.ZodString;
@@ -330,7 +330,7 @@ export declare const AdminUserRestoreResponse: z.ZodObject<{
330
330
  }, z.core.$strip>;
331
331
  export type AdminUserRestoreResponse = z.output<typeof AdminUserRestoreResponse>;
332
332
  /**
333
- * What `@pithy-sh/auth` holds about one account, as its purge contribution exports it (#622) — the `data` of
333
+ * What `@pithy-sh/auth` holds about one account, as its purge contribution exports it — the `data` of
334
334
  * the `auth` entry in an export.
335
335
  *
336
336
  * The person's own data and none of their credentials: no session token, no provider token, no push token.
@@ -414,7 +414,7 @@ export declare const AuthUserExport: z.ZodObject<{
414
414
  }, z.core.$strip>;
415
415
  export type AuthUserExport = z.output<typeof AuthUserExport>;
416
416
  /**
417
- * `GET {base}/admin/users/:userId/export` (#622).
417
+ * `POST {base}/admin/users/:userId/export`.
418
418
  *
419
419
  * Everything the kit holds about one account — the answer to an access request. One entry per composed
420
420
  * capability that declares a purge contribution, in the order the purge runs them, each read on its own so
@@ -516,7 +516,7 @@ export declare const MyDeviceRevokeResponse: z.ZodObject<{
516
516
  }, z.core.$strip>;
517
517
  export type MyDeviceRevokeResponse = z.output<typeof MyDeviceRevokeResponse>;
518
518
  /**
519
- * `DELETE {base}/account` (#622) — the signed-in person deleted their own account. Always soft, on the
519
+ * `DELETE {base}/account` — the signed-in person deleted their own account. Always soft, on the
520
520
  * configured window. Their sessions end with it, this one included.
521
521
  */
522
522
  export declare const AccountDeleteResponse: z.ZodObject<{
@@ -1 +1 @@
1
- {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyCxB,kDAAkD;AAClD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;iBAuCsF,CAAC;AACjH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAE3D,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB;;;;;;;;iBAUiF,CAAC;AAC/G,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE,0GAA0G;AAC1G,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;iBAawF,CAAC;AACrH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,gCAAgC;AAChC,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;iBAKQ,CAAC;AACxC,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAoDrE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY3B,CAAC;AACJ,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,kCAAkC;AAClC,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;iBAKY,CAAC;AAC9C,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;iBAqByE,CAAC;AAC5G,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAE3E,8EAA8E;AAC9E,eAAO,MAAM,sBAAsB;;;;;;;;;iBAQwB,CAAC;AAC5D,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAY6D,CAAC;AACrG,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAErF;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;iBAEsB,CAAC;AACvD,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,wDAAwD;AACxD,eAAO,MAAM,yBAAyB;;;iBAKoE,CAAC;AAC3G,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAEnF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;;iBAuBkF,CAAC;AACxH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEjF;;;;GAIG;AACH,eAAO,MAAM,0BAA0B;;;;;;;;iBAeiE,CAAC;AACzG,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,0BAA0B,CAAC,CAAC;AASrF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;iBAwB8E,CAAC;AACnH,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,wBAAwB;;;;;;;;;;iBAYyD,CAAC;AAC/F,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,wBAAwB,CAAC,CAAC;AA2BjF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA0B8D,CAAC;AAC1F,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAqD7D;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAauE,CAAC;AAC5G,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAQ/E,kCAAkC;AAClC,eAAO,MAAM,mBAAmB;;;;iBAgB7B,CAAC;AACJ,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,6BAA6B;AAC7B,eAAO,MAAM,uBAAuB;;;iBASyD,CAAC;AAC9F,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAE/E,kDAAkD;AAClD,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;iBAcwC,CAAC;AAClE,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,4BAA4B;AAC5B,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;iBAIqB,CAAC;AACpD,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE,oCAAoC;AACpC,eAAO,MAAM,sBAAsB;;iBAEyE,CAAC;AAC7G,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;GAGG;AACH,eAAO,MAAM,qBAAqB;;;;iBAU2E,CAAC;AAC9G,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC"}
1
+ {"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
@@ -25,7 +25,7 @@ import { Locale } from "@pithy-sh/core/src/i18n/locale";
25
25
  * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
26
26
  * version boundary — a management client validates a response with this schema against a customer's
27
27
  * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
28
- * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
28
+ * below that release and takes the whole pane with it. Absent then means *this Worker cannot
29
29
  * say*, which is a different fact from `null`.
30
30
  */
31
31
  /** Where a page resumes, or the end of the list. */
@@ -73,14 +73,14 @@ const AdminDeviceView = z.object({
73
73
  lastSeenAt: z.iso.datetime().describe("When it was last seen, ISO-8601."),
74
74
  createdAt: z.iso.datetime().describe("When it first registered, ISO-8601.")
75
75
  }).describe("One registered device as a management client sees it — without the push token, which is a credential.");
76
- /** `GET {base}/admin/users`. */
76
+ /** `GET {base}/admin/users` and `POST {base}/admin/users/search`. */
77
77
  const AdminUsersResponse = z.object({
78
78
  users: z.array(AdminUserView).describe("The page, newest first."),
79
79
  nextCursor: NextCursor
80
80
  }).describe("A page of the user list.");
81
81
  /** `GET {base}/admin/users/:userId`. */
82
82
  /**
83
- * A sub-read of the user pane that could not be made (#380).
83
+ * A sub-read of the user pane that could not be made.
84
84
  *
85
85
  * The pane fans out over three independent tables and this route used to `Promise.all` them: one D1 read
86
86
  * failing took the whole page down, so a support agent looking at a locked-out account saw a 500 instead
@@ -115,7 +115,7 @@ const AdminDevicesResponse = z.object({
115
115
  nextCursor: NextCursor
116
116
  }).describe("A page of the device registry.");
117
117
  /**
118
- * One sign-in link or code from the verification ledger (#829), as a management client sees it.
118
+ * One sign-in link or code from the verification ledger, as a management client sees it.
119
119
  *
120
120
  * Never the token and never the address: the ledger holds neither. The mail is named by its job id, which is how
121
121
  * a reader holding `email:jobs:read` joins this to a bounce, a deferral or a suppression.
@@ -139,7 +139,7 @@ const VerificationTypeCounts = z.object({
139
139
  pending: z.number().int().min(0).describe("How many are unused and still work. The three add up to `issued`.")
140
140
  }).describe("One type's counts over the window, by state.");
141
141
  /**
142
- * `GET {base}/admin/verifications` (#829): the window it covered, the counts by type and state over all of it,
142
+ * `GET {base}/admin/verifications`: the window it covered, the counts by type and state over all of it,
143
143
  * and a page of its rows, newest issue first.
144
144
  *
145
145
  * The counts cover every row in the window whatever the page or the filters say, and every type, with zeros —
@@ -168,7 +168,7 @@ const AdminDeviceRevokeResponse = z.object({
168
168
  removed: z.boolean().describe("Whether a device row was deleted. False when the user had no such device.")
169
169
  }).describe("How many sessions the device revocation ended, and whether the registry row went with them.");
170
170
  /**
171
- * `POST {base}/admin/users/:userId/suspend` (#621).
171
+ * `POST {base}/admin/users/:userId/suspend`.
172
172
  *
173
173
  * The suspension the account is now under, how many sessions ended with it, and whether the person was told.
174
174
  * Not the reason: the caller wrote it, the trail keeps it, and echoing it back would put it in one more place
@@ -184,7 +184,7 @@ const AdminUserSuspendResponse = z.object({
184
184
  mailed: z.boolean().describe("Whether the account-suspended mail was enqueued. False for `notify: false`, when the config turns it off, or when no email capability is composed.")
185
185
  }).describe("A suspended account: since when, until when, how many sessions it cost, and whether the person was told.");
186
186
  /**
187
- * `POST {base}/admin/users/:userId/reinstate` (#621).
187
+ * `POST {base}/admin/users/:userId/reinstate`.
188
188
  *
189
189
  * No session count: a reinstatement restores none. The person signs in again.
190
190
  */
@@ -197,7 +197,7 @@ const AdminUserReinstateResponse = z.object({
197
197
  /** When the purge may erase a deleted account, ISO-8601. */
198
198
  const PurgeAfter = z.iso.datetime().describe("When the purge may erase the account, ISO-8601. It can be restored until then; a hard deletion's is the moment it was deleted.");
199
199
  /**
200
- * `DELETE {base}/admin/users/:userId` (#622).
200
+ * `DELETE {base}/admin/users/:userId`.
201
201
  *
202
202
  * What the deletion left in force, how many sessions ended with it, whether the person was told, and what
203
203
  * became of the purge. Not the reason: the caller wrote it and the trail keeps it.
@@ -222,7 +222,7 @@ const AdminUserDeleteResponse = z.object({
222
222
  mailed: z.boolean().describe("Whether the deletion-scheduled mail was enqueued. Always false for `hard`, whose mail the purge sends, for `notify: false`, and when the config turns it off.")
223
223
  }).describe("A deleted account: when, until when it can be restored, what became of the purge, and its sessions.");
224
224
  /**
225
- * `POST {base}/admin/users/:userId/restore` (#622). No session count: a restoration restores none.
225
+ * `POST {base}/admin/users/:userId/restore`. No session count: a restoration restores none.
226
226
  */
227
227
  const AdminUserRestoreResponse = z.object({
228
228
  userId: z.string().describe("The account restored, as `pithy_auth_users.id` stores it."),
@@ -243,7 +243,7 @@ const AuthExportTransition = z.object({
243
243
  createdAt: z.iso.datetime().describe("When it happened, ISO-8601.")
244
244
  }).describe("One transition in the account's history. The operator's identity is theirs, not the person's, so it is not here.");
245
245
  /**
246
- * What `@pithy-sh/auth` holds about one account, as its purge contribution exports it (#622) — the `data` of
246
+ * What `@pithy-sh/auth` holds about one account, as its purge contribution exports it — the `data` of
247
247
  * the `auth` entry in an export.
248
248
  *
249
249
  * The person's own data and none of their credentials: no session token, no provider token, no push token.
@@ -288,7 +288,7 @@ const AdminUserExportEntry = z.discriminatedUnion("state", [
288
288
  }).describe("Nothing was established about this capability's rows. Deliberately empty — it is not 'none'.")
289
289
  ]).describe("One capability's part of an export, behind a state, so an unread part cannot be taken for an empty one.");
290
290
  /**
291
- * `GET {base}/admin/users/:userId/export` (#622).
291
+ * `POST {base}/admin/users/:userId/export`.
292
292
  *
293
293
  * Everything the kit holds about one account — the answer to an access request. One entry per composed
294
294
  * capability that declares a purge contribution, in the order the purge runs them, each read on its own so
@@ -332,7 +332,7 @@ const MyDevicesResponse = z.object({ devices: z.array(MyDeviceView).describe("Ev
332
332
  /** `POST {base}/devices/revoke`. */
333
333
  const MyDeviceRevokeResponse = z.object({ revoked: RevokedCount }).describe("How many of the device's sessions the revocation signed out. The device's row goes with them.");
334
334
  /**
335
- * `DELETE {base}/account` (#622) — the signed-in person deleted their own account. Always soft, on the
335
+ * `DELETE {base}/account` — the signed-in person deleted their own account. Always soft, on the
336
336
  * configured window. Their sessions end with it, this one included.
337
337
  */
338
338
  const AccountDeleteResponse = z.object({
@@ -70,24 +70,46 @@ export declare const UserIdParam: z.ZodObject<{
70
70
  userId: z.ZodString;
71
71
  }, z.core.$strip>;
72
72
  export type UserIdParam = z.output<typeof UserIdParam>;
73
- /** The user listing query. */
73
+ /**
74
+ * The user listing query. Strict, and there is no `search`: a search term is usually somebody's address, and
75
+ * a query string is written to every request log, so a search is {@link SearchUsersBody}, in a body. A
76
+ * client still sending `?search=` is refused as `validation/invalid_input` rather than handed every user as
77
+ * though they were the match.
78
+ */
74
79
  export declare const ListUsersQuery: z.ZodObject<{
75
- search: z.ZodOptional<z.ZodString>;
76
80
  state: z.ZodOptional<z.ZodEnum<{
77
81
  active: "active";
78
82
  deleted: "deleted";
79
83
  suspended: "suspended";
80
84
  }>>;
85
+ since: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
86
+ until: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
87
+ cursor: z.ZodOptional<z.ZodString>;
81
88
  verified: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
82
89
  false: "false";
83
90
  true: "true";
84
91
  }>, z.ZodTransform<boolean, "false" | "true">>>;
85
- since: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
86
- until: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
87
- cursor: z.ZodOptional<z.ZodString>;
88
92
  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
89
- }, z.core.$strip>;
93
+ }, z.core.$strict>;
90
94
  export type ListUsersQuery = z.output<typeof ListUsersQuery>;
95
+ /**
96
+ * The body of `POST {base}/admin/users/search`: the term, the listing's filters, and the cursor, all in a body
97
+ * so the term never reaches a request log. Pages exactly as the listing does.
98
+ */
99
+ export declare const SearchUsersBody: z.ZodObject<{
100
+ state: z.ZodOptional<z.ZodEnum<{
101
+ active: "active";
102
+ deleted: "deleted";
103
+ suspended: "suspended";
104
+ }>>;
105
+ since: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
106
+ until: z.ZodOptional<z.ZodPipe<z.ZodISODateTime, z.ZodTransform<Date, string>>>;
107
+ search: z.ZodString;
108
+ cursor: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodString>>, z.ZodTransform<string | undefined, string | null | undefined>>;
109
+ verified: z.ZodOptional<z.ZodBoolean>;
110
+ limit: z.ZodOptional<z.ZodNumber>;
111
+ }, z.core.$strict>;
112
+ export type SearchUsersBody = z.output<typeof SearchUsersBody>;
91
113
  /** The device-registry listing query. */
92
114
  export declare const ListDevicesQuery: z.ZodObject<{
93
115
  userId: z.ZodOptional<z.ZodString>;
@@ -172,13 +194,14 @@ export declare const RestoreUserBody: z.ZodObject<{
172
194
  }, z.core.$strip>;
173
195
  export type RestoreUserBody = z.output<typeof RestoreUserBody>;
174
196
  /**
175
- * The query of `GET /admin/users/:userId/export`. A disclosure of everything the kit holds about one person
176
- * says why, like every lifecycle call: the reason goes on the trail beside who asked.
197
+ * The body of `POST /admin/users/:userId/export`. A disclosure of everything the kit holds about one person
198
+ * says why, like every lifecycle call: the reason goes on the trail beside who asked, and in a body, never a
199
+ * URL, because a reason names the request it answers and often the person who made it.
177
200
  */
178
- export declare const ExportUserQuery: z.ZodObject<{
201
+ export declare const ExportUserBody: z.ZodObject<{
179
202
  reason: z.ZodString;
180
- }, z.core.$strip>;
181
- export type ExportUserQuery = z.output<typeof ExportUserQuery>;
203
+ }, z.core.$strict>;
204
+ export type ExportUserBody = z.output<typeof ExportUserBody>;
182
205
  /**
183
206
  * The body of `DELETE /account`, the signed-in person deleting their own account.
184
207
  *
@@ -1 +1 @@
1
- {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;iBAQ2E,CAAC;AACzG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;iBAesF,CAAC;AACvH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,mHAAmH;AACnH,eAAO,MAAM,gBAAgB;;;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;iBAqBhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;iBAIoD,CAAC;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAqBvD,8BAA8B;AAC9B,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;iBAgCxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,yCAAyC;AACzC,eAAO,MAAM,gBAAgB;;;;;;;;;iBAYwE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAKjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;iBAaiF,CAAC;AACrH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;iBAQqC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AA0BnE,uDAAuD;AACvD,eAAO,MAAM,eAAe;;;;iBAUzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,yDAAyD;AACzD,eAAO,MAAM,iBAAiB;;;iBAE8D,CAAC;AAC7F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;EAItB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;;;;;iBAakD,CAAC;AAC9E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,uDAAuD;AACvD,eAAO,MAAM,eAAe;;iBAEiF,CAAC;AAC9G,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,eAAe;;iBAMmB,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;iBAM+E,CAAC;AAC9G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
1
+ {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"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"}
@@ -6,6 +6,7 @@ import "../lifecycle/reason.js";
6
6
  import { z } from "zod";
7
7
  import { JsonDate } from "@pithy-sh/core/src/data/codecs";
8
8
  import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
9
+ import { freeText } from "@pithy-sh/core/src/http/freeText";
9
10
  //#region src/http/schemas.ts
10
11
  /**
11
12
  * The request schemas for the auth routes Pithy owns. Validation happens at the HTTP boundary
@@ -67,20 +68,45 @@ const PageLimit = z.coerce.number().int().min(1).max(MAX_PAGE_SIZE).optional().d
67
68
  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.");
68
69
  /** A signup-window bound, as ISO-8601, decoded to a `Date` by the schema so the handler takes a typed value. */
69
70
  const SignupBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
70
- /** The user listing query. */
71
- const ListUsersQuery = z.object({
72
- 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."),
71
+ /** The narrowing a listing and a search share, beside `verified`, which a query and a body spell differently. */
72
+ const userFilterFields = {
73
73
  state: z.enum([
74
74
  "active",
75
75
  "suspended",
76
76
  "deleted"
77
- ]).optional().describe("Narrow to where the account stands now: `active`, `suspended` or `deleted`. A suspension whose end has passed reads `active`, as enforcement reads it."),
78
- verified: z.enum(["true", "false"]).describe("`true` or `false`.").transform((value) => value === "true").optional().describe("`true` for the users whose address is verified, `false` for those whose is not. Both when absent."),
77
+ ]).describe("Narrow to where the account stands now: `active`, `suspended` or `deleted`. A suspension whose end has passed reads `active`, as enforcement reads it.").optional().describe("Narrow to where the account stands now: `active`, `suspended` or `deleted`. A suspension whose end has passed reads `active`, as enforcement reads it."),
79
78
  since: SignupBound.optional().describe("Created at or after this instant, ISO-8601. Inclusive."),
80
79
  until: SignupBound.optional().describe("Created before this instant, ISO-8601. Exclusive."),
81
- cursor: PageCursorParam,
80
+ cursor: PageCursorParam
81
+ };
82
+ /** A signup window that ends before it starts holds nothing. */
83
+ const SIGNUP_WINDOW_ORDER = { message: "`since` must be before `until`. A window that ends before it starts holds nothing." };
84
+ /** Whether a signup window is in order: either bound may be absent. */
85
+ function windowInOrder(query) {
86
+ return query.since === void 0 || query.until === void 0 || query.since < query.until;
87
+ }
88
+ /**
89
+ * The user listing query. Strict, and there is no `search`: a search term is usually somebody's address, and
90
+ * a query string is written to every request log, so a search is {@link SearchUsersBody}, in a body. A
91
+ * client still sending `?search=` is refused as `validation/invalid_input` rather than handed every user as
92
+ * though they were the match.
93
+ */
94
+ const ListUsersQuery = z.object({
95
+ ...userFilterFields,
96
+ verified: z.enum(["true", "false"]).describe("`true` or `false`.").transform((value) => value === "true").optional().describe("`true` for the users whose address is verified, `false` for those whose is not. Both when absent."),
82
97
  limit: PageLimit
83
- }).refine((query) => query.since === void 0 || query.until === void 0 || query.since < query.until, { message: "`since` must be before `until`. A window that ends before it starts holds nothing." }).describe("The user listing query: what to search for, which standing, verification and signup window to narrow to, how many to return, and where to resume.");
98
+ }).strict().refine(windowInOrder, SIGNUP_WINDOW_ORDER).describe("The user listing query: which standing, verification and signup window to narrow to, how many to return, and where to resume. To search by address or name, POST to `/admin/users/search`.");
99
+ /**
100
+ * The body of `POST {base}/admin/users/search`: the term, the listing's filters, and the cursor, all in a body
101
+ * so the term never reaches a request log. Pages exactly as the listing does.
102
+ */
103
+ const SearchUsersBody = z.object({
104
+ search: freeText(z.string().trim().min(1).max(200)).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."),
105
+ ...userFilterFields,
106
+ cursor: z.string().max(512).nullish().transform((value) => value ?? void 0).describe("Where to resume, from the previous page's `nextCursor`, passed back as it came: `null` or absent is a first page. Opaque; a malformed one is a first page."),
107
+ verified: z.boolean().optional().describe("`true` for the users whose address is verified, `false` for those whose is not. Both when absent."),
108
+ limit: z.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.")
109
+ }).strict().refine(windowInOrder, SIGNUP_WINDOW_ORDER).describe("A user search: the term, which standing, verification and signup window to narrow to, how many to return, and where to resume.");
84
110
  /** The device-registry listing query. */
85
111
  const ListDevicesQuery = z.object({
86
112
  userId: z.string().min(1).max(255).optional().describe("Narrow to one user's devices. Absent walks the whole fleet, most-recently-seen first."),
@@ -119,7 +145,7 @@ const RevokeSessionBody = z.object({ sessionId: z.string().min(1).max(255).descr
119
145
  * is a 400 here rather than a conflict later. Required rather than defaulted: a suspension nobody explained is
120
146
  * a lockout the person cannot answer, and the trail would record nothing about why.
121
147
  */
122
- const LifecycleReason = z.string().trim().min(1).max(500).describe("Why, in a sentence written for the person. A suspension's reason is what every refused sign-in shows them.");
148
+ const LifecycleReason = freeText(z.string().trim().min(1).max(500)).describe("Why, in a sentence written for the person. A suspension's reason is what every refused sign-in shows them.");
123
149
  /** Whether the person is mailed. */
124
150
  const Notify = z.boolean().optional().describe("Whether to mail the person. Absent is true. The config can turn a lifecycle mail off for every call; this turns it off for one.");
125
151
  /** The body of `POST /admin/users/:userId/suspend`. */
@@ -148,10 +174,11 @@ const DeleteUserBody = z.object({
148
174
  /** The body of `POST /admin/users/:userId/restore`. */
149
175
  const RestoreUserBody = z.object({ reason: LifecycleReason }).describe("A restoration inside the purge window: why. It restores no session; the person signs in again.");
150
176
  /**
151
- * The query of `GET /admin/users/:userId/export`. A disclosure of everything the kit holds about one person
152
- * says why, like every lifecycle call: the reason goes on the trail beside who asked.
177
+ * The body of `POST /admin/users/:userId/export`. A disclosure of everything the kit holds about one person
178
+ * says why, like every lifecycle call: the reason goes on the trail beside who asked, and in a body, never a
179
+ * URL, because a reason names the request it answers and often the person who made it.
153
180
  */
154
- const ExportUserQuery = z.object({ reason: LifecycleReason.describe("Why this person's data is being exported — the access request it answers. Recorded on the audit trail.") }).describe("An export: why it is being made.");
181
+ const ExportUserBody = z.object({ reason: LifecycleReason.describe("Why this person's data is being exported — the access request it answers. Recorded on the audit trail.") }).strict().describe("An export: why it is being made.");
155
182
  /**
156
183
  * The body of `DELETE /account`, the signed-in person deleting their own account.
157
184
  *
@@ -161,4 +188,4 @@ const ExportUserQuery = z.object({ reason: LifecycleReason.describe("Why this pe
161
188
  */
162
189
  const DeleteAccountBody = z.object({ confirm: z.literal(true).describe("Must be `true`. The person confirmed, in your app, that they want their account deleted.") }).describe("A self-service deletion: the person's own confirmation. Always soft, on the configured window.");
163
190
  //#endregion
164
- export { DeleteAccountBody, DeleteUserBody, DeletionMode, ExportUserQuery, HandoffExchangeBody, ListDevicesQuery, ListUsersQuery, ListVerificationsQuery, RedirectProvider, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SocialSignInStartQuery, SuspendUserBody, UserIdParam };
191
+ export { DeleteAccountBody, DeleteUserBody, DeletionMode, ExportUserBody, HandoffExchangeBody, ListDevicesQuery, ListUsersQuery, ListVerificationsQuery, RedirectProvider, ReinstateUserBody, RestoreUserBody, RevokeDeviceBody, RevokeSessionBody, SearchUsersBody, SocialSignInStartQuery, SuspendUserBody, UserIdParam };
@@ -1 +1 @@
1
- {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/mcp/http/schemas.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,qDAAqD;AACrD,eAAO,MAAM,cAAc;;;;;iBAAa,CAAC;AAEzC,qGAAqG;AACrG,eAAO,MAAM,YAAY;;iBAQ8C,CAAC;AAExE,wDAAwD;AACxD,eAAO,MAAM,WAAW;;;kBAUqE,CAAC;AAE9F,mCAAmC;AACnC,eAAO,MAAM,eAAe;;iBAEa,CAAC"}
1
+ {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../../src/mcp/http/schemas.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,qDAAqD;AACrD,eAAO,MAAM,cAAc;;;;;iBAAa,CAAC;AAEzC,qGAAqG;AACrG,eAAO,MAAM,YAAY;;iBAM8C,CAAC;AAExE,wDAAwD;AACxD,eAAO,MAAM,WAAW;;;kBAUqE,CAAC;AAE9F,mCAAmC;AACnC,eAAO,MAAM,eAAe;;iBAEa,CAAC"}
@@ -2,11 +2,12 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
  import { RpcMessage } from "../rpc.js";
4
4
  import { z } from "zod";
5
+ import { notFreeText } from "@pithy-sh/core/src/http/freeText";
5
6
  //#region src/mcp/http/schemas.ts
6
7
  /** The MCP endpoint's body: one JSON-RPC message. */
7
8
  const McpRequestBody = RpcMessage;
8
9
  /** The consent screen's question: the signed authorization query the provider redirected it with. */
9
- const ConsentQuery = z.object({ oauth_query: z.string().min(1).max(8192).describe("The query string the authorization server redirected the screen with, signed by it.") }).describe("Which authorization request the consent screen is about.");
10
+ const ConsentQuery = z.object({ oauth_query: notFreeText(z.string().min(1).max(8192)).describe("The query string the authorization server redirected the screen with, signed by it. Machine-made: no person types it.") }).describe("Which authorization request the consent screen is about.");
10
11
  /** The consent decision: one, for the whole request. */
11
12
  const ConsentBody = z.object({
12
13
  oauth_query: z.string().min(1).max(8192).describe("The query string the authorization server redirected the screen with, signed by it."),
@@ -3,5 +3,5 @@
3
3
  /** This package's npm name — the join key against a release feed. */
4
4
  export declare const PACKAGE_NAME = "@pithy-sh/auth";
5
5
  /** This package's version, stamped from its own package.json at generation time. */
6
- export declare const PACKAGE_VERSION = "0.13.0";
6
+ export declare const PACKAGE_VERSION = "0.14.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/auth";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.13.0";
7
+ const PACKAGE_VERSION = "0.14.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
@@ -82,10 +82,10 @@ Three routes. Deleting and restoring are gated by `auth:users:delete`, exporting
82
82
  ```
83
83
  DELETE /auth/admin/users/:userId { mode?, reason, notify? }
84
84
  POST /auth/admin/users/:userId/restore { reason }
85
- GET /auth/admin/users/:userId/export?reason=…
85
+ POST /auth/admin/users/:userId/export { reason }
86
86
  ```
87
87
 
88
- `reason` is required on all three, on the same terms as a suspension's. A request without one is `validation/invalid_input`.
88
+ `reason` is required on all three, on the same terms as a suspension's, and travels in the body on all three: a reason often names the request it answers, and a URL is written to every request log. A request without one is `validation/invalid_input`.
89
89
 
90
90
  **Two modes, and soft is the default.** `mode: "soft"`, or no mode at all, stamps `deleted_at` and `purge_after` — now plus the purge window — and revokes every session the account holds. Signing in again answers `auth/account_deleted`. The deletion-scheduled mail goes out with the purge date and, when you configure one, the restore path. `onUserDeleted` fires. The account can be restored until `purge_after`. `mode: "hard"` closes the window now: `purge_after` is the moment of the deletion, nothing can restore it, and the purge starts in the same call. You name it on purpose. A typo — `"Hard"`, `"hrad"` — is a 400, never either mode. A hard deletion of an account already deleted softly brings its purge forward to now.
91
91
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/auth",
3
- "version": "0.13.0",
3
+ "version": "0.14.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -46,10 +46,10 @@
46
46
  "better-auth": "^1.7.11"
47
47
  },
48
48
  "peerDependencies": {
49
- "@pithy-sh/core": "^0.17.0",
50
- "@pithy-sh/email": "^0.9.0",
51
- "@pithy-sh/secrets": "^0.6.5",
52
- "@pithy-sh/turnstile": "^0.8.1",
49
+ "@pithy-sh/core": "^0.18.0",
50
+ "@pithy-sh/email": "^0.10.0",
51
+ "@pithy-sh/secrets": "^0.6.6",
52
+ "@pithy-sh/turnstile": "^0.8.2",
53
53
  "hono": "^4.13.2",
54
54
  "kysely": "^0.29.0",
55
55
  "zod": "^4.4.0"
@@ -71,7 +71,7 @@ import {
71
71
  } from "./responses";
72
72
  import {
73
73
  DeleteUserBody,
74
- ExportUserQuery,
74
+ ExportUserBody,
75
75
  ListDevicesQuery,
76
76
  ListUsersQuery,
77
77
  ListVerificationsQuery,
@@ -79,6 +79,7 @@ import {
79
79
  RestoreUserBody,
80
80
  RevokeDeviceBody,
81
81
  RevokeSessionBody,
82
+ SearchUsersBody,
82
83
  SuspendUserBody,
83
84
  UserIdParam,
84
85
  } from "./schemas";
@@ -102,6 +103,7 @@ type Ctx = Context<PithyHonoEnv>;
102
103
  * revocations an incident costs.
103
104
  *
104
105
  * GET {base}/admin/users auth:users:read query: ListUsersQuery
106
+ * POST {base}/admin/users/search auth:users:read json: SearchUsersBody
105
107
  * GET {base}/admin/users/:userId auth:users:read param: UserIdParam
106
108
  * GET {base}/admin/devices auth:devices:read query: ListDevicesQuery
107
109
  * GET {base}/admin/verifications auth:verifications:read query: ListVerificationsQuery
@@ -112,7 +114,7 @@ type Ctx = Context<PithyHonoEnv>;
112
114
  * POST {base}/admin/users/:userId/reinstate auth:users:suspend param + json: ReinstateUserBody
113
115
  * DELETE {base}/admin/users/:userId auth:users:delete param + json: DeleteUserBody
114
116
  * POST {base}/admin/users/:userId/restore auth:users:delete param + json: RestoreUserBody
115
- * GET {base}/admin/users/:userId/export auth:users:export param + query: ExportUserQuery
117
+ * POST {base}/admin/users/:userId/export auth:users:export param + json: ExportUserBody
116
118
  *
117
119
  * ## Registered before the catch-all, or dead
118
120
  *
@@ -155,11 +157,11 @@ function db(c: Ctx, wiring: AuthWiring) {
155
157
  }
156
158
 
157
159
  /**
158
- * One of the user pane's sub-reads, guarded and projected in one step (#380).
160
+ * One of the user pane's sub-reads, guarded and projected in one step.
159
161
  *
160
162
  * **`try`/`catch` inside an `async` function, never `.catch()`.** The read is *called* inside the `try`,
161
163
  * so a seam that throws before it returns a promise is caught too — a rejected promise is not the only
162
- * way a D1 read fails, and a `.catch()` guard has been escaped by exactly that before (#371).
164
+ * way a D1 read fails, and a `.catch()` guard is escaped by exactly that.
163
165
  *
164
166
  * **The guard takes no binding.** The state is the whole of what travels; what the read threw names a
165
167
  * query and a table, and this response goes to a management client across a trust boundary.
@@ -246,7 +248,7 @@ function lifecycleCall(c: Ctx, wiring: AuthWiring, caller: ControlPlaneContext,
246
248
  }
247
249
 
248
250
  /**
249
- * A lifecycle route's body validator, which audits the bodies it refuses (#621). Every call is on the trail,
251
+ * A lifecycle route's body validator, which audits the bodies it refuses. Every call is on the trail,
250
252
  * a refusal included, and a body the validator turns away never reaches `auditedLifecycleCall`. So it is
251
253
  * recorded here, as `denied` under the route's own action, with whatever reason the body carried — cut to the
252
254
  * reason's own limit, so a refused essay is not stored whole — and the 400 is thrown as before.
@@ -301,7 +303,7 @@ async function endSessions(
301
303
  }
302
304
 
303
305
  /**
304
- * Start the purge of one account now (#622): `started` when this Worker binds the purge Workflow and it took the
306
+ * Start the purge of one account now: `started` when this Worker binds the purge Workflow and it took the
305
307
  * instance — or already held it — and `pending` when it binds none or the start failed; the account is due
306
308
  * either way, and the daily pass starts it. A failed start is not this call's failure: the deletion is already
307
309
  * written, and a 500 over it would invite a retry that finds the account deleted and says nothing new.
@@ -351,50 +353,66 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
351
353
  return (app) => {
352
354
  const base = wiring.config.basePath;
353
355
 
356
+ /** One page of users, audited as a listing: whether it was a search and how much came back, never the term. */
357
+ const pageOfUsers = async (c: Ctx, query: ListUsersQuery | SearchUsersBody) => {
358
+ const caller = controlPlaneCaller(c);
359
+ // One instant for the page, so the filter and every user on it are judged at the same moment.
360
+ const now = new Date();
361
+ const page = await listUsers(db(c, wiring), { ...query, now });
362
+ await emitControlPlaneAction(c.var.emit, {
363
+ action: AuthAuditActions.adminUsersListed,
364
+ subject: caller.subject,
365
+ connectionId: caller.connectionId,
366
+ resourceType: "user",
367
+ ...context(c),
368
+ // `searched`, not the term. A search term is usually somebody's email address, and the audit trail
369
+ // is queryable and kept far longer than the pane that displayed it, so the term would copy the
370
+ // personal data the caller already saw into a second store. That it was a search, and how much came
371
+ // back, is what makes an exfiltration pattern visible.
372
+ metadata: {
373
+ searched: "search" in query,
374
+ returned: page.items.length,
375
+ filters: {
376
+ state: query.state ?? null,
377
+ verified: query.verified ?? null,
378
+ since: query.since?.toISOString() ?? null,
379
+ until: query.until?.toISOString() ?? null,
380
+ },
381
+ },
382
+ });
383
+ return c.json({
384
+ users: page.items.map((user) => userView(user, now)),
385
+ nextCursor: page.nextCursor,
386
+ } satisfies AdminUsersResponse);
387
+ };
388
+
354
389
  app.get(
355
390
  `${base}/admin/users`,
356
391
  describeRoute({
357
392
  summary:
358
- "Page through the users, newest first, optionally searching by email or name and narrowing by standing, verification or signup window.",
393
+ "Page through the users, newest first, narrowing by standing, verification or signup window. A search by address or name is `POST /admin/users/search`.",
359
394
  verification: "control-plane",
360
395
  scopes: [AUTH_USERS_READ_SCOPE],
361
396
  responses: { 200: AdminUsersResponse },
362
397
  }),
363
398
  requireControlPlane(AUTH_USERS_READ_SCOPE),
364
399
  validate("query", ListUsersQuery),
365
- async (c) => {
366
- const query = c.req.valid("query");
367
- const caller = controlPlaneCaller(c);
368
- // One instant for the page, so the filter and every user on it are judged at the same moment.
369
- const now = new Date();
370
- const page = await listUsers(db(c, wiring), { ...query, now });
371
- await emitControlPlaneAction(c.var.emit, {
372
- action: AuthAuditActions.adminUsersListed,
373
- subject: caller.subject,
374
- connectionId: caller.connectionId,
375
- resourceType: "user",
376
- ...context(c),
377
- // `searched`, not the term. A search term on this route is usually somebody's email address,
378
- // and the audit trail is queryable and kept far longer than the pane that displayed it — so
379
- // recording the term would copy the personal data the caller already saw into a second store
380
- // with a different retention policy. That it was a search, and how much came back, is what
381
- // makes an exfiltration pattern visible; the string itself adds nothing to that.
382
- metadata: {
383
- searched: query.search !== undefined,
384
- returned: page.items.length,
385
- filters: {
386
- state: query.state ?? null,
387
- verified: query.verified ?? null,
388
- since: query.since?.toISOString() ?? null,
389
- until: query.until?.toISOString() ?? null,
390
- },
391
- },
392
- });
393
- return c.json({
394
- users: page.items.map((user) => userView(user, now)),
395
- nextCursor: page.nextCursor,
396
- } satisfies AdminUsersResponse);
397
- },
400
+ async (c) => pageOfUsers(c, c.req.valid("query")),
401
+ );
402
+
403
+ app.post(
404
+ `${base}/admin/users/search`,
405
+ describeRoute({
406
+ summary: "Search the users by email or name, newest first, with the listing's filters, paged on its cursor.",
407
+ description:
408
+ "The term travels in the body, because a query string is written to every request log between the client and the Worker and a search term is usually somebody's address. Answers the listing's envelope. Audited as a listing that searched, never with the term. Read-only.",
409
+ verification: "control-plane",
410
+ scopes: [AUTH_USERS_READ_SCOPE],
411
+ responses: { 200: AdminUsersResponse },
412
+ }),
413
+ requireControlPlane(AUTH_USERS_READ_SCOPE),
414
+ validate("json", SearchUsersBody),
415
+ async (c) => pageOfUsers(c, c.req.valid("json")),
398
416
  );
399
417
 
400
418
  app.get(
@@ -419,10 +437,9 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
419
437
  // Bounded, because a device id is client-generated: a user can mint as many device rows as they
420
438
  // like, so an unbounded sub-list would let any end user decide how much work this pane does.
421
439
  //
422
- // Each read is guarded on its own (#380). They are three independent tables and this was a
423
- // `Promise.all`, so one of them failing 500'd the whole page — the user, their sessions and
424
- // their devices all lost to whichever list would not read, on the pane a support agent opens
425
- // when an account is already in trouble. Still concurrent: the guard is inside each arm.
440
+ // Each read is guarded on its own: they are three independent tables, and one that will not read
441
+ // must not take the user and the other two lists with it, on the pane a support agent opens when an
442
+ // account is already in trouble. Still concurrent: the guard is inside each arm.
426
443
  const [sessions, devices, providers] = await Promise.all([
427
444
  readBounded(() => listUserSessions(database, userId, MAX_PAGE_SIZE), sessionView),
428
445
  readBounded(() => listUserDevices(database, userId, MAX_PAGE_SIZE), deviceView),
@@ -815,22 +832,22 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
815
832
  },
816
833
  );
817
834
 
818
- app.get(
835
+ app.post(
819
836
  `${base}/admin/users/:userId/export`,
820
837
  describeRoute({
821
838
  summary: "Export everything the kit holds about one user, from every composed capability, as one document.",
822
839
  description:
823
- "The answer to an access request. One entry per composed capability that declares a purge contribution, in the order the purge erases them. Audited as a disclosure, with the reason.",
840
+ "The answer to an access request. One entry per composed capability that declares a purge contribution, in the order the purge erases them. Audited as a disclosure, with the reason, which travels in the body because a reason often names the person who asked and a URL is written to every request log. Changes nothing.",
824
841
  verification: "control-plane",
825
842
  scopes: [AUTH_USERS_EXPORT_SCOPE],
826
843
  responses: { 200: AdminUserExportResponse },
827
844
  }),
828
845
  requireControlPlane(AUTH_USERS_EXPORT_SCOPE),
829
846
  validate("param", UserIdParam),
830
- validate("query", ExportUserQuery),
847
+ validate("json", ExportUserBody),
831
848
  async (c) => {
832
849
  const { userId } = c.req.valid("param");
833
- const { reason } = c.req.valid("query");
850
+ const { reason } = c.req.valid("json");
834
851
  const caller = controlPlaneCaller(c);
835
852
  const call = lifecycleCall(c, wiring, caller, userId, reason);
836
853
  const exportedAt = new Date();
@@ -846,7 +863,7 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
846
863
  return purgeExports(wiring.purgeSteps ?? [], {
847
864
  subject: { type: "user", id: userId },
848
865
  env: c.env as Record<string, unknown>,
849
- // A capability holding rows by address — a suppression, a tester's membership — reads it here (#814).
866
+ // A capability holding rows by address — a suppression, a tester's membership — reads it here.
850
867
  address: () => purgeAddress(database, userId),
851
868
  });
852
869
  },
@@ -159,7 +159,16 @@ export function authAdminRoutes(basePath: string): AdminRouteDeclaration[] {
159
159
  path: `${basePath}/admin/users`,
160
160
  scope: AUTH_USERS_READ_SCOPE,
161
161
  kind: "reads",
162
- summary: "Find a user. Lists everyone newest first, or searches email and display name.",
162
+ summary: "List the users newest first, narrowed by standing, verification or signup window.",
163
+ },
164
+ {
165
+ method: "POST",
166
+ operation: "users.search",
167
+ path: `${basePath}/admin/users/search`,
168
+ scope: AUTH_USERS_READ_SCOPE,
169
+ kind: "reads",
170
+ readInBody: true,
171
+ summary: "Find a user by email or display name, the term in the body so it never reaches a request log.",
163
172
  },
164
173
  {
165
174
  method: "GET",
@@ -244,11 +253,12 @@ export function authAdminRoutes(basePath: string): AdminRouteDeclaration[] {
244
253
  "Every sign-in link and code sent over a window: used, expired or still waiting, and the mail that carried it.",
245
254
  },
246
255
  {
247
- method: "GET",
256
+ method: "POST",
248
257
  operation: "users.export",
249
258
  path: `${basePath}/admin/users/:userId/export`,
250
259
  scope: AUTH_USERS_EXPORT_SCOPE,
251
260
  kind: "reads",
261
+ readInBody: true,
252
262
  summary: "Everything the kit holds about one user, from every capability — the answer to an access request.",
253
263
  },
254
264
  ];
@@ -26,7 +26,7 @@ import { VerificationState, VerificationType } from "../data/verificationOutcome
26
26
  * **A field added here later is `.optional()`, not merely `.nullable()`.** This module is read across a
27
27
  * version boundary — a management client validates a response with this schema against a customer's
28
28
  * Worker at whatever kit version it is on — so an additive required key fails `safeParse` for everyone
29
- * below that release and takes the whole pane with it (#450). Absent then means *this Worker cannot
29
+ * below that release and takes the whole pane with it. Absent then means *this Worker cannot
30
30
  * say*, which is a different fact from `null`.
31
31
  */
32
32
 
@@ -60,7 +60,7 @@ export const AdminUserView = z
60
60
  ),
61
61
  createdAt: z.iso.datetime().describe("When the user was created, ISO-8601."),
62
62
  updatedAt: z.iso.datetime().describe("When the row was last written, ISO-8601."),
63
- // Where the account stands (#813), on the organization view's shape. Each optional: absent from a Worker
63
+ // Where the account stands, on the organization view's shape. Each optional: absent from a Worker
64
64
  // older than the field. No reason and no actor — the reason is on the trail, and the trail is audit's.
65
65
  state: z
66
66
  .enum(["active", "suspended", "deleted"])
@@ -117,7 +117,7 @@ export const AdminDeviceView = z
117
117
  .describe("One registered device as a management client sees it — without the push token, which is a credential.");
118
118
  export type AdminDeviceView = z.output<typeof AdminDeviceView>;
119
119
 
120
- /** `GET {base}/admin/users`. */
120
+ /** `GET {base}/admin/users` and `POST {base}/admin/users/search`. */
121
121
  export const AdminUsersResponse = z
122
122
  .object({
123
123
  users: z.array(AdminUserView).describe("The page, newest first."),
@@ -128,7 +128,7 @@ export type AdminUsersResponse = z.output<typeof AdminUsersResponse>;
128
128
 
129
129
  /** `GET {base}/admin/users/:userId`. */
130
130
  /**
131
- * A sub-read of the user pane that could not be made (#380).
131
+ * A sub-read of the user pane that could not be made.
132
132
  *
133
133
  * The pane fans out over three independent tables and this route used to `Promise.all` them: one D1 read
134
134
  * failing took the whole page down, so a support agent looking at a locked-out account saw a 500 instead
@@ -201,7 +201,7 @@ export const AdminDevicesResponse = z
201
201
  export type AdminDevicesResponse = z.output<typeof AdminDevicesResponse>;
202
202
 
203
203
  /**
204
- * One sign-in link or code from the verification ledger (#829), as a management client sees it.
204
+ * One sign-in link or code from the verification ledger, as a management client sees it.
205
205
  *
206
206
  * Never the token and never the address: the ledger holds neither. The mail is named by its job id, which is how
207
207
  * a reader holding `email:jobs:read` joins this to a bounce, a deferral or a suppression.
@@ -243,7 +243,7 @@ export const VerificationTypeCounts = z
243
243
  export type VerificationTypeCounts = z.output<typeof VerificationTypeCounts>;
244
244
 
245
245
  /**
246
- * `GET {base}/admin/verifications` (#829): the window it covered, the counts by type and state over all of it,
246
+ * `GET {base}/admin/verifications`: the window it covered, the counts by type and state over all of it,
247
247
  * and a page of its rows, newest issue first.
248
248
  *
249
249
  * The counts cover every row in the window whatever the page or the filters say, and every type, with zeros —
@@ -286,7 +286,7 @@ export const AdminDeviceRevokeResponse = z
286
286
  export type AdminDeviceRevokeResponse = z.output<typeof AdminDeviceRevokeResponse>;
287
287
 
288
288
  /**
289
- * `POST {base}/admin/users/:userId/suspend` (#621).
289
+ * `POST {base}/admin/users/:userId/suspend`.
290
290
  *
291
291
  * The suspension the account is now under, how many sessions ended with it, and whether the person was told.
292
292
  * Not the reason: the caller wrote it, the trail keeps it, and echoing it back would put it in one more place
@@ -319,7 +319,7 @@ export const AdminUserSuspendResponse = z
319
319
  export type AdminUserSuspendResponse = z.output<typeof AdminUserSuspendResponse>;
320
320
 
321
321
  /**
322
- * `POST {base}/admin/users/:userId/reinstate` (#621).
322
+ * `POST {base}/admin/users/:userId/reinstate`.
323
323
  *
324
324
  * No session count: a reinstatement restores none. The person signs in again.
325
325
  */
@@ -349,7 +349,7 @@ const PurgeAfter = z.iso
349
349
  );
350
350
 
351
351
  /**
352
- * `DELETE {base}/admin/users/:userId` (#622).
352
+ * `DELETE {base}/admin/users/:userId`.
353
353
  *
354
354
  * What the deletion left in force, how many sessions ended with it, whether the person was told, and what
355
355
  * became of the purge. Not the reason: the caller wrote it and the trail keeps it.
@@ -382,7 +382,7 @@ export const AdminUserDeleteResponse = z
382
382
  export type AdminUserDeleteResponse = z.output<typeof AdminUserDeleteResponse>;
383
383
 
384
384
  /**
385
- * `POST {base}/admin/users/:userId/restore` (#622). No session count: a restoration restores none.
385
+ * `POST {base}/admin/users/:userId/restore`. No session count: a restoration restores none.
386
386
  */
387
387
  export const AdminUserRestoreResponse = z
388
388
  .object({
@@ -425,7 +425,7 @@ const AuthExportTransition = z
425
425
  );
426
426
 
427
427
  /**
428
- * What `@pithy-sh/auth` holds about one account, as its purge contribution exports it (#622) — the `data` of
428
+ * What `@pithy-sh/auth` holds about one account, as its purge contribution exports it — the `data` of
429
429
  * the `auth` entry in an export.
430
430
  *
431
431
  * The person's own data and none of their credentials: no session token, no provider token, no push token.
@@ -513,7 +513,7 @@ const AdminUserExportEntry = z
513
513
  .describe("One capability's part of an export, behind a state, so an unread part cannot be taken for an empty one.");
514
514
 
515
515
  /**
516
- * `GET {base}/admin/users/:userId/export` (#622).
516
+ * `POST {base}/admin/users/:userId/export`.
517
517
  *
518
518
  * Everything the kit holds about one account — the answer to an access request. One entry per composed
519
519
  * capability that declares a purge contribution, in the order the purge runs them, each read on its own so
@@ -607,7 +607,7 @@ export const MyDeviceRevokeResponse = z
607
607
  export type MyDeviceRevokeResponse = z.output<typeof MyDeviceRevokeResponse>;
608
608
 
609
609
  /**
610
- * `DELETE {base}/account` (#622) — the signed-in person deleted their own account. Always soft, on the
610
+ * `DELETE {base}/account` — the signed-in person deleted their own account. Always soft, on the
611
611
  * configured window. Their sessions end with it, this one included.
612
612
  */
613
613
  export const AccountDeleteResponse = z
@@ -3,6 +3,7 @@
3
3
 
4
4
  import { JsonDate } from "@pithy-sh/core/src/data/codecs";
5
5
  import { MAX_PAGE_SIZE } from "@pithy-sh/core/src/data/cursor";
6
+ import { freeText } from "@pithy-sh/core/src/http/freeText";
6
7
  import { z } from "zod";
7
8
  import { DevicePlatform } from "../data/device";
8
9
  import { VerificationState, VerificationType } from "../data/verificationOutcome";
@@ -131,42 +132,94 @@ const PageCursorParam = z
131
132
  /** A signup-window bound, as ISO-8601, decoded to a `Date` by the schema so the handler takes a typed value. */
132
133
  const SignupBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
133
134
 
134
- /** The user listing query. */
135
+ /** Where an account stands now, as a listing or a search narrows to it. */
136
+ const UserStateFilter = z
137
+ .enum(["active", "suspended", "deleted"])
138
+ .describe(
139
+ "Narrow to where the account stands now: `active`, `suspended` or `deleted`. A suspension whose end has passed reads `active`, as enforcement reads it.",
140
+ );
141
+
142
+ /** The narrowing a listing and a search share, beside `verified`, which a query and a body spell differently. */
143
+ const userFilterFields = {
144
+ state: UserStateFilter.optional().describe(
145
+ "Narrow to where the account stands now: `active`, `suspended` or `deleted`. A suspension whose end has passed reads `active`, as enforcement reads it.",
146
+ ),
147
+ since: SignupBound.optional().describe("Created at or after this instant, ISO-8601. Inclusive."),
148
+ until: SignupBound.optional().describe("Created before this instant, ISO-8601. Exclusive."),
149
+ cursor: PageCursorParam,
150
+ };
151
+
152
+ /** A signup window that ends before it starts holds nothing. */
153
+ const SIGNUP_WINDOW_ORDER = {
154
+ message: "`since` must be before `until`. A window that ends before it starts holds nothing.",
155
+ };
156
+
157
+ /** Whether a signup window is in order: either bound may be absent. */
158
+ function windowInOrder(query: { since?: Date | undefined; until?: Date | undefined }): boolean {
159
+ return query.since === undefined || query.until === undefined || query.since < query.until;
160
+ }
161
+
162
+ /**
163
+ * The user listing query. Strict, and there is no `search`: a search term is usually somebody's address, and
164
+ * a query string is written to every request log, so a search is {@link SearchUsersBody}, in a body. A
165
+ * client still sending `?search=` is refused as `validation/invalid_input` rather than handed every user as
166
+ * though they were the match.
167
+ */
135
168
  export const ListUsersQuery = z
136
169
  .object({
137
- search: z
138
- .string()
139
- .min(1)
140
- .max(200)
141
- .optional()
142
- .describe(
143
- "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.",
144
- ),
145
- state: z
146
- .enum(["active", "suspended", "deleted"])
147
- .optional()
148
- .describe(
149
- "Narrow to where the account stands now: `active`, `suspended` or `deleted`. A suspension whose end has passed reads `active`, as enforcement reads it.",
150
- ),
170
+ ...userFilterFields,
151
171
  verified: z
152
172
  .enum(["true", "false"])
153
173
  .describe("`true` or `false`.")
154
174
  .transform((value) => value === "true")
155
175
  .optional()
156
176
  .describe("`true` for the users whose address is verified, `false` for those whose is not. Both when absent."),
157
- since: SignupBound.optional().describe("Created at or after this instant, ISO-8601. Inclusive."),
158
- until: SignupBound.optional().describe("Created before this instant, ISO-8601. Exclusive."),
159
- cursor: PageCursorParam,
160
177
  limit: PageLimit,
161
178
  })
162
- .refine((query) => query.since === undefined || query.until === undefined || query.since < query.until, {
163
- message: "`since` must be before `until`. A window that ends before it starts holds nothing.",
164
- })
179
+ .strict()
180
+ .refine(windowInOrder, SIGNUP_WINDOW_ORDER)
165
181
  .describe(
166
- "The user listing query: what to search for, which standing, verification and signup window to narrow to, how many to return, and where to resume.",
182
+ "The user listing query: which standing, verification and signup window to narrow to, how many to return, and where to resume. To search by address or name, POST to `/admin/users/search`.",
167
183
  );
168
184
  export type ListUsersQuery = z.output<typeof ListUsersQuery>;
169
185
 
186
+ /**
187
+ * The body of `POST {base}/admin/users/search`: the term, the listing's filters, and the cursor, all in a body
188
+ * so the term never reaches a request log. Pages exactly as the listing does.
189
+ */
190
+ export const SearchUsersBody = z
191
+ .object({
192
+ search: freeText(z.string().trim().min(1).max(200)).describe(
193
+ "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.",
194
+ ),
195
+ ...userFilterFields,
196
+ cursor: z
197
+ .string()
198
+ .max(512)
199
+ .nullish()
200
+ .transform((value) => value ?? undefined)
201
+ .describe(
202
+ "Where to resume, from the previous page's `nextCursor`, passed back as it came: `null` or absent is a first page. Opaque; a malformed one is a first page.",
203
+ ),
204
+ verified: z
205
+ .boolean()
206
+ .optional()
207
+ .describe("`true` for the users whose address is verified, `false` for those whose is not. Both when absent."),
208
+ limit: z
209
+ .number()
210
+ .int()
211
+ .min(1)
212
+ .max(MAX_PAGE_SIZE)
213
+ .optional()
214
+ .describe("How many rows to return. Bounded, because a verified client can still have a bug."),
215
+ })
216
+ .strict()
217
+ .refine(windowInOrder, SIGNUP_WINDOW_ORDER)
218
+ .describe(
219
+ "A user search: the term, which standing, verification and signup window to narrow to, how many to return, and where to resume.",
220
+ );
221
+ export type SearchUsersBody = z.output<typeof SearchUsersBody>;
222
+
170
223
  /** The device-registry listing query. */
171
224
  export const ListDevicesQuery = z
172
225
  .object({
@@ -233,14 +286,9 @@ export type RevokeSessionBody = z.output<typeof RevokeSessionBody>;
233
286
  * is a 400 here rather than a conflict later. Required rather than defaulted: a suspension nobody explained is
234
287
  * a lockout the person cannot answer, and the trail would record nothing about why.
235
288
  */
236
- const LifecycleReason = z
237
- .string()
238
- .trim()
239
- .min(1)
240
- .max(MAX_REASON)
241
- .describe(
242
- "Why, in a sentence written for the person. A suspension's reason is what every refused sign-in shows them.",
243
- );
289
+ const LifecycleReason = freeText(z.string().trim().min(1).max(MAX_REASON)).describe(
290
+ "Why, in a sentence written for the person. A suspension's reason is what every refused sign-in shows them.",
291
+ );
244
292
 
245
293
  /** Whether the person is mailed. */
246
294
  const Notify = z
@@ -306,17 +354,19 @@ export const RestoreUserBody = z
306
354
  export type RestoreUserBody = z.output<typeof RestoreUserBody>;
307
355
 
308
356
  /**
309
- * The query of `GET /admin/users/:userId/export`. A disclosure of everything the kit holds about one person
310
- * says why, like every lifecycle call: the reason goes on the trail beside who asked.
357
+ * The body of `POST /admin/users/:userId/export`. A disclosure of everything the kit holds about one person
358
+ * says why, like every lifecycle call: the reason goes on the trail beside who asked, and in a body, never a
359
+ * URL, because a reason names the request it answers and often the person who made it.
311
360
  */
312
- export const ExportUserQuery = z
361
+ export const ExportUserBody = z
313
362
  .object({
314
363
  reason: LifecycleReason.describe(
315
364
  "Why this person's data is being exported — the access request it answers. Recorded on the audit trail.",
316
365
  ),
317
366
  })
367
+ .strict()
318
368
  .describe("An export: why it is being made.");
319
- export type ExportUserQuery = z.output<typeof ExportUserQuery>;
369
+ export type ExportUserBody = z.output<typeof ExportUserBody>;
320
370
 
321
371
  /**
322
372
  * The body of `DELETE /account`, the signed-in person deleting their own account.
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
+ import { notFreeText } from "@pithy-sh/core/src/http/freeText";
4
5
  import { z } from "zod";
5
6
  import { RpcMessage } from "../rpc";
6
7
 
@@ -10,11 +11,9 @@ export const McpRequestBody = RpcMessage;
10
11
  /** The consent screen's question: the signed authorization query the provider redirected it with. */
11
12
  export const ConsentQuery = z
12
13
  .object({
13
- oauth_query: z
14
- .string()
15
- .min(1)
16
- .max(8192)
17
- .describe("The query string the authorization server redirected the screen with, signed by it."),
14
+ oauth_query: notFreeText(z.string().min(1).max(8192)).describe(
15
+ "The query string the authorization server redirected the screen with, signed by it. Machine-made: no person types it.",
16
+ ),
18
17
  })
19
18
  .describe("Which authorization request the consent screen is about.");
20
19
 
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/auth";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.13.0";
16
+ export const PACKAGE_VERSION = "0.14.0";