@consentera/react-native-consent 2.0.0

package/src/session.ts

@@ -0,0 +1,1051 @@
+import { NativeModules } from 'react-native';
+
+/**
+ * What this SDK calls itself on the wire, in `X-Consentera-SDK`.
+ *
+ * ONE declaration. The Android and iOS twins each had an SDK_VERSION constant
+ * that no request builder ever read, which is the same as not having one.
+ */
+export const SDK_VERSION = '2.0.0';
+export const SDK_IDENTIFIER = `react-native/${SDK_VERSION}`;
+
+/**
+ * The User-Agent the platform's audit coarsening actually parses.
+ *
+ * THE PLATFORM PARSES User-Agent, SO THAT IS WHERE THE VERSION GOES.
+ *
+ * consentera-api/internal/core/audit/user_agent_coarsening_test.go:39-40 drives
+ * CoarsenUserAgent with `ConsenteraSDK/2.3.1 (Android 14; SM-G991B; build 4471)`
+ * and asserts it coarsens to `ConsenteraSDK/2` — the platform has a rule, a test
+ * and an audit consequence for exactly that spelling. The other string in the
+ * platform tree, `consentera-sdk/1.2` (validation_envelope_test.go:233), is an
+ * inert fixture with no parser behind it. So `ConsenteraSDK/<version>` is the one
+ * that is agreed by evidence rather than by preference; raised with the platform
+ * lane as MANIFEST-CORRECTIONS M-11.
+ *
+ * AND X-Consentera-SDK STAYS, because the two answer different questions.
+ * User-Agent is DELIBERATELY COARSENED into the audit record — `ConsenteraSDK/2`
+ * is all that survives, which is the point: an audit row must not carry a
+ * fingerprint of the person's device. A support ticket needs the exact build, and
+ * that is what the custom header carries, outside the audit trail.
+ */
+export const SDK_USER_AGENT = `ConsenteraSDK/${SDK_VERSION} (react-native)`;
+
+/**
+ * `Retry-After` in either RFC 9110 form — delta-seconds, or an HTTP-date — as
+ * milliseconds, or null when the header is absent or unparseable.
+ *
+ * Capped at 60s: a server that asks for an hour is not something a consent UI
+ * can wait out, and the caller's own deadline should decide.
+ */
+export function parseRetryAfter(header: string | null | undefined, now = Date.now()): number | null {
+  if (!header) return null;
+  const trimmed = header.trim();
+  if (/^\d+$/.test(trimmed)) return Math.min(Number(trimmed) * 1000, 60000);
+  const when = Date.parse(trimmed);
+  if (Number.isNaN(when)) return null;
+  return Math.min(Math.max(0, when - now), 60000);
+}
+
+/**
+ * A typed error with the status, the canonical code and the request id.
+ *
+ * Errors used to be `new Error(\`Consentera \${path} \${status}: \${body}\`)` — a
+ * string, with the response body interpolated into the message (where it could
+ * carry the person's own identifiers into whatever the host logs), and nothing
+ * a caller could switch on.
+ */
+export class ConsenteraError extends Error {
+  /** HTTP status, when this came from a non-2xx answer. */
+  readonly status?: number;
+  /** The platform's canonical error code, e.g. `VALIDATION_ERROR`. */
+  readonly code?: string;
+  /**
+   * The platform's own sentence for a refusal: the `message` of its
+   * `{code, message}` envelope, verbatim (SDK register MOB-042). It is what
+   * an app shows the person to say WHY: "\"phone\" is not one of this
+   * organisation's identifier fields — send email". It is kept out of
+   * `message`, like the rest of the body: `message` goes wherever the host
+   * logs, and this is a sentence for a screen. Undefined when the answer had
+   * no envelope, for example a proxy's HTML page.
+   */
+  readonly platformMessage?: string;
+  /** `X-Request-Id` off the response, for a support ticket. */
+  readonly requestId?: string;
+  /** True for a timeout or a transport failure — the call may be retried. */
+  readonly retryable: boolean;
+
+  constructor(
+    message: string,
+    opts: {
+      status?: number;
+      code?: string;
+      platformMessage?: string;
+      requestId?: string;
+      retryable?: boolean;
+    } = {},
+  ) {
+    super(message);
+    this.name = 'ConsenteraError';
+    this.status = opts.status;
+    this.code = opts.code;
+    this.platformMessage = opts.platformMessage;
+    this.requestId = opts.requestId;
+    this.retryable = opts.retryable ?? false;
+  }
+}
+
+/**
+ * The platform's error envelope, `{code, message}` (core/apierrors/errors.go
+ * APIError), read out of a response body. Tolerates the older
+ * `{error: {code, message}}` nesting. Never throws: a body that is not an
+ * envelope yields nothing.
+ */
+export function readErrorEnvelope(text: string): { code?: string; message?: string } {
+  try {
+    const parsed = JSON.parse(text) as {
+      code?: unknown;
+      message?: unknown;
+      error?: { code?: unknown; message?: unknown };
+    };
+    const src = parsed && typeof parsed === 'object' && parsed.error && typeof parsed.error === 'object'
+      && parsed.code === undefined ? parsed.error : parsed;
+    return {
+      code: typeof src?.code === 'string' && src.code ? src.code : undefined,
+      message: typeof src?.message === 'string' && src.message ? src.message : undefined,
+    };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 160 bits from the platform CSPRNG, URL-safe, unpadded.
+ *
+ * REFUSES RATHER THAN DEGRADING. React Native ships no `crypto.getRandomValues`
+ * by default, and the obvious substitute — `Math.random` — is not a CSPRNG: this
+ * nonce is the only thing standing between a forged
+ * `myapp://consent/callback?status=granted` from another app and a host that
+ * believes it, so a predictable one is worse than none. Install
+ * `react-native-get-random-values` and import it once at the top of your entry
+ * file, which is what every RN crypto consumer already does.
+ */
+export function newCallbackState(): string {
+  const g = (globalThis as { crypto?: { getRandomValues?: (a: Uint8Array) => Uint8Array } }).crypto;
+  if (!g?.getRandomValues) {
+    throw new ConsenteraError(
+      'no cryptographic random source: install react-native-get-random-values and ' +
+        "add `import 'react-native-get-random-values';` to the top of index.js. " +
+        'This SDK will not fall back to Math.random for the callback nonce.',
+    );
+  }
+  const bytes = g.getRandomValues(new Uint8Array(20));
+  let bin = '';
+  bytes.forEach((b) => {
+    bin += String.fromCharCode(b);
+  });
+  // btoa exists in RN's JS runtime (Hermes and JSC both provide it).
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** The one shape the SDK needs from whichever in-app browser the host installed. */
+export interface InAppBrowserAdapter {
+  /** Open `url`, intercept `redirectScheme`, resolve the URL or null on dismiss. */
+  openAuth(url: string, redirectScheme: string): Promise<string | null>;
+}
+
+let injectedBrowser: InAppBrowserAdapter | null = null;
+
+/**
+ * Supply the in-app browser explicitly — for Expo, or for a host that already
+ * has one:
+ *
+ *     import * as WebBrowser from 'expo-web-browser';
+ *     setInAppBrowser({
+ *       openAuth: async (url, scheme) => {
+ *         const r = await WebBrowser.openAuthSessionAsync(url, scheme);
+ *         return r.type === 'success' ? r.url : null;
+ *       },
+ *     });
+ */
+export function setInAppBrowser(adapter: InAppBrowserAdapter | null): void {
+  injectedBrowser = adapter;
+}
+
+/**
+ * The injected adapter, else `react-native-inappbrowser-reborn` if the host
+ * installed it, else null — and null makes `presentConsent` THROW rather than
+ * fall back to `Linking.openURL`.
+ *
+ * The peer is resolved with a guarded `require` rather than a top-level import
+ * on purpose: a static import would make the peer mandatory for every consumer,
+ * including the ones that inject their own.
+ */
+export function resolveInAppBrowser(): InAppBrowserAdapter | null {
+  if (injectedBrowser) return injectedBrowser;
+  try {
+    // Declared locally rather than pulling in @types/node: this is Metro's
+    // require, and the SDK has no other CommonJS surface.
+    const req = (globalThis as { require?: (id: string) => unknown }).require
+      ?? (eval('require') as (id: string) => unknown);
+    const mod = req('react-native-inappbrowser-reborn') as {
+      InAppBrowser?: {
+        isAvailable(): Promise<boolean>;
+        openAuth(url: string, redirect: string, opts?: object): Promise<{ type: string; url?: string }>;
+      };
+    };
+    const b = mod?.InAppBrowser;
+    if (!b || !NativeModules.RNInAppBrowser) return null;
+    return {
+      openAuth: async (url, redirectScheme) => {
+        const r = await b.openAuth(url, redirectScheme, {
+          ephemeralWebSession: false,
+          showTitle: true,
+          enableUrlBarHiding: false,
+        });
+        return r.type === 'success' && r.url ? r.url : null;
+      },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * ConsenteraSession — the React Native twin of the Android SDK's session
+ * package. Pure JS: the DPDP flow needs no native module.
+ *
+ * Flow (identical to every other platform):
+ *   1. createSession({ dataPrincipalRef, noticeInternalName }) via YOUR
+ *      backend/proxy (the app never holds tiq_live_*)
+ *   2. presentConsent(session) → the hosted collect page in an IN-APP browser
+ *      (react-native-inappbrowser-reborn, or your own via setInAppBrowser).
+ *      It REFUSES rather than falling back to the external browser.
+ *   3. deep-link back is BEST-EFFORT (Chrome blocks gesture-less custom-scheme
+ *      redirects) — always re-validate on appState → 'active', and put any link
+ *      through parseCallback, which checks scheme, host, path and the `state`
+ *      nonce before you look at `status`
+ *   4. validate()/withdraw() by a PrincipalRef — `data_principal_id` or typed
+ *      `data_principal_identifiers`. A bare `data_principal_ref` is refused
+ *      outright by the API. openPortal() for the full DP portal (rights,
+ *      receipts, grievances) via one-tap SSO — that road, and only that road,
+ *      still takes the old pair.
+ */
+
+/**
+ * The one check on `backendBaseUrl`: present, and an absolute http(s) URL.
+ * Throws a {@link ConsenteraError} with code `BACKEND_BASE_URL_REQUIRED`.
+ */
+function assertBackendBaseUrl(value: unknown): string {
+  const base = typeof value === 'string' ? value.trim() : '';
+  // A regex, NOT `new URL(base).protocol`: React Native's built-in URL class
+  // implements the constructor and `href` only, and its other getters throw
+  // "not implemented" unless the host installed a polyfill — so a check built
+  // on them would refuse every URL on a device while passing under Jest.
+  if (!/^https?:\/\/[^\s/?#]+/i.test(base)) {
+    throw new ConsenteraError(
+      'backendBaseUrl is required and must be an absolute http(s) URL. There is no default ' +
+        "server: set it to your own backend's Consentera route (the server that holds the " +
+        'tiq_live_ key).',
+      { code: 'BACKEND_BASE_URL_REQUIRED' },
+    );
+  }
+  return value as string;
+}
+
+export interface SessionConfig {
+  /**
+   * Your backend/proxy base, e.g. https://api.yourbank.in/consentera.
+   * REQUIRED, with no default: a blank or non-http(s) value throws
+   * `ConsenteraError` (`code: 'BACKEND_BASE_URL_REQUIRED'`) from the constructor.
+   */
+  backendBaseUrl: string;
+  /** Registered deep-link scheme (ops: ALLOWED_CALLBACK_APP_SCHEMES) */
+  callbackScheme: string;
+  callbackHost?: string;
+  callbackPath?: string;
+  /** Per-ATTEMPT timeout in ms (default 30000) — a dead backend fails fast. */
+  requestTimeoutMs?: number;
+  /**
+   * Ceiling on the whole call including retries (default 2x requestTimeoutMs).
+   * Without it, N retries multiply the caller's wait by N and a consent screen
+   * hangs for a minute and a half on a bad network.
+   */
+  totalTimeoutMs?: number;
+  /** Attempts INCLUDING the first (default 3). 1 disables retrying. */
+  maxAttempts?: number;
+  /** Full-jitter base delay in ms (default 250). */
+  retryBaseDelayMs?: number;
+  /**
+   * The identifier fields of your organisation's locked integration key, in
+   * the order you prefer them for signing a person in to the privacy portal —
+   * e.g. `['customer_id', 'mobile']`. Optional. {@link ConsenteraSession.openPortal}
+   * uses it to choose which ONE identifier to send when you pass it several;
+   * without it, pass exactly one (MOB-043).
+   */
+  identifierScheme?: string[];
+  /**
+   * Opt-in diagnostics sink. Undefined (the default) means the SDK is SILENT.
+   *
+   * It replaces a bare `console.warn`, which could not be turned off, redirected
+   * or levelled. Nothing PII-bearing is passed here: the messages name
+   * conditions, never values, and the transport deliberately keeps response
+   * bodies out of its errors for the same reason.
+   */
+  onDiagnostic?: (message: string) => void;
+}
+
+/**
+ * The deep link handed to the platform as `callback_url`, carrying `state`.
+ *
+ * THE STATE SURVIVES THE ROUND TRIP, AND THAT IS A PLATFORM FACT, not an
+ * assumption: `addRedirectParams` (consent/collection.go) appends with `&` when
+ * the callback URL already contains a `?`, so `myapp://consent/callback?state=X`
+ * comes back as `…?artifact_id=…&pending=1&session_id=…&state=X&status=…`
+ * (setRedirectParam re-encodes the query, so the keys arrive sorted). If that ever
+ * changes, `parseCallback` starts refusing every callback rather than silently
+ * accepting a forged one.
+ */
+export function callbackUrlFor(cfg: SessionConfig, state: string): string {
+  const host = cfg.callbackHost ?? 'consent';
+  const path = cfg.callbackPath ?? '/callback';
+  return `${cfg.callbackScheme}://${host}${path}?state=${encodeURIComponent(state)}`;
+}
+
+/**
+ * THE STATUS VOCABULARY THE PLATFORM PUTS ON A CALLBACK — and only these.
+ *
+ * consent/collection.go (platform pre-main 35cd853ac7) derives it at
+ * :4094-4098 — `granted`; no purpose granted → `denied`; some denied →
+ * `partial` — and SETS it on the redirect at :4243. Any other value
+ * (`success`, `completed`, `expired`, a different case, none at all) did not
+ * come from the platform and is `unknown`: never read it as a grant.
+ */
+export type CallbackStatus = 'granted' | 'partial' | 'denied' | 'unknown';
+
+/** Map a raw `status` query value onto the platform's vocabulary. Exact match: the server writes lowercase. */
+export function callbackStatusOf(raw: string | null | undefined): CallbackStatus {
+  return raw === 'granted' || raw === 'partial' || raw === 'denied' ? raw : 'unknown';
+}
+
+/**
+ * Parsed from the deep link the hosted page redirects to on submit.
+ *
+ * A CALLBACK IS A HINT AND NEVER A DECISION. What `parseCallback` guarantees is
+ * narrower and still worth having: this callback came back to the deep link THIS
+ * SDK asked for, carrying the nonce THIS SDK generated.
+ */
+export interface ConsentCallback {
+  sessionId?: string;
+  artifactId?: string;
+  /** The raw `status` query value, exactly as it arrived. Prefer {@link callbackStatus}. */
+  status?: string;
+  /**
+   * `status` read against the platform's vocabulary: `granted`, `partial`
+   * (some purposes declined) or `denied`, else `unknown`. A HINT, not proof —
+   * confirm by reading the consent back through your backend (`validate`).
+   */
+  callbackStatus: CallbackStatus;
+  /**
+   * `pending=1` on the return (collection.go:4274, walk finding F018): the
+   * consent was recorded and its record is STILL BEING WRITTEN. The platform
+   * sets it on every capture. It is not signed and says nothing about whether
+   * a consent exists — it tells your backend to expect the read-back to wait
+   * (202 + Retry-After) rather than to treat an early miss as "no consent".
+   */
+  pending: boolean;
+  /**
+   * The nonce this SDK generated, echoed back by the platform and already
+   * compared against the expected value before this object was returned.
+   */
+  state?: string;
+  /**
+   * The platform's HMAC over (session_id, artifact_id, status), present only
+   * when the DF has a `callback_signing_secret` (collection.go:4175-4182).
+   *
+   * DO NOT VERIFY IT IN THE APP. Verifying needs the secret, and a secret in an
+   * app binary is not a secret. Send it to your own backend.
+   */
+  signature?: string;
+  /** Every query parameter, for logging. */
+  parameters: Record<string, string>;
+}
+
+export interface ConsentSession {
+  consent_session_id: string;
+  consent_url: string;
+  notice_hash?: string;
+  /**
+   * When this session stops being usable. Read it: a host that cannot see the
+   * expiry cannot decide whether to re-create rather than re-open. camelCase is
+   * the API's entrenched contract (collection.go:241).
+   */
+  expiresAt?: string;
+  /** The notice VERSION this session is bound to (collection.go:243). */
+  notice_version_id?: string;
+  /** The language the platform actually served, after its fallback chain. */
+  languageCode?: string;
+  /** The schema version the hosted page renders with (collection.go:247). */
+  ui_schema_version?: string;
+  /**
+   * The client-generated nonce this SDK put on the callback URL.
+   *
+   * NOT FROM THE SERVER — `createSession` sets it after parsing the response.
+   * `challengeNonce` is the SERVER's nonce for the render/submit legs and is a
+   * different value with a different job. It is not persisted: if the app is
+   * killed while the browser is open it is gone, which is the case
+   * resume-revalidate covers.
+   */
+  callbackState?: string;
+  /**
+   * camelCase on the wire, and that is the wire, not a transcription error:
+   * `expiresAt`, `languageCode` and `challengeNonce` are pinned camelCase in the
+   * API's own struct as an entrenched contract while the rest of the response is
+   * snake_case.
+   */
+  challengeNonce?: string;
+  /**
+   * The platform's own uuid for the person. Always returned — store it and send
+   * it as `dataPrincipalId` next time.
+   */
+  data_principal_id?: string;
+  /**
+   * Consequences that did not refuse the request. READ THEM: an unknown age, or
+   * a guardian channel whose invitation could not be sent, arrives here with a
+   * 200 and is otherwise invisible.
+   */
+  warnings?: string[];
+  /**
+   * Present when this session is a child's and an invitation went out to the
+   * guardian channel the request carried. The consent is NOT recorded until that
+   * guardian verifies.
+   */
+  guardian_verification?: GuardianVerificationPending;
+}
+
+/**
+ * The §9(1) state a child's session rests in while the guardian verifies.
+ *
+ * IT CARRIES NO LINK AND NO TOKEN, deliberately. The verification URL is a
+ * bearer credential — address-bound, 72 hours, single use — and it goes to the
+ * guardian's own address. Returning it here would put it in the organisation's
+ * logs, and the organisation is not the party the link is for.
+ */
+export interface GuardianVerificationPending {
+  /** `'pending'`: the guardianship exists and nothing about it is proven yet. */
+  status: string;
+  /** Which channel the invitation went out on — `'email'` or `'sms'`. */
+  channel: string;
+  /** Names the guardianship, so it can be followed on the guardian APIs. */
+  link_id: string;
+}
+
+/**
+ * `data_principal_identifiers` — how every consent LIFECYCLE road names a
+ * person.
+ *
+ * ─── IT IS THE SAME SHAPE AS `dataPrincipal` ON SESSION CREATE (F015) ─────
+ *
+ * An OPEN map keyed by THE TENANT'S OWN LOCKED INTEGRATION KEY — the same
+ * value `data_principal` carries on create (update_context.go:104-119).
+ * F015 (consent/one-identifier-vocabulary-20260922) deleted the earlier
+ * closed five-field object, because a closed struct cannot carry a per-tenant
+ * vocabulary:
+ *
+ *   * ONE VOCABULARY NOW, ONE SPELLING. The mobile atom is `mobile` on BOTH
+ *     roads; F015 removed the old server-side fold, so `phone` is refused BY
+ *     NAME (400 UNKNOWN_IDENTIFIER_FIELD, "…use mobile"). Do NOT send `phone`.
+ *   * THE ADMISSIBLE SET IS PER-TENANT, so this SDK cannot know it and must NOT
+ *     allow-list. Send the fields the organisation locked; the SERVER answers
+ *     UNKNOWN_IDENTIFIER_FIELD, naming the field, when you get it wrong.
+ *   * THERE IS NO `pan` KEY — it is evidence-class and can never be a scheme
+ *     field.
+ *
+ * Only the wire KEY differs from create (`data_principal` may mint a person,
+ * `data_principal_identifiers` resolves only). Any ONE field is enough. A raw
+ * 12-digit `aadhaar` value is refused 400 INVALID_IDENTIFIER_FORMAT (F015
+ * folded the old AADHAAR_RAW_REFUSED into that one refusal); send the
+ * Aadhaar-LINKED token, never the number.
+ */
+export type DataPrincipalIdentifiers = Record<string, string>;
+
+/**
+ * The ONE way a consent lifecycle road names a person.
+ *
+ * `data_principal_ref` is REFUSED OUTRIGHT since 2026-09-21 — no transition
+ * period (consent/lifecycle_identity.go:8-11) — and the refusal fires even when
+ * `data_principal_id` is also present, because two fields naming a person can
+ * disagree and the caller would never learn which one the answer was about.
+ * A union makes the refused request unrepresentable rather than a round trip.
+ */
+export type PrincipalRef =
+  | { dataPrincipalId: string; dataPrincipalIdentifiers?: never }
+  | { dataPrincipalIdentifiers: DataPrincipalIdentifiers; dataPrincipalId?: never };
+
+/** Turn a {@link PrincipalRef} into the body fields that name the person. */
+export function principalBody(who: PrincipalRef): Record<string, unknown> {
+  if ('dataPrincipalId' in who && who.dataPrincipalId) {
+    return { data_principal_id: who.dataPrincipalId };
+  }
+  const ids = who.dataPrincipalIdentifiers;
+  if (!ids || Object.keys(ids).length === 0) {
+    // The fields are the tenant's own locked integration key, which this SDK
+    // cannot know and does not enumerate (F015). The server lists them in its
+    // UNKNOWN_IDENTIFIER_FIELD refusal.
+    // ConsenteraError, not a bare Error: "you named nobody" is the caller's
+    // own bug and a caller must be able to switch on it, like every other
+    // failure this SDK raises. The code is the one the SERVER would answer with
+    // if the body reached it, so the same branch handles both.
+    throw new ConsenteraError(
+      'Consentera: name the Data Principal with dataPrincipalId, or with ' +
+        'dataPrincipalIdentifiers carrying the identifier fields of this ' +
+        "organisation's integration key. data_principal_ref is refused by the API.",
+      { code: 'IDENTIFIER_REQUIRED' }
+    );
+  }
+  return { data_principal_identifiers: ids };
+}
+
+/**
+ * The ONE identifier the portal road is sent, as `[kind, value]`.
+ *
+ * The map's only entry, or, when it has several, the first field of
+ * `scheme` that it carries. It throws (a ConsenteraError whose `code` is the
+ * one the server would use) rather than guess: an empty map is
+ * IDENTIFIER_REQUIRED, several entries and no scheme to choose by is
+ * IDENTIFIER_AMBIGUOUS, and `phone` is UNKNOWN_IDENTIFIER_FIELD.
+ */
+export function portalIdentifier(
+  identifiers: DataPrincipalIdentifiers,
+  scheme?: readonly string[],
+): [kind: string, value: string] {
+  const entries = Object.entries(identifiers ?? {}).filter(([, v]) => typeof v === 'string' && v.trim() !== '');
+  if (entries.some(([k]) => k === 'phone')) {
+    throw new ConsenteraError(
+      "Consentera: `phone` is not an identifier field. This platform spells it `mobile` (F015).",
+      { code: 'UNKNOWN_IDENTIFIER_FIELD' },
+    );
+  }
+  if (entries.length === 0) {
+    throw new ConsenteraError(
+      'Consentera: name the person for the portal with one identifier of your organisation\'s ' +
+        "integration key, e.g. { mobile: '+91…' }.",
+      { code: 'IDENTIFIER_REQUIRED' },
+    );
+  }
+  const only = entries.length === 1 ? entries[0] : undefined;
+  if (only) return [only[0], only[1]];
+  const chosen = (scheme ?? []).find((field) => entries.some(([k]) => k === field));
+  const chosenValue = chosen === undefined ? undefined : identifiers[chosen];
+  if (chosen === undefined || chosenValue === undefined) {
+    throw new ConsenteraError(
+      `Consentera: the portal takes ONE identifier and ${entries.length} were given ` +
+        `(${entries.map(([k]) => k).join(', ')}). Pass one, or set identifierScheme in the ` +
+        'SessionConfig so the SDK can choose.',
+      { code: 'IDENTIFIER_AMBIGUOUS' },
+    );
+  }
+  return [chosen, chosenValue];
+}
+
+export interface ConsentDecision {
+  decision: string; // ALLOW | DENY
+  reason_code?: string;
+  purpose_code?: string;
+  effective_at?: string;
+  expires_at?: string;
+}
+
+export interface PortalSession {
+  portal_url: string;
+  expires_in_seconds: number;
+  auto_provisioned: boolean;
+}
+
+export interface CreateSessionRequest {
+  /**
+   * The person's identifiers, KEYED BY THE FIELD NAMES OF YOUR ORGANISATION'S
+   * LOCKED INTEGRATION KEY — `{ email: 'riya@example.in' }`,
+   * `{ customer_id: 'CUST-90210', mobile: '+919876500000' }`.
+   *
+   * A MAP AND NOT A SET OF NAMED FIELDS (U58). The admissible key set is a
+   * PER-TENANT fact the platform reads at request time, and THE TYPE COMES FROM
+   * THE FIELD NAME: there is no declared type to disagree with the value and no
+   * shape to guess from. A field outside your key is refused 400
+   * UNKNOWN_IDENTIFIER_FIELD, whose message LISTS the allowed fields; too few of
+   * them is 400 IDENTIFIER_REQUIRED.
+   *
+   * NO SPELLING IS FOLDED ANY MORE. On a key of {email, mobile}, `phone` is an
+   * unknown field, not a spelling of `mobile`.
+   */
+  dataPrincipal?: Record<string, string>;
+  /** The platform's own uuid for the person, from any previous createSession response. */
+  dataPrincipalId?: string;
+  noticeInternalName: string;
+  /** Bind exactly this version NUMBER of the notice code; omit for its default version. */
+  noticeVersionNumber?: number;
+  sessionRef?: string;
+  /**
+   * YYYY-MM-DD, sent as `age.date_of_birth` (U58; it was
+   * `data_principal_details.date_of_birth`). Age is server-authoritative: the
+   * date is re-read every time, so a person graduates at eighteen without
+   * anyone updating a flag. Omit it and the person's age is UNKNOWN — the
+   * session is still created, and purposes restricted for children are then
+   * refused. A malformed or implausible date is refused 400
+   * INVALID_DATE_OF_BIRTH.
+   */
+  dateOfBirth?: string;
+  /**
+   * Preferred language for the consent page, sent as `language` — ONE field,
+   * replacing `locale_pref`, `notice_language` and `template_language`
+   * together (U58). It goes AHEAD of the tenant's own default in the server's
+   * fallback chain, so send it only when a language was actually asked for. A
+   * language the platform does not serve is refused 400 UNSUPPORTED_LANGUAGE.
+   */
+  language?: string;
+
+  // ─── The guardian channel (U58) ────────────────────────────────────────
+  //
+  // NEW ON THIS SURFACE. Before this flip a React Native host could send a
+  // `dateOfBirth` and nothing else, so a child whose parent is not already a
+  // customer of the organisation could not consent through this SDK at all.
+  //
+  // WHEN YOU NEED ONE: when `dateOfBirth` is a child's. The gate is the
+  // SERVER'S determination from that date — there is no flag to omit — and a
+  // request without a channel is refused 412 GUARDIAN_REQUIRED.
+  //
+  // EITHER, NOT BOTH: one invitation goes to one address, and two addresses
+  // name two people with nothing saying which is the guardian.
+  //
+  // TOP-LEVEL, AND NEVER INSIDE `dataPrincipal`, which holds the identifiers of
+  // the person the consent is ABOUT. A guardian contact is a channel to a
+  // DIFFERENT person and identifies nobody on this request.
+
+  /** Where the guardian's verification request is sent. Not with [guardianPhone]. */
+  guardianEmail?: string;
+  /** Where the guardian's verification request is sent. Not with [guardianEmail]. */
+  guardianPhone?: string;
+  /**
+   * What the child SAYS the guardian is to them ('mother', 'father', 'legal
+   * guardian', …). Recorded as a CLAIM and confirmed or corrected by the
+   * guardian on the verification road; nothing downstream treats it as proven.
+   */
+  guardianRelationship?: string;
+}
+
+export class ConsenteraSession {
+  constructor(private cfg: SessionConfig) {
+    // NO DEFAULT SERVER, and the refusal names the field. The app talks to its
+    // OWN backend and nothing else, so no host this SDK could ship would ever
+    // be the right one — and SDKs in this repository did ship one, on a domain
+    // the company does not own. The type says `string`, but a JS caller, an
+    // unset env var or a blank remote-config value reaches here as undefined
+    // or '', which used to surface as a TypeError on `.startsWith` or as a
+    // fetch to a relative path at the first request.
+    const base = assertBackendBaseUrl(cfg?.backendBaseUrl);
+    // Enterprise guard: consent traffic must be HTTPS in production. Plain
+    // HTTP is tolerated only for the local dev bridges, and loudly.
+    if (base.startsWith('http://') && !/^http:\/\/(10\.0\.2\.2|localhost|127\.0\.0\.1)[:/]/.test(base)) {
+      cfg.onDiagnostic?.('backendBaseUrl is plain HTTP — production integrations must use HTTPS.');
+    }
+  }
+
+  /**
+   * ONE transport for every road.
+   *
+   * WHAT IT ADDS, and why each one:
+   *
+   *  * **Identity.** `X-Consentera-SDK: react-native/<version>` on every
+   *    request. Without it the platform cannot tell which SDK build produced a
+   *    failure, which is the first question on every support ticket.
+   *  * **Idempotency.** One key per OPERATION, not per attempt: a retried
+   *    mutation must not record a second consent or a second withdrawal. The key
+   *    is minted once per `post` call and reused across its retries.
+   *  * **Retry with backoff and FULL JITTER**, on 429, 5xx and transport
+   *    failures only. Never on a 4xx: a refused body is refused on every
+   *    attempt, and retrying it just spends the tenant's rate budget.
+   *  * **`Retry-After` is obeyed** when the server sends one, in either its
+   *    delta-seconds or HTTP-date form. The platform rate-limits these roads
+   *    (routes_consent.go:377,389,406,567), so this is not hypothetical.
+   *  * **Request id**, surfaced on the error rather than discarded.
+   *  * **A per-ATTEMPT timeout inside a per-CALL deadline**, so N retries cannot
+   *    silently multiply the caller's wait by N.
+   */
+  private async post<T>(path: string, body: unknown, opts: { idempotent?: boolean } = {}): Promise<T> {
+    const perAttemptMs = this.cfg.requestTimeoutMs ?? 30000;
+    const deadline = Date.now() + (this.cfg.totalTimeoutMs ?? perAttemptMs * 2);
+    const maxAttempts = Math.max(1, this.cfg.maxAttempts ?? 3);
+    // MINTED ONCE, REUSED ACROSS RETRIES. A fresh key per attempt would defeat
+    // the whole mechanism — that is the bug idempotency keys exist to prevent.
+    const idempotencyKey = opts.idempotent === false ? undefined : newCallbackState();
+
+    let lastError: ConsenteraError | undefined;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      const controller = new AbortController();
+      const budget = Math.min(perAttemptMs, Math.max(0, deadline - Date.now()));
+      const timer = setTimeout(() => controller.abort(), budget);
+      let res: Response;
+      try {
+        res = await fetch(`${this.cfg.backendBaseUrl}${path}`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'User-Agent': SDK_USER_AGENT,
+            'X-Consentera-SDK': SDK_IDENTIFIER,
+            ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+          },
+          body: JSON.stringify(body),
+          signal: controller.signal,
+        });
+      } catch (e: unknown) {
+        const err = e as { name?: string; message?: string };
+        lastError = new ConsenteraError(
+          err?.name === 'AbortError'
+            ? `Consentera ${path}: request timed out after ${budget}ms`
+            : `Consentera ${path}: ${err?.message ?? 'network error'}`,
+          { retryable: true },
+        );
+        if (attempt < maxAttempts && (await this.backoff(attempt, null, deadline))) continue;
+        throw lastError;
+      } finally {
+        clearTimeout(timer);
+      }
+
+      const requestId = res.headers.get('X-Request-Id') ?? res.headers.get('x-request-id') ?? undefined;
+      const text = await res.text();
+      if (res.ok) {
+        try {
+          return JSON.parse(text) as T;
+        } catch {
+          // A 200 that is not JSON is a proxy or a captive portal, never the
+          // platform. It is NOT retried: the same hop answers the same way.
+          throw new ConsenteraError(
+            `Consentera ${path}: a 2xx response was not JSON (${text.length} bytes)`,
+            { status: res.status, requestId },
+          );
+        }
+      }
+
+      // The envelope's code and message ride on the error as FIELDS, never in
+      // the message: the body can carry the person's own identifiers back, and
+      // an exception message ends up wherever the host logs (MOB-042).
+      const envelope = readErrorEnvelope(text);
+      const code = envelope.code;
+      const retryable = res.status === 429 || res.status >= 500;
+      lastError = new ConsenteraError(
+        `Consentera ${path} failed with ${res.status}${code ? ` (${code})` : ''}`,
+        { status: res.status, code, platformMessage: envelope.message, requestId, retryable },
+      );
+      if (retryable && attempt < maxAttempts) {
+        const ok = await this.backoff(attempt, res.headers.get('Retry-After'), deadline);
+        if (ok) continue;
+      }
+      throw lastError;
+    }
+    /* istanbul ignore next — the loop either returns or throws */
+    throw lastError ?? new ConsenteraError(`Consentera ${path}: no attempt was made`);
+  }
+
+  /**
+   * Sleep before the next attempt. Returns false when the call's deadline would
+   * be passed, in which case the caller throws instead of sleeping into it.
+   *
+   * FULL JITTER: `random(0, base * 2^n)`, the AWS architecture-blog form. A
+   * fixed backoff synchronises every client that failed on the same server
+   * event and reproduces the spike that caused it.
+   */
+  private async backoff(attempt: number, retryAfter: string | null, deadline: number): Promise<boolean> {
+    let waitMs: number;
+    const serverAsked = parseRetryAfter(retryAfter);
+    if (serverAsked !== null) {
+      // The server named a time. Obey it exactly — jittering a value the server
+      // computed just puts some clients back inside the window it rejected.
+      waitMs = serverAsked;
+    } else {
+      const base = this.cfg.retryBaseDelayMs ?? 250;
+      waitMs = Math.random() * base * Math.pow(2, attempt - 1);
+    }
+    if (Date.now() + waitMs >= deadline) return false;
+    await new Promise((r) => setTimeout(r, waitMs));
+    return true;
+  }
+
+  /**
+   * Create a consent session; returns the hosted collect URL.
+   *
+   *   createSession({
+   *     dataPrincipal: { email: 'riya@example.in' },
+   *     noticeInternalName: 'bnb_consent_v2',
+   *     dateOfBirth: '1998-04-12',
+   *   })
+   *
+   * Send `dataPrincipal` — the identifiers, keyed by YOUR organisation's locked
+   * integration key — or `dataPrincipalId` when you already hold the platform's
+   * uuid for the person. Sent together they must agree, or the call is refused
+   * 409 IDENTITY_MISMATCH. A request carrying neither falls to the key's floor,
+   * 400 IDENTIFIER_REQUIRED.
+   *
+   * ─── THIS IS THE U58 WIRE, AND THERE IS NO OVERLAP WINDOW ──────────────
+   *
+   * EVERY KEY BELOW IS ONE THE API DECODES. The handler decodes with NO
+   * DisallowUnknownFields — on the old wire and on this one alike — so a key it
+   * does not know is dropped in SILENCE; the request is then refused for
+   * carrying no identifier, which names a condition and not the field you sent.
+   * That is why an SDK on the wrong wire fails obscurely rather than loudly,
+   * and why this version talks to an API carrying U58 and to no other.
+   */
+  async createSession(req: CreateSessionRequest): Promise<ConsentSession> {
+    // THE CALLBACK NONCE, minted here and nowhere else. It has to exist BEFORE
+    // the call, because `callback_url` is a REQUEST field — there is no later
+    // point at which anything could be added to the URL the platform will
+    // redirect to. That is also why it is not `challengeNonce`, which arrives in
+    // the RESPONSE, one round trip too late to appear in the callback.
+    const state = newCallbackState();
+    const callback = callbackUrlFor(this.cfg, state);
+    const session = await this.post<ConsentSession>('/consent/sessions', {
+      notice_internal_name: req.noticeInternalName,
+      ui_mode: 'redirect',
+      callback_url: callback,
+      // Sent verbatim: this SDK does not know the tenant's key and must not
+      // guess at it — a guess could only turn the API's field-naming 400 into
+      // silence.
+      ...(req.dataPrincipal && Object.keys(req.dataPrincipal).length > 0
+        ? { data_principal: req.dataPrincipal }
+        : {}),
+      ...(req.dataPrincipalId ? { data_principal_id: req.dataPrincipalId } : {}),
+      ...(req.sessionRef ? { session_ref: req.sessionRef } : {}),
+      ...(req.noticeVersionNumber !== undefined ? { notice_version_number: req.noticeVersionNumber } : {}),
+      ...(req.dateOfBirth ? { age: { date_of_birth: req.dateOfBirth } } : {}),
+      ...(req.language ? { language: req.language } : {}),
+      // Top level, never inside data_principal.
+      ...(req.guardianEmail ? { guardian_email: req.guardianEmail } : {}),
+      ...(req.guardianPhone ? { guardian_phone: req.guardianPhone } : {}),
+      ...(req.guardianRelationship ? { guardian_relationship: req.guardianRelationship } : {}),
+    });
+    session.callbackState = state;
+    return session;
+  }
+
+  /**
+   * Present the hosted consent notice in an IN-APP browser.
+   *
+   * ─── WHY A PEER AND NOT `Linking.openURL` ───────────────────────────────
+   *
+   * This used to be `Linking.openURL`, which leaves the app entirely for the
+   * external browser. Three things follow and none is acceptable for a consent
+   * surface: the callback comes back over a custom scheme any installed app can
+   * also claim; nothing tells the caller whether the page even opened; and the
+   * person is gone from the app with no cancellation signal. React Native has no
+   * built-in Custom Tabs / SFSafariViewController binding, so the in-app browser
+   * comes from a peer.
+   *
+   * INSTALL THE PEER:
+   *
+   *     npm i react-native-inappbrowser-reborn   # then: cd ios && pod install
+   *
+   * Expo apps can pass `expo-web-browser`'s `openAuthSessionAsync` through
+   * {@link SessionConfig} instead — see `openInAppBrowser` below.
+   *
+   * ─── IT REFUSES RATHER THAN DEGRADING ───────────────────────────────────
+   *
+   * With no peer available this THROWS. It does not fall back to
+   * `Linking.openURL`, because that would quietly restore every property above
+   * on exactly the devices where the peer failed to link.
+   *
+   * @returns the callback URL the in-app browser intercepted, or null when the
+   *   person dismissed it. THE DEEP LINK IS STILL BEST-EFFORT — Chrome blocks
+   *   gesture-less custom-scheme redirects — so treat null as "unknown" and
+   *   re-validate, never as "denied".
+   */
+  async presentConsent(session: ConsentSession | string): Promise<string | null> {
+    const url = typeof session === 'string' ? session : session.consent_url;
+    const browser = resolveInAppBrowser();
+    if (!browser) {
+      throw new ConsenteraError(
+        'no in-app browser is available. Install react-native-inappbrowser-reborn ' +
+          '(npm i react-native-inappbrowser-reborn && cd ios && pod install), or pass an ' +
+          'expo-web-browser openAuthSessionAsync adapter. This SDK will not fall back to ' +
+          'Linking.openURL, which hands the hosted notice to the external browser and leaves ' +
+          'the callback to any app that claims the scheme.',
+      );
+    }
+    const redirect = `${this.cfg.callbackScheme}://`;
+    const result = await browser.openAuth(url, redirect);
+    return result;
+  }
+
+  /**
+   * Open a non-consent hosted page (the DP portal) in the same in-app browser.
+   * Returns nothing to check: the portal has no consent callback.
+   */
+  private async presentHosted(url: string): Promise<void> {
+    const browser = resolveInAppBrowser();
+    if (!browser) {
+      throw new ConsenteraError(
+        'no in-app browser is available — install react-native-inappbrowser-reborn.',
+      );
+    }
+    await browser.openAuth(url, `${this.cfg.callbackScheme}://`);
+  }
+
+  /**
+   * Authoritative decision check — the ONLY source of consent truth.
+   *
+   *   validate({ dataPrincipalIdentifiers: { email: 'riya@example.in' } }, 'product_analytics')
+   *   validate({ dataPrincipalId: '…' }, 'product_analytics')
+   *
+   * `data_principal_ref` is REFUSED OUTRIGHT (400, message prefixed
+   * `DATA_PRINCIPAL_REF_REFUSED`). Name people by the organisation's locked
+   * key fields — the mobile atom is `mobile` here and on create alike (F015);
+   * `phone` is refused by name.
+   */
+  // `async`, and that is not cosmetic. principalBody() THROWS when the caller
+  // names nobody, and on a non-async method returning Promise<T> that throw is
+  // SYNCHRONOUS: a caller written as `session.validate(...).catch(handle)`
+  // never reaches its handler and the app takes an uncaught exception instead.
+  // Marking it async turns the throw into a rejection, so both call styles —
+  // try/await and .catch() — behave the same. Found by the F015 test below,
+  // which had to use `.rejects` and got a synchronous throw.
+  async validate(who: PrincipalRef, purposeCode: string): Promise<ConsentDecision> {
+    return this.post<ConsentDecision>('/consent/validate', {
+      ...principalBody(who),
+      purpose_code: purposeCode,
+    });
+  }
+
+  /** Withdraw purposes (codes or UUIDs) for the person named by [who]. */
+  async withdraw(who: PrincipalRef, purposes: string[]): Promise<unknown> {
+    return this.post('/consent/withdraw', { ...principalBody(who), purposes });
+  }
+
+  /**
+   * Mint a fresh single-use DP-portal SSO link (never cache it).
+   *
+   *   createPortalSession({ mobile: '+919876500000' })
+   *   createPortalSession({ customer_id: 'CUST-90210' })
+   *
+   * The person is named THE SAME WAY AS EVERYWHERE ELSE in this SDK: a map
+   * keyed by your organisation's identifier fields (F015). The KEY is the
+   * identifier's kind. Before MOB-043 this took a bare string and always
+   * declared it `email`, whatever your organisation is keyed on, so an
+   * organisation keyed on mobile or customer_id sent every person's number as
+   * an email address.
+   *
+   * THE WIRE IS STILL THE PAIR. The portal road (rights/principal
+   * portal_session_handlers.go at 4fda7e3d05) takes one `data_principal_ref`
+   * and its `data_principal_ref_type`, and defaults an absent type to email.
+   * So this SDK always sends the type, and sends exactly ONE identifier: the
+   * map's only entry, or, when you pass several and configured
+   * {@link SessionConfig.identifierScheme}, the first scheme field present.
+   *
+   * `phone` is refused here, before the wire (UNKNOWN_IDENTIFIER_FIELD). The
+   * portal road would silently fold it to `mobile`, but this SDK's
+   * vocabulary has one spelling, and on every other road `phone` is refused
+   * by name. The accepted kinds are the platform's resolver set:
+   * customer_id, email, mobile, aadhaar. The platform refuses anything else
+   * and names that set. It auto-provisions a portal account only from an
+   * email; for another kind the person must already have one (404, whose
+   * `platformMessage` says so).
+   */
+  // `async` so that a refusal before the wire is a REJECTION, not a synchronous
+  // throw a `.catch()` caller never sees (the same reason validate is async).
+  async createPortalSession(identifiers: DataPrincipalIdentifiers): Promise<PortalSession> {
+    const [kind, value] = portalIdentifier(identifiers, this.cfg.identifierScheme);
+    return this.post<PortalSession>('/consent/portal-sessions', {
+      data_principal_ref: value,
+      data_principal_ref_type: kind,
+    });
+  }
+
+  /** Mint + open the full DP portal in one tap, in the same in-app browser. */
+  async openPortal(identifiers: DataPrincipalIdentifiers): Promise<void> {
+    const p = await this.createPortalSession(identifiers);
+    await this.presentHosted(p.portal_url);
+  }
+
+  /**
+   * Parse and CHECK the deep link the hosted page redirects to on submit.
+   *
+   * ─── WHAT IS CHECKED, AND WHY EACH ONE ──────────────────────────────────
+   *
+   * scheme AND host AND path, all three. This used to compare only
+   * `url.startsWith('myapp://')`, which accepts
+   * `myapp://anything/anywhere?status=granted`. A custom scheme is first-come on
+   * Android and undefined on iOS: another installed app can register the same
+   * one, and the only thing that distinguishes OUR callback from its invention
+   * is the whole URL plus the nonce.
+   *
+   * `state` must equal `expectedState` when one is given — the nonce
+   * `createSession` put on `callback_url`, echoed back because
+   * `addRedirectParams` (consent/collection.go) appends to an existing query
+   * rather than replacing it.
+   *
+   * The query is parsed with the platform URL parser, not by splitting on `=`.
+   * The old hand-rolled split kept only the first two parts of each pair, so any
+   * value containing `=` — a base64 artifact id, for instance — was silently
+   * truncated.
+   *
+   * ─── WHAT IS STILL NOT PROVEN ───────────────────────────────────────────
+   *
+   * That the person granted anything. `status=granted` is a query parameter, and
+   * this SDK cannot verify the platform's `sig` without the DF's signing secret,
+   * which must not be in the app. ALWAYS confirm by reading the consent back
+   * through your backend (`validate`) — and expect that read to wait while
+   * `pending` is true.
+   *
+   * `callbackStatus` is `granted | partial | denied` exactly as the platform
+   * issues them; anything else is `unknown`, never a grant.
+   *
+   * Pass `expectedState` as null ONLY when the app was killed during the browser
+   * leg and `ConsentSession.callbackState` is genuinely gone — then re-validate
+   * rather than trusting this.
+   *
+   * @throws ConsenteraError when the link is not ours.
+   */
+  parseCallback(url: string, expectedState: string | null): ConsentCallback {
+    let parsed: URL;
+    try {
+      parsed = new URL(url);
+    } catch {
+      throw new ConsenteraError(`callback rejected: ${url.slice(0, 80)} did not parse as a URL`);
+    }
+    // URL normalises `scheme:` with the colon; compare without it.
+    const scheme = parsed.protocol.replace(/:$/, '').toLowerCase();
+    if (scheme !== this.cfg.callbackScheme.toLowerCase()) {
+      throw new ConsenteraError(
+        `callback rejected: scheme was ${scheme}, expected ${this.cfg.callbackScheme}`,
+      );
+    }
+    const expectedHost = (this.cfg.callbackHost ?? 'consent').toLowerCase();
+    if (parsed.hostname.toLowerCase() !== expectedHost) {
+      throw new ConsenteraError(
+        `callback rejected: host was ${parsed.hostname}, expected ${expectedHost}`,
+      );
+    }
+    const expectedPath = this.cfg.callbackPath ?? '/callback';
+    if (parsed.pathname !== expectedPath) {
+      throw new ConsenteraError(
+        `callback rejected: path was ${parsed.pathname}, expected ${expectedPath}`,
+      );
+    }
+    const parameters: Record<string, string> = {};
+    parsed.searchParams.forEach((v, k) => {
+      parameters[k] = v;
+    });
+    if (expectedState !== null && parameters.state !== expectedState) {
+      throw new ConsenteraError(
+        'callback rejected: state did not match the nonce this session was created with',
+      );
+    }
+    return {
+      sessionId: parameters.session_id,
+      artifactId: parameters.artifact_id,
+      status: parameters.status,
+      callbackStatus: callbackStatusOf(parameters.status),
+      pending: parameters.pending === '1',
+      state: parameters.state,
+      signature: parameters.sig,
+      parameters,
+    };
+  }
+}