@pithy-sh/auth 0.6.2 → 0.6.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -0
- package/dist/audit/actions.d.ts +78 -5
- package/dist/audit/actions.d.ts.map +1 -1
- package/dist/audit/actions.js +78 -5
- package/dist/audit/emit.d.ts +223 -2
- package/dist/audit/emit.d.ts.map +1 -1
- package/dist/audit/emit.js +251 -20
- package/dist/audit/evidence.d.ts +207 -0
- package/dist/audit/evidence.d.ts.map +1 -0
- package/dist/audit/evidence.js +162 -0
- package/dist/capability.d.ts +7 -0
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +7 -2
- package/dist/client/api.d.ts +8 -0
- package/dist/client/api.d.ts.map +1 -1
- package/dist/client/api.js +8 -0
- package/dist/email/send.d.ts +10 -2
- package/dist/email/send.d.ts.map +1 -1
- package/dist/email/send.js +36 -14
- package/dist/http/errorCallbackUrl.d.ts +40 -0
- package/dist/http/errorCallbackUrl.d.ts.map +1 -0
- package/dist/http/errorCallbackUrl.js +395 -0
- package/dist/http/providerRefusal.d.ts +181 -0
- package/dist/http/providerRefusal.d.ts.map +1 -0
- package/dist/http/providerRefusal.js +363 -0
- package/dist/http/resolve.js +1 -0
- package/dist/http/routes.d.ts.map +1 -1
- package/dist/http/routes.js +12 -1
- package/dist/instance/auth.d.ts +132 -26
- package/dist/instance/auth.d.ts.map +1 -1
- package/dist/instance/auth.js +118 -13
- package/dist/instance/githubUserInfo.d.ts +13 -7
- package/dist/instance/githubUserInfo.d.ts.map +1 -1
- package/dist/instance/githubUserInfo.js +13 -7
- package/dist/instance/plugins.d.ts +41 -13
- package/dist/instance/plugins.d.ts.map +1 -1
- package/dist/instance/plugins.js +95 -18
- package/dist/instance/providerSignInGate.d.ts +130 -0
- package/dist/instance/providerSignInGate.d.ts.map +1 -0
- package/dist/instance/providerSignInGate.js +230 -0
- package/dist/instance/refusalTransport.d.ts +91 -0
- package/dist/instance/refusalTransport.d.ts.map +1 -0
- package/dist/instance/refusalTransport.js +32 -0
- package/dist/migrations/pluginTables.d.ts.map +1 -1
- package/dist/migrations/pluginTables.js +2 -1
- package/dist/peer.d.ts +54 -0
- package/dist/peer.d.ts.map +1 -0
- package/dist/peer.js +31 -0
- package/dist/version.generated.d.ts +1 -1
- package/dist/version.generated.js +1 -1
- package/package.json +5 -5
- package/src/audit/actions.ts +78 -5
- package/src/audit/emit.ts +340 -25
- package/src/audit/evidence.ts +297 -0
- package/src/capability.ts +19 -7
- package/src/client/api.ts +8 -0
- package/src/email/send.ts +51 -14
- package/src/http/errorCallbackUrl.ts +463 -0
- package/src/http/providerRefusal.ts +424 -0
- package/src/http/resolve.ts +3 -0
- package/src/http/routes.ts +38 -1
- package/src/instance/auth.ts +167 -19
- package/src/instance/githubUserInfo.ts +13 -7
- package/src/instance/plugins.ts +119 -18
- package/src/instance/providerSignInGate.ts +323 -0
- package/src/instance/refusalTransport.ts +119 -0
- package/src/migrations/pluginTables.ts +4 -1
- package/src/peer.ts +29 -0
- package/src/version.generated.ts +1 -1
package/dist/instance/auth.js
CHANGED
|
@@ -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
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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
|
|
34
|
-
* the tokens —
|
|
35
|
-
*
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
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
|
|
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
|
|
35
|
-
* the tokens —
|
|
36
|
-
*
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
*
|
|
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
|
|
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.
|
|
16
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
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
|
|
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
|
|
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
|
-
*
|
|
79
|
-
*
|
|
80
|
-
*
|
|
81
|
-
*
|
|
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":"
|
|
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"}
|
package/dist/instance/plugins.js
CHANGED
|
@@ -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
|
|
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.
|
|
18
|
-
*
|
|
19
|
-
*
|
|
20
|
-
*
|
|
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
|
-
|
|
48
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
*
|
|
91
|
-
*
|
|
92
|
-
*
|
|
93
|
-
*
|
|
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.`,
|