The best way to control Claude Code, Codex and more from any computer or phone
fix(auth): preserve pairing codes after scope rejection (#25222)
Co-authored-by: Alex Southwell <4596216+saphid@users.noreply.github.com>
maria committed
Oct 29, 2026 at 17:58 UTC
7860ee983d81d287eaf15664ffd92dc6964d92cc
5 files changed
+67
-12
apps/server/src/auth/EnvironmentAuth.test.ts
+29
@@ -377,6 +377,35 @@ it.layer(NodeServices.layer)("EnvironmentAuth.layer", (it) => {
377
}).pipe(Effect.provide(layerEnvironmentAuth())),
378
);
379
380
+ it.effect(
381
+ "preserves a rejected MCP pairing code for exactly one concurrent lower-access retry",
382
+ () =>
383
+ Effect.gen(function* () {
384
+ const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
385
+ const pairing = yield* serverAuth.issuePairingCredential({
386
+ scopes: ["orchestration:read"],
387
+ });
388
+
389
+ const rejected = yield* Effect.flip(
390
+ serverAuth.consumeMcpApprovalCode(pairing.credential, "full-access"),
391
+ );
392
+ expect(rejected).toMatchObject({
393
+ _tag: "ServerAuthMcpApprovalCodeError",
394
+ reason: "insufficient_scope",
395
+ });
396
+
397
+ const retry = Effect.result(
398
+ serverAuth.consumeMcpApprovalCode(pairing.credential, "read-only"),
399
+ );
400
+ const results = yield* Effect.all([retry, retry], { concurrency: "unbounded" });
401
+
402
+ expect(results.filter((result) => result._tag === "Success")).toHaveLength(1);
403
+ expect(results.filter((result) => result._tag === "Failure")).toMatchObject([
404
+ { failure: { _tag: "ServerAuthMcpApprovalCodeError", reason: "unknown_or_used" } },
405
+ ]);
406
+ }).pipe(Effect.provide(layerEnvironmentAuth())),
407
+ );
408
+
409
it.effect("narrows seeded desktop grants to the requested scopes", () =>
410
Effect.gen(function* () {
411
const serverAuth = yield* EnvironmentAuth.EnvironmentAuth;
apps/server/src/auth/EnvironmentAuth.ts
+10
-5
@@ -429,7 +429,7 @@ export class ServerAuthMcpApprovalCodeError extends Schema.TaggedError<ServerAut
429
) {
430
override get message(): string {
431
return this.reason === "insufficient_scope"
432
- ? "That pairing code cannot grant this access, and it is now used up. Create one with the standard scopes, or choose Read only with a new code."
432
+ ? "That pairing code cannot grant this access. It has not been used, so choose an access level it grants, or create a code with the standard scopes."
433
: this.reason === "not_a_pairing_code"
434
? "That is not a one-time pairing code."
435
: "That pairing code is unknown, expired, or already used.";
@@ -902,6 +902,7 @@ export const make = Effect.gen(function* () {
902
input?: {
903
readonly proofKeyThumbprint?: string;
904
readonly requestedScopes?: ReadonlyArray<AuthEnvironmentScope>;
905
+ readonly requiredScopes?: ReadonlyArray<AuthEnvironmentScope>;
906
},
907
): Effect.Effect<
908
ResolvedBootstrapGrant,
@@ -920,6 +921,12 @@ export const make = Effect.gen(function* () {
921
}
922
return sessions.verify(credential).pipe(
923
mapSessionVerificationErrors,
924
+ Effect.filterOrFail(
925
+ (session) =>
926
+ input?.requiredScopes === undefined ||
927
+ input.requiredScopes.every((scope) => session.scopes.includes(scope)),
928
+ () => new ServerAuthScopeNotGrantedError({}),
929
+ ),
930
Effect.map(
931
(session) =>
932
({
@@ -1340,7 +1347,7 @@ export const make = Effect.gen(function* () {
1347
code,
1348
access,
1349
) =>
1343
- resolveBootstrapGrant(code.trim()).pipe(
1350
+ resolveBootstrapGrant(code.trim(), { requiredScopes: mcpClientScopes(access) }).pipe(
1351
Effect.catchTags({
1352
ServerAuthInvalidCredentialError: () =>
1353
Effect.fail(new ServerAuthMcpApprovalCodeError({ reason: "unknown_or_used" })),
@@ -1350,9 +1357,7 @@ export const make = Effect.gen(function* () {
1357
Effect.flatMap((grant) =>
1358
grant.method !== "one-time-token" && grant.method !== "reusable-dev-token"
1359
? Effect.fail(new ServerAuthMcpApprovalCodeError({ reason: "not_a_pairing_code" }))
1353
- : mcpClientScopes(access).every((scope) => grant.scopes.includes(scope))
1354
- ? Effect.void
1355
- : Effect.fail(new ServerAuthMcpApprovalCodeError({ reason: "insufficient_scope" })),
1360
+ : Effect.void,
1361
),
1362
Effect.withSpan("EnvironmentAuth.consumeMcpApprovalCode"),
1363
);
apps/server/src/auth/McpOAuth.test.ts
+1
-2
@@ -457,11 +457,10 @@ it.live(
457
});
458
expect(operatorFull.status).toBe(400);
459
460
- const readOnlyCode = yield* auth.issuePairingCredential({ scopes: ["orchestration:read"] });
460
const readOnlyApproval = yield* decide(handler, params, {
461
_tag: "pairing-code",
462
access: "read-only",
464
- code: readOnlyCode.credential,
463
+ code: readOnly.credential,
464
});
465
expect(readOnlyApproval.status).toBe(200);
466
const readOnlyToken = yield* handler(
apps/server/src/auth/PairingGrantStore.ts
+11
-4
@@ -226,6 +226,8 @@ export class PairingGrantStore extends Context.Service<
226
input?: {
227
readonly proofKeyThumbprint?: string;
228
readonly requestedScopes?: ReadonlyArray<AuthEnvironmentScope>;
229
+ /** All scopes must be granted; requestedScopes only requires an overlap for OAuth. */
230
+ readonly requiredScopes?: ReadonlyArray<AuthEnvironmentScope>;
231
},
232
) => Effect.Effect<BootstrapGrant, BootstrapCredentialError>;
233
}
@@ -486,8 +488,10 @@ const make = Effect.gen(function* () {
488
}
489
490
if (
489
- input?.requestedScopes !== undefined &&
490
- !input.requestedScopes.some((scope) => grant.scopes.includes(scope))
491
+ (input?.requestedScopes !== undefined &&
492
+ !input.requestedScopes.some((scope) => grant.scopes.includes(scope))) ||
493
+ (input?.requiredScopes !== undefined &&
494
+ !input.requiredScopes.every((scope) => grant.scopes.includes(scope)))
495
) {
496
return [
497
{
@@ -550,6 +554,7 @@ const make = Effect.gen(function* () {
554
...(input?.requestedScopes !== undefined
555
? { requestedScopes: input.requestedScopes }
556
: {}),
557
+ ...(input?.requiredScopes !== undefined ? { requiredScopes: input.requiredScopes } : {}),
558
consumedAt: now,
559
now,
560
})
@@ -596,8 +601,10 @@ const make = Effect.gen(function* () {
601
}
602
603
if (
599
- input?.requestedScopes !== undefined &&
600
- !input.requestedScopes.some((scope) => matching.value.scopes.includes(scope))
604
+ (input?.requestedScopes !== undefined &&
605
+ !input.requestedScopes.some((scope) => matching.value.scopes.includes(scope))) ||
606
+ (input?.requiredScopes !== undefined &&
607
+ !input.requiredScopes.every((scope) => matching.value.scopes.includes(scope)))
608
) {
609
return yield* new BootstrapCredentialScopeNotGrantedError({});
610
}
apps/server/src/persistence/AuthPairingLinks.ts
+16
-1
@@ -48,6 +48,7 @@ export const ConsumeAuthPairingLinkInput = Schema.Struct({
48
credential: Schema.String,
49
proofKeyThumbprint: Schema.NullOr(Schema.String),
50
requestedScopes: Schema.optionalKey(AuthEnvironmentScopes),
51
+ requiredScopes: Schema.optionalKey(AuthEnvironmentScopes),
52
consumedAt: Schema.DateTimeUtcFromString,
53
now: Schema.DateTimeUtcFromString,
54
});
@@ -161,7 +162,14 @@ export const make = Effect.gen(function* () {
162
const consumeAvailablePairingLinkRow = SqlSchema.findOneOption({
163
Request: ConsumeAuthPairingLinkInput,
164
Result: AuthPairingLinkRawDbRow,
164
- execute: ({ credential, proofKeyThumbprint, requestedScopes, consumedAt, now }) =>
165
+ execute: ({
166
+ credential,
167
+ proofKeyThumbprint,
168
+ requestedScopes,
169
+ requiredScopes,
170
+ consumedAt,
171
+ now,
172
+ }) =>
173
sql`
174
UPDATE auth_pairing_links
175
SET consumed_at = ${consumedAt}
@@ -180,6 +188,13 @@ export const make = Effect.gen(function* () {
188
SELECT value FROM json_each(auth_pairing_links.scopes)
189
)
190
))
191
+ AND NOT EXISTS (
192
+ SELECT 1
193
+ FROM json_each(${JSON.stringify(requiredScopes ?? [])}) AS required
194
+ WHERE required.value NOT IN (
195
+ SELECT value FROM json_each(auth_pairing_links.scopes)
196
+ )
197
+ )
198
RETURNING
199
id AS "id",
200
credential AS "credential",