5151 * consumes nothing: the real holder still redeems afterwards. The verifier
5252 * never leaves the device (only its hash travels, in step 2).
5353 *
54+ * ## Who can open it (maintainer ruling A, card comment 6597001931)
55+ *
56+ * The binding stops a callback being redeemed by an app that intercepts it.
57+ * It does not stop an app or a web page from OPENING the hand-off itself,
58+ * with its own challenge, in a browser that already holds the user's session.
59+ * Two refusals close that:
60+ *
61+ * - **Freshness.** The session must have been created within
62+ * {@link ONE_TIME_TOKEN_HANDOFF_SESSION_MAX_AGE_SECONDS}; an older one
63+ * answers `401 UNAUTHENTICATED` (the remedy is a sign-in, the same remedy
64+ * as no session). So the shell completes a full sign-in in the system auth
65+ * session before every hand-off (an ephemeral session is fine); an existing
66+ * Safari or Custom Tabs session is not enough.
67+ * - **Cross-site navigation.** A request carrying `Sec-Fetch-Site:
68+ * cross-site` answers `400 VALIDATION_ERROR` before anything else is read:
69+ * a malformed request context, not a missing sign-in. The header is judged
70+ * only when present.
71+ *
5472 * Generation happens only inside this route ({@link withHandoffChallenge}):
5573 * the plugin's generate endpoint refuses every HTTP request
5674 * (`disableClientRequest`), and a server-side call made outside this route's
@@ -94,6 +112,17 @@ export const ONE_TIME_TOKEN_GENERATE_PATH = '/one-time-token/generate';
94112 */
95113export const ONE_TIME_TOKEN_EXPIRES_IN_MINUTES = 1 ;
96114
115+ /**
116+ * How old the caller's session may be, in SECONDS, for the hand-off to carry
117+ * it (maintainer ruling A on the residual risk this PR raised, card comment
118+ * 6597001931). The hand-off hands over a session the shell has just watched
119+ * the user create in the system auth session; a session older than this was
120+ * made for something else, and a page or app that opens the hand-off against
121+ * it would carry it off silently. Five minutes covers a sign-in with a slow
122+ * second factor.
123+ */
124+ export const ONE_TIME_TOKEN_HANDOFF_SESSION_MAX_AGE_SECONDS = 5 * 60 ;
125+
97126/** The route's CLOSED query-parameter set. */
98127export const ONE_TIME_TOKEN_HANDOFF_QUERY_PARAMS : readonly string [ ] = [
99128 'redirect_uri' ,
@@ -228,8 +257,14 @@ export interface HandoffAnswer {
228257export interface HandoffDeps {
229258 /** The registered app schemes ({@link registeredAppSchemesOf}). */
230259 registeredSchemes : readonly string [ ] ;
231- /** Whether `headers` carry a live session. */
232- hasSession ( headers : Headers ) : Promise < boolean > ;
260+ /**
261+ * When the live session `headers` carry was created, or `null` when they
262+ * carry none: the vendor session's `session.createdAt` (`sys_session.created_at`),
263+ * which a refresh or a bearer replay never moves (those move `updatedAt`).
264+ */
265+ sessionCreatedAt ( headers : Headers ) : Promise < Date | null > ;
266+ /** The clock, for the freshness window; `Date.now` by default. */
267+ now ?: ( ) => number ;
233268 /** The vendor plugin's generate endpoint, called server-side with the caller's headers. */
234269 generate ( headers : Headers ) : Promise < { token : string } > ;
235270}
@@ -256,6 +291,19 @@ function single(queries: Record<string, readonly string[]>, name: string): { val
256291
257292/** `GET /api/v1/auth/one-time-token/handoff` — see the module docblock. */
258293export async function runOneTimeTokenHandoff ( deps : HandoffDeps , request : HandoffRequest ) : Promise < HandoffAnswer > {
294+ // A navigation another site started (a link, a form, a script) arrives with
295+ // `Sec-Fetch-Site: cross-site` and the session cookie, since `SameSite=Lax`
296+ // sends it on a top-level GET. The shell opens the hand-off itself, which a
297+ // browser reports as `none`. Judged only when the header is present: a
298+ // browser that sends none is not refused for its absence (ruling A).
299+ if ( request . headers . get ( 'sec-fetch-site' ) ?. trim ( ) . toLowerCase ( ) === 'cross-site' ) {
300+ return refusal (
301+ 400 ,
302+ 'VALIDATION_ERROR' ,
303+ 'The sign-in hand-off cannot be opened from another site: the app opens it in its own system auth session.' ,
304+ ) ;
305+ }
306+
259307 const unknown = unknownQueryParamRefusalMessage ( request . queries , ONE_TIME_TOKEN_HANDOFF_QUERY_PARAMS ) ;
260308 if ( unknown !== undefined ) return refusal ( 400 , 'VALIDATION_ERROR' , unknown ) ;
261309
@@ -296,9 +344,19 @@ export async function runOneTimeTokenHandoff(deps: HandoffDeps, request: Handoff
296344 return refusal ( 400 , 'VALIDATION_ERROR' , 'The "code_challenge_method" query parameter accepts only "S256".' ) ;
297345 }
298346
299- if ( ! ( await deps . hasSession ( request . headers ) ) ) {
347+ const createdAt = await deps . sessionCreatedAt ( request . headers ) ;
348+ if ( ! createdAt ) {
300349 return refusal ( 401 , 'UNAUTHENTICATED' , 'Sign in first: the hand-off carries the signed-in session of this browser to the app.' ) ;
301350 }
351+ const ageMs = ( deps . now ?? Date . now ) ( ) - createdAt . getTime ( ) ;
352+ if ( ! ( ageMs <= ONE_TIME_TOKEN_HANDOFF_SESSION_MAX_AGE_SECONDS * 1000 ) ) {
353+ return refusal (
354+ 401 ,
355+ 'UNAUTHENTICATED' ,
356+ `Sign in again: the hand-off carries only a session signed in within the last ${ ONE_TIME_TOKEN_HANDOFF_SESSION_MAX_AGE_SECONDS / 60 } minutes, ` +
357+ 'so the app completes a sign-in in its system auth session before every hand-off.' ,
358+ ) ;
359+ }
302360
303361 const { token } = await withHandoffChallenge ( challenge . value , ( ) => deps . generate ( request . headers ) ) ;
304362 target . searchParams . set ( 'token' , token ) ;
0 commit comments