feat(serenity): auto-provision workspace member on read 401/403 (flag-gated)

Productizes the member-add mechanism as the real flow: when a brand-scoped Semrush
data read fails because the caller is not yet a workspace member (401/403), provision
them (viewer) using the dedicated Semrush IMS token and retry the read once.

- add src/support/serenity/member-autoprovision.js: withMemberAutoProvision (single
  retry, best-effort — a failed grant surfaces the original read error; no-op when
  disabled / missing ids / non-401-403) + isSemrushMembershipDenied.
- controllers/serenity.js: wrap the 5 brand-scoped reads (prompts, markets, getMarket,
  tags, models) via readWithProvision; gate on SERENITY_MEMBER_AUTOPROVISION (default
  off) + the existing serenity-active/workspace gate; resolve caller email.
- mapError: surface upstream 422 as unprocessableEntity (was flattened to 502); the
  limit/emails body stays server-side only.
- utils.js: resolveCallerEmail. .env.example documents the flag.
- tests: member-autoprovision (9), addMembers 422 passthrough, read-provision wiring (3).

The standalone POST /serenity/members endpoint is kept for testing and must be removed
before merge.

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

Author: ravverma

.env.example

@@ -135,6 +135,10 @@ SEO_CLIENT_SECRET=
 # SEMRUSH_IMS_TECH_ID=
 # SEMRUSH_IMS_TECH_SECRET=
 # SEMRUSH_IMS_TECH_SCOPE=
+# When 'true', a brand-scoped Semrush READ that 401/403s because the caller is not yet a
+# workspace member auto-provisions them (viewer) via the token above, then retries once.
+# Default off — enabling is a config flip once the dedicated IMS account is wired.
+# SERENITY_MEMBER_AUTOPROVISION=false
 
 # ── Server port (optional, default 3002) ──────────────────────────────────────
 # PORT=3001

src/controllers/serenity.js

@@ -25,6 +25,7 @@ import {
   clearBrandWorkspaceCache,
 } from '../support/serenity/workspace-resolver.js';
 import { mintSemrushImsToken } from '../support/serenity/semrush-ims-token.js';
+import { withMemberAutoProvision } from '../support/serenity/member-autoprovision.js';
 import {
   handleListPrompts,
   handleCreatePrompts,
@@ -81,7 +82,7 @@ import { resolveBrandUuid } from '../support/prompts-storage.js';
 import {
   getBrandAliases, getBrandUrlSources, getBrandCompetitors, updateBrand, getBrandBaseSiteId,
 } from '../support/brands-storage.js';
-import { ErrorWithStatusCode, resolveSemrushImsToken as resolveImsTokenViaPromise } from '../support/utils.js';
+import { ErrorWithStatusCode, resolveSemrushImsToken as resolveImsTokenViaPromise, resolveCallerEmail } from '../support/utils.js';
 import { hostnameFromUrlString } from '../support/url-utils.js';
 import { ensureMarketSite, resolveSiteDomain, unlinkMarketSiteIfOrphaned } from '../support/serenity/site-linkage.js';
 import { X_PROMISE_TOKEN_HEADER, PROMISE_TOKEN_REQUIRED_ERROR_CODE } from '../utils/constants.js';
@@ -201,6 +202,17 @@ function mapError(e, log) {
         err.status,
       );
     }
+    if (err.status === 422) {
+      // An upstream unprocessable-entity refusal (e.g. member add rejected with
+      // "corporate account does not have enough user units" / limit_exceeded) is the
+      // caller's to act on, not an outage. Surface 422 with a specific token instead of
+      // flattening to a generic 502; the body (limit flag + emails) stays server-side only
+      // (logged above), consistent with the 401/403 redaction.
+      return createResponse(
+        { error: 'unprocessableEntity', message: 'Upstream rejected the request as unprocessable (quota or validation)' },
+        422,
+      );
+    }
     return createResponse({
       error: 'serenityUpstreamError',
       message: 'Upstream request failed',
@@ -450,6 +462,28 @@ function SerenityController(context, log, env) {
     return createSerenityTransport({ env: ctx.env || env, imsToken });
   }
 
+  // Auto-provision-on-401/403 flag (env/Vault boolean, default OFF). When a brand-scoped
+  // Semrush READ fails because the caller is not yet a member of the workspace, provision
+  // them on the fly (dedicated IMS token → add member, viewer) and retry the read once.
+  // Only meaningful when Semrush is integrated for the org (serenity active + a workspace
+  // resolves) — which `authorize` already guarantees before any read handler runs.
+  const memberAutoProvisionEnabled = (ctx) => (ctx?.env || env)?.SERENITY_MEMBER_AUTOPROVISION === 'true';
+
+  /**
+   * Wraps a Semrush read so a "caller not yet a member" 401/403 self-heals: on that
+   * upstream denial (and only when the flag is on and we have a workspace + caller email),
+   * the calling user is granted viewer access and the read is retried once. Best-effort —
+   * see member-autoprovision.js. `run` must be idempotent (it may execute twice).
+   */
+  const readWithProvision = (ctx, auth, run) => withMemberAutoProvision({
+    run,
+    env: ctx.env || env,
+    log,
+    enabled: memberAutoProvisionEnabled(ctx),
+    workspaceId: auth.workspaceId,
+    memberEmail: resolveCallerEmail(ctx),
+  });
+
   // Global dynamic-allocation kill-switch for this request (env/Vault boolean, default OFF). Read
   // per request off ctx.env, mirroring buildTransport's env resolution. When OFF the metered
   // handlers front through a no-op guard (byte-for-byte pre-PR behavior).
@@ -511,15 +545,15 @@ function SerenityController(context, log, env) {
         return auth.error;
       }
       const transport = buildTransport(ctx, imsToken);
-      const result = auth.mode === 'subworkspace'
-        ? await handleListPromptsSubworkspace(transport, auth.workspaceId, parsedQuery(ctx), log)
-        : await handleListPrompts(
+      const result = await readWithProvision(ctx, auth, () => (auth.mode === 'subworkspace'
+        ? handleListPromptsSubworkspace(transport, auth.workspaceId, parsedQuery(ctx), log)
+        : handleListPrompts(
           transport,
           ctx.dataAccess,
           auth.brandUuid,
           auth.workspaceId,
           parsedQuery(ctx),
-        );
+        )));
       return createResponse(result, 200);
     } catch (e) {
       return mapError(e, log);
@@ -706,8 +740,8 @@ function SerenityController(context, log, env) {
         return auth.error;
       }
       const transport = buildTransport(ctx, imsToken);
-      const result = auth.mode === 'subworkspace'
-        ? await handleListMarketsSubworkspace(
+      const result = await readWithProvision(ctx, auth, () => (auth.mode === 'subworkspace'
+        ? handleListMarketsSubworkspace(
           transport,
           /** @type {string} */ (auth.brandUuid),
           /** @type {string} */ (auth.workspaceId),
@@ -716,12 +750,12 @@ function SerenityController(context, log, env) {
           ctx.dataAccess,
           log,
         )
-        : await handleListMarkets(
+        : handleListMarkets(
           transport,
           ctx.dataAccess,
           auth.brandUuid,
           auth.workspaceId,
-        );
+        )));
       return createResponse(result, 200);
     } catch (e) {
       return mapError(e, log);
@@ -743,8 +777,8 @@ function SerenityController(context, log, env) {
       // coerce '2840abc' → 2840 and silently resolve a different slice.
       const geoTargetId = /^\d+$/.test(String(pGeo || '')) ? Number(pGeo) : null;
       const languageCode = pLang ? String(pLang).toLowerCase() : null;
-      const result = auth.mode === 'subworkspace'
-        ? await handleGetMarketSubworkspace(
+      const result = await readWithProvision(ctx, auth, () => (auth.mode === 'subworkspace'
+        ? handleGetMarketSubworkspace(
           buildTransport(ctx, imsToken),
           auth.brandUuid,
           auth.workspaceId,
@@ -754,7 +788,7 @@ function SerenityController(context, log, env) {
           // Enrich the resolved slice with its siteId (LLMO-6405 Phase 2).
           ctx.dataAccess,
         )
-        : await handleGetMarket(ctx.dataAccess, auth.brandUuid, geoTargetId, languageCode);
+        : handleGetMarket(ctx.dataAccess, auth.brandUuid, geoTargetId, languageCode)));
       return createResponse(result, 200);
     } catch (e) {
       return mapError(e, log);
@@ -997,16 +1031,16 @@ function SerenityController(context, log, env) {
         return auth.error;
       }
       const transport = buildTransport(ctx, imsToken);
-      const result = auth.mode === 'subworkspace'
-        ? await handleListTagsSubworkspace(transport, auth.workspaceId, parsedQuery(ctx), log)
-        : await handleListTags(
+      const result = await readWithProvision(ctx, auth, () => (auth.mode === 'subworkspace'
+        ? handleListTagsSubworkspace(transport, auth.workspaceId, parsedQuery(ctx), log)
+        : handleListTags(
           transport,
           ctx.dataAccess,
           auth.brandUuid,
           auth.workspaceId,
           parsedQuery(ctx),
           log,
-        );
+        )));
       return createResponse(result, 200);
     } catch (e) {
       return mapError(e, log);
@@ -1106,15 +1140,15 @@ function SerenityController(context, log, env) {
         return auth.error;
       }
       const transport = buildTransport(ctx, imsToken);
-      const result = auth.mode === 'subworkspace'
-        ? await handleListModelsSubworkspace(transport, auth.workspaceId, parsedQuery(ctx), log)
-        : await handleListModels(
+      const result = await readWithProvision(ctx, auth, () => (auth.mode === 'subworkspace'
+        ? handleListModelsSubworkspace(transport, auth.workspaceId, parsedQuery(ctx), log)
+        : handleListModels(
           transport,
           ctx.dataAccess,
           auth.brandUuid,
           auth.workspaceId,
           parsedQuery(ctx),
-        );
+        )));
       return createResponse(result, 200);
     } catch (e) {
       return mapError(e, log);

src/support/serenity/member-autoprovision.js

@@ -0,0 +1,101 @@
+/*
+ * 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 { isSemrushTransportError, unwrapTransportCause } from './errors.js';
+import { mintSemrushImsToken } from './semrush-ims-token.js';
+import { createSerenityTransport } from './rest-transport.js';
+
+const DEFAULT_ROLE = 'role/workspace/viewer';
+
+/**
+ * True when the error is a Semrush auth denial (HTTP 401/403) on an outbound call.
+ * 403 is the fixable "authenticated but not yet a workspace member" case; 401 (an
+ * invalid/expired token) is included for completeness, but the single non-looping
+ * retry below makes an unfixable 401 harmless.
+ *
+ * @param {unknown} e
+ * @returns {boolean}
+ */
+export function isSemrushMembershipDenied(e) {
+  const err = unwrapTransportCause(e);
+  return isSemrushTransportError(err) && (err.status === 401 || err.status === 403);
+}
+
+/**
+ * Runs a Semrush data read and, if it fails because the caller is not yet a member of
+ * the workspace (upstream 401/403), provisions the caller onto the workspace (viewer
+ * role) using the DEDICATED Semrush IMS technical-account token, then runs the read
+ * exactly once more.
+ *
+ * Guarantees:
+ *  - SINGLE retry — never loops, even if the retry also 401/403s.
+ *  - Best-effort provisioning: if the grant itself fails (e.g. 422 "no user units", or a
+ *    token-mint config error), the ORIGINAL read error is surfaced — the grant error
+ *    never masks why the read failed.
+ *  - Transparent no-op (runs the read once, unwrapped) when disabled, when
+ *    workspaceId/memberEmail is missing, or when the error is not a Semrush 401/403.
+ *
+ * The read keeps using the caller's own transport (passed in via `run`); provisioning
+ * uses a SEPARATE admin transport built from the minted service token.
+ *
+ * @template T
+ * @param {object} params
+ * @param {() => Promise<T>} params.run - executes the Semrush read; must be safe to call twice.
+ * @param {object} params.env
+ * @param {{ info: Function, error: (m: string, meta?: object) => void }} params.log
+ * @param {boolean} params.enabled - the SERENITY_MEMBER_AUTOPROVISION flag.
+ * @param {string | null | undefined} params.workspaceId - the resolved brand workspace.
+ * @param {string | null | undefined} params.memberEmail - the calling user's email.
+ * @param {string} [params.role] - Semrush role to grant (default `role/workspace/viewer`).
+ * @returns {Promise<T>}
+ */
+export async function withMemberAutoProvision({
+  run, env, log, enabled, workspaceId, memberEmail, role = DEFAULT_ROLE,
+}) {
+  if (!enabled) {
+    return run();
+  }
+  try {
+    return await run();
+  } catch (readError) {
+    // The truthiness checks also narrow the `string | null | undefined` params to
+    // `string` for TS (hasText is not a type guard — see this dir's CLAUDE.md).
+    if (!isSemrushMembershipDenied(readError)
+      || !workspaceId || !hasText(workspaceId)
+      || !memberEmail || !hasText(memberEmail)) {
+      throw readError;
+    }
+    try {
+      log.info('[serenity] auto-provisioning workspace member after upstream 401/403', {
+        workspaceId,
+      });
+      const imsToken = await mintSemrushImsToken(env, log);
+      const adminTransport = createSerenityTransport({ env, imsToken });
+      await adminTransport.addWorkspaceMembers(workspaceId, [memberEmail], role);
+    } catch (provisionError) {
+      // Provisioning is best-effort: surface the ORIGINAL read error (the 401/403), not
+      // the grant error, so a "no seats" (422) or mint-config failure never masks the
+      // reason the read failed. The grant error is logged for diagnosis only.
+      log.error('[serenity] member auto-provision failed; surfacing original read error', {
+        workspaceId,
+        provisionError: provisionError?.message,
+      });
+      throw readError;
+    }
+    // Provisioned — retry the read exactly once. If it still fails, that error propagates
+    // (no further provisioning attempt).
+    return run();
+  }
+}

src/support/utils.js

@@ -874,6 +874,22 @@ export function resolveCallerImsUserId(context) {
   return hasText(raw) ? String(raw) : null;
 }
 
+/**
+ * Resolves the caller's human email address (NOT the opaque IMS user id) from the
+ * authenticated profile — the address to add as a Semrush workspace member. Prefers
+ * `email`, then `preferred_username` (IMS typically sets this to the email), then
+ * `trial_email`. Returns null when none resolve, in which case callers must skip any
+ * member-provisioning rather than guess.
+ *
+ * @param {object} context - The request context.
+ * @returns {string|null} The caller's email, or null when unresolvable.
+ */
+export function resolveCallerEmail(context) {
+  const profile = context?.attributes?.authInfo?.getProfile?.();
+  const raw = profile?.email ?? profile?.preferred_username ?? profile?.trial_email;
+  return hasText(raw) ? String(raw) : null;
+}
+
 /**
  * Resolves the IMS access token to forward to the Semrush gateway for a request.
  *