@redacto.io/consent-sdk-react 10.0.0-beta.0 → 10.0.0-beta.11

package/src/RedactoNoticeConsent/api/index.ts

@@ -1,16 +1,18 @@
 import { jwtDecode } from "jwt-decode";
 import { parseApiError } from "../../shared/api-errors";
+import {
+  buildAuthHeaders,
+  resolveRequestAuth,
+  sandboxBodyIdentity,
+  sandboxQueryIdentity,
+} from "./sandbox";
 import type {
   ConsentContent,
   ConsentEventPayload,
-  DataElementSelection,
   FetchConsentContentParams,
-  FetchNoticeConsentStatusParams,
   FetchTTSAudioUrlsParams,
   InitiateGuardianVerificationParams,
   InitiateGuardianVerificationResponse,
-  NoticeConsentStatusResponse,
-  PurposeSelection,
   RedactoJwtPayload,
   SubmitConsentEventParams,
   TTSAudioUrlsResponse,
@@ -18,6 +20,11 @@ import type {
   VerifyGuardianStatusResponse,
 } from "./types";
 
+// The ledger `check-consent` read is shared with RedactoNoticeConsentInline.
+// Re-exported through this barrel so `./api` importers (and the test mock)
+// resolve it here unchanged.
+export { fetchNoticeConsentStatus } from "../../shared/notice-consent-status";
+
 const BASE_URL = "https://api.redacto.io/consent";
 
 // Simple in-memory cache for API responses to reduce calls
@@ -65,25 +72,28 @@ export const fetchConsentContent = async ({
   validate_against = "all",
   include_fully_consented_data = false,
   signal,
+  ...sandboxParams
 }: FetchConsentContentParams & { signal?: AbortSignal }): Promise<ConsentContent> => {
-  if (!noticeId || !accessToken || !validate_against) {
-    throw new Error("noticeId and accessToken are required");
+  if (!noticeId || !validate_against) {
+    throw new Error("noticeId is required");
   }
-
-  const decodedToken = decodeTokenSafely(accessToken);
-  if (!decodedToken) {
-    throw new Error("Invalid access token");
+  if (!accessToken && !sandboxParams.token) {
+    throw new Error("accessToken or token is required");
   }
 
-  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
-  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
-    throw new Error("Invalid token: missing organization or workspace UUID");
-  }
+  const { organisationUuid: ORGANISATION_UUID, workspaceUuid: WORKSPACE_UUID, sandbox } =
+    resolveRequestAuth(accessToken, sandboxParams, decodeTokenSafely);
 
   const apiBaseUrl = baseUrl || BASE_URL;
 
-  // Create cache key for this request - include accessToken to ensure different users get different cache
-  const cacheKey = `${accessToken}-${noticeId}-${validate_against}-${language}-${specific_uuid || ''}-${include_fully_consented_data}`;
+  // Create cache key for this request - include the auth identity (token or
+  // sandbox org/workspace/subject) so different users get different cache
+  // entries. Org + workspace are part of the sandbox identity so two sessions
+  // sharing a subject but scoped to different orgs never collide.
+  const cacheIdentity = sandbox
+    ? `sandbox:${sandbox.organisationUuid}:${sandbox.workspaceUuid}:${sandbox.ucic || sandbox.subject}`
+    : accessToken;
+  const cacheKey = `${cacheIdentity}-${noticeId}-${validate_against}-${language}-${specific_uuid || ''}-${include_fully_consented_data}`;
 
   if (validate_against === "all" && !specific_uuid) {
     const cachedData = getCachedData(cacheKey);
@@ -103,11 +113,18 @@ export const fetchConsentContent = async ({
   if (include_fully_consented_data) {
     url.searchParams.append("include_fully_consented_data", "true");
   }
+  // Sandbox mode: the acting identity travels as query params
+  // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
+  if (sandbox) {
+    for (const [key, value] of Object.entries(sandboxQueryIdentity(sandbox))) {
+      url.searchParams.append(key, value);
+    }
+  }
 
   const response = await fetch(url.toString(), {
     method: "GET",
     headers: {
-      Authorization: `Bearer ${accessToken}`,
+      ...buildAuthHeaders(accessToken, sandbox),
       "Accept-Language": language,
     },
     signal,
@@ -131,6 +148,7 @@ export const fetchConsentContent = async ({
 
 export const submitConsentEvent = async ({
   accessToken,
+  baseUrl,
   ledgerBaseUrl,
   noticeUuid,
   purposes,
@@ -140,25 +158,23 @@ export const submitConsentEvent = async ({
   guardianVerificationReference,
   selfDeclaredAdult,
   signal,
+  ...sandboxParams
 }: SubmitConsentEventParams & { signal?: AbortSignal }): Promise<void> => {
-  if (!noticeUuid || !accessToken || !Array.isArray(purposes)) {
-    throw new Error("noticeUuid, accessToken, and purposes array are required");
+  if (!noticeUuid || !Array.isArray(purposes)) {
+    throw new Error("noticeUuid and purposes array are required");
   }
-
-  const decodedToken = decodeTokenSafely(accessToken);
-  if (!decodedToken) {
-    throw new Error("Invalid access token");
+  if (!accessToken && !sandboxParams.token) {
+    throw new Error("accessToken or token is required");
   }
 
-  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
-  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
-    throw new Error("Invalid token: missing organization or workspace UUID");
-  }
+  const { organisationUuid: ORGANISATION_UUID, workspaceUuid: WORKSPACE_UUID, sandbox } =
+    resolveRequestAuth(accessToken, sandboxParams, decodeTokenSafely);
 
-  if (!ledgerBaseUrl) {
-    throw new Error("ledgerBaseUrl is required to submit consent");
-  }
-  const apiBaseUrl = ledgerBaseUrl;
+  // Fall back to the consent server when no ledger is configured, so existing
+  // integrations that only pass baseUrl remain backwards compatible. Sandbox
+  // never routes to the Go ledger (no X-Consent-Token support), so a sandbox
+  // session forces the consent-server path even if a ledgerBaseUrl is set.
+  const apiBaseUrl = (sandbox ? null : ledgerBaseUrl) || baseUrl || BASE_URL;
 
   const validatedPurposes = purposes.map((purpose) => {
     if (!purpose.uuid) {
@@ -192,15 +208,19 @@ export const submitConsentEvent = async ({
     self_declared_adult: selfDeclaredAdult,
   };
 
+  // Sandbox mode: merge the acting test identity into the body (the server has
+  // no subject header; it namespaces this identity `test::`).
+  const requestBody = sandbox ? { ...payload, ...sandboxBodyIdentity(sandbox) } : payload;
+
   const response = await fetch(
     `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/submit-consent`,
     {
       method: "POST",
       headers: {
-        Authorization: `Bearer ${accessToken}`,
+        ...buildAuthHeaders(accessToken, sandbox),
         "Content-Type": "application/json",
       },
-      body: JSON.stringify(payload),
+      body: JSON.stringify(requestBody),
       signal,
     }
   );
@@ -216,157 +236,42 @@ export const submitConsentEvent = async ({
   apiCache.clear();
 };
 
-/**
- * Fetch the principal's current consent status for a notice from the Go
- * ledger (`check-consent`). The principal resolves from the JWT, so the body
- * is empty. Returns null on any failure so the caller can fall back to the
- * Python-provided overlay (graceful degradation). This is how the banner
- * learns prior-consent / reconsent state post-cutover, since Python's notice
- * validation reads its own (now-empty) consent DB.
- */
-export const fetchNoticeConsentStatus = async ({
-  accessToken,
-  ledgerBaseUrl,
-  noticeUuid,
-  signal,
-}: FetchNoticeConsentStatusParams): Promise<NoticeConsentStatusResponse | null> => {
-  if (!accessToken || !ledgerBaseUrl || !noticeUuid) {
-    return null;
-  }
-
-  const decodedToken = decodeTokenSafely(accessToken);
-  if (!decodedToken) {
-    return null;
-  }
-
-  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
-  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
-    return null;
-  }
-
-  try {
-    const response = await fetch(
-      `${ledgerBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/notices/${noticeUuid}/check-consent`,
-      {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          "Content-Type": "application/json",
-        },
-        body: "{}",
-        signal,
-      }
-    );
-
-    if (!response.ok) {
-      return null;
-    }
-
-    const data = (await response.json()) as
-      | NoticeConsentStatusResponse
-      | { detail?: NoticeConsentStatusResponse };
-    // The ledger returns the response directly; tolerate a {detail} envelope too.
-    const body =
-      data && typeof data === "object" && "detail" in data && data.detail
-        ? data.detail
-        : (data as NoticeConsentStatusResponse);
-
-    if (!body || !Array.isArray(body.purposes)) {
-      return null;
-    }
-    return body;
-  } catch {
-    // Network / abort / parse failure — degrade to the Python overlay.
-    return null;
-  }
-};
-
-/**
- * Translate the ledger's notice consent status into the
- * `{ purpose_selections, reconsent_required }` shape the banner already
- * consumes, so prior-consent pre-fill and reconsent categorization work off
- * the ledger. Returns null for a first-time principal (no consent record —
- * every purpose INACTIVE), preserving the normal first-time consent flow.
- *
- * `needs_reconsent` is derived from `status` (anything not ACTIVE needs
- * reconsent: expired / withdrawn / declined / inactive). NOTE: notice-version
- * reconsent is NOT covered — the ledger's check-consent has no version
- * awareness yet, so a republished-notice version bump won't re-prompt until
- * that lands on the ledger (tracked fast-follow).
- */
-export const buildLedgerConsentOverlay = (
-  status: NoticeConsentStatusResponse,
-  configPurposes: ConsentContent["detail"]["active_config"]["purposes"]
-): {
-  reconsent_required: boolean;
-  purpose_selections: Record<string, PurposeSelection>;
-} | null => {
-  const byUuid = new Map(status.purposes.map((p) => [p.uuid, p]));
-  const hasHistory = status.purposes.some(
-    (p) => (p.status || "INACTIVE") !== "INACTIVE"
-  );
-  if (!hasHistory) {
-    return null;
-  }
-
-  const purpose_selections: Record<string, PurposeSelection> = {};
-  for (const cp of configPurposes) {
-    const lp = byUuid.get(cp.uuid);
-    const purposeStatus = lp?.status || "INACTIVE";
-    const selectedByUuid = new Map(
-      (lp?.data_elements || []).map((de) => [de.uuid, de.selected])
-    );
-    const data_elements: Record<string, DataElementSelection> = {};
-    for (const de of cp.data_elements) {
-      data_elements[de.uuid] = {
-        selected: selectedByUuid.get(de.uuid) ?? false,
-        enabled: de.enabled,
-        required: de.required,
-      };
-    }
-    purpose_selections[cp.uuid] = {
-      selected: lp?.selected ?? false,
-      status: purposeStatus,
-      needs_reconsent: purposeStatus !== "ACTIVE",
-      data_elements,
-    };
-  }
-
-  const reconsent_required = configPurposes.some(
-    (cp) => (purpose_selections[cp.uuid]?.status || "INACTIVE") !== "ACTIVE"
-  );
-  return { reconsent_required, purpose_selections };
-};
-
 export const fetchTTSAudioUrls = async ({
   accessToken,
   baseUrl,
+  ledgerBaseUrl,
   noticeUuid,
   language,
   signal,
+  ...sandboxParams
 }: FetchTTSAudioUrlsParams & { signal?: AbortSignal }): Promise<TTSAudioUrlsResponse> => {
-  if (!accessToken || !noticeUuid || !language) {
-    throw new Error("accessToken, noticeUuid, and language are required");
-  }
-
-  const decodedToken = decodeTokenSafely(accessToken);
-  if (!decodedToken) {
-    throw new Error("Invalid access token");
+  if ((!accessToken && !sandboxParams.token) || !noticeUuid || !language) {
+    throw new Error("accessToken (or token), noticeUuid, and language are required");
   }
 
-  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
-  if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
-    throw new Error("Invalid token: missing organization or workspace UUID");
-  }
+  const { organisationUuid: ORGANISATION_UUID, workspaceUuid: WORKSPACE_UUID, sandbox } =
+    resolveRequestAuth(accessToken, sandboxParams, decodeTokenSafely);
 
-  const apiBaseUrl = baseUrl || BASE_URL;
+  // Prefer the Go ledger for audio, but a sandbox session never routes there:
+  // the ledger has no X-Consent-Token support, so it stays on the consent
+  // server. Mirrors submitConsentEvent's base-url selection.
+  const apiBaseUrl = (sandbox ? null : ledgerBaseUrl) || baseUrl || BASE_URL;
 
-  const url = `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/notices/${noticeUuid}/audio/${language}`;
+  const url = new URL(
+    `${apiBaseUrl}/public/organisations/${ORGANISATION_UUID}/workspaces/${WORKSPACE_UUID}/notices/${noticeUuid}/audio/${language}`
+  );
+  // Sandbox mode: the acting identity travels as query params
+  // (primary_email / primary_mobile); the credential is the X-Consent-Token header.
+  if (sandbox) {
+    for (const [key, value] of Object.entries(sandboxQueryIdentity(sandbox))) {
+      url.searchParams.append(key, value);
+    }
+  }
 
-  const response = await fetch(url, {
+  const response = await fetch(url.toString(), {
     method: "GET",
     headers: {
-      Authorization: `Bearer ${accessToken}`,
+      ...buildAuthHeaders(accessToken, sandbox),
       Accept: "application/json",
     },
     signal,
@@ -404,6 +309,9 @@ export const initiateGuardianVerification = async ({
   signal,
 }: InitiateGuardianVerificationParams): Promise<InitiateGuardianVerificationResponse> => {
   try {
+    // Guardian verification is JWT-only: sandbox sessions have no minor-notice /
+    // guardian support (the server 403s them, and C1 blocks minor notices at
+    // render), so no sandbox identity is wired through here.
     if (!accessToken) {
       throw new Error("accessToken is required");
     }
@@ -424,8 +332,10 @@ export const initiateGuardianVerification = async ({
     if (!decodedToken) {
       throw new Error("Invalid access token");
     }
-
-    const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
+    const {
+      organisation_uuid: ORGANISATION_UUID,
+      workspace_uuid: WORKSPACE_UUID,
+    } = decodedToken;
     if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
       throw new Error("Invalid token: missing organization or workspace UUID");
     }
@@ -519,6 +429,9 @@ export const verifyGuardianStatus = async ({
   sessionToken,
   signal,
 }: VerifyGuardianStatusParams): Promise<VerifyGuardianStatusResponse> => {
+  // Guardian verification is JWT-only: sandbox sessions have no minor-notice /
+  // guardian support (the server 403s them, and C1 blocks minor notices at
+  // render), so no sandbox identity is wired through here.
   if (!accessToken || !sessionToken) {
     throw new Error("accessToken and sessionToken are required");
   }
@@ -527,8 +440,10 @@ export const verifyGuardianStatus = async ({
   if (!decodedToken) {
     throw new Error("Invalid access token");
   }
-
-  const { organisation_uuid: ORGANISATION_UUID, workspace_uuid: WORKSPACE_UUID } = decodedToken;
+  const {
+    organisation_uuid: ORGANISATION_UUID,
+    workspace_uuid: WORKSPACE_UUID,
+  } = decodedToken;
   if (!ORGANISATION_UUID || !WORKSPACE_UUID) {
     throw new Error("Invalid token: missing organization or workspace UUID");
   }
@@ -543,9 +458,7 @@ export const verifyGuardianStatus = async ({
         Authorization: `Bearer ${accessToken}`,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({
-        session_token: sessionToken,
-      }),
+      body: JSON.stringify({ session_token: sessionToken }),
       signal,
     }
   );

package/src/RedactoNoticeConsent/api/sandbox.ts

@@ -0,0 +1,150 @@
+/**
+ * Sandbox-mode auth primitives for the consent PoC.
+ *
+ * In sandbox mode the SDK talks to the consent-server with a pasted static
+ * token and an explicit test subject, bypassing the JWT entirely. Org/workspace
+ * UUIDs come from props (they still build the `/public/organisations/{org}/
+ * workspaces/{ws}/...` URL paths) instead of being decoded from a token.
+ *
+ * Auth is the single `X-Consent-Token` header carrying the static token; its
+ * presence alone marks the request as `environment=test`. There is no subject
+ * header. The acting identity (the test subject) rides the request's own
+ * payload: query params (`primary_email` / `primary_mobile`) on GET/query reads,
+ * and the body on POSTs. The server normalizes and namespaces it `test::`
+ * server-side. Call sites resolve the credential via {@link buildAuthHeaders}
+ * and the identity via {@link sandboxQueryIdentity} / {@link sandboxBodyIdentity}.
+ *
+ * This file exists so every API call site resolves its org/workspace UUIDs and
+ * builds its auth header through one place, keeping sandbox vs. JWT branching
+ * from drifting across the ~6 fetch sites.
+ */
+import { SANDBOX_TOKEN_HEADER } from "../../shared/sandbox";
+import type {
+  RedactoJwtPayload,
+  ResolvedRequestAuth,
+  SandboxAuth,
+  SandboxAuthParams,
+  SandboxIdentityPayload,
+} from "./types";
+
+export { SANDBOX_TOKEN_HEADER };
+
+/**
+ * Resolve a {@link SandboxAuth} from the raw sandbox props, or return null when
+ * sandbox mode is not active (no token).
+ *
+ * @throws Error when a sandbox token is provided but org/workspace or the acting
+ *   identity are incomplete — sandbox mode cannot build URLs or identify the
+ *   acting principal without them, so failing loudly beats a silent malformed
+ *   request.
+ */
+export const resolveSandboxAuth = (
+  params: SandboxAuthParams
+): SandboxAuth | null => {
+  const token = params.token?.trim();
+  if (!token) {
+    return null;
+  }
+
+  const organisationUuid = params.organisationUuid?.trim();
+  const workspaceUuid = params.workspaceUuid?.trim();
+  const ucic = params.sandboxUcic?.trim();
+  const subject = params.sandboxSubject?.trim();
+
+  if (!organisationUuid || !workspaceUuid) {
+    throw new Error(
+      "Sandbox mode requires organisationUuid and workspaceUuid props"
+    );
+  }
+  if (!ucic && !subject) {
+    throw new Error("Sandbox mode requires a UCIC, email, or mobile");
+  }
+
+  return { token, ucic, subject: subject ?? "", organisationUuid, workspaceUuid };
+};
+
+/**
+ * Resolve the org/workspace UUIDs and sandbox auth for a request. In sandbox
+ * mode these come straight from props; otherwise they are decoded from the JWT
+ * (preserving the pre-sandbox behavior and error messages exactly). The JWT
+ * decoder is injected so this module stays free of a direct jwt-decode import.
+ *
+ * @throws Error when neither a valid sandbox config nor a decodable token with
+ *   org/workspace UUIDs is available.
+ */
+export const resolveRequestAuth = (
+  accessToken: string | undefined,
+  sandboxParams: SandboxAuthParams,
+  decodeTokenSafely: (token: string) => RedactoJwtPayload | null
+): ResolvedRequestAuth => {
+  const sandbox = resolveSandboxAuth(sandboxParams);
+  if (sandbox) {
+    return {
+      organisationUuid: sandbox.organisationUuid,
+      workspaceUuid: sandbox.workspaceUuid,
+      sandbox,
+    };
+  }
+
+  const decodedToken = accessToken ? decodeTokenSafely(accessToken) : null;
+  if (!decodedToken) {
+    throw new Error("Invalid access token");
+  }
+  const { organisation_uuid, workspace_uuid } = decodedToken;
+  if (!organisation_uuid || !workspace_uuid) {
+    throw new Error("Invalid token: missing organization or workspace UUID");
+  }
+  return {
+    organisationUuid: organisation_uuid,
+    workspaceUuid: workspace_uuid,
+    sandbox: null,
+  };
+};
+
+/**
+ * Build the request headers for an authenticated call. In sandbox mode this is
+ * the single `X-Consent-Token` credential (its presence marks the request as
+ * `environment=test`); otherwise the standard `Authorization: Bearer`. There is
+ * no subject header — the acting identity travels in the request's own payload
+ * (see {@link sandboxQueryIdentity} for reads, {@link sandboxBodyIdentity} for
+ * POSTs).
+ */
+export const buildAuthHeaders = (
+  accessToken: string | undefined,
+  sandbox: SandboxAuth | null
+): Record<string, string> => {
+  if (sandbox) {
+    return { [SANDBOX_TOKEN_HEADER]: sandbox.token };
+  }
+  return { Authorization: `Bearer ${accessToken}` };
+};
+
+/**
+ * The identity payload fragment for the sandbox acting principal:
+ * `{ org_user_id }` when a UCIC is set (it takes precedence), else
+ * `{ primary_email }` when the subject looks like an email (contains "@"),
+ * otherwise `{ primary_mobile }`. Merge this into a JSON request body (POST) or
+ * into query params (GET) so the server can resolve the acting test identity.
+ */
+export const sandboxBodyIdentity = (
+  sandbox: SandboxAuth
+): SandboxIdentityPayload => {
+  if (sandbox.ucic) {
+    return { org_user_id: sandbox.ucic };
+  }
+  return sandbox.subject.includes("@")
+    ? { primary_email: sandbox.subject }
+    : { primary_mobile: sandbox.subject };
+};
+
+/**
+ * The identity query fragment for GET/query reads: `{ org_user_id }` when a UCIC
+ * is set (it takes precedence), else `{ primary_email }` when the subject looks
+ * like an email (contains "@"), otherwise `{ primary_mobile }`. Append these to
+ * the request's query string so the server can resolve the acting test identity
+ * (the server reads `org_user_id` / `primary_email` / `primary_mobile` query
+ * params on sandbox reads).
+ */
+export const sandboxQueryIdentity = (
+  sandbox: SandboxAuth
+): SandboxIdentityPayload => sandboxBodyIdentity(sandbox);