@consentera/react-native-consent 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Consentera
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,200 @@
+# @consentera/react-native-consent
+
+DPDP (India, Digital Personal Data Protection Act 2023) consent for React Native.
+
+The app **never holds a secret key**. Your own backend holds `tiq_live_*` and
+proxies to Consentera; this SDK talks to your backend, opens Consentera's hosted
+notice in an in-app browser, and reads the decision back.
+
+- **Version** 2.0.0 · **peers** react ≥18.2, react-native ≥0.73
+- **Pure JS.** No native module of its own, no codegen, nothing to link.
+
+## Install
+
+```sh
+npm i @consentera/react-native-consent
+# Two peers this SDK REFUSES to work without. It does not silently degrade.
+npm i react-native-inappbrowser-reborn react-native-get-random-values
+cd ios && pod install
+```
+
+Add `import 'react-native-get-random-values';` as the **first line of
+`index.js`**, and register your callback scheme in `AndroidManifest.xml`
+(`<data android:scheme="yourapp" android:host="consent" />`) and in
+`Info.plist` (`CFBundleURLTypes`). The scheme must also be registered
+server-side in `ALLOWED_CALLBACK_APP_SCHEMES`, or session create is refused 400.
+
+Expo, or any host that already has a browser: skip
+`react-native-inappbrowser-reborn` and inject your own.
+
+```ts
+import * as WebBrowser from 'expo-web-browser';
+import { setInAppBrowser } from '@consentera/react-native-consent';
+
+setInAppBrowser({
+  openAuth: async (url, scheme) => {
+    const r = await WebBrowser.openAuthSessionAsync(url, scheme);
+    return r.type === 'success' ? r.url : null;
+  },
+});
+```
+
+## Quickstart
+
+```ts
+import {
+  ConsenteraSession,
+  ConsentGate,
+  type PrincipalRef,
+} from '@consentera/react-native-consent';
+
+const session = new ConsenteraSession({
+  // YOUR backend's route to Consentera. Required — there is no default server,
+  // and a blank or scheme-less value throws ConsenteraError
+  // (code BACKEND_BASE_URL_REQUIRED).
+  backendBaseUrl: 'https://api.yourbank.in/consentera',
+  callbackScheme: 'yourapp',
+});
+
+// The ONE shape the lifecycle roads accept: an OPEN map keyed by YOUR
+// organisation's locked integration key (F015), the same shape and the same
+// vocabulary `dataPrincipal` uses on create. A bare string
+// (`data_principal_ref`) is refused outright by the API.
+const who: PrincipalRef = { dataPrincipalIdentifiers: { email: 'riya@example.in' } };
+
+// 1 — create the session through YOUR backend
+const s = await session.createSession({
+  // Keyed by YOUR organisation's locked integration key — the SAME vocabulary
+  // the lifecycle roads take. The mobile atom is `mobile` on both.
+  dataPrincipal: { email: 'riya@example.in' },
+  noticeInternalName: 'your_notice_code',
+  dateOfBirth: '1998-04-12', // omit and the person's age is UNKNOWN
+});
+if (s.warnings?.length) console.log(s.warnings);          // arrive with a 200
+if (s.guardianVerification) { /* §9(1): a child, invitation sent, not yet consented */ }
+
+// 2 — present the hosted notice in the in-app browser and check the callback
+const returned = await session.presentConsent(s);
+if (returned) {
+  const cb = session.parseCallback(returned, s.callbackState ?? null);
+  // cb is a HINT. It proves the callback came back to the deep link this SDK
+  // asked for with the nonce this SDK generated — not that anyone consented.
+  //
+  // The platform returns
+  //   <callback>?artifact_id=…&pending=1&session_id=…&state=…&status=granted|partial|denied
+  // cb.callbackStatus is 'granted' | 'partial' | 'denied', else 'unknown' (never
+  // a grant). cb.pending is true when the record is still being written: your
+  // backend's read-back may answer 202 + Retry-After — wait, do not conclude
+  // "no consent". Confirm by reading the consent back through your backend.
+}
+
+// 3 — validate. THIS is the only source of consent truth, and it is also what
+// covers the person who simply closed the tab (no callback ever arrives).
+const d = await session.validate(who, 'product_analytics');
+if (d.decision === 'ALLOW') { /* process */ }
+
+// 4 — withdrawal must be as easy as giving (DPDP §6(4))
+await session.withdraw(who, ['product_analytics']);
+
+// 5 — the full rights portal (access, erasure, nomination, grievance), one tap.
+//     The same identifier map as everywhere else; the key is the kind.
+await session.openPortal({ email: 'riya@example.in' });
+```
+
+Re-validate on `AppState` `'active'`: Chrome blocks gesture-less custom-scheme
+redirects, so a person who closes the tab produces **no callback at all**.
+
+## One identifier vocabulary (F015)
+
+`dataPrincipal` on create and the lifecycle roads' identifiers are the **same
+open map**, keyed by the fields your organisation locked. This SDK does **not**
+allow-list them: the admissible set is a per-tenant fact the platform reads at
+request time, so send what your key defines and let the server answer.
+
+| | |
+|---|---|
+| the mobile atom | **`mobile`** on both roads. `phone` is refused **by name** — `UNKNOWN_IDENTIFIER_FIELD`, whose message says "…use mobile". |
+| `pan` | **not a scheme field at all.** It is evidence-class and can never be one. |
+| the portal (`openPortal`) | **the same map**, and the key is the kind: `{ mobile: '+91…' }` is sent as a `mobile` reference, never as an email. The portal takes ONE identifier: pass one, or set `identifierScheme` so the SDK can choose. `phone` is refused before the wire. |
+| `aadhaar` | the Aadhaar-**linked token**, never the number. A raw 12-digit value is refused — but **the code differs by road**: `INVALID_IDENTIFIER_FORMAT` on the lifecycle roads (F015 folded the old token into it there), and still `AADHAAR_RAW_REFUSED` on session create. Switch on both, or on the 400 alone. |
+
+The four refusals you can switch on: `UNKNOWN_IDENTIFIER_FIELD` (names the field
+you sent and the ones that are allowed), `IDENTIFIER_REQUIRED` (you named
+nobody), `INVALID_IDENTIFIER_FORMAT` (right field, wrong value — this is also where a raw
+Aadhaar number lands on these roads), and `SCHEME_NOT_CONFIGURED` (this tenant has no locked key yet — an onboarding
+problem, not a request problem).
+
+Only the wire KEY differs between the two roads: `data_principal` on create may
+mint a person, `data_principal_identifiers` on the lifecycle roads resolves only.
+
+## ConsentGate — the mobile equivalent of cookie consent
+
+```ts
+const gate = new ConsentGate(session, who);
+gate.register({
+  purposeCode: 'product_analytics',
+  name: 'Analytics SDK',
+  init: () => analytics.start(),
+  revoke: () => { analytics.stop(); analytics.clearIdentifiers(); },
+});
+await gate.refresh();   // on start and on every resume
+```
+
+`init` runs at most once per allowed-transition; `revoke` runs when a purpose
+stops validating. Validation failures are **fail-closed**. Never "initialise
+then opt out".
+
+## What this SDK will not do
+
+It **refuses rather than degrading**, in four places, and each refusal is a
+decision rather than an omission:
+
+| Missing | It does | It will not |
+|---|---|---|
+| in-app browser | throws with the install line | fall back to `Linking.openURL` — the external browser leaves the callback to any app that claims the scheme |
+| CSPRNG | throws | fall back to `Math.random` for the callback nonce |
+| callback whose scheme, host, path or `state` does not match | throws | accept it |
+| a withdrawal response it cannot decode | throws | report success |
+
+It has **no advertising function**: no advertising identifier, no IABTCF keys,
+no ATT. That is a separate concern and would be a separate package.
+
+## Errors
+
+Every failure is a `ConsenteraError` with `status`, `code` (the platform's
+canonical code), `platformMessage`, `requestId` and `retryable`.
+
+`platformMessage` is the platform's own sentence for a refusal, verbatim, for
+example *"\"phone\" is not one of this organisation's identifier fields —
+send email"*. Show it to the person: it says **why**. It is kept out of
+`message`, as is the rest of the response body, because a body can carry the
+person's own identifiers and `message` ends up wherever you log.
+
+```ts
+try { await session.validate(who, 'product_analytics'); }
+catch (e) {
+  if (e instanceof ConsenteraError) show(e.platformMessage ?? 'Something went wrong');
+  report({ code: e.code, status: e.status, requestId: e.requestId });  // for support
+}
+```
+
+Mutations carry an `Idempotency-Key` minted once per operation and reused across
+retries; 429 and 5xx are retried with full jitter, honouring `Retry-After`; a
+4xx is never retried.
+
+## Configuration
+
+| Option | Default | |
+|---|---|---|
+| `requestTimeoutMs` | 30000 | per ATTEMPT |
+| `totalTimeoutMs` | 2× the above | ceiling on the whole call including retries |
+| `maxAttempts` | 3 | including the first; 1 disables retrying |
+| `identifierScheme` | — | your integration key's fields, in the order `openPortal` should prefer when you pass several identifiers |
+| `retryBaseDelayMs` | 250 | full-jitter base |
+| `onDiagnostic` | — | opt-in sink; the SDK is otherwise SILENT |
+| `callbackHost` / `callbackPath` | `consent` / `/callback` | both are CHECKED on the callback |
+
+## Support
+
+Security issues: see `SECURITY.md` at the repository root.
+Full integration guide: <https://docs.consentera.in/docs/developer/df-integration/apps/mobile-03-react-native>

package/lib/commonjs/gate.js

@@ -0,0 +1,87 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.ConsentGate = void 0;
+/**
+ * ConsentGate — the mobile equivalent of cookie consent (RN twin of the
+ * Android SDK's gate package). Gate third-party SDKs (analytics, ads,
+ * attribution) and advertising identifiers on the DP's live consent state:
+ * `init` runs only after the purpose validates ALLOW; `revoke` runs when a
+ * previously-allowed purpose stops validating (stop the SDK, flush queues,
+ * clear stored identifiers). Never "initialize then opt out".
+ *
+ * Call refresh() on app start and whenever the app returns to the foreground
+ * (AppState 'active') — the deep-link callback is best-effort only.
+ */
+
+class ConsentGate {
+  trackers = [];
+  started = new Set();
+  listeners = new Set();
+  states = [];
+
+  /**
+   * @param who the person this gate is about, in the ONE shape the lifecycle
+   *   roads accept. It was a bare `dataPrincipalRef: string` until 2026-09-22,
+   *   which no longer type-checked against `validate` (tsc: "Argument of type
+   *   'string' is not assignable to parameter of type 'PrincipalRef'") and could
+   *   not express the identifiers the API now requires.
+   */
+  constructor(session, who) {
+    this.session = session;
+    this.who = who;
+  }
+  register(tracker) {
+    this.trackers.push(tracker);
+    this.states = [...this.states, {
+      name: tracker.name,
+      purposeCode: tracker.purposeCode,
+      allowed: false
+    }];
+  }
+  onChange(fn) {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  /** Re-validate every registered purpose; fail-closed on errors. */
+  async refresh() {
+    const next = [];
+    for (const t of this.trackers) {
+      let allowed = false;
+      try {
+        const d = await this.session.validate(this.who, t.purposeCode);
+        allowed = (d.decision ?? '').toUpperCase() === 'ALLOW';
+      } catch {
+        allowed = false;
+      }
+      const wasStarted = this.started.has(t.name);
+      if (allowed && !wasStarted) {
+        try {
+          t.init();
+        } catch {/* tracker init must never crash the app */}
+        this.started.add(t.name);
+      } else if (!allowed && wasStarted) {
+        try {
+          t.revoke();
+        } catch {/* ditto */}
+        this.started.delete(t.name);
+      }
+      next.push({
+        name: t.name,
+        purposeCode: t.purposeCode,
+        allowed
+      });
+    }
+    this.states = next;
+    this.listeners.forEach(fn => fn(next));
+    return next;
+  }
+  isAllowed(purposeCode) {
+    return this.states.some(s => s.purposeCode === purposeCode && s.allowed);
+  }
+}
+exports.ConsentGate = ConsentGate;
+//# sourceMappingURL=gate.js.map

package/lib/commonjs/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["ConsentGate","trackers","started","Set","listeners","states","constructor","session","who","register","tracker","push","name","purposeCode","allowed","onChange","fn","add","delete","refresh","next","t","d","validate","decision","toUpperCase","wasStarted","has","init","revoke","forEach","isAllowed","some","s","exports"],"sourceRoot":"../../src","sources":["gate.ts"],"mappings":";;;;;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAcO,MAAMA,WAAW,CAAC;EACfC,QAAQ,GAAc,EAAE;EACxBC,OAAO,GAAG,IAAIC,GAAG,CAAS,CAAC;EAC3BC,SAAS,GAAG,IAAID,GAAG,CAAgC,CAAC;EAC5DE,MAAM,GAAgB,EAAE;;EAExB;AACF;AACA;AACA;AACA;AACA;AACA;EACEC,WAAWA,CAASC,OAA0B,EAAUC,GAAiB,EAAE;IAAA,KAAvDD,OAA0B,GAA1BA,OAA0B;IAAA,KAAUC,GAAiB,GAAjBA,GAAiB;EAAG;EAE5EC,QAAQA,CAACC,OAAgB,EAAQ;IAC/B,IAAI,CAACT,QAAQ,CAACU,IAAI,CAACD,OAAO,CAAC;IAC3B,IAAI,CAACL,MAAM,GAAG,CAAC,GAAG,IAAI,CAACA,MAAM,EAAE;MAAEO,IAAI,EAAEF,OAAO,CAACE,IAAI;MAAEC,WAAW,EAAEH,OAAO,CAACG,WAAW;MAAEC,OAAO,EAAE;IAAM,CAAC,CAAC;EAC1G;EAEAC,QAAQA,CAACC,EAAiC,EAAc;IACtD,IAAI,CAACZ,SAAS,CAACa,GAAG,CAACD,EAAE,CAAC;IACtB,OAAO,MAAM,IAAI,CAACZ,SAAS,CAACc,MAAM,CAACF,EAAE,CAAC;EACxC;;EAEA;EACA,MAAMG,OAAOA,CAAA,EAAyB;IACpC,MAAMC,IAAiB,GAAG,EAAE;IAC5B,KAAK,MAAMC,CAAC,IAAI,IAAI,CAACpB,QAAQ,EAAE;MAC7B,IAAIa,OAAO,GAAG,KAAK;MACnB,IAAI;QACF,MAAMQ,CAAC,GAAG,MAAM,IAAI,CAACf,OAAO,CAACgB,QAAQ,CAAC,IAAI,CAACf,GAAG,EAAEa,CAAC,CAACR,WAAW,CAAC;QAC9DC,OAAO,GAAG,CAACQ,CAAC,CAACE,QAAQ,IAAI,EAAE,EAAEC,WAAW,CAAC,CAAC,KAAK,OAAO;MACxD,CAAC,CAAC,MAAM;QACNX,OAAO,GAAG,KAAK;MACjB;MACA,MAAMY,UAAU,GAAG,IAAI,CAACxB,OAAO,CAACyB,GAAG,CAACN,CAAC,CAACT,IAAI,CAAC;MAC3C,IAAIE,OAAO,IAAI,CAACY,UAAU,EAAE;QAC1B,IAAI;UAAEL,CAAC,CAACO,IAAI,CAAC,CAAC;QAAE,CAAC,CAAC,MAAM,CAAE;QAC1B,IAAI,CAAC1B,OAAO,CAACe,GAAG,CAACI,CAAC,CAACT,IAAI,CAAC;MAC1B,CAAC,MAAM,IAAI,CAACE,OAAO,IAAIY,UAAU,EAAE;QACjC,IAAI;UAAEL,CAAC,CAACQ,MAAM,CAAC,CAAC;QAAE,CAAC,CAAC,MAAM,CAAE;QAC5B,IAAI,CAAC3B,OAAO,CAACgB,MAAM,CAACG,CAAC,CAACT,IAAI,CAAC;MAC7B;MACAQ,IAAI,CAACT,IAAI,CAAC;QAAEC,IAAI,EAAES,CAAC,CAACT,IAAI;QAAEC,WAAW,EAAEQ,CAAC,CAACR,WAAW;QAAEC;MAAQ,CAAC,CAAC;IAClE;IACA,IAAI,CAACT,MAAM,GAAGe,IAAI;IAClB,IAAI,CAAChB,SAAS,CAAC0B,OAAO,CAAEd,EAAE,IAAKA,EAAE,CAACI,IAAI,CAAC,CAAC;IACxC,OAAOA,IAAI;EACb;EAEAW,SAASA,CAAClB,WAAmB,EAAW;IACtC,OAAO,IAAI,CAACR,MAAM,CAAC2B,IAAI,CAAEC,CAAC,IAAKA,CAAC,CAACpB,WAAW,KAAKA,WAAW,IAAIoB,CAAC,CAACnB,OAAO,CAAC;EAC5E;AACF;AAACoB,OAAA,CAAAlC,WAAA,GAAAA,WAAA","ignoreList":[]}

package/lib/commonjs/index.js

@@ -0,0 +1,92 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ConsentGate", {
+  enumerable: true,
+  get: function () {
+    return _gate.ConsentGate;
+  }
+});
+Object.defineProperty(exports, "ConsenteraError", {
+  enumerable: true,
+  get: function () {
+    return _session.ConsenteraError;
+  }
+});
+Object.defineProperty(exports, "ConsenteraSession", {
+  enumerable: true,
+  get: function () {
+    return _session.ConsenteraSession;
+  }
+});
+Object.defineProperty(exports, "SDK_IDENTIFIER", {
+  enumerable: true,
+  get: function () {
+    return _session.SDK_IDENTIFIER;
+  }
+});
+Object.defineProperty(exports, "SDK_USER_AGENT", {
+  enumerable: true,
+  get: function () {
+    return _session.SDK_USER_AGENT;
+  }
+});
+Object.defineProperty(exports, "SDK_VERSION", {
+  enumerable: true,
+  get: function () {
+    return _session.SDK_VERSION;
+  }
+});
+Object.defineProperty(exports, "callbackStatusOf", {
+  enumerable: true,
+  get: function () {
+    return _session.callbackStatusOf;
+  }
+});
+Object.defineProperty(exports, "callbackUrlFor", {
+  enumerable: true,
+  get: function () {
+    return _session.callbackUrlFor;
+  }
+});
+Object.defineProperty(exports, "newCallbackState", {
+  enumerable: true,
+  get: function () {
+    return _session.newCallbackState;
+  }
+});
+Object.defineProperty(exports, "parseRetryAfter", {
+  enumerable: true,
+  get: function () {
+    return _session.parseRetryAfter;
+  }
+});
+Object.defineProperty(exports, "portalIdentifier", {
+  enumerable: true,
+  get: function () {
+    return _session.portalIdentifier;
+  }
+});
+Object.defineProperty(exports, "readErrorEnvelope", {
+  enumerable: true,
+  get: function () {
+    return _session.readErrorEnvelope;
+  }
+});
+Object.defineProperty(exports, "resolveInAppBrowser", {
+  enumerable: true,
+  get: function () {
+    return _session.resolveInAppBrowser;
+  }
+});
+Object.defineProperty(exports, "setInAppBrowser", {
+  enumerable: true,
+  get: function () {
+    return _session.setInAppBrowser;
+  }
+});
+var _session = require("./session");
+var _gate = require("./gate");
+//# sourceMappingURL=index.js.map

package/lib/commonjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["_session","require","_gate"],"sourceRoot":"../../src","sources":["index.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoBA,IAAAA,QAAA,GAAAC,OAAA;AA4BA,IAAAC,KAAA,GAAAD,OAAA","ignoreList":[]}