@redacto.io/consent-sdk-react 10.0.0-beta.7 → 10.0.0-beta.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redacto.io/consent-sdk-react",
-  "version": "10.0.0-beta.7",
+  "version": "10.0.0-beta.9",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",

package/src/RedactoNoticeConsent/RedactoNoticeConsent.tsx

@@ -1297,6 +1297,12 @@ export const RedactoNoticeConsent = ({
   noticeId,
   accessToken,
   refreshToken,
+  token,
+  email,
+  mobile,
+  ucic,
+  organisationUuid,
+  workspaceUuid,
   baseUrl,
   ledgerBaseUrl,
   language = "en",
@@ -1312,6 +1318,25 @@ export const RedactoNoticeConsent = ({
   includeFullyConsentedData = false,
   reviewModeButtonText = "Continue",
 }: Props) => {
+  // =============================================================================
+  // SANDBOX MODE
+  // =============================================================================
+
+  // Sandbox PoC: when `token` is set, every API call bypasses the JWT and sends
+  // the single X-Consent-Token header, carrying the acting identity (subject) in
+  // each request's own payload. Org/workspace/subject are taken straight from
+  // props. Passed through to the API layer alongside `accessToken`.
+  const sandboxParams = useMemo(
+    () => ({
+      token,
+      sandboxUcic: ucic,
+      sandboxSubject: email || mobile,
+      organisationUuid,
+      workspaceUuid,
+    }),
+    [token, ucic, email, mobile, organisationUuid, workspaceUuid]
+  );
+
   // =============================================================================
   // PROP VALIDATION
   // =============================================================================
@@ -1321,11 +1346,31 @@ export const RedactoNoticeConsent = ({
     if (!noticeId?.trim()) {
       return "RedactoNoticeConsent: 'noticeId' prop is required and cannot be empty";
     }
+    // Sandbox mode: require a static token, org/workspace, and a subject instead
+    // of a JWT access token.
+    if (token?.trim()) {
+      if (!organisationUuid?.trim() || !workspaceUuid?.trim()) {
+        return "RedactoNoticeConsent: sandbox mode requires 'organisationUuid' and 'workspaceUuid'";
+      }
+      if (!email?.trim() && !mobile?.trim() && !ucic?.trim()) {
+        return "RedactoNoticeConsent: sandbox mode requires 'email', 'mobile', or 'ucic'";
+      }
+      return null;
+    }
     if (!accessToken?.trim()) {
       return "RedactoNoticeConsent: 'accessToken' prop is required and cannot be empty";
     }
     return null;
-  }, [noticeId, accessToken]);
+  }, [
+    noticeId,
+    accessToken,
+    token,
+    organisationUuid,
+    workspaceUuid,
+    email,
+    mobile,
+    ucic,
+  ]);
 
   // Show error UI if props are invalid
   if (propValidationError) {
@@ -1822,6 +1867,7 @@ export const RedactoNoticeConsent = ({
         validate_against: validateAgainst,
         include_fully_consented_data: includeFullyConsentedData,
         signal: abortControllerRef.current?.signal,
+        ...sandboxParams,
       });
       const activeConfig = consentContentData.detail.active_config;
       setContent(activeConfig);
@@ -1856,6 +1902,7 @@ export const RedactoNoticeConsent = ({
           ledgerBaseUrl,
           noticeUuid: noticeId,
           signal: abortControllerRef.current?.signal,
+          ...sandboxParams,
         });
         if (ledgerStatus) {
           const overlay = buildLedgerConsentOverlay(
@@ -2033,6 +2080,7 @@ export const RedactoNoticeConsent = ({
     noticeId,
     accessToken,
     refreshToken,
+    sandboxParams,
     language,
     applicationId,
     validateAgainst,
@@ -2194,6 +2242,7 @@ export const RedactoNoticeConsent = ({
           guardianVerificationReference: verificationReference || undefined,
           selfDeclaredAdult: selfDeclaredAdult || undefined,
           signal: submitController.signal,
+          ...sandboxParams,
         });
       }
       onAccept?.();
@@ -2437,7 +2486,7 @@ export const RedactoNoticeConsent = ({
     } finally {
       setIsSubmittingGuardian(false);
     }
-  }, [accessToken, baseUrl, guardianFormData, digilockerMode, digilockerCallbackUrl, selectedPurposes, selectedDataElements, noticeId, onError]);
+  }, [accessToken, sandboxParams, baseUrl, guardianFormData, digilockerMode, digilockerCallbackUrl, selectedPurposes, selectedDataElements, noticeId, onError]);
 
   // Age verification handlers
   const handleAgeVerificationYes = useCallback(() => {
@@ -2516,7 +2565,7 @@ export const RedactoNoticeConsent = ({
     setIsPollingStatus(false);
     isPollingStatusRef.current = false;
     setIsInitiatingVerification(false);
-  }, [accessToken, baseUrl]);
+  }, [accessToken, sandboxParams, baseUrl]);
 
   const startPopupMonitoring = useCallback((popup: Window) => {
     // Check every 500ms if popup is closed
@@ -2697,7 +2746,7 @@ export const RedactoNoticeConsent = ({
       // First poll after 3s
       statusPollIntervalRef.current = window.setTimeout(poll, POLL_INTERVAL);
     },
-    [accessToken, baseUrl, getVerificationErrorMessage]
+    [accessToken, sandboxParams, baseUrl, getVerificationErrorMessage]
   );
 
 
@@ -3232,6 +3281,7 @@ export const RedactoNoticeConsent = ({
       noticeUuid: content.notice_uuid,
       language: languageCode,
       signal: ttsAbortController.signal,
+      ...sandboxParams,
     })
       .then((response) => {
         // Store the response and mark TTS as available
@@ -3250,7 +3300,7 @@ export const RedactoNoticeConsent = ({
     return () => {
       ttsAbortController.abort();
     };
-  }, [content, selectedLanguage, accessToken, baseUrl, getLanguageCode]);
+  }, [content, selectedLanguage, accessToken, sandboxParams, baseUrl, getLanguageCode]);
 
   const modalStyle = {
     borderRadius: settings?.borderRadius || "8px",

package/src/RedactoNoticeConsent/api/index.ts

@@ -1,5 +1,11 @@
 import { jwtDecode } from "jwt-decode";
 import { parseApiError } from "../../shared/api-errors";
+import {
+  buildAuthHeaders,
+  resolveRequestAuth,
+  sandboxBodyIdentity,
+  sandboxQueryIdentity,
+} from "./sandbox";
 import type {
   ConsentContent,
   ConsentEventPayload,
@@ -69,25 +75,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);
@@ -107,11 +116,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,
@@ -145,24 +161,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);
 
   // Fall back to the consent server when no ledger is configured, so existing
-  // integrations that only pass baseUrl remain backwards compatible.
-  const apiBaseUrl = ledgerBaseUrl || baseUrl || BASE_URL;
+  // 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) {
@@ -196,15 +211,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,
     }
   );
@@ -283,29 +302,32 @@ export const fetchTTSAudioUrls = async ({
   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;
 
-  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,
@@ -343,6 +365,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");
     }
@@ -363,8 +388,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");
     }
@@ -458,6 +485,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");
   }
@@ -466,8 +496,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");
   }
@@ -482,9 +514,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);

package/src/RedactoNoticeConsent/api/types.ts

@@ -6,6 +6,52 @@ export type RedactoJwtPayload = {
   iat?: number;
 };
 
+/**
+ * Optional sandbox-mode auth fields shared by every API param type. When
+ * `token` is set the call sends the single `X-Consent-Token` header instead of
+ * `Authorization: Bearer`, injects the subject into each request's own payload
+ * (body for POSTs, query param for GETs), and takes org/workspace from these
+ * props instead of decoding the JWT. All optional so existing JWT callers are
+ * unaffected.
+ */
+export type SandboxAuthParams = {
+  token?: string;
+  /** UCIC — the client's own user id (`org_user_id`); takes precedence over the subject. */
+  sandboxUcic?: string;
+  sandboxSubject?: string;
+  organisationUuid?: string;
+  workspaceUuid?: string;
+};
+
+/**
+ * Sandbox authentication context. Present only when the host opts into sandbox
+ * mode by passing a sandbox token; the token/org/workspace are always required
+ * at that point because there is no JWT to fall back on. The acting identity is
+ * a UCIC (the client's own `org_user_id`) or a `subject` (email/mobile) — at
+ * least one is present (UCIC takes precedence when both are set).
+ */
+export type SandboxAuth = {
+  token: string;
+  /** UCIC — the client's own user id (`org_user_id`). Takes precedence over `subject`. */
+  ucic?: string;
+  subject: string;
+  organisationUuid: string;
+  workspaceUuid: string;
+};
+
+/** The identity payload fragment for the sandbox acting principal. */
+export type SandboxIdentityPayload =
+  | { org_user_id: string }
+  | { primary_email: string }
+  | { primary_mobile: string };
+
+/** Org/workspace UUIDs plus the resolved sandbox context for a request. */
+export type ResolvedRequestAuth = {
+  organisationUuid: string;
+  workspaceUuid: string;
+  sandbox: SandboxAuth | null;
+};
+
 export type PurposeSelection = {
   selected: boolean;
   status: string; // ACTIVE | EXPIRED | WITHDRAW | DECLINED
@@ -157,10 +203,10 @@ export type Settings = {
   font?: string;
 };
 
-export type FetchConsentContentParams = {
+export type FetchConsentContentParams = SandboxAuthParams & {
   noticeId: string;
-  accessToken: string;
-  refreshToken: string;
+  accessToken?: string;
+  refreshToken?: string;
   baseUrl?: string;
   language?: string;
   specific_uuid?: string;
@@ -207,8 +253,8 @@ export type Purpose = {
   data_elements: Array<DataElement>;
 };
 
-export type SubmitConsentEventParams = {
-  accessToken: string;
+export type SubmitConsentEventParams = SandboxAuthParams & {
+  accessToken?: string;
   baseUrl?: string;
   ledgerBaseUrl?: string;
   noticeUuid: string;
@@ -331,8 +377,8 @@ export type DpoInfoAudio = {
   grievance_email_audio_url?: string;
 };
 
-export type FetchTTSAudioUrlsParams = {
-  accessToken: string;
+export type FetchTTSAudioUrlsParams = SandboxAuthParams & {
+  accessToken?: string;
   baseUrl?: string;
   noticeUuid: string;
   language: string;
@@ -346,8 +392,8 @@ export type FetchTTSAudioUrlsParams = {
  * Parameters for initiating guardian verification
  * POST /guardian/initiate-verification
  */
-export type InitiateGuardianVerificationParams = {
-  accessToken: string;
+export type InitiateGuardianVerificationParams = SandboxAuthParams & {
+  accessToken?: string;
   baseUrl?: string;
   guardianName: string;
   guardianContact: string;
@@ -382,8 +428,8 @@ export type InitiateGuardianVerificationResponse = {
  * Parameters for checking verification status
  * POST /guardian/verify-status
  */
-export type VerifyGuardianStatusParams = {
-  accessToken: string;
+export type VerifyGuardianStatusParams = SandboxAuthParams & {
+  accessToken?: string;
   baseUrl?: string;
   sessionToken: string;
   signal?: AbortSignal;

package/src/RedactoNoticeConsent/types.ts

@@ -2,8 +2,34 @@ import type { Settings, DpoInfoTranslation } from "./api/types";
 
 export type Props = Readonly<{
   noticeId: string;
-  accessToken: string;
-  refreshToken: string;
+  /**
+   * JWT access token. Optional so sandbox integrations (see `token`) can
+   * omit it. Required in the normal JWT flow.
+   */
+  accessToken?: string;
+  /** JWT refresh token. Optional; accepted for source-compat, currently unused. */
+  refreshToken?: string;
+  /**
+   * Sandbox PoC: a pasted static token. When set, the SDK runs against the
+   * sandbox with no JWT — it sends the single `X-Consent-Token` header, carries
+   * the acting identity (`email` || `mobile`) in each request's own payload,
+   * takes org/workspace from `organisationUuid`/`workspaceUuid`, and does no
+   * token refresh.
+   */
+  token?: string;
+  /** Sandbox test subject email (carried in the request payload when set). */
+  email?: string;
+  /** Sandbox test subject mobile (fallback subject when `email` is absent). */
+  mobile?: string;
+  /**
+   * Sandbox UCIC: the client's own user id / org_user_id, e.g. a UUID or
+   * customer code; optional third identifier alongside email/mobile.
+   */
+  ucic?: string;
+  /** Sandbox org UUID (replaces the JWT-decoded org in sandbox mode). */
+  organisationUuid?: string;
+  /** Sandbox workspace UUID (replaces the JWT-decoded workspace in sandbox mode). */
+  workspaceUuid?: string;
   baseUrl?: string;
   ledgerBaseUrl?: string;
   settings?: Partial<Settings>;