@consentera/react-native-consent 2.0.0

package/lib/commonjs/session.js

@@ -0,0 +1,805 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SDK_VERSION = exports.SDK_USER_AGENT = exports.SDK_IDENTIFIER = exports.ConsenteraSession = exports.ConsenteraError = void 0;
+exports.callbackStatusOf = callbackStatusOf;
+exports.callbackUrlFor = callbackUrlFor;
+exports.newCallbackState = newCallbackState;
+exports.parseRetryAfter = parseRetryAfter;
+exports.portalIdentifier = portalIdentifier;
+exports.principalBody = principalBody;
+exports.readErrorEnvelope = readErrorEnvelope;
+exports.resolveInAppBrowser = resolveInAppBrowser;
+exports.setInAppBrowser = setInAppBrowser;
+var _reactNative = require("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.
+ */
+const SDK_VERSION = exports.SDK_VERSION = '2.0.0';
+const SDK_IDENTIFIER = exports.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.
+ */
+const SDK_USER_AGENT = exports.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.
+ */
+function parseRetryAfter(header, now = Date.now()) {
+  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.
+ */
+class ConsenteraError extends Error {
+  /** HTTP status, when this came from a non-2xx answer. */
+
+  /** The platform's canonical error code, e.g. `VALIDATION_ERROR`. */
+
+  /**
+   * 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.
+   */
+
+  /** `X-Request-Id` off the response, for a support ticket. */
+
+  /** True for a timeout or a transport failure — the call may be retried. */
+
+  constructor(message, opts = {}) {
+    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.
+ */
+exports.ConsenteraError = ConsenteraError;
+function readErrorEnvelope(text) {
+  try {
+    const parsed = JSON.parse(text);
+    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.
+ */
+function newCallbackState() {
+  const g = globalThis.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. */
+
+let injectedBrowser = 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;
+ *       },
+ *     });
+ */
+function setInAppBrowser(adapter) {
+  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.
+ */
+function resolveInAppBrowser() {
+  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.require ?? eval('require');
+    const mod = req('react-native-inappbrowser-reborn');
+    const b = mod?.InAppBrowser;
+    if (!b || !_reactNative.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) {
+  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;
+}
+/**
+ * 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.
+ */
+function callbackUrlFor(cfg, state) {
+  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.
+ */
+
+/** Map a raw `status` query value onto the platform's vocabulary. Exact match: the server writes lowercase. */
+function callbackStatusOf(raw) {
+  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.
+ */
+
+/**
+ * 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.
+ */
+
+/**
+ * `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.
+ */
+
+/**
+ * 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.
+ */
+
+/** Turn a {@link PrincipalRef} into the body fields that name the person. */
+function principalBody(who) {
+  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.
+ */
+function portalIdentifier(identifiers, scheme) {
+  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];
+}
+class ConsenteraSession {
+  constructor(cfg) {
+    this.cfg = cfg;
+    // 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.
+   */
+  async post(path, body, opts = {}) {
+    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;
+    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;
+      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) {
+        const err = e;
+        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);
+        } 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.
+   */
+  async backoff(attempt, retryAfter, deadline) {
+    let waitMs;
+    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) {
+    // 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('/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) {
+    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.
+   */
+  async presentHosted(url) {
+    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, purposeCode) {
+    return this.post('/consent/validate', {
+      ...principalBody(who),
+      purpose_code: purposeCode
+    });
+  }
+
+  /** Withdraw purposes (codes or UUIDs) for the person named by [who]. */
+  async withdraw(who, purposes) {
+    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) {
+    const [kind, value] = portalIdentifier(identifiers, this.cfg.identifierScheme);
+    return this.post('/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) {
+    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, expectedState) {
+    let parsed;
+    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 = {};
+    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
+    };
+  }
+}
+exports.ConsenteraSession = ConsenteraSession;
+//# sourceMappingURL=session.js.map