@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.
- 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.map +1 -1
- package/dist/capability.js +2 -1
- 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/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 +11 -6
- 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/version.generated.ts +1 -1
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
// SPDX-FileCopyrightText: 2026 Pithy
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* One answer for every refusal the user table decided, on every transport the kit can hold (#625).
|
|
6
|
+
*
|
|
7
|
+
* ## This is the second line now, and the first one is upstream
|
|
8
|
+
*
|
|
9
|
+
* `../instance/providerSignInGate` decides a refused provider sign-in **before** Better Auth branches,
|
|
10
|
+
* so `account_not_linked` and `signup_disabled` — the pair this module was written for — are no longer
|
|
11
|
+
* produced anywhere on the redirect callback. The roster below still carries them, because a roster
|
|
12
|
+
* whose completeness is gated against the dependency's own error tables has to name every code the
|
|
13
|
+
* dependency can emit, not every code the kit can currently reach.
|
|
14
|
+
*
|
|
15
|
+
* **What is left for this module is the rest of the roster**, and it is not nothing: `unable_to_create_user`
|
|
16
|
+
* and `validation_context_missing` are raised inside `createUser`, which is the no-row side, and
|
|
17
|
+
* `INVALID_PROFILE_FIELD` on the matched-row side — all three downstream of a gate decision the gate
|
|
18
|
+
* passed through, because passing through is what it does whenever Better Auth might have succeeded.
|
|
19
|
+
* So both ends stay: the gate stops the pair being produced, and this checks what the dependency
|
|
20
|
+
* answered against the roster.
|
|
21
|
+
*
|
|
22
|
+
* ## Reach, stated before the argument, because six rounds have turned on this
|
|
23
|
+
*
|
|
24
|
+
* This module reads exactly one thing: the `Location` header of the Response `instance.handler()`
|
|
25
|
+
* returned. So the guarantee is **a refusal that leaves this Worker through that header is collapsed** —
|
|
26
|
+
* which covers the kit's own routes, because Better Auth's social callback answers that way, and covers
|
|
27
|
+
* any composed plugin that answers refusals through `Location` too.
|
|
28
|
+
*
|
|
29
|
+
* It does not cover a plugin that replaces the callback's response with something else. There is no way
|
|
30
|
+
* for a header rewrite to reach a code that is now in a body, so the guarantee is bounded at the other
|
|
31
|
+
* end instead: `../instance/refusalTransport` refuses such a plugin at composition, by a reviewed roster
|
|
32
|
+
* whose completeness is gated against the dependency's own sources. `oauthPopup()` is the shipped
|
|
33
|
+
* instance and is refused. **An adopter's own plugin doing the same thing is not detectable at `auth()`
|
|
34
|
+
* and is not covered** — that residue is named here rather than left for a seventh round to find.
|
|
35
|
+
*
|
|
36
|
+
* ## The defect
|
|
37
|
+
*
|
|
38
|
+
* A refused social sign-in redirects to the adopter's `errorCallbackURL` with `?error=<code>`, and two
|
|
39
|
+
* of those codes are decided by **whether a row exists at the address the provider handed over**:
|
|
40
|
+
*
|
|
41
|
+
* | Code | Emitted only when |
|
|
42
|
+
* | --- | --- |
|
|
43
|
+
* | `account_not_linked` | a user row **did** match (`better-auth/dist/oauth2/link-account.mjs:86`) |
|
|
44
|
+
* | `signup_disabled` | **no** row matched (`:202`) |
|
|
45
|
+
*
|
|
46
|
+
* Both leave through one line — `redirectOnError(result.error.split(" ").join("_"))`,
|
|
47
|
+
* `dist/api/routes/callback.mjs:245` — so from outside the Worker they are one question with two
|
|
48
|
+
* answers. Press the provider button, read the `Location` header, repeat: an account-enumeration oracle
|
|
49
|
+
* needing one GitHub account, no account on the target, and no page render. It works against the
|
|
50
|
+
* configuration the kit's own security guidance recommends (`allowSignUp: false`, #554), so the
|
|
51
|
+
* projects that followed the advice are the exposed ones.
|
|
52
|
+
*
|
|
53
|
+
* ## Two more producers, found by asking the question instead of reading the issue
|
|
54
|
+
*
|
|
55
|
+
* The issue named two codes and cleared `EMAIL_NOT_VERIFIED` as "the provider's own state". The *text*
|
|
56
|
+
* is the provider's state; its **reachability** is not. The kit throws it from `user.create.before`
|
|
57
|
+
* (`instance/auth.ts`), and creating a user is something the callback only ever attempts when no row
|
|
58
|
+
* matched. So with sign-up permitted — the default — the pair is `account_not_linked` against
|
|
59
|
+
* `EMAIL_NOT_VERIFIED`, and it is the same oracle wearing a different name. Measured, not reasoned:
|
|
60
|
+
* `providerRefusal.workers.test.ts` drives both sign-up policies. `unable_to_create_user` sits on the
|
|
61
|
+
* same side of the same branch and joins them.
|
|
62
|
+
*
|
|
63
|
+
* That is why this module is a **roster with a verdict per code** rather than a pair of strings. The
|
|
64
|
+
* question a code has to answer is not "is this sentence sensitive" but "could the Worker have produced
|
|
65
|
+
* it without looking in its own user table".
|
|
66
|
+
*
|
|
67
|
+
* ## Why this is the kit's job and not an adopter's
|
|
68
|
+
*
|
|
69
|
+
* An adopter can only put middleware in front of the same Response and rewrite the header — collapsing
|
|
70
|
+
* the code *and losing the reason with it*. Held here, at the one place the capability hands a Better
|
|
71
|
+
* Auth response back, both halves survive: the browser gets one code, and {@link CollapsedRefusal}'s
|
|
72
|
+
* `reason` says which refusal it really was, for `handleBetterAuth` to put on the audit trail.
|
|
73
|
+
* Composing `auth` is the whole of what an adopter does to get it, and there is no option to forget.
|
|
74
|
+
*
|
|
75
|
+
* ## This module is the second line of defense, not the only one
|
|
76
|
+
*
|
|
77
|
+
* It reads the `Location` a refused callback answered with — which is the output of
|
|
78
|
+
* `redirectOnError`'s raw string concatenation (`callback.mjs:78`), performed on a value the caller
|
|
79
|
+
* supplied. It was walked around twice that way, and the second bypass was the diagnosis: **every input
|
|
80
|
+
* shape where that concatenation and this parsing disagree is another one**, so patching the parsing
|
|
81
|
+
* again only moves the report later. `./errorCallbackUrl` therefore guards the value on the way *in*,
|
|
82
|
+
* and by the time this module runs the string being parsed is one the kit produced.
|
|
83
|
+
*
|
|
84
|
+
* **Both stay.** That module decides what the dependency is handed; this one still checks what it
|
|
85
|
+
* answered. An input guard that depends on out-guessing a dependency's string handling is exactly what
|
|
86
|
+
* round 3 exists to stop relying on — so the guess is made once, about a value the kit then owns, and
|
|
87
|
+
* checked again here against the roster. Neither is asked to carry the whole load.
|
|
88
|
+
*
|
|
89
|
+
* ## And the third line is not a guard at all
|
|
90
|
+
*
|
|
91
|
+
* Round 6 found a refusal that needs no malformed input: a composed `oauthPopup()` turns the callback's
|
|
92
|
+
* redirect into a 200 HTML page carrying the code in its body, and neither guard above can see a header
|
|
93
|
+
* that was never sent. Guarding a sixth channel would have been the same move a sixth time. Instead the
|
|
94
|
+
* composition is refused — `../instance/refusalTransport` — and this module's claim is bounded to what it
|
|
95
|
+
* can actually hold. See the reach section at the top; it is the contract, not a caveat.
|
|
96
|
+
*/
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* The one code a refused social sign-in redirects with, whatever the Worker actually found.
|
|
100
|
+
*
|
|
101
|
+
* Named for the outcome the reader may know — the provider did not sign them in — rather than the
|
|
102
|
+
* reason they may not. **Do not make this more helpful.** Every sentence that distinguishes "you have
|
|
103
|
+
* no account here" from "you have one and this provider is not attached to it" is the oracle back, and
|
|
104
|
+
* the adopter screen reading this code is where the (identical, deliberately unspecific) copy lives.
|
|
105
|
+
*/
|
|
106
|
+
export const NEUTRAL_PROVIDER_REFUSAL = "provider_sign_in_refused";
|
|
107
|
+
|
|
108
|
+
/** Whether a code may travel to the browser, and the reason that verdict was reached. */
|
|
109
|
+
interface RefusalVerdict {
|
|
110
|
+
/**
|
|
111
|
+
* `true` when the code is reachable on only one side of "did a row match", and must therefore
|
|
112
|
+
* collapse. `false` when nothing about it depends on this Worker's user table.
|
|
113
|
+
*/
|
|
114
|
+
readonly collapse: boolean;
|
|
115
|
+
/** Why. Written for the next person to be asked to make an error message more useful. */
|
|
116
|
+
readonly why: string;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/**
|
|
120
|
+
* Every `error` code reachable on the social callback's redirect, with its verdict.
|
|
121
|
+
*
|
|
122
|
+
* **Completeness is gated, which is what keeps this from being a list of forbidden strings.**
|
|
123
|
+
* `providerRefusal.test.ts` reads Better Auth's own `OAUTH_CALLBACK_ERROR_CODES`, scans the
|
|
124
|
+
* `result.error` literals out of `link-account.mjs`, and scans the `new APIError(…, { code })` sites in
|
|
125
|
+
* both codebases — `better-auth`'s on the callback's path and the kit's across this whole package,
|
|
126
|
+
* because `callback.mjs:239` re-emits *anything* thrown inside `handleOAuthUserInfo` as `?error=`. Every
|
|
127
|
+
* code any of them can produce must appear here. A dependency bump that adds one turns that red, and
|
|
128
|
+
* somebody writes a verdict for it. So the roster records a *review*, and the review cannot silently fall
|
|
129
|
+
* behind the thing it reviews.
|
|
130
|
+
*
|
|
131
|
+
* **Off-roster codes travel, and that is a decision rather than an oversight.** Collapsing the unknown
|
|
132
|
+
* would be the safer default for our own codes and the wrong one overall: `callback.mjs:85` forwards the
|
|
133
|
+
* provider's own `error` parameter verbatim, and RFC 6749 §4.1.2.1 leaves that an open set. A reader who
|
|
134
|
+
* pressed Cancel at GitHub would get `provider_sign_in_refused` — "we could not sign you in" for an act
|
|
135
|
+
* they know perfectly well they performed — and every adopter screen that reads `access_denied` would go
|
|
136
|
+
* quiet. Nothing in that set can be decided by our user table, because it is decided before this Worker
|
|
137
|
+
* looks at anything. The completeness gate is what covers the half that can.
|
|
138
|
+
*/
|
|
139
|
+
const PROVIDER_REFUSAL_VERDICTS: Readonly<Record<string, RefusalVerdict>> = {
|
|
140
|
+
// ── Decided by the user table. These are the defect. ───────────────────────────────────────────
|
|
141
|
+
account_not_linked: {
|
|
142
|
+
collapse: true,
|
|
143
|
+
why: "link-account.mjs:86 — returned only inside `if (dbUser)`, so it is literally the statement that a row matched.",
|
|
144
|
+
},
|
|
145
|
+
signup_disabled: {
|
|
146
|
+
collapse: true,
|
|
147
|
+
why: "link-account.mjs:202 — the `else` of that same branch, so it is literally the statement that none did.",
|
|
148
|
+
},
|
|
149
|
+
EMAIL_NOT_VERIFIED: {
|
|
150
|
+
collapse: true,
|
|
151
|
+
why: "The kit's own `user.create.before` hook (instance/auth.ts). A user is only ever created when no row matched, so this code cannot be observed against an address that has an account — which makes it the other half of `account_not_linked` whenever sign-up is permitted. The sentence is about the provider; the fact that you are reading it is about us.",
|
|
152
|
+
},
|
|
153
|
+
unable_to_create_user: {
|
|
154
|
+
collapse: true,
|
|
155
|
+
why: "link-account.mjs:254 — the create path only, so it sits on the no-row side exactly as `signup_disabled` does. A fault rather than a refusal, and still an answer to the question being asked.",
|
|
156
|
+
},
|
|
157
|
+
INVALID_PROFILE_FIELD: {
|
|
158
|
+
collapse: true,
|
|
159
|
+
why: "The kit's `user.update.before` hook, and **the branch it sits on was read wrong the first time.** `if (dbUser) {` opens at link-account.mjs:77 and the `if (!linkedAccount) {…} else {…}` pair sits *inside* it, so the ownership argument that carries `unable_to_update_account` does not reach here: the `updateUser` that can carry a provider's `name`/`image` is the `overrideUserInfo` write at :185, which runs after **either** sub-branch — including the one that has just linked an account that did not exist a line earlier. What every path to it does share is `if (dbUser)`: a matched row. The other side of that branch calls `createUser`, where the kit's `user.create.before` **sanitizes** the same two fields instead of refusing them. So a hostile provider display name answers `?error=INVALID_PROFILE_FIELD` against an address that has a row and a completed sign-in against one that does not, which is the oracle with a different name on it.",
|
|
160
|
+
},
|
|
161
|
+
validation_context_missing: {
|
|
162
|
+
collapse: true,
|
|
163
|
+
why: "internal-adapter.mjs:160 — raised when `getCurrentAuthContext()` fails inside `createUser`, and `createUser` is the no-row side. `updateUser` runs no such check (internal-adapter.mjs:599), so this code cannot be observed against an address that has a row: it is `signup_disabled`'s shape reached through the adopter's `validateUserInfo` option rather than through the sign-up policy.",
|
|
164
|
+
},
|
|
165
|
+
|
|
166
|
+
// ── The caller's own request, or the provider's. Nothing to do with our rows. ──────────────────
|
|
167
|
+
no_code: {
|
|
168
|
+
collapse: false,
|
|
169
|
+
why: "The provider came back without a code. The shape of the request itself, settled before any lookup.",
|
|
170
|
+
},
|
|
171
|
+
invalid_code: {
|
|
172
|
+
collapse: false,
|
|
173
|
+
why: "The code would not exchange at the provider's token endpoint. Settled before any lookup.",
|
|
174
|
+
},
|
|
175
|
+
invalid_callback_request: {
|
|
176
|
+
collapse: false,
|
|
177
|
+
why: "callback.mjs:55 — the callback's own query or body would not parse. Raised before `parseState`, so nothing had been read from anywhere yet.",
|
|
178
|
+
},
|
|
179
|
+
oauth_provider_not_found: {
|
|
180
|
+
collapse: false,
|
|
181
|
+
why: "This deployment does not serve that provider. A fact about the configuration, and `providers.ts` already draws the one distinction that matters here.",
|
|
182
|
+
},
|
|
183
|
+
issuer_missing: {
|
|
184
|
+
collapse: false,
|
|
185
|
+
why: "The provider's own response did not name an issuer. Nothing was looked up.",
|
|
186
|
+
},
|
|
187
|
+
issuer_mismatch: {
|
|
188
|
+
collapse: false,
|
|
189
|
+
why: "The provider's response named the wrong issuer. Nothing was looked up.",
|
|
190
|
+
},
|
|
191
|
+
nonce_binding_missing: {
|
|
192
|
+
collapse: false,
|
|
193
|
+
why: "The request's own nonce binding. Checked against the state, never against a user row.",
|
|
194
|
+
},
|
|
195
|
+
unable_to_get_user_info: {
|
|
196
|
+
collapse: false,
|
|
197
|
+
why: "The provider would not say who this is. Decided before any lookup — and the kit's resolver fails closed to exactly here, so collapsing it would render a GitHub outage as a refusal (githubUserInfo.ts).",
|
|
198
|
+
},
|
|
199
|
+
no_callback_url: {
|
|
200
|
+
collapse: false,
|
|
201
|
+
why: "No `callbackURL` was carried in the state. The adopter's own configuration, and the same answer for everybody.",
|
|
202
|
+
},
|
|
203
|
+
email_not_found: {
|
|
204
|
+
collapse: false,
|
|
205
|
+
why: "The provider returned no address at all. Its state, and reached before this Worker looks anything up.",
|
|
206
|
+
},
|
|
207
|
+
email_not_verified: {
|
|
208
|
+
collapse: false,
|
|
209
|
+
why: "Better Auth's lower-case code, from `requireEmailVerification` (link-account.mjs:263) — which the kit does not set. Reachable for a registering and a returning user alike, so it names no row either way. Not to be confused with the kit's upper-case `EMAIL_NOT_VERIFIED` above; the two are different strings from different places and only one of them is the oracle.",
|
|
210
|
+
},
|
|
211
|
+
unable_to_create_session: {
|
|
212
|
+
collapse: false,
|
|
213
|
+
why: "link-account.mjs:269 — after the user is resolved, so it is reached from both sides of the branch equally.",
|
|
214
|
+
},
|
|
215
|
+
state_not_found: {
|
|
216
|
+
collapse: false,
|
|
217
|
+
why: "The request carried no state to parse. Raised at state.mjs:90, before any lookup.",
|
|
218
|
+
},
|
|
219
|
+
state_mismatch: {
|
|
220
|
+
collapse: false,
|
|
221
|
+
why: "The request's own state did not match what was stored. Nothing about a user was read to decide it.",
|
|
222
|
+
},
|
|
223
|
+
state_security_mismatch: {
|
|
224
|
+
collapse: false,
|
|
225
|
+
why: "The same fact as `state_mismatch`, which is what `oauth2/state.mjs` remaps it to before it reaches a browser. Rostered under its own name because the remap is the dependency's internal detail, not a promise.",
|
|
226
|
+
},
|
|
227
|
+
state_invalid: {
|
|
228
|
+
collapse: false,
|
|
229
|
+
why: "The state would not decrypt or parse. The request's own credential, and nothing else.",
|
|
230
|
+
},
|
|
231
|
+
state_generation_error: {
|
|
232
|
+
collapse: false,
|
|
233
|
+
why: "Minting the state failed on the way out. A fault on this Worker's own side, raised before there is a callback to answer, let alone a row to read.",
|
|
234
|
+
},
|
|
235
|
+
internal_server_error: {
|
|
236
|
+
collapse: false,
|
|
237
|
+
why: "A fault, raised in place of the lookup it would otherwise have reported on — so it says a lookup did not finish, never what one found.",
|
|
238
|
+
},
|
|
239
|
+
account_hook_binding_conflict: {
|
|
240
|
+
collapse: false,
|
|
241
|
+
why: "link-account.mjs:120/176/237 — a hook moved the account binding out from under the write that had just been made. Raised on the link path, the sign-in path *and* the create path, so it is reached from both sides of `if (dbUser)` equally and names neither.",
|
|
242
|
+
},
|
|
243
|
+
validation_source_missing: {
|
|
244
|
+
collapse: false,
|
|
245
|
+
why: "validate-user-info.mjs:5/9/13 — the `source` handed to the adopter's `validateUserInfo` gate did not name a method or a provider. A fact about the call Better Auth just built, identical on both sides of the branch, and settled before the gate is even asked.",
|
|
246
|
+
},
|
|
247
|
+
validation_failed: {
|
|
248
|
+
collapse: false,
|
|
249
|
+
why: "validate-user-info.mjs:34 — the adopter's own `validateUserInfo` callback threw, and Better Auth fails closed. Called on the link path (link-account.mjs:92), the sign-in path (:137) and the create path (internal-adapter.mjs:164), so it is reachable whether or not a row matched. What that callback *returns* is the adopter's own code and travels off-roster, which is the same decision as for the provider's own `error` values.",
|
|
250
|
+
},
|
|
251
|
+
|
|
252
|
+
// ── The link flow. The caller already holds a session for the account in question. ─────────────
|
|
253
|
+
unable_to_link_account: {
|
|
254
|
+
collapse: false,
|
|
255
|
+
why: "callback.mjs:173/198, inside `if (link)` — reachable only on `/link-social`, where the caller is signed in as the user being changed. Telling somebody about their own account is not enumeration.",
|
|
256
|
+
},
|
|
257
|
+
email_does_not_match: {
|
|
258
|
+
collapse: false,
|
|
259
|
+
why: "The link flow, and the address compared against is the signed-in caller's own. The caller's account, as above.",
|
|
260
|
+
},
|
|
261
|
+
account_already_linked_to_different_user: {
|
|
262
|
+
collapse: false,
|
|
263
|
+
why: "The link flow. The caller's own account, as above — and the other user is named by nothing here.",
|
|
264
|
+
},
|
|
265
|
+
unable_to_update_account: {
|
|
266
|
+
collapse: false,
|
|
267
|
+
why: "link-account.mjs:172, inside `if (linkedAccount)` — reaching it requires an account row already binding this provider identity to this user, and the caller proved control of that identity at the provider to get here. Ownership, not a matched row. (This is the argument `INVALID_PROFILE_FIELD` was wrongly given: that code's write sits outside this branch.)",
|
|
268
|
+
},
|
|
269
|
+
|
|
270
|
+
// ── The account-selection flow, which the social callback never enters. ────────────────────────
|
|
271
|
+
// Every code below is guarded by `opts.selectedUser` or by `opts.requireExactAccountBinding`, and
|
|
272
|
+
// `callback.mjs` passes neither to `handleOAuthUserInfo`. They are rostered because the completeness
|
|
273
|
+
// gate scans the file rather than the reachable subset of it — and "cannot be reached from here" is a
|
|
274
|
+
// verdict a reader can check, where silence is not.
|
|
275
|
+
account_ownership_conflict: {
|
|
276
|
+
collapse: false,
|
|
277
|
+
why: "link-account.mjs:38, inside `if (opts.selectedUser && …)`. The lookup it reports on is keyed by the *provider* identity the caller has just proved control of, not by an address handed over — and the social callback passes no `selectedUser`, so this never reaches that redirect at all.",
|
|
278
|
+
},
|
|
279
|
+
account_provider_conflict: {
|
|
280
|
+
collapse: false,
|
|
281
|
+
why: "link-account.mjs:42, guarded by `requireExactAccountBinding`, which is `opts.selectedUser || opts.requireExactAccountBinding` — neither of which `callback.mjs` passes. Keyed by the caller's own provider identity, as above.",
|
|
282
|
+
},
|
|
283
|
+
user_not_found: {
|
|
284
|
+
collapse: false,
|
|
285
|
+
why: "link-account.mjs:54 — `findUserById(opts.selectedUser.userId)`, so it answers about a user id the caller was already handed, on a flow the social callback does not enter. It reads a row by id, never by a provider-resolved address.",
|
|
286
|
+
},
|
|
287
|
+
user_hook_selection_conflict: {
|
|
288
|
+
collapse: false,
|
|
289
|
+
why: "link-account.mjs:195, inside `if (opts.selectedUser …)`. A hook returned a different user than the one the caller picked from a list they had already been shown, and the social callback never picks one.",
|
|
290
|
+
},
|
|
291
|
+
session_hook_user_conflict: {
|
|
292
|
+
collapse: false,
|
|
293
|
+
why: "link-account.mjs:275 — after the user is resolved and the session minted, under the same `requireExactAccountBinding` gate. Reached from both sides of `if (dbUser)` when it is reached at all, which on the social callback is never.",
|
|
294
|
+
},
|
|
295
|
+
};
|
|
296
|
+
|
|
297
|
+
/** The codes this module refuses to let out. Derived from the roster, so the two cannot disagree. */
|
|
298
|
+
export const PROVIDER_REFUSAL_CODES: readonly string[] = Object.entries(PROVIDER_REFUSAL_VERDICTS)
|
|
299
|
+
.filter(([, verdict]) => verdict.collapse)
|
|
300
|
+
.map(([code]) => code);
|
|
301
|
+
|
|
302
|
+
/** The roster, for the completeness gate. Not part of the package's surface. */
|
|
303
|
+
export const PROVIDER_REFUSAL_ROSTER: Readonly<Record<string, RefusalVerdict>> = PROVIDER_REFUSAL_VERDICTS;
|
|
304
|
+
|
|
305
|
+
/** A refusal that was collapsed: what now goes on the wire, and what really happened. */
|
|
306
|
+
export interface CollapsedRefusal {
|
|
307
|
+
/** The redirect with the neutral code in place of the revealing one. */
|
|
308
|
+
readonly response: Response;
|
|
309
|
+
/**
|
|
310
|
+
* The code that was taken off the wire — for the audit trail, and for nothing else.
|
|
311
|
+
*
|
|
312
|
+
* Space-separated when the header carried more than one collapsing `error`, which it can: Better Auth
|
|
313
|
+
* *appends* its code to whatever the adopter's error URL already had. Recording only the first would
|
|
314
|
+
* put a caller-supplied value in the trail's place.
|
|
315
|
+
*/
|
|
316
|
+
readonly reason: string;
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
/**
|
|
320
|
+
* Collapse a social-callback refusal that our own user table decided, or answer `undefined`.
|
|
321
|
+
*
|
|
322
|
+
* `undefined` for every response that is not a redirect off the callback path carrying a rostered,
|
|
323
|
+
* collapsing `error` — which is nearly all of them, including every successful sign-in, since a
|
|
324
|
+
* completed callback redirects to `callbackURL` with no `error` at all.
|
|
325
|
+
*
|
|
326
|
+
* **`undefined` also for a callback answered with no `Location` at all**, which is what a composed plugin
|
|
327
|
+
* that replaced the response leaves behind. That is not this function failing open by oversight: a code
|
|
328
|
+
* moved into a body is not reachable from a header rewrite, so the composition is refused at `auth()`
|
|
329
|
+
* instead (`../instance/refusalTransport`). The module docblock's reach section is the whole claim.
|
|
330
|
+
*
|
|
331
|
+
* **`error_description` goes with it.** Nothing sets one for these today, and a description is a whole
|
|
332
|
+
* sentence written by whoever raises the code next — so it is dropped rather than carried past a header
|
|
333
|
+
* that was just made deliberately uninformative.
|
|
334
|
+
*
|
|
335
|
+
* **Set-Cookie is re-attached one header at a time.** A callback response expires the state cookie, and
|
|
336
|
+
* folding several cookies into one comma-joined header is how a browser that would have accepted them
|
|
337
|
+
* silently keeps them instead.
|
|
338
|
+
*
|
|
339
|
+
* ## Two things the caller chooses, and neither may choose the answer
|
|
340
|
+
*
|
|
341
|
+
* The `Location` this reads is built from `errorCallbackURL`, which arrives in the body of
|
|
342
|
+
* `POST /sign-in/social`. An earlier draft read it as though Better Auth had built the whole thing, and
|
|
343
|
+
* both halves of that assumption were wrong:
|
|
344
|
+
*
|
|
345
|
+
* - **It need not be absolute.** `api/middlewares/origin-check.mjs` passes `allowRelativePaths: true`,
|
|
346
|
+
* `matchesOriginPattern` admits `/path?query`, `oauth2/state.mjs` stores the value as a bare
|
|
347
|
+
* `z.string().optional()`, and `redirectOnError` concatenates it raw. So a relative `Location` is a
|
|
348
|
+
* supported answer, and returning `undefined` to one sent the true code to the browser and wrote no
|
|
349
|
+
* audit row.
|
|
350
|
+
* - **`error` need not be the only one.** `redirectOnError` *appends* `&error=<code>`. An
|
|
351
|
+
* `errorCallbackURL` ending `?error=access_denied` therefore answers
|
|
352
|
+
* `?error=access_denied&error=account_not_linked`, and `searchParams.get` reads the planted value.
|
|
353
|
+
*
|
|
354
|
+
* So: a relative target is resolved against the request the way a browser resolves it, and **every**
|
|
355
|
+
* `error` value is put to the roster rather than the first.
|
|
356
|
+
*
|
|
357
|
+
* **Both of those shapes are now refused or normalized before the flow starts** (`./errorCallbackUrl`),
|
|
358
|
+
* and this handling stays anyway — the collapse still has to work on a `Location` whose `errorURL`
|
|
359
|
+
* came from `defaultErrorURL` rather than from a caller, and on whatever a future dependency writes
|
|
360
|
+
* there. What it cannot do is be the only guard: the third bypass was a fragment, and a fragment is
|
|
361
|
+
* precisely the shape a query parser cannot see. That is the whole argument for the other end.
|
|
362
|
+
*
|
|
363
|
+
* @param requestUrl The absolute URL of the request being answered — the callback's own, which a relative
|
|
364
|
+
* `Location` resolves against. Callers pass `c.req.raw.url`.
|
|
365
|
+
*/
|
|
366
|
+
export function collapseProviderRefusal(requestUrl: string, response: Response): CollapsedRefusal | undefined {
|
|
367
|
+
let request: URL;
|
|
368
|
+
try {
|
|
369
|
+
request = new URL(requestUrl);
|
|
370
|
+
} catch {
|
|
371
|
+
return undefined;
|
|
372
|
+
}
|
|
373
|
+
// Only the OAuth callback issues this redirect. Scoped to it rather than applied to every `?error=`
|
|
374
|
+
// this capability might ever return, so nothing else acquires a rewriting middleware by accident.
|
|
375
|
+
// Matched against the path alone, so a query parameter cannot talk its way into this branch.
|
|
376
|
+
if (!request.pathname.includes("/callback/")) return undefined;
|
|
377
|
+
if (response.status < 300 || response.status >= 400) return undefined;
|
|
378
|
+
const location = response.headers.get("location");
|
|
379
|
+
if (!location) return undefined;
|
|
380
|
+
|
|
381
|
+
let target: URL;
|
|
382
|
+
try {
|
|
383
|
+
target = new URL(location);
|
|
384
|
+
} catch {
|
|
385
|
+
try {
|
|
386
|
+
target = new URL(location, request);
|
|
387
|
+
} catch {
|
|
388
|
+
// Not a location any resolution accepts, so it carries no query to read and no target to rewrite.
|
|
389
|
+
return undefined;
|
|
390
|
+
}
|
|
391
|
+
}
|
|
392
|
+
|
|
393
|
+
// The verdicts decide, and all of them do. One collapsing code anywhere in the list is the whole
|
|
394
|
+
// condition — the caller controls the order, so "the first one" is the caller's answer, not the roster's.
|
|
395
|
+
const collapsing = target.searchParams
|
|
396
|
+
.getAll("error")
|
|
397
|
+
.filter((code) => PROVIDER_REFUSAL_VERDICTS[code]?.collapse === true);
|
|
398
|
+
if (collapsing.length === 0) return undefined;
|
|
399
|
+
|
|
400
|
+
// `set` replaces the first `error` and drops the rest, which is exactly the contract: one answer. A
|
|
401
|
+
// value the caller planted beside the real one is not a second answer worth forwarding.
|
|
402
|
+
target.searchParams.set("error", NEUTRAL_PROVIDER_REFUSAL);
|
|
403
|
+
target.searchParams.delete("error_description");
|
|
404
|
+
|
|
405
|
+
const headers = new Headers();
|
|
406
|
+
for (const [name, value] of response.headers) {
|
|
407
|
+
if (name.toLowerCase() !== "set-cookie") headers.append(name, value);
|
|
408
|
+
}
|
|
409
|
+
for (const cookie of response.headers.getSetCookie()) headers.append("set-cookie", cookie);
|
|
410
|
+
// A root-relative target goes back root-relative, because that is what the adopter configured and this
|
|
411
|
+
// Worker's own origin is not necessarily theirs. Only that one shape: `//host/path` is *also* relative
|
|
412
|
+
// and resolves to another origin, so answering it as `/path` would quietly retarget the redirect here.
|
|
413
|
+
const rootRelative = location.startsWith("/") && !location.startsWith("//");
|
|
414
|
+
headers.set("location", rootRelative ? `${target.pathname}${target.search}${target.hash}` : target.toString());
|
|
415
|
+
|
|
416
|
+
return {
|
|
417
|
+
response: new Response(response.body, {
|
|
418
|
+
status: response.status,
|
|
419
|
+
statusText: response.statusText,
|
|
420
|
+
headers,
|
|
421
|
+
}),
|
|
422
|
+
reason: collapsing.join(" "),
|
|
423
|
+
};
|
|
424
|
+
}
|
package/src/http/resolve.ts
CHANGED
|
@@ -160,6 +160,9 @@ async function buildAuthInstance(c: Context<PithyHonoEnv>, wiring: AuthWiring):
|
|
|
160
160
|
// Read the emit seam lazily so a later-composed audit capability is honored regardless of the
|
|
161
161
|
// capability order (the instance may be built before audit's middleware runs).
|
|
162
162
|
emit: (event) => c.var.emit(event),
|
|
163
|
+
// This request's own headers, for the refusal rows `../instance/providerSignInGate` writes from
|
|
164
|
+
// inside `getUserInfo`, where no request is in scope to read them from.
|
|
165
|
+
requestHeaders: c.req.raw.headers,
|
|
163
166
|
// The adopter's additional Better Auth plugins, exactly as `auth({ plugins: [...] })` declared them
|
|
164
167
|
// and already checked for additivity at `auth()` call time. The same list the derived migrations
|
|
165
168
|
// were built from — the routes a plugin serves and the tables it needs come from one declaration.
|
package/src/http/routes.ts
CHANGED
|
@@ -23,9 +23,11 @@ import {
|
|
|
23
23
|
revokeFamily,
|
|
24
24
|
} from "../token/rotation";
|
|
25
25
|
import { registerAuthAdminRoutes } from "./adminRoutes";
|
|
26
|
+
import { guardErrorCallbackURL } from "./errorCallbackUrl";
|
|
26
27
|
import { apiErrorToPithy } from "./errors";
|
|
27
28
|
import { requireAuth } from "./middleware";
|
|
28
29
|
import { requireFreshAuthentication } from "./providerFreshness";
|
|
30
|
+
import { collapseProviderRefusal } from "./providerRefusal";
|
|
29
31
|
import { getAuthInstance, resolveDb } from "./resolve";
|
|
30
32
|
import { RevokeDeviceBody } from "./schemas";
|
|
31
33
|
|
|
@@ -190,12 +192,47 @@ async function auditRefusal(c: Ctx, response: Response): Promise<void> {
|
|
|
190
192
|
*/
|
|
191
193
|
async function handleBetterAuth(c: Ctx, wiring: AuthWiring): Promise<Response> {
|
|
192
194
|
const instance = await getAuthInstance(c, wiring);
|
|
195
|
+
|
|
196
|
+
// **The first of the two guards on the refusal redirect (#625).** `errorCallbackURL` is the caller's
|
|
197
|
+
// string and `redirectOnError` concatenates it without parsing, so the shape handed *in* decides
|
|
198
|
+
// whether the collapse below is reading a query at all. `./errorCallbackUrl` normalizes it to something
|
|
199
|
+
// the kit produced, or refuses it — and carries the argument for why guarding the input is not the same
|
|
200
|
+
// job as reading the output, and why both stay.
|
|
201
|
+
const request = await guardErrorCallbackURL(c.req.raw, c.req.raw.url);
|
|
202
|
+
|
|
193
203
|
let response: Response;
|
|
194
204
|
try {
|
|
195
|
-
response = await instance.handler(
|
|
205
|
+
response = await instance.handler(request);
|
|
196
206
|
} catch (error) {
|
|
197
207
|
throw apiErrorToPithy(error);
|
|
198
208
|
}
|
|
209
|
+
|
|
210
|
+
// **The enumeration oracle on the social callback, closed here because here is the only place both
|
|
211
|
+
// halves are in reach (#625).** A refused social sign-in redirects with a code that says whether an
|
|
212
|
+
// account exists at the address the provider handed over; `./providerRefusal` carries the full
|
|
213
|
+
// argument and the roster. The collapse has to happen where the capability hands the response back,
|
|
214
|
+
// rather than in an adopter's middleware, for a reason this line demonstrates: middleware could
|
|
215
|
+
// rewrite the header and would then hold nothing to record, while from here the neutral code goes on
|
|
216
|
+
// the wire *and* the true reason goes on the trail.
|
|
217
|
+
//
|
|
218
|
+
// **What this reads is the `Location` header, and that is the whole of the claim.** A composed plugin
|
|
219
|
+
// that replaced the callback's response with a body carrying the code leaves nothing here to collapse,
|
|
220
|
+
// so such a plugin is refused where it is composed instead — `../instance/refusalTransport`, gated in
|
|
221
|
+
// `assertAdditivePlugins`. The guarantee is the kit's own routes plus any plugin that answers refusals
|
|
222
|
+
// through `Location`; it is stated that way in `./providerRefusal` and it is bounded that way here.
|
|
223
|
+
const collapsed = collapseProviderRefusal(c.req.raw.url, response);
|
|
224
|
+
if (collapsed) {
|
|
225
|
+
// **A 302 is not in `DENIED_STATUSES`, and this does not change that.** Widening it would be wrong:
|
|
226
|
+
// a 302 is also what a *successful* OAuth callback answers with, so `auditRefusal` — which knows
|
|
227
|
+
// only a status and a JSON body — would either read every completed social sign-in as a denial or
|
|
228
|
+
// have to re-derive this decision from the Location header it is not looking at. The refusal is
|
|
229
|
+
// recorded from the one place that has already established it is a refusal and knows which one, so
|
|
230
|
+
// these refusals reach `pithy_audit_events` for the first time (#449 closed the same gap for the
|
|
231
|
+
// JSON refusals and could not see this one, because it is not a JSON refusal).
|
|
232
|
+
await emitDenied(c.var.emit, { ...correlation(c.req.raw.headers), detail: collapsed.reason });
|
|
233
|
+
return collapsed.response;
|
|
234
|
+
}
|
|
235
|
+
|
|
199
236
|
await auditRefusal(c, response);
|
|
200
237
|
return response;
|
|
201
238
|
}
|