@pithy-sh/auth 0.6.0 → 0.6.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.
@@ -11,8 +11,16 @@
11
11
  * every identifier in the emitted DDL (CLAUDE.md §Data layer) — and the same plugin lets Better
12
12
  * Auth's camelCase queries land on these snake_case columns. Better-Auth `date` columns are **text**
13
13
  * (it stores ISO-8601 strings on SQLite; ISO sorts chronologically); Pithy's own device timestamps
14
- * are **integer** ms-epoch. Foreign keys are omitted to match the repo convention (D1 does not enforce
15
- * them without a per-connection PRAGMA); linkage is by indexed id columns.
14
+ * are **integer** ms-epoch. Linkage is by indexed id columns.
15
+ *
16
+ * **No foreign keys across a capability boundary — a choice, not a limitation.** D1 *does* enforce
17
+ * them: `PRAGMA foreign_keys` is on, a cascade fires, and an orphan insert is refused with
18
+ * `FOREIGN KEY constraint failed`. `packages/core/src/data/foreignKeys.workers.test.ts` measures both
19
+ * directions, because this is the kind of claim that rots quietly. What is traded away is real, and the
20
+ * reason is the boundary rather than the platform: a constraint from one capability's table to another's
21
+ * binds two release cadences together and breaks the day either moves to its own database. Within a
22
+ * single capability's own tables a foreign key is available and is simply not used here — worth
23
+ * revisiting per table rather than as a rule.
16
24
  *
17
25
  * `down` is the tested inverse — indexes then tables, in reverse creation order (D1 has no
18
26
  * transactional DDL, so order matters).
@@ -0,0 +1,152 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { z } from "zod";
4
+ /**
5
+ * A person's own display name and face — the two things about themselves they may change.
6
+ *
7
+ * ## Why the column takes two shapes
8
+ *
9
+ * `pithy_auth_users.image` has always held **a link**: a URL on whichever provider signed somebody in,
10
+ * written once and never again. Two things follow, and both are things every adopter hits.
11
+ *
12
+ * **A linked avatar is a third-party fetch per face.** A roster of twenty people is twenty requests to
13
+ * hosts the viewer did not choose, leaking their IP and referrer before they had done anything, and it
14
+ * needs a CSP hole to render at all.
15
+ *
16
+ * **And nothing in the kit could change it.** Somebody who signed in with GitHub was called whatever
17
+ * GitHub calls them, forever.
18
+ *
19
+ * So the column keeps accepting the provider URL it already holds — an existing row is untouched — and
20
+ * gains a second accepted shape: bytes, stored as a bounded `data:` URL under the kit's one image rule
21
+ * (`@pithy-sh/core/src/image/storedImage`). Where the column is settable by its subject, the host is
22
+ * chosen by them.
23
+ *
24
+ * ## Why the rule is core's and not this package's
25
+ *
26
+ * `@pithy-sh/organization` holds an account's mark under the identical rule. It is the same object at a
27
+ * different scale, and two answers to *what may be stored as an image* is one of them being wrong.
28
+ *
29
+ * ## Why this is `auth` and not `organization`
30
+ *
31
+ * Somebody in two accounts is the same person in both, and being asked to upload the same photograph
32
+ * twice would be a product mistaking a membership for an identity. A single-tenant app — a consumer app
33
+ * with no organizations at all — wants a display name and a face just as much, and should not have to
34
+ * compose a tenancy capability to get one.
35
+ *
36
+ * ## What this package does *not* decide: who may see whose face
37
+ *
38
+ * Serving a raster by URL needs an answer to *is this caller entitled to see this person*, and this
39
+ * capability has no such notion — everyone signed in is a peer. So the route here serves exactly one
40
+ * image: **the caller's own**, at a path carrying no id at all, which cannot be an enumeration oracle
41
+ * because there is nothing in it to enumerate. A roster of other people's faces is a tenancy question,
42
+ * and `@pithy-sh/organization` answers it with membership, through the same core helpers.
43
+ */
44
+ /**
45
+ * The ceiling on a display name, in characters — applied on the **write** and not on the read.
46
+ *
47
+ * Deliberately asymmetric, and the reason is the one `data/kitFields.ts` already records: a bound on
48
+ * the *column* schema turns a row a provider wrote before the bound existed into a row that throws on
49
+ * every later read, and an admin listing reading a page of rows would then fail for every operator
50
+ * rather than only for the author. A bound on the write is a 400 to the one caller who exceeded it.
51
+ *
52
+ * 256, which is longer than any name and short enough that a roster cannot be made expensive with it.
53
+ */
54
+ export declare const MAX_DISPLAY_NAME_CHARS = 256;
55
+ /** A display name somebody may set for themselves. Trimmed by the caller; bounded here. */
56
+ export declare const DisplayName: z.ZodString;
57
+ /**
58
+ * A picture linked on a provider's host — the shape the column has always held.
59
+ *
60
+ * Accepted rather than blessed: it is what Google, GitHub and Apple write at sign-in, and refusing it
61
+ * would break every existing row. **Bounded and scheme-pinned**, because the only two things that can
62
+ * be checked about somebody else's URL are how long it is and that it is not a `javascript:` or `data:`
63
+ * payload wearing a URL's clothes.
64
+ */
65
+ export declare const ProviderImageUrl: z.ZodURL;
66
+ /**
67
+ * What `pithy_auth_users.image` may hold: a provider's link, or bytes this application stores.
68
+ *
69
+ * The union is ordered link-first only for readability; the two shapes cannot both match, because a
70
+ * `data:` URL is not `http(s):` and a stored image is pinned to an allowlisted media type inline in the
71
+ * string. `data:text/html` matches neither, which is the whole of what makes this column safe to render.
72
+ */
73
+ export declare const UserImage: z.ZodUnion<readonly [z.ZodURL, z.ZodString]>;
74
+ export type UserImage = z.output<typeof UserImage>;
75
+ /** The path a signed-in caller's own stored raster is served from, relative to the auth base path. */
76
+ export declare const PROFILE_IMAGE_PATH = "/profile/image";
77
+ /**
78
+ * What a screen should draw this person's face from.
79
+ *
80
+ * Three answers, and a caller renders every one of them through the same `<img src>`:
81
+ *
82
+ * - **A provider link passes through.** It is already a URL and already cached by somebody else; there
83
+ * is nothing this origin can add to it.
84
+ * - **A stored raster becomes a versioned URL on this origin**, so a browser caches it and a roster
85
+ * costs one request per face once rather than its bytes on every read.
86
+ * - **A stored vector stays inline**, and the serving route refuses to serve one. An `<img src>` is
87
+ * inert by specification; a URL is navigable, and a navigated SVG runs script in the origin that
88
+ * served it. The class of attack is removed rather than managed with headers.
89
+ *
90
+ * `path` is where the owning capability serves bytes from — `basePath + PROFILE_IMAGE_PATH` here, and a
91
+ * membership-scoped path in `@pithy-sh/organization`.
92
+ */
93
+ export declare function userImageSource(image: string | null, path: string, version: Date | number): string | null;
94
+ /**
95
+ * Whether this value is drawn inline rather than fetched.
96
+ *
97
+ * Exported for the projection tests and for a caller deciding whether a listing response is carrying
98
+ * bytes — which is what `@pithy-sh/organization`'s roster budget counts.
99
+ */
100
+ export declare function isInlineImage(image: string | null): boolean;
101
+ /** A profile field a write supplied, and why it was refused. */
102
+ export interface ProfileRefusal {
103
+ /** Which field failed — `name` or `image`. Named so a caller's message can say which. */
104
+ readonly field: "name" | "image";
105
+ /** Client-safe text. Says what is wrong without echoing the value back. */
106
+ readonly message: string;
107
+ }
108
+ /**
109
+ * Check the profile fields of a write, or say which one is refused and why.
110
+ *
111
+ * **This is the gate, and it sits at the database hook rather than at a route, deliberately.** Better
112
+ * Auth's own `/update-user` endpoint pulls `name` and `image` out of the body and passes them straight
113
+ * to the adapter — `parseUserInput` runs `validator.input` over the *additional* fields only, so the
114
+ * mechanism `KIT_USER_FIELDS` relies on for `locale` does not reach these two at all. A validator
115
+ * declared next to the column would therefore have been a validator nothing ran.
116
+ *
117
+ * A `databaseHooks.user` hook does reach it, and reaches every other producer with it: `/update-user`,
118
+ * a social sign-in writing a provider's avatar, an admin route, and whatever the adopter composes next.
119
+ * One rule, at the thing being called rather than at each call site.
120
+ *
121
+ * Absent fields pass: a write that does not mention a field is not a write to it.
122
+ */
123
+ export declare function refuseUnsafeProfile(fields: {
124
+ name?: unknown;
125
+ image?: unknown;
126
+ }): ProfileRefusal | null;
127
+ /** What a sign-in's profile fields become after the kit has made them safe to store. */
128
+ export interface SanitizedProfile {
129
+ /** The name, truncated to the bound. Absent when the write did not mention one. */
130
+ readonly name?: string;
131
+ /** The picture, or null when the provider offered one this kit will not hold. */
132
+ readonly image?: string | null;
133
+ }
134
+ /**
135
+ * Make a **provider's** profile fields storable, rather than refusing them.
136
+ *
137
+ * The asymmetry with {@link refuseUnsafeProfile} is the point, and it is about whose act it is.
138
+ *
139
+ * A person setting their own name and picture is one caller doing one thing: a 400 tells them what to
140
+ * send, and they send it. A provider's profile arrives in the middle of somebody signing in, and they
141
+ * did not choose it — refusing there would mean **a person cannot sign in because Google gave them a
142
+ * long display name.** So an over-long name is truncated and an avatar this kit will not hold becomes
143
+ * no avatar, which draws initials, which is a real answer.
144
+ *
145
+ * Nothing unsafe reaches the column either way. The two paths differ in what they do about it, not in
146
+ * what they accept.
147
+ */
148
+ export declare function sanitizeProfile(fields: {
149
+ name?: unknown;
150
+ image?: unknown;
151
+ }): SanitizedProfile;
152
+ //# sourceMappingURL=profile.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/profile/profile.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,2FAA2F;AAC3F,eAAO,MAAM,WAAW,aAMrB,CAAC;AAEJ;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,UAK1B,CAAC;AAEJ;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,8CAInB,CAAC;AACJ,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,SAAS,CAAC,CAAC;AAEnD,sGAAsG;AACtG,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAQzG;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAI3D;AAED,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,cAAc,GAAG,IAAI,CAgBtG;AAED,wFAAwF;AACxF,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,gBAAgB,CAuB7F"}
@@ -0,0 +1,157 @@
1
+ // SPDX-FileCopyrightText: 2026 Pithy
2
+ // SPDX-License-Identifier: MIT
3
+ import { z } from "zod";
4
+ import { INLINE_IMAGE_TYPES, StoredImage, storedImageSource, typeOfStoredImage } from "@pithy-sh/core/src/image/storedImage";
5
+ //#region src/profile/profile.ts
6
+ /**
7
+ * A person's own display name and face — the two things about themselves they may change.
8
+ *
9
+ * ## Why the column takes two shapes
10
+ *
11
+ * `pithy_auth_users.image` has always held **a link**: a URL on whichever provider signed somebody in,
12
+ * written once and never again. Two things follow, and both are things every adopter hits.
13
+ *
14
+ * **A linked avatar is a third-party fetch per face.** A roster of twenty people is twenty requests to
15
+ * hosts the viewer did not choose, leaking their IP and referrer before they had done anything, and it
16
+ * needs a CSP hole to render at all.
17
+ *
18
+ * **And nothing in the kit could change it.** Somebody who signed in with GitHub was called whatever
19
+ * GitHub calls them, forever.
20
+ *
21
+ * So the column keeps accepting the provider URL it already holds — an existing row is untouched — and
22
+ * gains a second accepted shape: bytes, stored as a bounded `data:` URL under the kit's one image rule
23
+ * (`@pithy-sh/core/src/image/storedImage`). Where the column is settable by its subject, the host is
24
+ * chosen by them.
25
+ *
26
+ * ## Why the rule is core's and not this package's
27
+ *
28
+ * `@pithy-sh/organization` holds an account's mark under the identical rule. It is the same object at a
29
+ * different scale, and two answers to *what may be stored as an image* is one of them being wrong.
30
+ *
31
+ * ## Why this is `auth` and not `organization`
32
+ *
33
+ * Somebody in two accounts is the same person in both, and being asked to upload the same photograph
34
+ * twice would be a product mistaking a membership for an identity. A single-tenant app — a consumer app
35
+ * with no organizations at all — wants a display name and a face just as much, and should not have to
36
+ * compose a tenancy capability to get one.
37
+ *
38
+ * ## What this package does *not* decide: who may see whose face
39
+ *
40
+ * Serving a raster by URL needs an answer to *is this caller entitled to see this person*, and this
41
+ * capability has no such notion — everyone signed in is a peer. So the route here serves exactly one
42
+ * image: **the caller's own**, at a path carrying no id at all, which cannot be an enumeration oracle
43
+ * because there is nothing in it to enumerate. A roster of other people's faces is a tenancy question,
44
+ * and `@pithy-sh/organization` answers it with membership, through the same core helpers.
45
+ */
46
+ /**
47
+ * The ceiling on a display name, in characters — applied on the **write** and not on the read.
48
+ *
49
+ * Deliberately asymmetric, and the reason is the one `data/kitFields.ts` already records: a bound on
50
+ * the *column* schema turns a row a provider wrote before the bound existed into a row that throws on
51
+ * every later read, and an admin listing reading a page of rows would then fail for every operator
52
+ * rather than only for the author. A bound on the write is a 400 to the one caller who exceeded it.
53
+ *
54
+ * 256, which is longer than any name and short enough that a roster cannot be made expensive with it.
55
+ */
56
+ const MAX_DISPLAY_NAME_CHARS = 256;
57
+ /** A display name somebody may set for themselves. Trimmed by the caller; bounded here. */
58
+ const DisplayName = z.string().min(1).max(256).describe("What this application calls somebody, as they typed it. Bounded on the write rather than on the column, so a longer name a provider wrote before the bound existed still reads.");
59
+ /**
60
+ * A picture linked on a provider's host — the shape the column has always held.
61
+ *
62
+ * Accepted rather than blessed: it is what Google, GitHub and Apple write at sign-in, and refusing it
63
+ * would break every existing row. **Bounded and scheme-pinned**, because the only two things that can
64
+ * be checked about somebody else's URL are how long it is and that it is not a `javascript:` or `data:`
65
+ * payload wearing a URL's clothes.
66
+ */
67
+ const ProviderImageUrl = z.url({ protocol: /^https?$/ }).max(2048).describe("An avatar on the provider's own host, written at sign-in. A third-party fetch per face — see the module note for why a stored image is preferred.");
68
+ /**
69
+ * What `pithy_auth_users.image` may hold: a provider's link, or bytes this application stores.
70
+ *
71
+ * The union is ordered link-first only for readability; the two shapes cannot both match, because a
72
+ * `data:` URL is not `http(s):` and a stored image is pinned to an allowlisted media type inline in the
73
+ * string. `data:text/html` matches neither, which is the whole of what makes this column safe to render.
74
+ */
75
+ const UserImage = z.union([ProviderImageUrl, StoredImage]).describe("A person's picture: either a provider URL, as the column has always held, or bytes stored under the kit's image rule. Rendered only through `<img>`.");
76
+ /** The path a signed-in caller's own stored raster is served from, relative to the auth base path. */
77
+ const PROFILE_IMAGE_PATH = "/profile/image";
78
+ /**
79
+ * What a screen should draw this person's face from.
80
+ *
81
+ * Three answers, and a caller renders every one of them through the same `<img src>`:
82
+ *
83
+ * - **A provider link passes through.** It is already a URL and already cached by somebody else; there
84
+ * is nothing this origin can add to it.
85
+ * - **A stored raster becomes a versioned URL on this origin**, so a browser caches it and a roster
86
+ * costs one request per face once rather than its bytes on every read.
87
+ * - **A stored vector stays inline**, and the serving route refuses to serve one. An `<img src>` is
88
+ * inert by specification; a URL is navigable, and a navigated SVG runs script in the origin that
89
+ * served it. The class of attack is removed rather than managed with headers.
90
+ *
91
+ * `path` is where the owning capability serves bytes from — `basePath + PROFILE_IMAGE_PATH` here, and a
92
+ * membership-scoped path in `@pithy-sh/organization`.
93
+ */
94
+ function userImageSource(image, path, version) {
95
+ if (image === null) return null;
96
+ if (typeOfStoredImage(image) === null) return ProviderImageUrl.safeParse(image).success ? image : null;
97
+ return storedImageSource(image, path, version);
98
+ }
99
+ /**
100
+ * Whether this value is drawn inline rather than fetched.
101
+ *
102
+ * Exported for the projection tests and for a caller deciding whether a listing response is carrying
103
+ * bytes — which is what `@pithy-sh/organization`'s roster budget counts.
104
+ */
105
+ function isInlineImage(image) {
106
+ if (image === null) return false;
107
+ const type = typeOfStoredImage(image);
108
+ return type !== null && INLINE_IMAGE_TYPES.includes(type);
109
+ }
110
+ /**
111
+ * Check the profile fields of a write, or say which one is refused and why.
112
+ *
113
+ * **This is the gate, and it sits at the database hook rather than at a route, deliberately.** Better
114
+ * Auth's own `/update-user` endpoint pulls `name` and `image` out of the body and passes them straight
115
+ * to the adapter — `parseUserInput` runs `validator.input` over the *additional* fields only, so the
116
+ * mechanism `KIT_USER_FIELDS` relies on for `locale` does not reach these two at all. A validator
117
+ * declared next to the column would therefore have been a validator nothing ran.
118
+ *
119
+ * A `databaseHooks.user` hook does reach it, and reaches every other producer with it: `/update-user`,
120
+ * a social sign-in writing a provider's avatar, an admin route, and whatever the adopter composes next.
121
+ * One rule, at the thing being called rather than at each call site.
122
+ *
123
+ * Absent fields pass: a write that does not mention a field is not a write to it.
124
+ */
125
+ function refuseUnsafeProfile(fields) {
126
+ if (fields.name !== void 0 && fields.name !== null && !DisplayName.safeParse(fields.name).success) return {
127
+ field: "name",
128
+ message: `A name is between 1 and 256 characters.`
129
+ };
130
+ if (fields.image !== void 0 && fields.image !== null && !UserImage.safeParse(fields.image).success) return {
131
+ field: "image",
132
+ message: "A picture must be an https URL or an image this application stores, within the size limit."
133
+ };
134
+ return null;
135
+ }
136
+ /**
137
+ * Make a **provider's** profile fields storable, rather than refusing them.
138
+ *
139
+ * The asymmetry with {@link refuseUnsafeProfile} is the point, and it is about whose act it is.
140
+ *
141
+ * A person setting their own name and picture is one caller doing one thing: a 400 tells them what to
142
+ * send, and they send it. A provider's profile arrives in the middle of somebody signing in, and they
143
+ * did not choose it — refusing there would mean **a person cannot sign in because Google gave them a
144
+ * long display name.** So an over-long name is truncated and an avatar this kit will not hold becomes
145
+ * no avatar, which draws initials, which is a real answer.
146
+ *
147
+ * Nothing unsafe reaches the column either way. The two paths differ in what they do about it, not in
148
+ * what they accept.
149
+ */
150
+ function sanitizeProfile(fields) {
151
+ const sanitized = {};
152
+ if (fields.name !== void 0 && !DisplayName.safeParse(fields.name).success) sanitized.name = typeof fields.name === "string" ? fields.name.slice(0, 256) || "—" : "—";
153
+ if (fields.image !== void 0 && fields.image !== null && !UserImage.safeParse(fields.image).success) sanitized.image = null;
154
+ return sanitized;
155
+ }
156
+ //#endregion
157
+ export { DisplayName, MAX_DISPLAY_NAME_CHARS, PROFILE_IMAGE_PATH, ProviderImageUrl, UserImage, isInlineImage, refuseUnsafeProfile, sanitizeProfile, userImageSource };
@@ -3,7 +3,6 @@
3
3
  import { DevLogin } from "@pithy-sh/core/src/seed/devLogin";
4
4
  import { type SeedSet } from "@pithy-sh/core/src/seed/seed";
5
5
  import { z } from "zod";
6
- import { Session } from "../data/betterAuth";
7
6
  /**
8
7
  * The dev-login seed set: a real, signed-in session for one seeded user, so local development does not
9
8
  * begin with a magic-link round trip.
@@ -50,15 +49,6 @@ export declare const AUTH_DEV_SESSION_SEED_ORDER: number;
50
49
  * Still locked to the running Better Auth version by a test that reads the name off a live instance.
51
50
  */
52
51
  export declare const DEV_SESSION_COOKIE_NAME: string;
53
- /**
54
- * The prefix every seeded dev session's id and token carry.
55
- *
56
- * It is what makes a dev session **findable without being told**, which is what the dev-login route
57
- * needs: the route reads the session out of D1 and has no artifact to consult (a Worker has no
58
- * filesystem). And it is what makes one identifiable at all — a `pithy_auth_sessions` row minted by a
59
- * seed is otherwise indistinguishable from one a real sign-in created.
60
- */
61
- export declare const DEV_SESSION_TOKEN_PREFIX = "dev-session-";
62
52
  /** The developer's machine-local preferences for this project, read from `~/.config/pithy/<project>/dev.json`. */
63
53
  export declare const DevPreferences: z.ZodObject<{
64
54
  user: z.ZodString;
@@ -76,11 +66,9 @@ export declare const SeededUser: z.ZodObject<{
76
66
  email: z.ZodString;
77
67
  }, z.core.$strip>;
78
68
  export type SeededUser = z.output<typeof SeededUser>;
79
- /** What {@link mintDevSession} produces: the row to write, and the artifact the browser is handed. */
80
- export interface MintedDevSession {
81
- /** The `pithy_auth_sessions` row, in app shape — re-encoded and validated by the seed writer. */
82
- session: Session;
83
- /** The dev-login artifact, written to `logs/dev-login.json` once the row lands. */
69
+ /** What {@link mintDevLogin} produces. One field, because a dev login is no longer a row — `#572`. */
70
+ export interface MintedDevLogin {
71
+ /** The dev-login artifact, written to `logs/dev-login.json`. */
84
72
  login: DevLogin;
85
73
  }
86
74
  /**
@@ -93,31 +81,52 @@ export interface MintedDevSession {
93
81
  * a real instance accept the result, which is the only check that actually matters.
94
82
  */
95
83
  export declare function signCookieValue(value: string, secret: string): Promise<string>;
96
- /**
97
- * A short, stable fingerprint of the auth secret.
98
- *
99
- * Putting it in the session token makes the token deterministic across reseeds — the same cookie keeps
100
- * working in every worktree once each is seeded, which is the whole point — while rotating the secret
101
- * changes the token *and* invalidates every cookie signed with the old one, for free. A truncated digest,
102
- * never the secret: the token is written to a file and read back by tooling.
103
- */
104
- export declare function secretFingerprint(secret: string): Promise<string>;
105
- /** Inputs to {@link mintDevSession}. `now` is a seam so the determinism tests do not depend on the clock. */
106
- export interface MintDevSessionInput {
84
+ /** Inputs to {@link mintDevLogin}. `now` is a seam so the tests do not depend on the clock. */
85
+ export interface MintDevLoginInput {
107
86
  /** The seeded user to sign in as. */
108
87
  user: SeededUser;
109
88
  /** The Better Auth signing secret for this environment — never logged, never stored, never in an error. */
110
89
  secret: string;
111
- /** The moment the session is minted. Defaults to now. */
90
+ /** The moment the claim is minted. Defaults to now. */
112
91
  now?: Date;
113
92
  }
114
93
  /**
115
- * Mint one deterministic dev session: the `pithy_auth_sessions` row and the signed cookie for it.
94
+ * Sign a claim naming the user a dev login signs in as — `#572`.
95
+ *
96
+ * **The payload is base64 of JSON, not a delimited string.** A user id is an adopter's to choose and may
97
+ * hold any character at all, including whichever one a hand-rolled format picked as its separator. JSON
98
+ * inside base64 has no separator to collide with, and the whole of it is what the signature covers.
99
+ *
100
+ * The same HMAC-SHA-256 construction {@link signCookieValue} uses, deliberately not the same function:
101
+ * that one mirrors better-call's cookie format because Better Auth has to accept its output, and this is
102
+ * ours. Two consumers, two formats, no shared spelling to break one by fixing the other.
103
+ */
104
+ export declare function signDevLoginClaim(input: MintDevLoginInput & {
105
+ expiresAt: Date;
106
+ }): Promise<string>;
107
+ /**
108
+ * What a claim says, once it has been proved to say it.
109
+ *
110
+ * `null` for every failure and never a reason: a malformed claim, one signed by another secret, and one
111
+ * naming a user who has since gone are the same answer to whoever presented it, because distinguishing
112
+ * them is a probe. The route turns all three into the one 404 it already had.
113
+ */
114
+ export declare function verifyDevLoginClaim(claim: string, secret: string, now?: Date): Promise<{
115
+ userId: string;
116
+ expiresAt: Date;
117
+ } | null>;
118
+ /**
119
+ * Mint one dev login: the signed claim, and the artifact that carries it.
120
+ *
121
+ * **No `pithy_auth_sessions` row — `#572`.** This used to write one and hand it over on every open, which
122
+ * meant the product's own sign-out revoked the dev login along with the session, and the only way back was
123
+ * a reseed. It also meant a row in that table which was, by this module's own admission, indistinguishable
124
+ * from a real sign-in — so it showed up in every surface built over sessions as a device nobody used.
116
125
  *
117
- * The row id carries the fingerprint too, not just the token. Seed writes are `INSERT OR IGNORE`, so an
118
- * id that ignored a rotation would keep the stale token alive under a row the next run refuses to replace.
126
+ * What is minted here is a claim about *who*. The route exchanges it for a session at the moment somebody
127
+ * opens the link, so the session is real, is theirs, and is the only thing a sign-out takes away.
119
128
  */
120
- export declare function mintDevSession(input: MintDevSessionInput): Promise<MintedDevSession>;
129
+ export declare function mintDevLogin(input: MintDevLoginInput): Promise<MintedDevLogin>;
121
130
  /**
122
131
  * The dev-login seed set. Composed by the auth capability; runs only in `dev`, only for a user this same run
123
132
  * creates, and only when the developer has opted in with a `dev.json`.
@@ -1 +1 @@
1
- {"version":3,"file":"devSession.d.ts","sourceRoot":"","sources":["../../src/seeds/devSession.ts"],"names":[],"mappings":"AAMA,OAAO,EAAkC,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAC5F,OAAO,EAKL,KAAK,OAAO,EACb,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAM1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAEvE;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,iBAAiB,CAAC;AAQvD,kHAAkH;AAClH,eAAO,MAAM,cAAc;;iBAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;iBAKgF,CAAC;AACxG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAErD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWpF;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAKvE;AAED,6GAA6G;AAC7G,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,IAAI,EAAE,UAAU,CAAC;IACjB,2GAA2G;IAC3G,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA+B1F;AA6CD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,OA6B/B,CAAC"}
1
+ {"version":3,"file":"devSession.d.ts","sourceRoot":"","sources":["../../src/seeds/devSession.ts"],"names":[],"mappings":"AAMA,OAAO,EAAkC,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAC5F,OAAO,EAA6D,KAAK,OAAO,EAAE,MAAM,8BAA8B,CAAC;AACvH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,QAAiB,CAAC;AAM1D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,QAAkC,CAAC;AAUvE,kHAAkH;AAClH,eAAO,MAAM,cAAc;;iBAUxB,CAAC;AACJ,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,UAAU;;;iBAKgF,CAAC;AACxG,MAAM,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAErD,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,KAAK,EAAE,QAAQ,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAWpF;AAED,+FAA+F;AAC/F,MAAM,WAAW,iBAAiB;IAChC,qCAAqC;IACrC,IAAI,EAAE,UAAU,CAAC;IACjB,2GAA2G;IAC3G,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,iBAAiB,GAAG;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CASvG;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,GAAG,GAAE,IAAiB,GACrB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAAC,CAqBrD;AAkDD;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,cAAc,CAAC,CAWpF;AA6CD;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,OA+B/B,CAAC"}