@pithy-sh/auth 0.12.1 → 0.13.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.
@@ -1,8 +1,11 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
+ import type { DatabaseSchema } from "@pithy-sh/core/src/data/db";
4
+ import { type Expression, type ExpressionBuilder, type SqlBool } from "kysely";
3
5
  import { Session, User } from "../data/betterAuth";
4
6
  import { Device, type DevicePlatform } from "../data/device";
5
- import type { AuthDatabase } from "../data/tables";
7
+ import type { AuthDatabase, AuthTables } from "../data/tables";
8
+ import type { AccountStanding } from "../lifecycle/state";
6
9
  /**
7
10
  * The reads a management dashboard's user panes resolve to, and the lookups its revocations need.
8
11
  *
@@ -46,11 +49,26 @@ export interface AdminSubList<T> {
46
49
  export interface ListUsersOptions {
47
50
  /** Free text matched against email and display name. Absent lists everyone, newest first. */
48
51
  search?: string;
52
+ /** Where the account stands, judged at `now` exactly as `accountStanding` judges it. */
53
+ state?: AccountStanding["state"];
54
+ /** Whether the address is verified. */
55
+ verified?: boolean;
56
+ /** Created at or after this instant. Inclusive. */
57
+ since?: Date;
58
+ /** Created before this instant. Exclusive. */
59
+ until?: Date;
60
+ /** The instant `state` is judged at. Defaults to the moment of the read. */
61
+ now?: Date;
49
62
  /** The previous page's `nextCursor`. A malformed one is a first page, never an error. */
50
63
  cursor?: string;
51
64
  /** How many rows to return, clamped into `[1, MAX_PAGE_SIZE]` by `pageLimit`. */
52
65
  limit?: number;
53
66
  }
67
+ /**
68
+ * The rows `accountStanding` reads as `state` at `now`, as one predicate: deleted outranks suspended, and a
69
+ * suspension ends at the instant its `suspendedUntil` names.
70
+ */
71
+ export declare function standingPredicate(state: AccountStanding["state"], now: Date): (eb: ExpressionBuilder<DatabaseSchema<AuthTables>, "pithyAuthUsers">) => Expression<SqlBool>;
54
72
  /**
55
73
  * Users, newest first, optionally filtered by a free-text term over email and display name.
56
74
  *
@@ -1 +1 @@
1
- {"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/admin/users.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"users.d.ts","sourceRoot":"","sources":["../../src/admin/users.ts"],"names":[],"mappings":"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"}
@@ -3,6 +3,7 @@
3
3
  import { Session, User } from "../data/betterAuth.js";
4
4
  import { Device } from "../data/device.js";
5
5
  import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
6
+ import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
6
7
  import { MAX_BOUND_PARAMETERS, boundParameterBudget } from "@pithy-sh/core/src/data/boundParameters";
7
8
  import { decodeCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
8
9
  import { sql } from "kysely";
@@ -41,6 +42,18 @@ function likePattern(term) {
41
42
  return `%${term.replace(/[\\%_]/g, (char) => `\\${char}`)}%`;
42
43
  }
43
44
  /**
45
+ * The rows `accountStanding` reads as `state` at `now`, as one predicate: deleted outranks suspended, and a
46
+ * suspension ends at the instant its `suspendedUntil` names.
47
+ */
48
+ function standingPredicate(state, now) {
49
+ const at = SQLiteDate.encode(now);
50
+ return (eb) => {
51
+ if (state === "deleted") return eb("deletedAt", "is not", null);
52
+ const inForce = eb.and([eb("suspendedAt", "is not", null), eb.or([eb("suspendedUntil", "is", null), eb("suspendedUntil", ">", at)])]);
53
+ return eb.and([eb("deletedAt", "is", null), state === "suspended" ? inForce : eb.not(inForce)]);
54
+ };
55
+ }
56
+ /**
44
57
  * Users, newest first, optionally filtered by a free-text term over email and display name.
45
58
  *
46
59
  * Keyset-paginated on `(createdAt, id)` — never an offset. The users table is written to constantly
@@ -58,6 +71,10 @@ async function listUsers(db, options = {}) {
58
71
  const pattern = likePattern(term);
59
72
  query = query.where(sql`(email like ${pattern} escape '\\' or name like ${pattern} escape '\\')`);
60
73
  }
74
+ if (options.state !== void 0) query = query.where(standingPredicate(options.state, options.now ?? /* @__PURE__ */ new Date()));
75
+ if (options.verified !== void 0) query = query.where("emailVerified", "=", SQLiteBoolean.encode(options.verified));
76
+ if (options.since !== void 0) query = query.where("createdAt", ">=", options.since.toISOString());
77
+ if (options.until !== void 0) query = query.where("createdAt", "<", options.until.toISOString());
61
78
  const cursor = decodeCursor(options.cursor);
62
79
  if (cursor) {
63
80
  const at = String(cursor.sort);
@@ -204,4 +221,4 @@ async function userSessionTokens(db, userId) {
204
221
  return (await db.selectFrom("pithyAuthSessions").select("token").where("userId", "=", userId).execute()).map((row) => row.token);
205
222
  }
206
223
  //#endregion
207
- export { MAX_USER_LOOKUP, USER_LOOKUP_FIXED_PARAMETERS, findSessionById, getUser, getUsers, listDeviceRegistry, listUserDevices, listUserSessions, listUsers, userProviders, userSessionTokens };
224
+ export { MAX_USER_LOOKUP, USER_LOOKUP_FIXED_PARAMETERS, findSessionById, getUser, getUsers, listDeviceRegistry, listUserDevices, listUserSessions, listUsers, standingPredicate, userProviders, userSessionTokens };
@@ -1 +1 @@
1
- {"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AA8ThD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CAmgB7F"}
1
+ {"version":3,"file":"adminRoutes.d.ts","sourceRoot":"","sources":["../../src/http/adminRoutes.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAS7E,OAAO,KAAK,EAAW,IAAI,EAAE,MAAM,MAAM,CAAC;AAe1C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AA8ThD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,UAAU,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,KAAK,IAAI,CA6gB7F"}
@@ -264,14 +264,18 @@ function registerAuthAdminRoutes(wiring) {
264
264
  return (app) => {
265
265
  const base = wiring.config.basePath;
266
266
  app.get(`${base}/admin/users`, describeRoute({
267
- summary: "Page through the users, newest first, optionally searching by email or name.",
267
+ summary: "Page through the users, newest first, optionally searching by email or name and narrowing by standing, verification or signup window.",
268
268
  verification: "control-plane",
269
269
  scopes: [AUTH_USERS_READ_SCOPE],
270
270
  responses: { 200: AdminUsersResponse }
271
271
  }), requireControlPlane(AUTH_USERS_READ_SCOPE), validate("query", ListUsersQuery), async (c) => {
272
272
  const query = c.req.valid("query");
273
273
  const caller = controlPlaneCaller(c);
274
- const page = await listUsers(db(c, wiring), query);
274
+ const now = /* @__PURE__ */ new Date();
275
+ const page = await listUsers(db(c, wiring), {
276
+ ...query,
277
+ now
278
+ });
275
279
  await emitControlPlaneAction(c.var.emit, {
276
280
  action: AuthAuditActions.adminUsersListed,
277
281
  subject: caller.subject,
@@ -280,10 +284,15 @@ function registerAuthAdminRoutes(wiring) {
280
284
  ...context(c),
281
285
  metadata: {
282
286
  searched: query.search !== void 0,
283
- returned: page.items.length
287
+ returned: page.items.length,
288
+ filters: {
289
+ state: query.state ?? null,
290
+ verified: query.verified ?? null,
291
+ since: query.since?.toISOString() ?? null,
292
+ until: query.until?.toISOString() ?? null
293
+ }
284
294
  }
285
295
  });
286
- const now = /* @__PURE__ */ new Date();
287
296
  return c.json({
288
297
  users: page.items.map((user) => userView(user, now)),
289
298
  nextCursor: page.nextCursor
@@ -73,6 +73,17 @@ export type UserIdParam = z.output<typeof UserIdParam>;
73
73
  /** The user listing query. */
74
74
  export declare const ListUsersQuery: z.ZodObject<{
75
75
  search: z.ZodOptional<z.ZodString>;
76
+ state: z.ZodOptional<z.ZodEnum<{
77
+ active: "active";
78
+ deleted: "deleted";
79
+ suspended: "suspended";
80
+ }>>;
81
+ verified: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
82
+ false: "false";
83
+ true: "true";
84
+ }>, 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>>>;
76
87
  cursor: z.ZodOptional<z.ZodString>;
77
88
  limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
78
89
  }, z.core.$strip>;
@@ -90,7 +101,7 @@ export declare const ListDevicesQuery: z.ZodObject<{
90
101
  }, z.core.$strip>;
91
102
  export type ListDevicesQuery = z.output<typeof ListDevicesQuery>;
92
103
  /**
93
- * The verification ledger read's query (#829): a window of issue times, what to narrow it to, and where to resume.
104
+ * The verification ledger read's query: a window of issue times, what to narrow it to, and where to resume.
94
105
  * Both bounds are optional — the last 30 days, ending now — and a window that ends before it starts is refused by
95
106
  * the handler, which is where the default is known.
96
107
  */
@@ -136,7 +147,7 @@ export declare const ReinstateUserBody: z.ZodObject<{
136
147
  }, z.core.$strip>;
137
148
  export type ReinstateUserBody = z.output<typeof ReinstateUserBody>;
138
149
  /**
139
- * How a deletion runs (#622). `soft` is the default and the only thing an omission reaches: the account is shut
150
+ * How a deletion runs. `soft` is the default and the only thing an omission reaches: the account is shut
140
151
  * now and erased once the window closes, restorable until then. `hard` starts the purge at once, with no
141
152
  * window, and is reached only by naming it — a typo is a 400, never either mode.
142
153
  */
@@ -169,7 +180,7 @@ export declare const ExportUserQuery: z.ZodObject<{
169
180
  }, z.core.$strip>;
170
181
  export type ExportUserQuery = z.output<typeof ExportUserQuery>;
171
182
  /**
172
- * The body of `DELETE /account`, the signed-in person deleting their own account (#622).
183
+ * The body of `DELETE /account`, the signed-in person deleting their own account.
173
184
  *
174
185
  * The confirmation is the literal `true`, so a client must say it on purpose: a stray `DELETE` with an empty
175
186
  * body, or a form posting `"false"`, deletes nothing. There is no field naming an account — the subject is the
@@ -1 +1 @@
1
- {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;iBAQ2E,CAAC;AACzG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;iBAesF,CAAC;AACvH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,mHAAmH;AACnH,eAAO,MAAM,gBAAgB;;;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;iBAqBhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;iBAIoD,CAAC;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAkBvD,8BAA8B;AAC9B,eAAO,MAAM,cAAc;;;;iBAawE,CAAC;AACpG,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,yCAAyC;AACzC,eAAO,MAAM,gBAAgB;;;;;;;;;iBAYwE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAKjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;iBAaiF,CAAC;AACrH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;iBAQqC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AA0BnE,uDAAuD;AACvD,eAAO,MAAM,eAAe;;;;iBAUzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,yDAAyD;AACzD,eAAO,MAAM,iBAAiB;;;iBAE8D,CAAC;AAC7F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;EAItB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;;;;;iBAakD,CAAC;AAC9E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,uDAAuD;AACvD,eAAO,MAAM,eAAe;;iBAEiF,CAAC;AAC9G,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,eAAe;;iBAMmB,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;iBAM+E,CAAC;AAC9G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
1
+ {"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/http/schemas.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB;;iBAQ2E,CAAC;AACzG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB;;;iBAesF,CAAC;AACvH,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEvE,mHAAmH;AACnH,eAAO,MAAM,gBAAgB;;;;;;EAI1B,CAAC;AACJ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAEjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;iBAqBhC,CAAC;AACJ,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,WAAW;;iBAIoD,CAAC;AAC7E,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,WAAW,CAAC,CAAC;AAqBvD,8BAA8B;AAC9B,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;iBAgCxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,yCAAyC;AACzC,eAAO,MAAM,gBAAgB;;;;;;;;;iBAYwE,CAAC;AACtG,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAKjE;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;iBAaiF,CAAC;AACrH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAE7E;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;iBAQqC,CAAC;AACpE,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AA0BnE,uDAAuD;AACvD,eAAO,MAAM,eAAe;;;;iBAUzB,CAAC;AACJ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D,yDAAyD;AACzD,eAAO,MAAM,iBAAiB;;;iBAE8D,CAAC;AAC7F,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,YAAY;;;EAItB,CAAC;AACJ,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEzD,iDAAiD;AACjD,eAAO,MAAM,cAAc;;;;;;;iBAakD,CAAC;AAC9E,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D,uDAAuD;AACvD,eAAO,MAAM,eAAe;;iBAEiF,CAAC;AAC9G,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,eAAe;;iBAMmB,CAAC;AAChD,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAE/D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;iBAM+E,CAAC;AAC9G,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC"}
@@ -65,12 +65,22 @@ const UserIdParam = z.object({ userId: z.string().min(1).max(255).describe("The
65
65
  const PageLimit = z.coerce.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.");
66
66
  /** Where a paged admin listing resumes. */
67
67
  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
+ /** A signup-window bound, as ISO-8601, decoded to a `Date` by the schema so the handler takes a typed value. */
69
+ const SignupBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
68
70
  /** The user listing query. */
69
71
  const ListUsersQuery = z.object({
70
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."),
73
+ state: z.enum([
74
+ "active",
75
+ "suspended",
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."),
79
+ since: SignupBound.optional().describe("Created at or after this instant, ISO-8601. Inclusive."),
80
+ until: SignupBound.optional().describe("Created before this instant, ISO-8601. Exclusive."),
71
81
  cursor: PageCursorParam,
72
82
  limit: PageLimit
73
- }).describe("The user listing query: what to search for, how many to return, and where to resume.");
83
+ }).refine((query) => query.since === void 0 || query.until === void 0 || query.since < query.until, { message: "`since` must be before `until`. A window that ends before it starts holds nothing." }).describe("The user listing query: what to search for, which standing, verification and signup window to narrow to, how many to return, and where to resume.");
74
84
  /** The device-registry listing query. */
75
85
  const ListDevicesQuery = z.object({
76
86
  userId: z.string().min(1).max(255).optional().describe("Narrow to one user's devices. Absent walks the whole fleet, most-recently-seen first."),
@@ -81,7 +91,7 @@ const ListDevicesQuery = z.object({
81
91
  /** A window bound on the verification read: ISO-8601 with an offset, decoded to a `Date` here so no handler parses it. */
82
92
  const WindowBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
83
93
  /**
84
- * The verification ledger read's query (#829): a window of issue times, what to narrow it to, and where to resume.
94
+ * The verification ledger read's query: a window of issue times, what to narrow it to, and where to resume.
85
95
  * Both bounds are optional — the last 30 days, ending now — and a window that ends before it starts is refused by
86
96
  * the handler, which is where the default is known.
87
97
  */
@@ -103,7 +113,7 @@ const ListVerificationsQuery = z.object({
103
113
  */
104
114
  const RevokeSessionBody = z.object({ sessionId: z.string().min(1).max(255).describe("The session's id, as the admin read routes report it. Not the session token.") }).describe("The body identifying which single session to revoke.");
105
115
  /**
106
- * Why an account's access is changing — required on both lifecycle routes (#621).
116
+ * Why an account's access is changing — required on both lifecycle routes.
107
117
  *
108
118
  * Trimmed, then bounded by the same constant the transition enforces, so a reason the transition would refuse
109
119
  * is a 400 here rather than a conflict later. Required rather than defaulted: a suspension nobody explained is
@@ -124,7 +134,7 @@ const ReinstateUserBody = z.object({
124
134
  notify: Notify
125
135
  }).describe("A reinstatement: why, and whether to tell the person. It restores no session.");
126
136
  /**
127
- * How a deletion runs (#622). `soft` is the default and the only thing an omission reaches: the account is shut
137
+ * How a deletion runs. `soft` is the default and the only thing an omission reaches: the account is shut
128
138
  * now and erased once the window closes, restorable until then. `hard` starts the purge at once, with no
129
139
  * window, and is reached only by naming it — a typo is a 400, never either mode.
130
140
  */
@@ -143,7 +153,7 @@ const RestoreUserBody = z.object({ reason: LifecycleReason }).describe("A restor
143
153
  */
144
154
  const ExportUserQuery = z.object({ reason: LifecycleReason.describe("Why this person's data is being exported — the access request it answers. Recorded on the audit trail.") }).describe("An export: why it is being made.");
145
155
  /**
146
- * The body of `DELETE /account`, the signed-in person deleting their own account (#622).
156
+ * The body of `DELETE /account`, the signed-in person deleting their own account.
147
157
  *
148
158
  * The confirmation is the literal `true`, so a client must say it on purpose: a stray `DELETE` with an empty
149
159
  * body, or a form posting `"false"`, deletes nothing. There is no field naming an account — the subject is the
@@ -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.12.1";
6
+ export declare const PACKAGE_VERSION = "0.13.0";
7
7
  //# sourceMappingURL=version.generated.d.ts.map
@@ -4,6 +4,6 @@
4
4
  /** This package's npm name — the join key against a release feed. */
5
5
  const PACKAGE_NAME = "@pithy-sh/auth";
6
6
  /** This package's version, stamped from its own package.json at generation time. */
7
- const PACKAGE_VERSION = "0.12.1";
7
+ const PACKAGE_VERSION = "0.13.0";
8
8
  //#endregion
9
9
  export { PACKAGE_NAME, PACKAGE_VERSION };
@@ -13,7 +13,7 @@ Both live on `pithy_auth_users`, so a session read already carries them. An acco
13
13
 
14
14
  No client can write its own state. The four columns are `input: false`, and only the kit's transitions set them.
15
15
 
16
- **The admin reads say where each account stands.** `GET /auth/admin/users` and `GET /auth/admin/users/:userId` return each user with `state` — `active`, `suspended` or `deleted` — `suspendedUntil`, the end of a suspension in force or null for one with none and in every other state, and `purgeAfter`, the last day a deleted account can be restored or null otherwise. They are read the way enforcement reads them, so a suspension past its end is `active`. The listing does not leave a suspended or deleted account out, and these are what let a pane offer suspend or reinstate without sending a write to find out. Neither the reason nor who acted is there: the reason is on the trail, and the trail is audit's. Each field is optional in `AdminUserView`, so a client reading a Worker older than them still parses its answer.
16
+ **The admin reads say where each account stands.** `GET /auth/admin/users` and `GET /auth/admin/users/:userId` return each user with `state` — `active`, `suspended` or `deleted` — `suspendedUntil`, the end of a suspension in force or null for one with none and in every other state, and `purgeAfter`, the last day a deleted account can be restored or null otherwise. They are read the way enforcement reads them, so a suspension past its end is `active`. The listing does not leave a suspended or deleted account out, and these are what let a pane offer suspend or reinstate without sending a write to find out. Neither the reason nor who acted is there: the reason is on the trail, and the trail is audit's. Each field is optional in `AdminUserView`, so a client reading a Worker older than them still parses its answer. The listing narrows on it too: `GET /auth/admin/users?state=suspended` pages the suspended accounts on the server, judged as enforcement judges them, so a suspension past its end is `active`.
17
17
 
18
18
  ## Enforcement
19
19
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pithy-sh/auth",
3
- "version": "0.12.1",
3
+ "version": "0.13.0",
4
4
  "license": "MIT",
5
5
  "repository": {
6
6
  "type": "git",
@@ -46,10 +46,10 @@
46
46
  "better-auth": "^1.7.11"
47
47
  },
48
48
  "peerDependencies": {
49
- "@pithy-sh/core": "^0.15.0",
50
- "@pithy-sh/email": "^0.8.1",
51
- "@pithy-sh/secrets": "^0.6.3",
52
- "@pithy-sh/turnstile": "^0.7.1",
49
+ "@pithy-sh/core": "^0.17.0",
50
+ "@pithy-sh/email": "^0.9.0",
51
+ "@pithy-sh/secrets": "^0.6.5",
52
+ "@pithy-sh/turnstile": "^0.8.1",
53
53
  "hono": "^4.13.2",
54
54
  "kysely": "^0.29.0",
55
55
  "zod": "^4.4.0"
@@ -2,12 +2,15 @@
2
2
  // SPDX-License-Identifier: MIT
3
3
 
4
4
  import { boundParameterBudget, MAX_BOUND_PARAMETERS } from "@pithy-sh/core/src/data/boundParameters";
5
+ import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
5
6
  import { decodeCursor, pageLimit, toPage } from "@pithy-sh/core/src/data/cursor";
7
+ import type { DatabaseSchema } from "@pithy-sh/core/src/data/db";
6
8
  import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
7
- import { type SqlBool, sql } from "kysely";
9
+ import { type Expression, type ExpressionBuilder, type SqlBool, sql } from "kysely";
8
10
  import { Session, User } from "../data/betterAuth";
9
11
  import { Device, type DevicePlatform } from "../data/device";
10
- import type { AuthDatabase } from "../data/tables";
12
+ import type { AuthDatabase, AuthTables } from "../data/tables";
13
+ import type { AccountStanding } from "../lifecycle/state";
11
14
 
12
15
  /**
13
16
  * The reads a management dashboard's user panes resolve to, and the lookups its revocations need.
@@ -89,12 +92,41 @@ function likePattern(term: string): string {
89
92
  export interface ListUsersOptions {
90
93
  /** Free text matched against email and display name. Absent lists everyone, newest first. */
91
94
  search?: string;
95
+ /** Where the account stands, judged at `now` exactly as `accountStanding` judges it. */
96
+ state?: AccountStanding["state"];
97
+ /** Whether the address is verified. */
98
+ verified?: boolean;
99
+ /** Created at or after this instant. Inclusive. */
100
+ since?: Date;
101
+ /** Created before this instant. Exclusive. */
102
+ until?: Date;
103
+ /** The instant `state` is judged at. Defaults to the moment of the read. */
104
+ now?: Date;
92
105
  /** The previous page's `nextCursor`. A malformed one is a first page, never an error. */
93
106
  cursor?: string;
94
107
  /** How many rows to return, clamped into `[1, MAX_PAGE_SIZE]` by `pageLimit`. */
95
108
  limit?: number;
96
109
  }
97
110
 
111
+ /**
112
+ * The rows `accountStanding` reads as `state` at `now`, as one predicate: deleted outranks suspended, and a
113
+ * suspension ends at the instant its `suspendedUntil` names.
114
+ */
115
+ export function standingPredicate(
116
+ state: AccountStanding["state"],
117
+ now: Date,
118
+ ): (eb: ExpressionBuilder<DatabaseSchema<AuthTables>, "pithyAuthUsers">) => Expression<SqlBool> {
119
+ const at = SQLiteDate.encode(now);
120
+ return (eb) => {
121
+ if (state === "deleted") return eb("deletedAt", "is not", null);
122
+ const inForce = eb.and([
123
+ eb("suspendedAt", "is not", null),
124
+ eb.or([eb("suspendedUntil", "is", null), eb("suspendedUntil", ">", at)]),
125
+ ]);
126
+ return eb.and([eb("deletedAt", "is", null), state === "suspended" ? inForce : eb.not(inForce)]);
127
+ };
128
+ }
129
+
98
130
  /**
99
131
  * Users, newest first, optionally filtered by a free-text term over email and display name.
100
132
  *
@@ -123,6 +155,12 @@ export async function listUsers(db: AuthDatabase, options: ListUsersOptions = {}
123
155
  query = query.where(sql<SqlBool>`(email like ${pattern} escape '\\' or name like ${pattern} escape '\\')`);
124
156
  }
125
157
 
158
+ if (options.state !== undefined) query = query.where(standingPredicate(options.state, options.now ?? new Date()));
159
+ if (options.verified !== undefined) query = query.where("emailVerified", "=", SQLiteBoolean.encode(options.verified));
160
+ // ISO-8601 text on both sides, as the cursor below compares it.
161
+ if (options.since !== undefined) query = query.where("createdAt", ">=", options.since.toISOString());
162
+ if (options.until !== undefined) query = query.where("createdAt", "<", options.until.toISOString());
163
+
126
164
  const cursor = decodeCursor(options.cursor);
127
165
  if (cursor) {
128
166
  // ISO-8601 text, because that is what the Better-Auth adapter wrote. Descending lexicographic order
@@ -354,7 +354,8 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
354
354
  app.get(
355
355
  `${base}/admin/users`,
356
356
  describeRoute({
357
- summary: "Page through the users, newest first, optionally searching by email or name.",
357
+ summary:
358
+ "Page through the users, newest first, optionally searching by email or name and narrowing by standing, verification or signup window.",
358
359
  verification: "control-plane",
359
360
  scopes: [AUTH_USERS_READ_SCOPE],
360
361
  responses: { 200: AdminUsersResponse },
@@ -364,7 +365,9 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
364
365
  async (c) => {
365
366
  const query = c.req.valid("query");
366
367
  const caller = controlPlaneCaller(c);
367
- const page = await listUsers(db(c, wiring), query);
368
+ // One instant for the page, so the filter and every user on it are judged at the same moment.
369
+ const now = new Date();
370
+ const page = await listUsers(db(c, wiring), { ...query, now });
368
371
  await emitControlPlaneAction(c.var.emit, {
369
372
  action: AuthAuditActions.adminUsersListed,
370
373
  subject: caller.subject,
@@ -376,10 +379,17 @@ export function registerAuthAdminRoutes(wiring: AuthWiring): (app: Hono<PithyHon
376
379
  // recording the term would copy the personal data the caller already saw into a second store
377
380
  // with a different retention policy. That it was a search, and how much came back, is what
378
381
  // makes an exfiltration pattern visible; the string itself adds nothing to that.
379
- metadata: { searched: query.search !== undefined, returned: page.items.length },
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
+ },
380
392
  });
381
- // One instant for the page, so every user on it is judged at the same moment.
382
- const now = new Date();
383
393
  return c.json({
384
394
  users: page.items.map((user) => userView(user, now)),
385
395
  nextCursor: page.nextCursor,
@@ -128,6 +128,9 @@ const PageCursorParam = z
128
128
  .optional()
129
129
  .describe("Where to resume, from the previous page's `nextCursor`. Opaque; a malformed one is a first page.");
130
130
 
131
+ /** A signup-window bound, as ISO-8601, decoded to a `Date` by the schema so the handler takes a typed value. */
132
+ const SignupBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
133
+
131
134
  /** The user listing query. */
132
135
  export const ListUsersQuery = z
133
136
  .object({
@@ -139,10 +142,29 @@ export const ListUsersQuery = z
139
142
  .describe(
140
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.",
141
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
+ ),
151
+ verified: z
152
+ .enum(["true", "false"])
153
+ .describe("`true` or `false`.")
154
+ .transform((value) => value === "true")
155
+ .optional()
156
+ .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."),
142
159
  cursor: PageCursorParam,
143
160
  limit: PageLimit,
144
161
  })
145
- .describe("The user listing query: what to search for, how many to return, and where to resume.");
162
+ .refine((query) => query.since === undefined || query.until === undefined || query.since < query.until, {
163
+ message: "`since` must be before `until`. A window that ends before it starts holds nothing.",
164
+ })
165
+ .describe(
166
+ "The user listing query: what to search for, which standing, verification and signup window to narrow to, how many to return, and where to resume.",
167
+ );
146
168
  export type ListUsersQuery = z.output<typeof ListUsersQuery>;
147
169
 
148
170
  /** The device-registry listing query. */
@@ -165,7 +187,7 @@ export type ListDevicesQuery = z.output<typeof ListDevicesQuery>;
165
187
  const WindowBound = z.iso.datetime({ offset: true }).transform((value) => new Date(value));
166
188
 
167
189
  /**
168
- * The verification ledger read's query (#829): a window of issue times, what to narrow it to, and where to resume.
190
+ * The verification ledger read's query: a window of issue times, what to narrow it to, and where to resume.
169
191
  * Both bounds are optional — the last 30 days, ending now — and a window that ends before it starts is refused by
170
192
  * the handler, which is where the default is known.
171
193
  */
@@ -205,7 +227,7 @@ export const RevokeSessionBody = z
205
227
  export type RevokeSessionBody = z.output<typeof RevokeSessionBody>;
206
228
 
207
229
  /**
208
- * Why an account's access is changing — required on both lifecycle routes (#621).
230
+ * Why an account's access is changing — required on both lifecycle routes.
209
231
  *
210
232
  * Trimmed, then bounded by the same constant the transition enforces, so a reason the transition would refuse
211
233
  * is a 400 here rather than a conflict later. Required rather than defaulted: a suspension nobody explained is
@@ -249,7 +271,7 @@ export const ReinstateUserBody = z
249
271
  export type ReinstateUserBody = z.output<typeof ReinstateUserBody>;
250
272
 
251
273
  /**
252
- * How a deletion runs (#622). `soft` is the default and the only thing an omission reaches: the account is shut
274
+ * How a deletion runs. `soft` is the default and the only thing an omission reaches: the account is shut
253
275
  * now and erased once the window closes, restorable until then. `hard` starts the purge at once, with no
254
276
  * window, and is reached only by naming it — a typo is a 400, never either mode.
255
277
  */
@@ -297,7 +319,7 @@ export const ExportUserQuery = z
297
319
  export type ExportUserQuery = z.output<typeof ExportUserQuery>;
298
320
 
299
321
  /**
300
- * The body of `DELETE /account`, the signed-in person deleting their own account (#622).
322
+ * The body of `DELETE /account`, the signed-in person deleting their own account.
301
323
  *
302
324
  * The confirmation is the literal `true`, so a client must say it on purpose: a stray `DELETE` with an empty
303
325
  * body, or a form posting `"false"`, deletes nothing. There is no field naming an account — the subject is the
@@ -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.1";
16
+ export const PACKAGE_VERSION = "0.13.0";