@pithy-sh/auth 0.13.0 → 0.14.1
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 +1 -1
- package/dist/http/adminRoutes.d.ts.map +1 -1
- package/dist/http/adminRoutes.js +28 -19
- package/dist/http/guards.d.ts.map +1 -1
- package/dist/http/guards.js +12 -2
- package/dist/http/responses.d.ts +10 -10
- package/dist/http/responses.d.ts.map +1 -1
- package/dist/http/responses.js +12 -12
- package/dist/http/schemas.d.ts +34 -11
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +39 -12
- package/dist/mcp/http/schemas.d.ts.map +1 -1
- package/dist/mcp/http/schemas.js +2 -1
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/docs/account-lifecycle.md +2 -2
- package/package.json +5 -5
- package/src/http/adminRoutes.ts +66 -49
- package/src/http/guards.ts +12 -2
- package/src/http/responses.ts +13 -13
- package/src/http/schemas.ts +84 -34
- package/src/mcp/http/schemas.ts +4 -5
- package/src/version.generated.ts +1 -1
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 `
|
|
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;
|
|
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"}
|
package/dist/http/adminRoutes.js
CHANGED
|
@@ -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,
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
267
|
-
|
|
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:
|
|
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.
|
|
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("
|
|
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("
|
|
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,
|
|
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"}
|
package/dist/http/guards.js
CHANGED
|
@@ -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: "
|
|
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: "
|
|
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
|
];
|
package/dist/http/responses.d.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
* `
|
|
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`
|
|
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,
|
|
1
|
+
{"version":3,"file":"responses.d.ts","sourceRoot":"","sources":["../../src/http/responses.ts"],"names":[],"mappings":"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"}
|
package/dist/http/responses.js
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
* `
|
|
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`
|
|
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({
|
package/dist/http/schemas.d.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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.$
|
|
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
|
|
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
|
|
201
|
+
export declare const ExportUserBody: z.ZodObject<{
|
|
179
202
|
reason: z.ZodString;
|
|
180
|
-
}, z.core.$
|
|
181
|
-
export type
|
|
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":"
|
|
1
|
+
{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"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"}
|
package/dist/http/schemas.js
CHANGED
|
@@ -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
|
|
71
|
-
const
|
|
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
|
-
}).
|
|
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
|
|
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
|
|
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,
|
|
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":"
|
|
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"}
|
package/dist/mcp/http/schemas.js
CHANGED
|
@@ -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.
|
|
6
|
+
export declare const PACKAGE_VERSION = "0.14.1";
|
|
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.
|
|
7
|
+
const PACKAGE_VERSION = "0.14.1";
|
|
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
|
-
|
|
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.
|
|
3
|
+
"version": "0.14.1",
|
|
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.
|
|
50
|
-
"@pithy-sh/email": "^0.
|
|
51
|
-
"@pithy-sh/secrets": "^0.6.
|
|
52
|
-
"@pithy-sh/turnstile": "^0.8.
|
|
49
|
+
"@pithy-sh/core": "^0.19.0",
|
|
50
|
+
"@pithy-sh/email": "^0.10.1",
|
|
51
|
+
"@pithy-sh/secrets": "^0.6.7",
|
|
52
|
+
"@pithy-sh/turnstile": "^0.8.3",
|
|
53
53
|
"hono": "^4.13.2",
|
|
54
54
|
"kysely": "^0.29.0",
|
|
55
55
|
"zod": "^4.4.0"
|
package/src/http/adminRoutes.ts
CHANGED
|
@@ -71,7 +71,7 @@ import {
|
|
|
71
71
|
} from "./responses";
|
|
72
72
|
import {
|
|
73
73
|
DeleteUserBody,
|
|
74
|
-
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
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
|
|
423
|
-
//
|
|
424
|
-
//
|
|
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.
|
|
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("
|
|
847
|
+
validate("json", ExportUserBody),
|
|
831
848
|
async (c) => {
|
|
832
849
|
const { userId } = c.req.valid("param");
|
|
833
|
-
const { reason } = c.req.valid("
|
|
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
|
|
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
|
},
|
package/src/http/guards.ts
CHANGED
|
@@ -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: "
|
|
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: "
|
|
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
|
];
|
package/src/http/responses.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
* `
|
|
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`
|
|
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
|
package/src/http/schemas.ts
CHANGED
|
@@ -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
|
-
/**
|
|
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
|
-
|
|
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
|
-
.
|
|
163
|
-
|
|
164
|
-
})
|
|
179
|
+
.strict()
|
|
180
|
+
.refine(windowInOrder, SIGNUP_WINDOW_ORDER)
|
|
165
181
|
.describe(
|
|
166
|
-
"The user listing query:
|
|
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
|
-
.
|
|
238
|
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
package/src/mcp/http/schemas.ts
CHANGED
|
@@ -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
|
-
.
|
|
15
|
-
|
|
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
|
|
package/src/version.generated.ts
CHANGED