@pithy-sh/auth 0.6.2 → 0.6.3

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.
Files changed (64) hide show
  1. package/README.md +15 -0
  2. package/dist/audit/actions.d.ts +78 -5
  3. package/dist/audit/actions.d.ts.map +1 -1
  4. package/dist/audit/actions.js +78 -5
  5. package/dist/audit/emit.d.ts +223 -2
  6. package/dist/audit/emit.d.ts.map +1 -1
  7. package/dist/audit/emit.js +251 -20
  8. package/dist/audit/evidence.d.ts +207 -0
  9. package/dist/audit/evidence.d.ts.map +1 -0
  10. package/dist/audit/evidence.js +162 -0
  11. package/dist/capability.d.ts.map +1 -1
  12. package/dist/capability.js +2 -1
  13. package/dist/client/api.d.ts +8 -0
  14. package/dist/client/api.d.ts.map +1 -1
  15. package/dist/client/api.js +8 -0
  16. package/dist/email/send.d.ts +10 -2
  17. package/dist/email/send.d.ts.map +1 -1
  18. package/dist/email/send.js +36 -14
  19. package/dist/http/errorCallbackUrl.d.ts +40 -0
  20. package/dist/http/errorCallbackUrl.d.ts.map +1 -0
  21. package/dist/http/errorCallbackUrl.js +395 -0
  22. package/dist/http/providerRefusal.d.ts +181 -0
  23. package/dist/http/providerRefusal.d.ts.map +1 -0
  24. package/dist/http/providerRefusal.js +363 -0
  25. package/dist/http/resolve.js +1 -0
  26. package/dist/http/routes.d.ts.map +1 -1
  27. package/dist/http/routes.js +12 -1
  28. package/dist/instance/auth.d.ts +132 -26
  29. package/dist/instance/auth.d.ts.map +1 -1
  30. package/dist/instance/auth.js +118 -13
  31. package/dist/instance/githubUserInfo.d.ts +13 -7
  32. package/dist/instance/githubUserInfo.d.ts.map +1 -1
  33. package/dist/instance/githubUserInfo.js +13 -7
  34. package/dist/instance/plugins.d.ts +41 -13
  35. package/dist/instance/plugins.d.ts.map +1 -1
  36. package/dist/instance/plugins.js +95 -18
  37. package/dist/instance/providerSignInGate.d.ts +130 -0
  38. package/dist/instance/providerSignInGate.d.ts.map +1 -0
  39. package/dist/instance/providerSignInGate.js +230 -0
  40. package/dist/instance/refusalTransport.d.ts +91 -0
  41. package/dist/instance/refusalTransport.d.ts.map +1 -0
  42. package/dist/instance/refusalTransport.js +32 -0
  43. package/dist/migrations/pluginTables.d.ts.map +1 -1
  44. package/dist/migrations/pluginTables.js +2 -1
  45. package/dist/version.generated.d.ts +1 -1
  46. package/dist/version.generated.js +1 -1
  47. package/package.json +5 -5
  48. package/src/audit/actions.ts +78 -5
  49. package/src/audit/emit.ts +340 -25
  50. package/src/audit/evidence.ts +297 -0
  51. package/src/capability.ts +11 -6
  52. package/src/client/api.ts +8 -0
  53. package/src/email/send.ts +51 -14
  54. package/src/http/errorCallbackUrl.ts +463 -0
  55. package/src/http/providerRefusal.ts +424 -0
  56. package/src/http/resolve.ts +3 -0
  57. package/src/http/routes.ts +38 -1
  58. package/src/instance/auth.ts +167 -19
  59. package/src/instance/githubUserInfo.ts +13 -7
  60. package/src/instance/plugins.ts +119 -18
  61. package/src/instance/providerSignInGate.ts +323 -0
  62. package/src/instance/refusalTransport.ts +119 -0
  63. package/src/migrations/pluginTables.ts +4 -1
  64. package/src/version.generated.ts +1 -1
@@ -1,6 +1,7 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
- import { emitAfterRequest, emitProviderUnavailable } from "../audit/emit.js";
3
+ import { emitAfterRequest, emitProviderAccountChanged, emitProviderUnavailable } from "../audit/emit.js";
4
+ import { claimedDelete, markSessionEnded, messageDeliveryDuring, sessionEndedDuring } from "../audit/evidence.js";
4
5
  import { KIT_SESSION_FIELDS, KIT_USER_FIELDS } from "../data/kitFields.js";
5
6
  import { parseDeviceMeta, registerDevice } from "../device/registry.js";
6
7
  import "../http/providerFreshness.js";
@@ -102,6 +103,29 @@ function refuseUnsafeProfileFields(user) {
102
103
  });
103
104
  }
104
105
  /**
106
+ * Who caused a row change, read from the endpoint context Better Auth hands a database hook.
107
+ *
108
+ * **The context is absent as often as it is present, and that absence is information.** A hook reached
109
+ * from `/unlink-account` gets the full endpoint context with the caller's session on it; one reached
110
+ * from a script, a queue consumer or a migration calling `internalAdapter` outside any dispatch gets
111
+ * `null`. So `fromRequest` distinguishes *nobody was calling* from *a caller with no session*, which is
112
+ * the difference between `system` and `anonymous` in the row — and it is what stops a cascade from being
113
+ * written as the account owner's own action, which is what #627's first cut did.
114
+ *
115
+ * **It is not, and must not be read as, "the cascade is `system`".** `getWithHooks` resolves its context
116
+ * from `getCurrentAuthContext()`, which is async-scoped to the dispatch, so a cascade reached through an
117
+ * endpoint arrives here with that endpoint's session and headers — and the operator who drove it is
118
+ * named as the actor of every row it writes, correctly. What this function reads is who was calling, and
119
+ * a cascade is not a special kind of caller.
120
+ */
121
+ function callerOf(ctx) {
122
+ return {
123
+ callerId: ctx?.context?.session?.user?.id ?? null,
124
+ fromRequest: Boolean(ctx),
125
+ headers: ctx?.headers
126
+ };
127
+ }
128
+ /**
105
129
  * Build the Better-Auth instance for one request.
106
130
  *
107
131
  * Passwordless only — `emailAndPassword` is never enabled. The Kysely adapter wraps our shared
@@ -141,6 +165,53 @@ function makeAuth(deps) {
141
165
  refuseUnsafeProfileFields(user);
142
166
  } }
143
167
  },
168
+ account: {
169
+ /**
170
+ * **The provider-link trail, recorded where the account table changes.**
171
+ *
172
+ * An account row is what lets a provider sign in as somebody, so its creation and its removal
173
+ * are the two account-security events — and the row is the only place both are visible. Better
174
+ * Auth reaches it from several directions: `/callback/:id` on a first social sign-up and on a
175
+ * link, `linkAccount` from the OAuth linking path, `/unlink-account`, and the cascade that drops
176
+ * every account when a user is deleted. All of them go through `createWithHooks` /
177
+ * `deleteWithHooks` on the `account` model (`better-auth/dist/db/internal-adapter.mjs`), so one
178
+ * pair of hooks covers what four endpoint wirings would have had to enumerate and keep current.
179
+ *
180
+ * **This is the seam `session.delete.after` below already argues for**, applied to the other
181
+ * table: a handler wired to one endpoint misses the others, and the row is what the fact is
182
+ * keyed by. #627 is what that costs — `/link-social` was wired, so a link recorded the request
183
+ * rather than the result, and an unlink recorded nothing.
184
+ *
185
+ * **After, not before, in both directions.** The write has happened by the time these run, so a
186
+ * slow or failing audit seam can neither hold up nor refuse a link or an unlink — and
187
+ * `emitProviderAccountChanged` swallows its own failure for the same reason.
188
+ */
189
+ create: { after: async (account, ctx) => {
190
+ await emitProviderAccountChanged(deps.emit, {
191
+ change: "link",
192
+ account,
193
+ ...callerOf(ctx)
194
+ });
195
+ } },
196
+ /**
197
+ * **Through `claimedDelete`, because `delete.after` fires on the row that was read.** Two
198
+ * concurrent unlinks of one account both reach `after` and the trail double-counts one removal.
199
+ * The pair below issues the delete in `before` and runs this body only for the caller whose
200
+ * statement removed the row — see `../audit/evidence.ts` for the primitive, its two
201
+ * preconditions, and why every `delete.after` here goes through it rather than two of them.
202
+ */
203
+ delete: claimedDelete({
204
+ db: deps.db,
205
+ table: "pithyAuthAccounts",
206
+ after: async (account, ctx) => {
207
+ await emitProviderAccountChanged(deps.emit, {
208
+ change: "unlink",
209
+ account,
210
+ ...callerOf(ctx)
211
+ });
212
+ }
213
+ })
214
+ },
144
215
  session: {
145
216
  create: {
146
217
  /**
@@ -183,9 +254,8 @@ before: async (session, ctx) => {
183
254
  authenticatedAt
184
255
  } };
185
256
  } },
186
- delete: {
187
257
  /**
188
- * Tell whoever keyed state on this session that it has gone.
258
+ * Tell whoever keyed state on this session that it has gone, and record that it did.
189
259
  *
190
260
  * A sign-out, a revoke, an admin ending somebody's devices — all of them land here, which is
191
261
  * why the seam is on the row rather than on the sign-out endpoint. A handler wired to one
@@ -194,16 +264,28 @@ before: async (session, ctx) => {
194
264
  * **After, not before.** The session is already gone when this runs, so a slow or failing
195
265
  * listener cannot hold up or refuse a sign-out — and it swallows its own failure for the same
196
266
  * reason the audit emit does: the thing it reports has already happened.
267
+ *
268
+ * **Through `claimedDelete`, and that is the second half of #627's last hole.** `/sign-out`
269
+ * reaches `internalAdapter.deleteSession(token)`, so concurrent sign-outs on one cookie all find
270
+ * the row, all issue a delete, exactly one removes anything — and all of them reached this body.
271
+ * `markSessionEnded` ran for each, and `emitAfterRequest` wrote `auth/signout outcome=success`
272
+ * for callers that signed nobody out. The same primitive the account hooks use covers it,
273
+ * because the defect is `deleteWithHooks`'s rather than either table's.
197
274
  */
198
- after: async (session) => {
199
- if (!deps.onSessionRevoked) return;
200
- try {
201
- await deps.onSessionRevoked({
202
- id: String(session.id),
203
- userId: String(session.userId)
204
- });
205
- } catch {}
206
- } }
275
+ delete: claimedDelete({
276
+ db: deps.db,
277
+ table: "pithyAuthSessions",
278
+ after: async (session, ctx) => {
279
+ markSessionEnded(ctx?.context, session.userId);
280
+ if (!deps.onSessionRevoked) return;
281
+ try {
282
+ await deps.onSessionRevoked({
283
+ id: String(session.id),
284
+ userId: String(session.userId)
285
+ });
286
+ } catch {}
287
+ }
288
+ })
207
289
  }
208
290
  },
209
291
  hooks: {
@@ -232,6 +314,26 @@ after: async (session) => {
232
314
  });
233
315
  throw providerUnavailable(provider);
234
316
  }),
317
+ /**
318
+ * Emit audit events for an auth request: sign-in (+device) from the new session, plus the
319
+ * send/sign-out/token event by path. Endpoint-scoped, so a rotation never emits.
320
+ *
321
+ * **`returned` is passed because this hook runs on refusals too.** Better Auth catches an
322
+ * endpoint's `APIError` into a result and dispatches the `after` hooks over it
323
+ * (`better-auth/dist/api/dispatch.mjs`), so a 401 `/token` reaches here looking exactly like one
324
+ * that minted a token — and wrote `auth/token_refresh outcome=success` for a request that was
325
+ * refused. `ctx.context.returned` is the only thing that tells them apart, and the judgment is
326
+ * `emitAfterRequest`'s so it is made once for every path rather than per wiring.
327
+ *
328
+ * **The two markers are passed because a refusal can answer 200.** `/sign-out` deletes nothing and
329
+ * says so cheerfully; `/email-otp/send-verification-otp` declines to send and answers
330
+ * `{"success":true}` on purpose, so a caller cannot tell a registered address from a stranger's.
331
+ * Neither decline is visible from anything this hook holds, so each audited path names what must
332
+ * have *happened* and `../audit/evidence.ts` carries it here from the place that saw it — the
333
+ * session row going away, and the email seam's own answer about the message, which is the send
334
+ * paths' evidence rather than the fact that a callback was entered. Reading them is all this does:
335
+ * the response has already been decided and is not touched.
336
+ */
235
337
  after: createAuthMiddleware(async (ctx) => {
236
338
  const newSession = ctx.context.newSession;
237
339
  await emitAfterRequest(deps.emit, {
@@ -242,7 +344,10 @@ after: async (session) => {
242
344
  sessionId: newSession.session.id,
243
345
  deviceId: newSession.session.deviceId ?? null
244
346
  } : null,
245
- currentUserId: ctx.context.session?.user?.id ?? null
347
+ currentUserId: ctx.context.session?.user?.id ?? null,
348
+ returned: ctx.context.returned,
349
+ endedSession: sessionEndedDuring(ctx.context),
350
+ messageDelivery: messageDeliveryDuring(ctx.context)
246
351
  });
247
352
  })
248
353
  },
@@ -30,13 +30,19 @@ import { z } from "zod";
30
30
  * read from GitHub.
31
31
  *
32
32
  * **Linking is Better Auth's branch, not this one, and that is worth knowing before editing here.**
33
- * `getUserInfo` runs at `callback.mjs:120`, upstream of the `if (link)` at `:150`, and it is handed only
34
- * the tokens — 1.7.1 exports no accessor that would let it read the OAuth state, so it genuinely cannot
35
- * tell a `/link-social` callback from a sign-in. It does not need to: what this module contributes to
36
- * that path is the boundary. The only address it ever returns is one GitHub reports `verified` for, so a
37
- * link licensed by an address GitHub never confirmed is not reachable from either flow. Linking also
38
- * cannot rewrite the user's own email — `applyUpdateUserInfoOnLink` returns early unless
39
- * `updateUserInfoOnLink` is set, and destructures `email` out even then.
33
+ * `getUserInfo` runs at `callback.mjs:120`, upstream of the `if (link)` at `:150`, and this resolver is
34
+ * handed only the tokens — it does not look at which flow it is on, and it does not need to: what this
35
+ * module contributes to that path is the boundary. The only address it ever returns is one GitHub
36
+ * reports `verified` for, so a link licensed by an address GitHub never confirmed is not reachable from
37
+ * either flow. Linking also cannot rewrite the user's own email — `applyUpdateUserInfoOnLink` returns
38
+ * early unless `updateUserInfoOnLink` is set, and destructures `email` out even then.
39
+ *
40
+ * **A previous version of this paragraph said 1.7.1 "exports no accessor that would let it read the
41
+ * OAuth state", and that was wrong.** `getOAuthState` is exported from `better-auth/api`
42
+ * (`api/index.mjs:216`) and `parseState` populates it at `callback.mjs:76`, before this runs — which is
43
+ * exactly what `./providerSignInGate` is built on. The correction is recorded rather than quietly
44
+ * deleted, because the false claim was load-bearing: it is the sentence that would have been cited to
45
+ * rule out the seam that closed #625.
40
46
  *
41
47
  * **Linking a provider whose address *differs* from the account's is not enabled here, and that is a
42
48
  * deliberate hold.** It needs `allowDifferentEmails: true`, which widens what a session alone can do —
@@ -1 +1 @@
1
- {"version":3,"file":"githubUserInfo.d.ts","sourceRoot":"","sources":["../../src/instance/githubUserInfo.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,gHAAgH;AAChH,eAAO,MAAM,WAAW;;;;iBAYiF,CAAC;AAC1G,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,2GAA2G;AAC3G,eAAO,MAAM,aAAa;;;;;iBAkBkF,CAAC;AAC7G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,aAAa,CAAC;IACvB,8FAA8F;IAC9F,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAM3F;AAED,6GAA6G;AAC7G,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,mBAAmB,GAAG,IAAI,CAG7F;AAED,+GAA+G;AAC/G,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE/E,8GAA8G;AAC9G,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,gHAAgH;AAChH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzG,IAAI,EAAE,aAAa,CAAC;CACrB;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;AAW/G,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,kBAAuB,GAAG,sBAAsB,CAyB3F"}
1
+ {"version":3,"file":"githubUserInfo.d.ts","sourceRoot":"","sources":["../../src/instance/githubUserInfo.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,gHAAgH;AAChH,eAAO,MAAM,WAAW;;;;iBAYiF,CAAC;AAC1G,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEtD,2GAA2G;AAC3G,eAAO,MAAM,aAAa;;;;;iBAkBkF,CAAC;AAC7G,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAE1D,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,OAAO,EAAE,aAAa,CAAC;IACvB,8FAA8F;IAC9F,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAM3F;AAED,6GAA6G;AAC7G,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,mBAAmB,GAAG,IAAI,CAG7F;AAED,+GAA+G;AAC/G,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAE/E,8GAA8G;AAC9G,MAAM,WAAW,kBAAkB;IACjC,gEAAgE;IAChE,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB;AAED,gHAAgH;AAChH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzG,IAAI,EAAE,aAAa,CAAC;CACrB;AAgBD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,KAAK,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;AAW/G,0GAA0G;AAC1G,wBAAgB,qBAAqB,CAAC,IAAI,GAAE,kBAAuB,GAAG,sBAAsB,CAyB3F"}
@@ -31,13 +31,19 @@ import { z } from "zod";
31
31
  * read from GitHub.
32
32
  *
33
33
  * **Linking is Better Auth's branch, not this one, and that is worth knowing before editing here.**
34
- * `getUserInfo` runs at `callback.mjs:120`, upstream of the `if (link)` at `:150`, and it is handed only
35
- * the tokens — 1.7.1 exports no accessor that would let it read the OAuth state, so it genuinely cannot
36
- * tell a `/link-social` callback from a sign-in. It does not need to: what this module contributes to
37
- * that path is the boundary. The only address it ever returns is one GitHub reports `verified` for, so a
38
- * link licensed by an address GitHub never confirmed is not reachable from either flow. Linking also
39
- * cannot rewrite the user's own email — `applyUpdateUserInfoOnLink` returns early unless
40
- * `updateUserInfoOnLink` is set, and destructures `email` out even then.
34
+ * `getUserInfo` runs at `callback.mjs:120`, upstream of the `if (link)` at `:150`, and this resolver is
35
+ * handed only the tokens — it does not look at which flow it is on, and it does not need to: what this
36
+ * module contributes to that path is the boundary. The only address it ever returns is one GitHub
37
+ * reports `verified` for, so a link licensed by an address GitHub never confirmed is not reachable from
38
+ * either flow. Linking also cannot rewrite the user's own email — `applyUpdateUserInfoOnLink` returns
39
+ * early unless `updateUserInfoOnLink` is set, and destructures `email` out even then.
40
+ *
41
+ * **A previous version of this paragraph said 1.7.1 "exports no accessor that would let it read the
42
+ * OAuth state", and that was wrong.** `getOAuthState` is exported from `better-auth/api`
43
+ * (`api/index.mjs:216`) and `parseState` populates it at `callback.mjs:76`, before this runs — which is
44
+ * exactly what `./providerSignInGate` is built on. The correction is recorded rather than quietly
45
+ * deleted, because the false claim was load-bearing: it is the sentence that would have been cited to
46
+ * rule out the seam that closed #625.
41
47
  *
42
48
  * **Linking a provider whose address *differs* from the account's is not enabled here, and that is a
43
49
  * deliberate hold.** It needs `allowDifferentEmails: true`, which widens what a session alone can do —
@@ -1,5 +1,6 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
+ import type { AuditEmit } from "@pithy-sh/core/src/audit/recorder";
3
4
  import type { BetterAuthPlugin } from "better-auth";
4
5
  import { bearer } from "better-auth/plugins/bearer";
5
6
  import { emailOTP } from "better-auth/plugins/email-otp";
@@ -8,16 +9,19 @@ import { magicLink } from "better-auth/plugins/magic-link";
8
9
  import { z } from "zod";
9
10
  import type { SendAuthEmail } from "./auth";
10
11
  /**
11
- * The four Better Auth plugins the kit composes for itself, and the reason they are fixed.
12
+ * The Better Auth plugins the kit composes for itself, and the reason they are fixed.
12
13
  *
13
14
  * `magic-link` and `email-otp` **are** the sign-in this product promises — passwordless, no
14
15
  * `emailAndPassword` anywhere. `jwt` mints the JWKS the control-plane seam verifies against and
15
- * `bearer` is how a mobile client presents its credential. Every one of them is depended on by code
16
- * outside this package, so an adopter who removed or redefined one would break a contract they cannot
17
- * see from their config. The adopter's list is therefore **additive**: it extends this set, never
18
- * replaces a member of it.
16
+ * `bearer` is how a mobile client presents its credential. `i18n` puts the dependency's own refusals in
17
+ * the reader's language, and {@link PROVIDER_SIGN_IN_GATE_ID} is the kit's own: it decides a refused
18
+ * provider sign-in before Better Auth branches, so the account-enumeration pair is never produced
19
+ * (#625, `./providerSignInGate`). Every one of them is depended on by code outside this package, so an
20
+ * adopter who removed or redefined one would break a contract they cannot see from their config — and
21
+ * for the gate, redefining it *is* removing it. The adopter's list is therefore **additive**: it extends
22
+ * this set, never replaces a member of it.
19
23
  */
20
- export declare const KIT_PLUGIN_IDS: readonly ["i18n", "bearer", "jwt", "magic-link", "email-otp"];
24
+ export declare const KIT_PLUGIN_IDS: readonly ["i18n", "bearer", "jwt", "magic-link", "email-otp", "pithy-provider-sign-in-gate"];
21
25
  /** What the kit's own plugins need to be constructed. The subset of `AuthInstanceDeps` they read. */
22
26
  export interface KitPluginDeps {
23
27
  /** Magic-link / OTP token lifetime in seconds. */
@@ -41,9 +45,21 @@ export interface KitPluginDeps {
41
45
  * is what the plugin answers with anyway, so its absence is not a special case.
42
46
  */
43
47
  locale?: string | null;
48
+ /**
49
+ * Audit seam — where a refused provider sign-in records which refusal it really was (#625).
50
+ *
51
+ * Read by `./providerSignInGate` and by nothing else in this list. The browser gets one code for rows
52
+ * 3 and 4 alike, so the trail is the only place the distinction survives.
53
+ */
54
+ emit: AuditEmit;
55
+ /**
56
+ * This request's headers, for the `ip` and `user-agent` a refusal row carries. Absent where no request
57
+ * built the instance — the schema baseline, a seed, a unit test. See `./providerSignInGate`.
58
+ */
59
+ requestHeaders?: Headers;
44
60
  }
45
61
  /**
46
- * The kit's four, as a **tuple** rather than an array. Better Auth infers a composed instance's whole
62
+ * The kit's own, as a **tuple** rather than an array. Better Auth infers a composed instance's whole
47
63
  * `$Infer` surface from the element types of its `plugins` list, so widening this to
48
64
  * `BetterAuthPlugin[]` here would erase the adopter's plugin types one line later, where `makeAuth`
49
65
  * spreads the two lists together.
@@ -53,7 +69,8 @@ export type KitPlugins = [
53
69
  ReturnType<typeof bearer>,
54
70
  ReturnType<typeof jwt>,
55
71
  ReturnType<typeof magicLink>,
56
- ReturnType<typeof emailOTP>
72
+ ReturnType<typeof emailOTP>,
73
+ BetterAuthPlugin
57
74
  ];
58
75
  /**
59
76
  * Build the kit's own plugins. **One definition, two readers**: `makeAuth` composes these into the
@@ -73,12 +90,23 @@ export declare function kitPlugins(deps: KitPluginDeps): KitPlugins;
73
90
  */
74
91
  export declare const AuthPlugin: z.ZodCustom<BetterAuthPlugin, BetterAuthPlugin>;
75
92
  /**
76
- * Refuse a plugin list that is not purely additive, naming the offending plugin.
93
+ * Refuse a plugin list the kit cannot compose, naming the offending plugin.
94
+ *
95
+ * Three ways it can fail, and each names a single id because that is what the adopter has to go delete.
96
+ *
97
+ * **Additivity, which is what this function was originally only about.** A plugin whose id is one of
98
+ * {@link KIT_PLUGIN_IDS} would sit beside the kit's own copy (Better Auth merges endpoints by id — the
99
+ * later registration silently wins, so this is a redefinition even when it reads like an addition), and
100
+ * two plugins sharing an id do the same to each other.
77
101
  *
78
- * Two ways it can fail, and both name a single id because that is what the adopter has to go delete:
79
- * a plugin whose id is one of {@link KIT_PLUGIN_IDS} would sit beside the kit's own copy (Better Auth
80
- * merges endpoints by id — the later registration silently wins, so this is a redefinition even when it
81
- * reads like an addition), and two plugins sharing an id do the same to each other.
102
+ * **And the transport a refusal leaves by (#625).** `../http/providerRefusal` collapses the
103
+ * account-enumeration oracle on the social callback by rewriting the `Location` header, which is the only
104
+ * transport it reads. A plugin that answers a refused callback through a **response body** instead —
105
+ * `oauthPopup()` is the shipped instance — restores the whole oracle with no malformed input anywhere,
106
+ * and no guard on the way in can see it coming. Such a plugin is refused here rather than composed and
107
+ * quietly left uncovered. `./refusalTransport` carries the verdict per plugin, the completeness gate over
108
+ * the dependency's own sources, and the argument for why that rule is a reviewed list rather than a
109
+ * property read off the object.
82
110
  *
83
111
  * **The `message` stays short on purpose.** `auth()` runs while `pithy.config.ts` is being imported, so
84
112
  * the CLI catches this through `classifyConfigLoadFailure`, which prints the cause's message and nothing
@@ -1 +1 @@
1
- {"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/instance/plugins.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,QAAQ,CAAC;AAE5C;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,YAAI,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,CAAU,CAAC;AAE5F,qGAAqG;AACrG,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,SAAS,EAAE,aAAa,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IAKvB,gBAAgB;IAChB,UAAU,CAAC,OAAO,MAAM,CAAC;IACzB,UAAU,CAAC,OAAO,GAAG,CAAC;IACtB,UAAU,CAAC,OAAO,SAAS,CAAC;IAC5B,UAAU,CAAC,OAAO,QAAQ,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAqC1D;AASD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,iDAMpB,CAAC;AAEJ;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CAoBhF"}
1
+ {"version":3,"file":"plugins.d.ts","sourceRoot":"","sources":["../../src/instance/plugins.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAEnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAE,GAAG,EAAE,MAAM,yBAAyB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAC3D,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,QAAQ,CAAC;AAI9D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,YAAI,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,gCAAoC,CAAC;AAEtH,qGAAqG;AACrG,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,qBAAqB,EAAE,MAAM,CAAC;IAC9B,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,aAAa,EAAE,OAAO,CAAC;IACvB,8EAA8E;IAC9E,SAAS,EAAE,aAAa,CAAC;IACzB;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;;OAKG;IACH,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IAKvB,gBAAgB;IAChB,UAAU,CAAC,OAAO,MAAM,CAAC;IACzB,UAAU,CAAC,OAAO,GAAG,CAAC;IACtB,UAAU,CAAC,OAAO,SAAS,CAAC;IAC5B,UAAU,CAAC,OAAO,QAAQ,CAAC;IAI3B,gBAAgB;CACjB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAkE1D;AAuCD;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,iDAMpB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI,CA4BhF"}
@@ -1,6 +1,9 @@
1
1
  // SPDX-FileCopyrightText: 2026 Pithy
2
2
  // SPDX-License-Identifier: MIT
3
+ import { SEND_FAULT, markMessageDelivery } from "../audit/evidence.js";
3
4
  import { authErrorTranslations } from "../i18n/errorCopy.js";
5
+ import { PROVIDER_SIGN_IN_GATE_ID, providerSignInGate } from "./providerSignInGate.js";
6
+ import { refusalTransportVerdict } from "./refusalTransport.js";
4
7
  import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
5
8
  import { z } from "zod";
6
9
  import { i18n } from "@better-auth/i18n";
@@ -10,21 +13,25 @@ import { jwt } from "better-auth/plugins/jwt";
10
13
  import { magicLink } from "better-auth/plugins/magic-link";
11
14
  //#region src/instance/plugins.ts
12
15
  /**
13
- * The four Better Auth plugins the kit composes for itself, and the reason they are fixed.
16
+ * The Better Auth plugins the kit composes for itself, and the reason they are fixed.
14
17
  *
15
18
  * `magic-link` and `email-otp` **are** the sign-in this product promises — passwordless, no
16
19
  * `emailAndPassword` anywhere. `jwt` mints the JWKS the control-plane seam verifies against and
17
- * `bearer` is how a mobile client presents its credential. Every one of them is depended on by code
18
- * outside this package, so an adopter who removed or redefined one would break a contract they cannot
19
- * see from their config. The adopter's list is therefore **additive**: it extends this set, never
20
- * replaces a member of it.
20
+ * `bearer` is how a mobile client presents its credential. `i18n` puts the dependency's own refusals in
21
+ * the reader's language, and {@link PROVIDER_SIGN_IN_GATE_ID} is the kit's own: it decides a refused
22
+ * provider sign-in before Better Auth branches, so the account-enumeration pair is never produced
23
+ * (#625, `./providerSignInGate`). Every one of them is depended on by code outside this package, so an
24
+ * adopter who removed or redefined one would break a contract they cannot see from their config — and
25
+ * for the gate, redefining it *is* removing it. The adopter's list is therefore **additive**: it extends
26
+ * this set, never replaces a member of it.
21
27
  */
22
28
  const KIT_PLUGIN_IDS = [
23
29
  "i18n",
24
30
  "bearer",
25
31
  "jwt",
26
32
  "magic-link",
27
- "email-otp"
33
+ "email-otp",
34
+ PROVIDER_SIGN_IN_GATE_ID
28
35
  ];
29
36
  /**
30
37
  * Build the kit's own plugins. **One definition, two readers**: `makeAuth` composes these into the
@@ -44,30 +51,83 @@ function kitPlugins(deps) {
44
51
  magicLink({
45
52
  expiresIn: deps.verificationExpiresIn,
46
53
  disableSignUp: deps.disableSignUp,
47
- sendMagicLink: async ({ email, url, token }) => {
48
- await deps.sendEmail({
54
+ /**
55
+ * **The only place that knows whether a message exists** — hence `sendAndRecord`, and see
56
+ * `../audit/evidence.ts` for why the two send events need it. `auth/magic_link_sent` claims a
57
+ * message; the endpoint answers `200 {"status":true}` whether or not one was made, and the `after`
58
+ * hook that writes the row cannot see the difference.
59
+ */
60
+ sendMagicLink: async ({ email, url, token }, ctx) => {
61
+ await sendAndRecord(deps, {
49
62
  to: email,
50
63
  template: "magicLink",
51
64
  token,
52
65
  url
53
- });
66
+ }, ctx);
54
67
  }
55
68
  }),
56
69
  emailOTP({
57
70
  otpLength: deps.otpLength,
58
71
  expiresIn: deps.verificationExpiresIn,
59
72
  disableSignUp: deps.disableSignUp,
60
- sendVerificationOTP: async ({ email, otp, type }) => {
73
+ /**
74
+ * **Two ways this declines, and neither shows on the wire.** Better Auth calls this only after its
75
+ * own user-enumeration guard has passed — an unregistered address that is not signing up gets the
76
+ * verification row dropped and `200 {"success":true}`, deliberately, so a caller cannot tell a
77
+ * registered address from a stranger's. And the kit declines again below: an OTP is a sign-in
78
+ * credential here, and no other `type` is a message this product sends.
79
+ *
80
+ * So the mark sits past the early return, beside the send itself. That is what `auth/otp_sent` has
81
+ * to mean, and reading it off the status wrote `success` for every one of these (#627).
82
+ *
83
+ * **And two more ways it declines, below this callback rather than above it.** The email capability
84
+ * withholds a message to a suppressed address, and an enqueue can simply fail; `runInBackgroundOrAwait`
85
+ * logs that failure and the endpoint still answers `200 {"success":true}`. Neither is visible from
86
+ * here except in what `sendEmail` answers, which is why the mark is the answer and comes after it.
87
+ */
88
+ sendVerificationOTP: async ({ email, otp, type }, ctx) => {
61
89
  if (type !== "sign-in") return;
62
- await deps.sendEmail({
90
+ await sendAndRecord(deps, {
63
91
  to: email,
64
92
  template: "otp",
65
93
  code: otp
66
- });
94
+ }, ctx);
67
95
  }
96
+ }),
97
+ providerSignInGate({
98
+ emit: deps.emit,
99
+ headers: deps.requestHeaders
68
100
  })
69
101
  ];
70
102
  }
103
+ /**
104
+ * Hand one message to the email seam and record what the seam answered.
105
+ *
106
+ * **After the await, and the answer rather than the attempt — that pair is #627's last hole.** The
107
+ * previous revision marked the evidence *before* `sendEmail` was awaited and discarded its result, so
108
+ * `@pithy-sh/email` deciding to withhold a message, or failing to queue one at all, was invisible to the
109
+ * event that claims the message exists. Both wrote `auth/otp_sent outcome=success` over a
110
+ * `200 {"success":true}`, for an unauthenticated caller, on the default composition.
111
+ *
112
+ * **A throw is marked and re-thrown, never swallowed.** Swallowing would move the wire —
113
+ * `/sign-in/magic-link` awaits this callback directly and answers 500 when it throws, while
114
+ * `/email-otp/send-verification-otp` routes it through `runInBackgroundOrAwait`, which logs and answers
115
+ * 200 either way. Nothing here decides a status; it records what happened underneath one. The recorded
116
+ * reason is {@link SEND_FAULT} and never the error's own text: an audit row is long-lived and queryable,
117
+ * and a thrown message is the one value in reach that nobody has vetted.
118
+ */
119
+ async function sendAndRecord(deps, message, ctx) {
120
+ const requestContext = ctx?.context;
121
+ try {
122
+ markMessageDelivery(requestContext, await deps.sendEmail(message));
123
+ } catch (error) {
124
+ markMessageDelivery(requestContext, {
125
+ delivery: "failed",
126
+ reason: SEND_FAULT
127
+ });
128
+ throw error;
129
+ }
130
+ }
71
131
  /** Is this value shaped like a Better Auth plugin — an object carrying a non-empty string `id`? */
72
132
  function isBetterAuthPlugin(value) {
73
133
  if (typeof value !== "object" || value === null) return false;
@@ -83,14 +143,25 @@ function isBetterAuthPlugin(value) {
83
143
  * checked without rebuilding it is checked: it is an object, and it has the `id` every other rule here
84
144
  * (reservation, duplication, migration keys, `pithy doctor`) is written in terms of.
85
145
  */
86
- const AuthPlugin = z.custom(isBetterAuthPlugin, { message: "Expected a Better Auth plugin — an object with a non-empty string `id`." }).describe("An additional Better Auth plugin, e.g. `organization()`, `passkey()`, `twoFactor()`. Added to the set the kit composes, never in place of one.");
146
+ const AuthPlugin = z.custom(isBetterAuthPlugin, { message: "Expected a Better Auth plugin — an object with a non-empty string `id`." }).describe("An additional Better Auth plugin, e.g. `organization()`, `passkey()`, `twoFactor()`. Added to the set the kit composes, never in place of one — and refused when it answers a social sign-in refusal through a response body, which the capability cannot collapse.");
87
147
  /**
88
- * Refuse a plugin list that is not purely additive, naming the offending plugin.
148
+ * Refuse a plugin list the kit cannot compose, naming the offending plugin.
149
+ *
150
+ * Three ways it can fail, and each names a single id because that is what the adopter has to go delete.
89
151
  *
90
- * Two ways it can fail, and both name a single id because that is what the adopter has to go delete:
91
- * a plugin whose id is one of {@link KIT_PLUGIN_IDS} would sit beside the kit's own copy (Better Auth
92
- * merges endpoints by id — the later registration silently wins, so this is a redefinition even when it
93
- * reads like an addition), and two plugins sharing an id do the same to each other.
152
+ * **Additivity, which is what this function was originally only about.** A plugin whose id is one of
153
+ * {@link KIT_PLUGIN_IDS} would sit beside the kit's own copy (Better Auth merges endpoints by id — the
154
+ * later registration silently wins, so this is a redefinition even when it reads like an addition), and
155
+ * two plugins sharing an id do the same to each other.
156
+ *
157
+ * **And the transport a refusal leaves by (#625).** `../http/providerRefusal` collapses the
158
+ * account-enumeration oracle on the social callback by rewriting the `Location` header, which is the only
159
+ * transport it reads. A plugin that answers a refused callback through a **response body** instead —
160
+ * `oauthPopup()` is the shipped instance — restores the whole oracle with no malformed input anywhere,
161
+ * and no guard on the way in can see it coming. Such a plugin is refused here rather than composed and
162
+ * quietly left uncovered. `./refusalTransport` carries the verdict per plugin, the completeness gate over
163
+ * the dependency's own sources, and the argument for why that rule is a reviewed list rather than a
164
+ * property read off the object.
94
165
  *
95
166
  * **The `message` stays short on purpose.** `auth()` runs while `pithy.config.ts` is being imported, so
96
167
  * the CLI catches this through `classifyConfigLoadFailure`, which prints the cause's message and nothing
@@ -101,6 +172,12 @@ function assertAdditivePlugins(plugins) {
101
172
  const reserved = KIT_PLUGIN_IDS;
102
173
  const seen = /* @__PURE__ */ new Set();
103
174
  for (const plugin of plugins) {
175
+ const verdict = refusalTransportVerdict(plugin.id);
176
+ if (verdict?.outsideLocation === true) throw new ValidationError({
177
+ message: `The auth capability cannot compose the Better Auth "${plugin.id}" plugin.`,
178
+ action: `Remove ${plugin.id}() from auth({ plugins: [...] }). It answers a refused social sign-in through a response body rather than the redirect the capability collapses, which would put back the enumeration oracle that tells a caller whether an account exists at an address a provider handed over.`,
179
+ detail: `plugin "${plugin.id}" answers callback refusals outside the Location header — ${verdict.why}`
180
+ });
104
181
  if (reserved.includes(plugin.id)) throw new ValidationError({
105
182
  message: `The auth capability already composes the Better Auth "${plugin.id}" plugin.`,
106
183
  action: `Remove ${plugin.id}() from auth({ plugins: [...] }). The four the kit composes (${KIT_PLUGIN_IDS.join(", ")}) are the sign-in this product promises and what the control-plane seam verifies against; your list adds to them.`,