@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.
@@ -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
- /** The user listing query. */
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
- search: z
135
- .string()
136
- .min(1)
137
- .max(200)
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
- .describe("The user listing query: what to search for, how many to return, and where to resume.");
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 (#829): a window of issue times, what to narrow it to, and where to resume.
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 (#621).
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
- .string()
216
- .trim()
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 (#622). `soft` is the default and the only thing an omission reaches: the account is shut
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 query of `GET /admin/users/:userId/export`. A disclosure of everything the kit holds about one person
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 ExportUserQuery = z
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 ExportUserQuery = z.output<typeof ExportUserQuery>;
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 (#622).
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
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
+ import { notFreeText } from "@pithy-sh/core/src/http/freeText";
4
5
  import { z } from "zod";
5
6
  import { RpcMessage } from "../rpc";
6
7
 
@@ -10,11 +11,9 @@ export const McpRequestBody = RpcMessage;
10
11
  /** The consent screen's question: the signed authorization query the provider redirected it with. */
11
12
  export const ConsentQuery = z
12
13
  .object({
13
- oauth_query: z
14
- .string()
15
- .min(1)
16
- .max(8192)
17
- .describe("The query string the authorization server redirected the screen with, signed by it."),
14
+ oauth_query: notFreeText(z.string().min(1).max(8192)).describe(
15
+ "The query string the authorization server redirected the screen with, signed by it. Machine-made: no person types it.",
16
+ ),
18
17
  })
19
18
  .describe("Which authorization request the consent screen is about.");
20
19
 
@@ -13,4 +13,4 @@
13
13
  export const PACKAGE_NAME = "@pithy-sh/auth";
14
14
 
15
15
  /** This package's version, stamped from its own package.json at generation time. */
16
- export const PACKAGE_VERSION = "0.12.2";
16
+ export const PACKAGE_VERSION = "0.14.0";