Skip to content

Commit 01e2f33

Browse files
committed
refactor(plugin-auth): the hand-off reads trustedAppSchemes and its route names from the spec
The spec slice (#29736) landed AuthConfig.trustedAppSchemes, TrustedAppSchemeSchema and AuthEndpointPaths.oneTimeTokenHandoff/oneTimeTokenVerify. appSchemeRefusal now runs the imported schema instead of a local copy of its rule (the local copy accepted an empty or trailing label: com..app, com.example.), the temporary AuthManagerOptions.trustedAppSchemes declaration is gone, the two path constants derive from the spec, and the changeset states ruling A and the stricter rule. Claude-Session: https://claude.ai/code/session_01JQwxbZkE4E6sE72j23Afwx Co-authored-by: Claude <noreply@anthropic.com>
1 parent 7cbd845 commit 01e2f33

4 files changed

Lines changed: 19 additions & 25 deletions

File tree

‎.changeset/29714-mobile-sign-in-handoff.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ Metadata-protocol: none
1010
Some identity providers (Google among them) refuse to sign a user in inside an embedded WebView, so a mobile shell signs in in the platform's system auth session, where the session lands in the system browser rather than in the WebView the Console runs in. A deployment that lists its app's custom URL scheme in `trustedAppSchemes` now gets a way to carry that session across, once:
1111

1212
- **`GET /api/v1/auth/one-time-token/handoff`** (session required). Query: `redirect_uri` (an app callback), `code_challenge` (RFC 7636 S256: `BASE64URL(SHA-256(code_verifier))`, 43 characters) and optionally `code_challenge_method=S256`; no other parameter is accepted. It answers `302` to `redirect_uri` with a `token` query parameter added, uncacheable. A `redirect_uri` whose scheme is not registered answers `400 VALIDATION_ERROR` with no redirect, so the route is never an open redirect; a missing or malformed challenge also answers `400`, and a signed-out caller `401 UNAUTHENTICATED`.
13+
- **The hand-off carries only a fresh sign-in.** A session signed in more than five minutes ago answers `401 UNAUTHENTICATED` (sign in again), so an app cannot silently carry away a session the browser has held for days; and a navigation the browser reports as `Sec-Fetch-Site: cross-site` answers `400 VALIDATION_ERROR` (the header is checked only when the browser sends it).
1314
- **`POST /api/v1/auth/one-time-token/verify`** (better-auth's route, no session needed). Body: `{ "token": "TOKEN.code_verifier" }`. It answers better-auth's `{ session, user }` with the session cookie, once, within one minute.
1415
- **An intercepted callback cannot be redeemed.** Another app on the device can register the same scheme and receive the callback, so the token is stored under a hash of the token and the challenge, and redemption recomputes it from the verifier the shell kept. A token presented without that verifier answers better-auth's `400 Invalid token` and consumes nothing, so the shell that started the hand-off still redeems it.
1516
- **`GET /api/v1/auth/one-time-token/generate`** is published by the plugin and refuses every client request (`400` with a session, `401` without); the hand-off is the only place a token is minted.
16-
- **`trustedAppSchemes`** entries must be lowercase reverse-domain private-use schemes with no `:` suffix (RFC 8252 §7.1, e.g. `com.example.app`); `http`, `https`, `javascript`, `data`, `file`, `blob`, `about`, `vbscript`, `ws` and `wss` are refused. A bad entry fails the auth manager's construction (and `applyConfigPatch`), naming the entry. With no scheme registered, the plugin is not mounted and the hand-off refuses every target.
17+
- **`trustedAppSchemes`** (the spec's `AuthConfig.trustedAppSchemes`) entries must be lowercase reverse-domain private-use schemes with no `:` suffix (RFC 8252 §7.1, e.g. `com.example.app`, no empty or trailing label); `http`, `https`, `javascript`, `data`, `file`, `blob`, `about`, `vbscript`, `ws` and `wss` are refused. A bad entry fails the auth manager's construction (and `applyConfigPatch`), naming the entry. With no scheme registered, the plugin is not mounted and the hand-off refuses every target.

‎packages/plugins/plugin-auth/src/auth-manager.ts‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -666,13 +666,6 @@ export function readInvitationPlacementIntent(
666666
}
667667

668668
export interface AuthManagerOptions extends Partial<AuthConfig> {
669-
/**
670-
* The app schemes the mobile sign-in hand-off may redirect a one-time token
671-
* to (`one-time-token-handoff.ts`). Declared here only until the spec's
672-
* `AuthConfig` carries the key; then this line goes and the spec's wins.
673-
*/
674-
trustedAppSchemes?: string[];
675-
676669
/**
677670
* Better-Auth instance (for advanced use cases)
678671
* If not provided, one will be created from config

‎packages/plugins/plugin-auth/src/one-time-token-handoff.test.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -331,7 +331,7 @@ describe('one-time-token hand-off — the request is validated before anything i
331331
describe('trustedAppSchemes — refused at construction, never dropped', () => {
332332
it.each([
333333
['https'], ['HTTPS'], ['javascript'], ['data'],
334-
['Com.Example.App'], ['com.example.app://'], ['com.example.app:'], ['myapp'], [''], [42],
334+
['Com.Example.App'], ['com.example.app://'], ['com.example.app:'], ['myapp'], ['com..app'], ['com.example.'], [''], [42],
335335
])('refuses %j', (entry) => {
336336
expect(appSchemeRefusal(entry)).toBeDefined();
337337
expect(() => assertTrustedAppSchemes(['com.example.ok', entry])).toThrow(/invalid trustedAppSchemes/);

‎packages/plugins/plugin-auth/src/one-time-token-handoff.ts‎

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -93,12 +93,14 @@
9393
import { AsyncLocalStorage } from 'node:async_hooks';
9494
import { createHash, randomBytes } from 'node:crypto';
9595
import { repeatedQueryParamMessage, unknownQueryParamRefusalMessage } from '@objectstack/rest';
96+
import { AuthEndpointPaths } from '@objectstack/spec/api';
97+
import { TrustedAppSchemeSchema } from '@objectstack/spec/system';
9698

97-
/** The hand-off route under the auth base path (an ObjectStack mount). */
98-
export const ONE_TIME_TOKEN_HANDOFF_PATH = '/one-time-token/handoff';
99+
/** The hand-off route under the auth base path (an ObjectStack mount), as the spec names it. */
100+
export const ONE_TIME_TOKEN_HANDOFF_PATH = AuthEndpointPaths.oneTimeTokenHandoff;
99101

100-
/** The vendor plugin's redemption route under the auth base path. */
101-
export const ONE_TIME_TOKEN_VERIFY_PATH = '/one-time-token/verify';
102+
/** The vendor plugin's redemption route under the auth base path, as the spec names it. */
103+
export const ONE_TIME_TOKEN_VERIFY_PATH = AuthEndpointPaths.oneTimeTokenVerify;
102104

103105
/** The vendor plugin's generate route; refused over HTTP (`disableClientRequest`). */
104106
export const ONE_TIME_TOKEN_GENERATE_PATH = '/one-time-token/generate';
@@ -188,26 +190,24 @@ export async function oneTimeTokenStoreHasher(input: string): Promise<string> {
188190
return bindingKey(token, s256Challenge(codeVerifier));
189191
}
190192

191-
/**
192-
* A registered app scheme, as RFC 8252 §7.1 requires of a private-use scheme:
193-
* lowercase RFC 3986 scheme syntax containing a dot (reverse-domain, e.g.
194-
* `com.example.app`), with no `:` suffix. The reverse-domain rule is also the
195-
* first interception defence: a scheme named for a domain the app's
196-
* publisher controls is one another app has no business claiming.
197-
*/
198-
const APP_SCHEME_SYNTAX = /^[a-z][a-z0-9+.-]*$/;
199-
200193
/**
201194
* Why `entry` cannot be a registered app scheme, or `undefined` when it can.
202-
* The same rules the spec's `AuthConfig.trustedAppSchemes` refuses at parse;
203-
* repeated here because the auth manager also receives plain objects.
195+
* The rule is the spec's own {@link TrustedAppSchemeSchema} (RFC 8252 §7.1:
196+
* a lowercase reverse-domain private-use scheme such as `com.example.app`,
197+
* with no `:` suffix), imported, never copied: the auth manager also
198+
* receives plain objects that never passed through `AuthConfigSchema`, so
199+
* it runs the same schema again. The reverse-domain rule is also the first
200+
* interception defence: a scheme named for a domain the app's publisher
201+
* controls is one another app has no business claiming.
202+
* {@link NEVER_APP_SCHEMES} is checked first only for the clearer message —
203+
* none of them contains a dot, so the schema refuses each one anyway.
204204
*/
205205
export function appSchemeRefusal(entry: unknown): string | undefined {
206206
if (typeof entry !== 'string') return 'is not a string';
207207
if (NEVER_APP_SCHEMES.includes(entry.toLowerCase().replace(/:.*$/, ''))) {
208208
return 'is a web or script scheme the browser itself handles, never an app scheme';
209209
}
210-
if (!APP_SCHEME_SYNTAX.test(entry) || !entry.includes('.')) {
210+
if (!TrustedAppSchemeSchema.safeParse(entry).success) {
211211
return 'is not a lowercase reverse-domain scheme with no ":" suffix (RFC 8252 §7.1), e.g. "com.example.app"';
212212
}
213213
return undefined;

0 commit comments

Comments
 (0)