Merge pull request #19992 from mozilla/FXA-12929

feat(oauth): Support session token to refresh token migration, add old device association for token exchange

Author: LZoog

packages/fxa-auth-server/lib/routes/oauth/token.js

@@ -75,6 +75,9 @@ const GRANT_TOKEN_EXCHANGE = 'urn:ietf:params:oauth:grant-type:token-exchange';
 const SUBJECT_TOKEN_TYPE_REFRESH =
   'urn:ietf:params:oauth:token-type:refresh_token';
 
+// For Desktop apps migrating from using the session token to a refresh token
+const CREDENTIALS_REASON_MIGRATION = 'token_migration';
+
 const ACCESS_TYPE_ONLINE = 'online';
 const ACCESS_TYPE_OFFLINE = 'offline';
 
@@ -440,6 +443,13 @@ module.exports = ({ log, oauthDB, db, mailer, devices, statsd, glean }) => {
     //  Original scope plus requested scope, e.g. Sync + Relay
     const combinedScope = subjectToken.scope.union(requestedScope);
 
+    // Look up the device associated with the old refresh token so we can
+    // link the new refresh token to the same device record
+    const existingDevice = await db.deviceFromRefreshTokenId(
+      hex(subjectToken.userId),
+      hex(subjectToken.tokenId)
+    );
+
     return {
       userId: subjectToken.userId,
       clientId: subjectToken.clientId,
@@ -448,6 +458,7 @@ module.exports = ({ log, oauthDB, db, mailer, devices, statsd, glean }) => {
       authAt: Math.floor(Date.now() / 1000),
       profileChangedAt: subjectToken.profileChangedAt,
       originalRefreshTokenId: subjectToken.tokenId, // for revocation after new token generation
+      existingDeviceId: existingDevice ? existingDevice.id : undefined, // to link new token to existing device
     };
   }
 
@@ -518,13 +529,22 @@ module.exports = ({ log, oauthDB, db, mailer, devices, statsd, glean }) => {
     glean.oauth.tokenCreated(req, {
       uid,
       oauthClientId,
-      reason: params.grant_type,
+      reason: params.reason
+        ? `${params.grant_type}:${params.reason}`
+        : params.grant_type,
     });
 
     if (tokens.keys_jwe) {
       statsd.increment('oauth.rp.keys-jwe', { clientId: oauthClientId });
     }
 
+    // Include grant properties needed by the /oauth/token handler for newTokenNotification.
+    // These are internal properties that get stripped before returning to the client.
+    tokens._clientId = oauthClientId;
+    if (grant.existingDeviceId) {
+      tokens._existingDeviceId = grant.existingDeviceId;
+    }
+
     return tokens;
   }
 
@@ -568,7 +588,13 @@ module.exports = ({ log, oauthDB, db, mailer, devices, statsd, glean }) => {
               .description(DESCRIPTION.keysJweOauth),
           }),
         },
-        handler: tokenHandler,
+        handler: async (req) => {
+          const result = await tokenHandler(req);
+          // Strip internal properties that are only used by /oauth/token handler
+          delete result._clientId;
+          delete result._existingDeviceId;
+          return result;
+        },
       },
     },
     {
@@ -641,6 +667,12 @@ module.exports = ({ log, oauthDB, db, mailer, devices, statsd, glean }) => {
               ttl: Joi.number().positive().optional(),
               resource: validators.resourceUrl.optional(),
               assertion: Joi.forbidden(),
+              // 'token_migration' indicates a silent migration from session token to
+              // refresh token for an already-authenticated user (e.g., for Relay/Sync).
+              // This skips the new token notification email.
+              reason: Joi.string()
+                .valid(CREDENTIALS_REASON_MIGRATION)
+                .optional(),
             }),
             // token exchange (RFC 8693)
             Joi.object({
@@ -788,18 +820,35 @@ module.exports = ({ log, oauthDB, db, mailer, devices, statsd, glean }) => {
           grant.session_token = newSessionToken.data;
         }
 
-        // Token exchange is swapping tokens for an already-authenticated user,
-        // so we skip the new token notification.
-        if (grant.refresh_token && req.payload.grant_type !== GRANT_TOKEN_EXCHANGE) {
-          // if a refresh token has
-          // been provisioned as part of the flow
-          // then we want to send some notifications to the user
+        // If a refresh token has been provisioned as part of the flow,
+        // link it to the device record and optionally notify the user.
+        // For token exchange and token migration, skip the email notification
+        // since these are for already-authenticated users.
+        //
+        // Device association:
+        // - Token exchange: We look up the device from the old refresh token
+        //   (grant._existingDeviceId) since there's no session token auth.
+        // - Token migration: The session token auth already includes deviceId
+        //   via the SessionWithDevice stored procedure, so it's available in
+        //   request.auth.credentials.deviceId. skipEmail is a fallback for
+        //   sessions without an associated device.
+        if (grant.refresh_token) {
+          const isTokenExchange =
+            req.payload.grant_type === GRANT_TOKEN_EXCHANGE;
+          const isTokenMigration =
+            req.payload.reason === CREDENTIALS_REASON_MIGRATION;
+          const skipEmail = isTokenExchange || isTokenMigration;
           await oauthRouteUtils.newTokenNotification(
             db,
             mailer,
             devices,
             req,
-            grant
+            grant,
+            {
+              skipEmail,
+              existingDeviceId: grant._existingDeviceId,
+              clientId: grant._clientId,
+            }
           );
         }
 
@@ -808,7 +857,9 @@ module.exports = ({ log, oauthDB, db, mailer, devices, statsd, glean }) => {
           await db.touchSessionToken(sessionToken, {}, true);
         }
 
-        // done with 'session_token_id' at this point, do not return it.
+        // Strip internal properties before returning to client
+        delete grant._clientId;
+        delete grant._existingDeviceId;
         delete grant.session_token_id;
 
         // attempt to record metrics, but swallow the error if one is thrown.

packages/fxa-auth-server/lib/routes/utils/oauth.js

@@ -29,12 +29,16 @@ module.exports = {
     mailer,
     devices,
     request,
-    grant
+    grant,
+    options = {}
   ) {
+    const { skipEmail = false, existingDeviceId, clientId: optionsClientId } = options;
     const fxaMailer = Container.get(FxaMailer);
     const oauthClientInfoService = Container.get(OAuthClientInfoServiceName);
 
-    const clientId = request.payload.client_id;
+    // Use clientId from options if provided (e.g., for token exchange where
+    // client_id is not in the request payload), otherwise fall back to payload
+    const clientId = optionsClientId || request.payload.client_id;
     const scopeSet = ScopeSet.fromString(grant.scope);
     const credentials = (request.auth && request.auth.credentials) || {};
 
@@ -66,6 +70,12 @@ module.exports = {
       credentials.id = grant.session_token_id;
     }
 
+    // Use existing device ID if provided (e.g., from token exchange where we looked
+    // up the device associated with the old refresh token)
+    if (!credentials.deviceId && existingDeviceId) {
+      credentials.deviceId = existingDeviceId;
+    }
+
     // we set tokenVerified because the granted scope is part of NOTIFICATION_SCOPES
     credentials.tokenVerified = true;
     credentials.client = await client.getClientById(clientId);
@@ -78,8 +88,8 @@ module.exports = {
     });
 
     // Email the user about their new device connection
-    // (but don't send anything if it was an existing device or new account)
-    if (!credentials.deviceId) {
+    // (but don't send anything if it was an existing device, new account, or skipEmail is set)
+    if (!credentials.deviceId && !skipEmail) {
       const account = await db.account(credentials.uid);
       const isNewAccount = Date.now() - account.createdAt < MAX_NEW_ACCOUNT_AGE;
 

packages/fxa-auth-server/test/local/routes/utils/oauth.js

@@ -137,4 +137,41 @@ describe('newTokenNotification', () => {
     assert.equal(args[1].refreshTokenId, MOCK_REFRESH_TOKEN_ID_2);
     assert.equal(args[2].id, MOCK_DEVICE_ID);
   });
+
+  it('creates a device but skips email when skipEmail option is true', async () => {
+    await oauthUtils.newTokenNotification(db, mailer, devices, request, grant, {
+      skipEmail: true,
+    });
+
+    assert.equal(fxaMailer.sendNewDeviceLoginEmail.callCount, 0);
+    assert.equal(devices.upsert.callCount, 1, 'created a device');
+    const args = devices.upsert.args[0];
+    assert.equal(
+      args[1].refreshTokenId,
+      request.auth.credentials.refreshTokenId
+    );
+  });
+
+  it('uses existingDeviceId when provided and credentials has no deviceId', async () => {
+    const EXISTING_DEVICE_ID = 'existingdevice123456';
+    // credentials without deviceId
+    credentials = {
+      uid: MOCK_UID,
+      refreshTokenId: MOCK_REFRESH_TOKEN,
+    };
+    request = mocks.mockRequest({ credentials });
+
+    await oauthUtils.newTokenNotification(db, mailer, devices, request, grant, {
+      existingDeviceId: EXISTING_DEVICE_ID,
+    });
+
+    // Should not send email since we have an existing device
+    assert.equal(fxaMailer.sendNewDeviceLoginEmail.callCount, 0);
+    assert.equal(devices.upsert.callCount, 1, 'updated the device');
+    const args = devices.upsert.args[0];
+    // Should use the existingDeviceId for the upsert
+    assert.equal(args[2].id, EXISTING_DEVICE_ID);
+    // credentials.deviceId should be set
+    assert.equal(args[1].deviceId, EXISTING_DEVICE_ID);
+  });
 });