feat(serenity): mint dedicated Semrush IMS token for member-add instead of caller token

The /serenity/members grant is now authenticated by a token minted for a dedicated
Semrush IMS technical account (SEMRUSH_IMS_TECH_ID/SECRET, client_credentials) rather
than the calling user's IMS token. This lets the "user hits 401/403 → provision them"
flow add a user who is not yet a member of the workspace: the mint identity holds the
member-management rights, the end user need not.

- add src/support/serenity/semrush-ims-token.js: mintSemrushImsToken(env, log) —
  client_credentials mint; token endpoint host from IMS_HOST; scope override via
  SEMRUSH_IMS_TECH_SCOPE; 503 on missing config, 502 on IMS failure; never logs secrets.
- controllers/serenity.js addMembers: org-level authorize + validation first, THEN mint
  the dedicated token, THEN call the transport (no more caller/promise-token path here).
- rest-transport addWorkspaceMembers doc updated (bearer = minted dedicated IMS token).
- tests: mint unit tests + addMembers uses-minted-token / mint-after-gate / mint-config
  failure; .env.example documents the new vars.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ravverma

.env.example

@@ -126,5 +126,15 @@ SEO_CLIENT_SECRET=
 # silently point a fresh local stack at the live upstream.
 # SEMRUSH_PROJECTS_BASE_URL=https://adobe-hackathon.semrush.com
 
+# ── Semrush User Manager provisioning (POST /serenity/members) ────────────────
+# Dedicated Semrush IMS technical account whose client_credentials token authorizes
+# the workspace member-add call (NOT the calling user's token — this is what lets the
+# flow provision a user who is not yet a workspace member). Token endpoint host is
+# derived from IMS_HOST; scope defaults to
+# openid,AdobeID,user_management_sdk,additional_info.projectedProductContext.
+# SEMRUSH_IMS_TECH_ID=
+# SEMRUSH_IMS_TECH_SECRET=
+# SEMRUSH_IMS_TECH_SCOPE=
+
 # ── Server port (optional, default 3002) ──────────────────────────────────────
 # PORT=3001

src/controllers/serenity.js

@@ -24,6 +24,7 @@ import {
   resolveBrandWorkspace,
   clearBrandWorkspaceCache,
 } from '../support/serenity/workspace-resolver.js';
+import { mintSemrushImsToken } from '../support/serenity/semrush-ims-token.js';
 import {
   handleListPrompts,
   handleCreatePrompts,
@@ -1233,18 +1234,21 @@ function SerenityController(context, log, env) {
 
   /**
    * POST /serenity/members — grant one or more users a Semrush workspace role
-   * (RBAC write slice; ADR-draft-2 spike). Resolves the brand's workspace via
+   * (RBAC write slice; ADR-draft-2/3). Resolves the brand's workspace via
    * `authorize` (the brand's sub-workspace in subworkspace mode, else the org's
-   * flat parent workspace) and forwards the caller's IMS token to Semrush's User
-   * Manager `POST /v1/workspaces/{ws}/members`. Body: `{ members: string[],
-   * role?: string }`; `role` defaults to `role/workspace/viewer`.
+   * flat parent workspace) and calls Semrush's User Manager
+   * `POST /v1/workspaces/{ws}/members`. Body: `{ members: string[], role?: string }`;
+   * `role` defaults to `role/workspace/viewer`.
    *
-   * Auth: unchanged pass-through — Semrush authorizes the forwarded token, so the
-   * grant only lands if the caller holds member-management rights on the workspace.
+   * Auth: the Adobe caller is authorized here at the ORG level (`authorize` →
+   * AccessControlUtil), but the OUTBOUND Semrush call is authenticated with a token
+   * minted for the DEDICATED Semrush IMS technical account (SEMRUSH_IMS_TECH_*),
+   * NOT the caller's own token. This is what lets the grant provision a user who is
+   * not yet a member of the workspace — the mint identity holds the member-management
+   * rights, so the "user hits 401/403 → provision them" flow can succeed.
    */
   const addMembers = async (ctx) => {
     try {
-      const imsToken = await resolveSemrushImsToken(ctx);
       const auth = await authorize(ctx);
       if (auth.error) {
         return auth.error;
@@ -1257,6 +1261,10 @@ function SerenityController(context, log, env) {
         throw new ErrorWithStatusCode('members must be a non-empty array of user identifiers', 400);
       }
       const role = hasText(body.role) ? body.role : 'role/workspace/viewer';
+      // Mint the dedicated Semrush IMS technical-account token (NOT the caller's) so a
+      // not-yet-a-member user can still be provisioned. Minted only after the org-level
+      // authorize gate + input validation pass, so a bad request never mints a token.
+      const imsToken = await mintSemrushImsToken(ctx.env || env, log);
       const transport = buildTransport(ctx, imsToken);
       const result = await transport.addWorkspaceMembers(
         /** @type {string} */ (auth.workspaceId),

src/support/serenity/rest-transport.js

@@ -1046,11 +1046,11 @@ export function createSerenityTransport({ env, imsToken }) {
     /**
      * POST /v1/workspaces/{ws}/members — grant one or more users a role on the
      * workspace (Semrush RBAC). Body: `{ members: string[], role: string }`
-     * (e.g. role `role/workspace/viewer`). SPIKE (ADR-draft-2): first RBAC write
-     * slice — reuses the already-wired User Manager client + IMS-bearer auth; no
-     * new secret/config. Auth model is unchanged: the CALLER'S IMS token is
-     * forwarded, so the grant succeeds only if that caller holds member-management
-     * rights on the workspace (Semrush is the auth boundary, not this proxy).
+     * (e.g. role `role/workspace/viewer`). ADR-draft-2/3: RBAC write slice that
+     * reuses the already-wired User Manager client. The bearer this transport is
+     * built with is the DEDICATED Semrush IMS technical-account token (minted by
+     * the controller via SEMRUSH_IMS_TECH_*), NOT the calling user's token — so it
+     * can provision a user who is not yet a member of the workspace.
      *
      * `/v1/workspaces/{id}/members` (op `workspace-add-members`) is present in the
      * user-manager-client generated spec with body `{ members: string[]; role: string }`.

src/support/serenity/semrush-ims-token.js

@@ -0,0 +1,117 @@
+/*
+ * Copyright 2026 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+// @ts-check
+
+import { hasText } from '@adobe/spacecat-shared-utils';
+import { ErrorWithStatusCode } from '../utils.js';
+
+const TOKEN_PATH = '/ims/token/v3';
+// Scopes required to manage Semrush workspace members via the User Manager API
+// (user_management_sdk is the operative one). Overridable via SEMRUSH_IMS_TECH_SCOPE.
+const DEFAULT_SCOPES = 'openid,AdobeID,user_management_sdk,additional_info.projectedProductContext';
+
+/**
+ * Builds the IMS token endpoint URL from `IMS_HOST` (accepts a bare host such as
+ * `ims-na1.adobelogin.com` or a full origin). This is only the IMS *host* — the
+ * dedicated Semrush IMS identity's own credentials come from the SEMRUSH_IMS_TECH_*
+ * vars below — so stage/prod stay switchable via the env var the service already
+ * carries, with no extra URL secret.
+ *
+ * @param {object} env
+ * @returns {string} the absolute `/ims/token/v3` URL.
+ */
+function imsTokenUrl(env) {
+  const raw = typeof env?.IMS_HOST === 'string' ? env.IMS_HOST.trim() : '';
+  if (!hasText(raw)) {
+    throw new ErrorWithStatusCode(
+      'IMS_HOST is not set; cannot mint the Semrush IMS token',
+      503,
+    );
+  }
+  const origin = raw.startsWith('http') ? raw : `https://${raw}`;
+  return new URL(TOKEN_PATH, origin).href;
+}
+
+/**
+ * Mints an IMS access token for the DEDICATED Semrush IMS technical account via the
+ * `client_credentials` grant, and returns it for use as the bearer on Semrush User
+ * Manager calls. This deliberately does NOT use the calling user's token: the flow
+ * must be able to provision a user who is not yet a member of the workspace, so the
+ * grant runs as this dedicated Semrush IMS identity (which holds the member-management
+ * rights), not as the end user.
+ *
+ * Credentials come from `SEMRUSH_IMS_TECH_ID` / `SEMRUSH_IMS_TECH_SECRET` (Vault:
+ * dx_mysticat/<env>/api-service). The token endpoint host is derived from `IMS_HOST`;
+ * scopes default to `DEFAULT_SCOPES` and are overridable via `SEMRUSH_IMS_TECH_SCOPE`.
+ *
+ * Never logs the credentials or the minted token — only the IMS-side error code and
+ * HTTP status on failure.
+ *
+ * @param {object} env - runtime env (reads IMS_HOST, SEMRUSH_IMS_TECH_ID,
+ *   SEMRUSH_IMS_TECH_SECRET, optional SEMRUSH_IMS_TECH_SCOPE).
+ * @param {{ error: (msg: string, meta?: object) => void }} log
+ * @returns {Promise<string>} the IMS access token (no 'Bearer ' prefix).
+ */
+export async function mintSemrushImsToken(env, log) {
+  const clientId = typeof env?.SEMRUSH_IMS_TECH_ID === 'string' ? env.SEMRUSH_IMS_TECH_ID.trim() : '';
+  const clientSecret = typeof env?.SEMRUSH_IMS_TECH_SECRET === 'string'
+    ? env.SEMRUSH_IMS_TECH_SECRET.trim()
+    : '';
+  if (!hasText(clientId) || !hasText(clientSecret)) {
+    throw new ErrorWithStatusCode(
+      'SEMRUSH_IMS_TECH_ID and SEMRUSH_IMS_TECH_SECRET must be set to mint the Semrush IMS token',
+      503,
+    );
+  }
+  const scope = hasText(env?.SEMRUSH_IMS_TECH_SCOPE)
+    ? env.SEMRUSH_IMS_TECH_SCOPE.trim()
+    : DEFAULT_SCOPES;
+  const body = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: clientId,
+    client_secret: clientSecret,
+    scope,
+  });
+
+  // Resolve the endpoint BEFORE the network try/catch so a config error (missing
+  // IMS_HOST → 503) is not rewrapped as a 502 transport failure.
+  const url = imsTokenUrl(env);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body,
+    });
+  } catch (e) {
+    throw new ErrorWithStatusCode(
+      `Failed to reach IMS to mint the Semrush IMS token: ${e?.message}`,
+      502,
+    );
+  }
+
+  let json = null;
+  try {
+    json = await response.json();
+  } catch { /* non-JSON error body handled below */ }
+
+  if (!response.ok || !hasText(json?.access_token)) {
+    // Do NOT log the credentials or token — only the IMS-side error signal.
+    log.error('Semrush IMS token mint failed', {
+      status: response.status,
+      imsError: typeof json?.error === 'string' ? json.error : '',
+    });
+    throw new ErrorWithStatusCode('Failed to mint the Semrush IMS token', 502);
+  }
+  return json.access_token;
+}

test/controllers/serenity.test.js

@@ -171,6 +171,7 @@ describe('SerenityController', () => {
   let resolveBrandWorkspaceStub;
   let isSerenityActiveStub;
   let createTransportStub;
+  let mintSemrushImsTokenStub;
   let resolveBrandUuidStub;
   let getBrandAliasesStub;
   let getBrandUrlSourcesStub;
@@ -204,6 +205,7 @@ describe('SerenityController', () => {
     ensureSubworkspaceStub = sinon.stub().resolves(SUBWS);
     clearBrandWorkspaceCacheStub = sinon.stub();
     createTransportStub = sinon.stub().returns({ name: 'transport' });
+    mintSemrushImsTokenStub = sinon.stub().resolves('semrush-ims-tech-token');
     resolveBrandUuidStub = sinon.stub().resolves(BRAND);
     getBrandAliasesStub = sinon.stub().resolves([]);
     getBrandUrlSourcesStub = sinon.stub()
@@ -245,6 +247,9 @@ describe('SerenityController', () => {
         resolveBrandWorkspace: resolveBrandWorkspaceStub,
         clearBrandWorkspaceCache: clearBrandWorkspaceCacheStub,
       },
+      '../../src/support/serenity/semrush-ims-token.js': {
+        mintSemrushImsToken: mintSemrushImsTokenStub,
+      },
       '../../src/support/serenity/handlers/prompts.js': {
         handleListPrompts: handlers.handleListPrompts,
         handleCreatePrompts: handlers.handleCreatePrompts,
@@ -1786,7 +1791,7 @@ describe('SerenityController', () => {
     });
   });
 
-  describe('addMembers (RBAC workspace member grant — ADR-draft-2 spike)', () => {
+  describe('addMembers (RBAC workspace member grant — minted Semrush IMS token)', () => {
     let addWorkspaceMembersStub;
 
     beforeEach(() => {
@@ -1810,6 +1815,17 @@ describe('SerenityController', () => {
       expect(await readBody(response)).to.deep.equal({ consumedUnits: -1 });
     });
 
+    it('authenticates with the MINTED Semrush IMS token, not the caller token', async () => {
+      const controller = SerenityController({ env: {} }, fakeLog(), {});
+      await controller.addMembers(fakeContext({
+        data: { members: ['a@adobe.com'] },
+      }));
+      // The dedicated Semrush IMS token is minted and passed to the transport.
+      expect(mintSemrushImsTokenStub).to.have.been.calledOnce;
+      expect(createTransportStub.firstCall.args[0])
+        .to.have.property('imsToken', 'semrush-ims-tech-token');
+    });
+
     it('defaults the role to role/workspace/viewer when none is supplied', async () => {
       const controller = SerenityController({ env: {} }, fakeLog(), {});
       const response = await controller.addMembers(fakeContext({
@@ -1842,12 +1858,14 @@ describe('SerenityController', () => {
       });
     });
 
-    it('rejects a missing members array with 400 and never calls upstream', async () => {
+    it('rejects a missing members array with 400 — no token minted, no upstream call', async () => {
       const controller = SerenityController({ env: {} }, fakeLog(), {});
       const response = await controller.addMembers(fakeContext({
         data: { role: 'role/workspace/viewer' },
       }));
       expect(response.status).to.equal(400);
+      // Mint happens only after the authorize gate + input validation pass.
+      expect(mintSemrushImsTokenStub).to.not.have.been.called;
       expect(addWorkspaceMembersStub).to.not.have.been.called;
     });
 
@@ -1860,13 +1878,27 @@ describe('SerenityController', () => {
       expect(addWorkspaceMembersStub).to.not.have.been.called;
     });
 
-    it('propagates an authorize failure (no org access) as 403 without calling upstream', async () => {
+    it('propagates an authorize failure (no org access) as 403 — no token minted', async () => {
       accessControlHasAccessStub.resolves(false);
       const controller = SerenityController({ env: {} }, fakeLog(), {});
       const response = await controller.addMembers(fakeContext({
         data: { members: ['a@adobe.com'] },
       }));
       expect(response.status).to.equal(403);
+      expect(mintSemrushImsTokenStub).to.not.have.been.called;
+      expect(addWorkspaceMembersStub).to.not.have.been.called;
+    });
+
+    it('surfaces a token-mint config failure (missing SEMRUSH_IMS_TECH_*) as 503', async () => {
+      mintSemrushImsTokenStub.rejects(
+        new ErrorWithStatusCode('SEMRUSH_IMS_TECH_ID and SEMRUSH_IMS_TECH_SECRET must be set', 503),
+      );
+      const controller = SerenityController({ env: {} }, fakeLog(), {});
+      const response = await controller.addMembers(fakeContext({
+        data: { members: ['a@adobe.com'] },
+      }));
+      expect(response.status).to.equal(503);
+      // Token mint failed → never reach the upstream member add.
       expect(addWorkspaceMembersStub).to.not.have.been.called;
     });