@pithy-sh/auth 0.12.2 → 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 +1 -1
- package/dist/admin/users.d.ts +19 -1
- package/dist/admin/users.d.ts.map +1 -1
- package/dist/admin/users.js +18 -1
- package/dist/http/adminRoutes.d.ts.map +1 -1
- package/dist/http/adminRoutes.js +40 -22
- 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 +45 -11
- package/dist/http/schemas.d.ts.map +1 -1
- package/dist/http/schemas.js +50 -13
- 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 +3 -3
- package/package.json +5 -5
- package/src/admin/users.ts +40 -2
- package/src/http/adminRoutes.ts +67 -40
- package/src/http/guards.ts +12 -2
- package/src/http/responses.ts +13 -13
- package/src/http/schemas.ts +98 -26
- package/src/mcp/http/schemas.ts +4 -5
- package/src/version.generated.ts +1 -1
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";
|
|
@@ -128,23 +129,97 @@ const PageCursorParam = z
|
|
|
128
129
|
.optional()
|
|
129
130
|
.describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page.");
|
|
130
131
|
|
|
131
|
-
/**
|
|
132
|
+
/** A signup-window bound, as ISO-8601, decoded to a `Date` by the schema so the handler takes a typed value. */
|
|
133
|
+
const SignupBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
|
|
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
|
+
*/
|
|
132
168
|
export const ListUsersQuery = z
|
|
133
169
|
.object({
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
.
|
|
137
|
-
.
|
|
170
|
+
...userFilterFields,
|
|
171
|
+
verified: z
|
|
172
|
+
.enum(["true", "false"])
|
|
173
|
+
.describe("`true` or `false`.")
|
|
174
|
+
.transform((value) => value === "true")
|
|
138
175
|
.optional()
|
|
139
|
-
.describe(
|
|
140
|
-
"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.",
|
|
141
|
-
),
|
|
142
|
-
cursor: PageCursorParam,
|
|
176
|
+
.describe("`true` for the users whose address is verified, `false` for those whose is not. Both when absent."),
|
|
143
177
|
limit: PageLimit,
|
|
144
178
|
})
|
|
145
|
-
.
|
|
179
|
+
.strict()
|
|
180
|
+
.refine(windowInOrder, SIGNUP_WINDOW_ORDER)
|
|
181
|
+
.describe(
|
|
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`.",
|
|
183
|
+
);
|
|
146
184
|
export type ListUsersQuery = z.output<typeof ListUsersQuery>;
|
|
147
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
|
+
|
|
148
223
|
/** The device-registry listing query. */
|
|
149
224
|
export const ListDevicesQuery = z
|
|
150
225
|
.object({
|
|
@@ -165,7 +240,7 @@ export type ListDevicesQuery = z.output<typeof ListDevicesQuery>;
|
|
|
165
240
|
const WindowBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
|
|
166
241
|
|
|
167
242
|
/**
|
|
168
|
-
* The verification ledger read's query
|
|
243
|
+
* The verification ledger read's query: a window of issue times, what to narrow it to, and where to resume.
|
|
169
244
|
* Both bounds are optional — the last 30 days, ending now — and a window that ends before it starts is refused by
|
|
170
245
|
* the handler, which is where the default is known.
|
|
171
246
|
*/
|
|
@@ -205,20 +280,15 @@ export const RevokeSessionBody = z
|
|
|
205
280
|
export type RevokeSessionBody = z.output<typeof RevokeSessionBody>;
|
|
206
281
|
|
|
207
282
|
/**
|
|
208
|
-
* Why an account's access is changing — required on both lifecycle routes
|
|
283
|
+
* Why an account's access is changing — required on both lifecycle routes.
|
|
209
284
|
*
|
|
210
285
|
* Trimmed, then bounded by the same constant the transition enforces, so a reason the transition would refuse
|
|
211
286
|
* is a 400 here rather than a conflict later. Required rather than defaulted: a suspension nobody explained is
|
|
212
287
|
* a lockout the person cannot answer, and the trail would record nothing about why.
|
|
213
288
|
*/
|
|
214
|
-
const LifecycleReason = z
|
|
215
|
-
.
|
|
216
|
-
|
|
217
|
-
.min(1)
|
|
218
|
-
.max(MAX_REASON)
|
|
219
|
-
.describe(
|
|
220
|
-
"Why, in a sentence written for the person. A suspension's reason is what every refused sign-in shows them.",
|
|
221
|
-
);
|
|
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
|
+
);
|
|
222
292
|
|
|
223
293
|
/** Whether the person is mailed. */
|
|
224
294
|
const Notify = z
|
|
@@ -249,7 +319,7 @@ export const ReinstateUserBody = z
|
|
|
249
319
|
export type ReinstateUserBody = z.output<typeof ReinstateUserBody>;
|
|
250
320
|
|
|
251
321
|
/**
|
|
252
|
-
* How a deletion runs
|
|
322
|
+
* How a deletion runs. `soft` is the default and the only thing an omission reaches: the account is shut
|
|
253
323
|
* now and erased once the window closes, restorable until then. `hard` starts the purge at once, with no
|
|
254
324
|
* window, and is reached only by naming it — a typo is a 400, never either mode.
|
|
255
325
|
*/
|
|
@@ -284,20 +354,22 @@ export const RestoreUserBody = z
|
|
|
284
354
|
export type RestoreUserBody = z.output<typeof RestoreUserBody>;
|
|
285
355
|
|
|
286
356
|
/**
|
|
287
|
-
* The
|
|
288
|
-
* 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.
|
|
289
360
|
*/
|
|
290
|
-
export const
|
|
361
|
+
export const ExportUserBody = z
|
|
291
362
|
.object({
|
|
292
363
|
reason: LifecycleReason.describe(
|
|
293
364
|
"Why this person's data is being exported — the access request it answers. Recorded on the audit trail.",
|
|
294
365
|
),
|
|
295
366
|
})
|
|
367
|
+
.strict()
|
|
296
368
|
.describe("An export: why it is being made.");
|
|
297
|
-
export type
|
|
369
|
+
export type ExportUserBody = z.output<typeof ExportUserBody>;
|
|
298
370
|
|
|
299
371
|
/**
|
|
300
|
-
* The body of `DELETE /account`, the signed-in person deleting their own account
|
|
372
|
+
* The body of `DELETE /account`, the signed-in person deleting their own account.
|
|
301
373
|
*
|
|
302
374
|
* The confirmation is the literal `true`, so a client must say it on purpose: a stray `DELETE` with an empty
|
|
303
375
|
* body, or a form posting `"false"`, deletes nothing. There is no field naming an account — the subject is the
|
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