@consentera/consent-sdk 2.0.0

package/README.md

@@ -0,0 +1,489 @@
+# @consentera/consent-sdk
+
+Consent management for the web, against the [Consentera](https://docs.consentera.in)
+platform. India's **DPDP Act** first, with TCF 2.2 and GPP surfaces for sites that
+also need them.
+
+- **Consent lifecycle** — create a consent session, validate a purpose, update,
+  withdraw, renew, verify the artefact.
+- **Cookie banner + preference centre** — a drop-in surface for cookie consent.
+- **React** — a provider, hooks and a `<ConsentGate>` that closes when consent is
+  withdrawn.
+
+```
+npm install @consentera/consent-sdk
+```
+
+Node ≥ 20. React ≥ 18 (optional peer, only for `@consentera/consent-sdk/react`).
+
+---
+
+## Quickstart (10 minutes)
+
+### 1. Put your secret key on YOUR server, never in the page
+
+A Data Fiduciary credential (`tiq_live_…` / `tiq_test_…`) is a **secret**. Every
+consent lifecycle road needs one, and a browser bundle is public, so the browser
+talks to **your** server and your server talks to us.
+
+```ts
+// app/api/consentera/[...path]/route.ts  (Next.js — any server framework works)
+export async function POST(req: Request, { params }: { params: { path: string[] } }) {
+  // CONSENTERA_API_URL is YOUR tenant's API origin — the SDK ships no default.
+  const upstream = `${process.env.CONSENTERA_API_URL}/api/v1/public/${params.path.join('/')}`;
+  const res = await fetch(upstream, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': process.env.CONSENTERA_API_KEY!,   // the secret, server-side only
+      'X-Tenant-Id': process.env.CONSENTERA_TENANT_ID!,
+      // pass these through so the SDK's guarantees survive the hop
+      'Idempotency-Key': req.headers.get('Idempotency-Key') ?? '',
+      'X-Consentera-SDK': req.headers.get('X-Consentera-SDK') ?? '',
+    },
+    body: await req.text(),
+  });
+  // expose the request id so SDK errors can carry it
+  const out = new Response(res.body, { status: res.status });
+  const rid = res.headers.get('X-Request-Id');
+  if (rid) out.headers.set('X-Request-Id', rid);
+  return out;
+}
+```
+
+### 2. Point the SDK at your route
+
+```ts
+import { ConsentEraClient } from '@consentera/consent-sdk';
+
+const ce = new ConsentEraClient({
+  proxyEndpoint: '/api/consentera',   // in a browser this is required
+  callbackUrl: 'https://your-site.example/consent/done',
+});
+```
+
+No `tenantId` behind a proxy: your route supplies the tenant (the
+`X-Tenant-Id` above) and the SDK sends no tenant header through it. With
+`apiEndpoint` (direct, server-side) `tenantId` is required, and a client
+without it is refused with `TENANT_ID_REQUIRED`.
+
+Putting `apiKey` here in a browser is **refused at construction** with
+`SECRET_KEY_IN_BROWSER`. That is deliberate — see *The credential model* below.
+
+### 3. Ask for consent
+
+```ts
+const session = await ce.consent.createSession({
+  // The identifiers, keyed by YOUR organisation's locked integration key.
+  // A field outside the key is 400 UNKNOWN_IDENTIFIER_FIELD, and the message
+  // lists the fields your key allows.
+  data_principal: { email: 'riya@example.in' },
+  notice_internal_name: 'bnb_consent_v2',
+  age: { date_of_birth: '1998-04-12' },     // the one age signal
+});
+
+ce.consent.redirectToConsent(session);       // or openConsentPopup(session)
+```
+
+`createSession` adds **its own `state`** to your `callbackUrl` — 32 random bytes,
+fresh per session, kept in this browser's session storage — so the return can
+be tied to the browser that started it. The platform keeps every parameter
+already on `callback_url` when it builds the return, so the state comes back.
+`state` is therefore reserved: a `callbackUrl` that already carries one is
+refused with `CALLBACK_STATE_RESERVED`. Pick a different name for your own
+parameter. `callbackUrl` must be absolute (`INVALID_CALLBACK_URL` otherwise).
+
+`openConsentPopup(session)` shows the consent page **in a dialog on your page**
+and resolves when the person decides:
+
+```ts
+const r = await ce.consent.openConsentPopup(session);
+if (r.outcome === 'decided') {
+  // r.status: 'granted' | 'partial' | 'denied'; r.pending: the record is still
+  // being written (redirect pending=1), so the read-back may answer 202 first
+  await confirmOnYourServer(r.session_id, r.artifact_id);   // the artefact is the record
+}
+// r.outcome === 'dismissed': the person closed the dialog
+```
+
+It listens for the one message the consent page posts to the page that frames
+it, `consentera:submitted` / `consentera:declined`, and only from the consent
+page's origin and the frame it opened.
+
+**The consent page posts that message only when it is framed.** A consent
+page in its own window or tab (`window.open`, a redirect) posts nothing. It
+sends the person to your `callback_url` instead, and that is what
+`redirectToConsent` + `handleCallback` are for. That is why the popup is a
+dialog with the page in an iframe, not a browser window. Two further
+conditions, both set by the platform:
+
+- the consent page addresses that message to the **origin of the session's
+  `callback_url`**, so your page must be on that origin. The SDK refuses up
+  front with `CALLBACK_ORIGIN_MISMATCH` rather than wait for a message the
+  browser would drop;
+- the platform lets only the **Allowed Domains** of your integration client
+  frame the page.
+
+The message is the consent page's report, not the consent record. Confirm the
+artefact (step 4) before you act on a grant.
+
+### 4. Verify the return trip — the artefact, not the URL
+
+```ts
+// on https://your-site.example/consent/done
+// arriving as ?artifact_id=…&pending=1&session_id=…&state=<ours>&status=granted|partial|denied
+const result = await ce.consent.handleCallback();
+
+if (result.status === 'completed') {
+  // the artefact was read from the platform FOR THIS SESSION and names the
+  // person this browser's session was created for
+  proceed(result.artifact);
+} else {
+  // 'unverified' | 'denied' | 'pending' | 'error' — result.reason says which and why
+  askAgain(result.reason);
+}
+```
+
+`handleCallback()` is **async** and returns `completed` **only** after confirming
+the artefact with the platform. A query string can never produce `completed`.
+
+**What the platform puts on the return URL** — and nothing else:
+
+```
+<your callback_url>?artifact_id=<uuid>&pending=1&session_id=<uuid>&status=granted|partial|denied
+```
+
+plus `&sig=<hex>` only when your integration client holds a callback signing
+secret (a hosted consent page's return is never signed). `status` is one of
+exactly three values, `granted`, `partial` or `denied`; the SDK exposes it as
+`result.claimed_status`, and any other value (`completed`, `success`, `expired`,
+a missing status) is `'unknown'` and is **never** confirmed — the result is
+`unverified`. `pending=1` (`result.claimed_pending`) means the consent was
+recorded and its record is **still being written**; the platform sets it on
+every capture, and it is why the first artefact read may answer 202.
+
+**Both are hints, not proof.** They are query parameters, and `pending` is not
+signed. Confirm the consent by reading the record back through your backend —
+which is what `handleCallback()` does on the `granted`/`partial` road — and read
+the artefact's purposes for what was granted: `partial` means some purposes
+were declined.
+
+**Statuses**: `completed` (verified; `claimed_status` says `granted` or
+`partial`), `denied`, `pending` (the consent WAS recorded, the artefact is not
+readable yet — see below), `error`, and `unverified` (nothing is proven; treat
+exactly as "no consent").
+
+#### The signature
+
+When you register a `callback_signing_secret` on your m2m client, the platform
+signs the callback:
+
+```
+sig = hex( HMAC_SHA256( callback_signing_secret,
+                        session_id + "|" + artifact_id + "|" + status ) )
+```
+
+**That key is yours and must not be in a browser.** So the browser cannot verify
+it: point `verifyCallbackSignature` at your own server, which does.
+
+```ts
+// browser
+const ce = new ConsentEraClient({
+  tenantId: TENANT,
+  proxyEndpoint: '/api/consentera',
+  verifyCallbackSignature: async (p) =>
+    (await fetch('/api/consentera/verify-callback', { method: 'POST', body: JSON.stringify(p) })).ok,
+});
+
+// your server route
+import { verifyCallbackSignature } from '@consentera/consent-sdk';
+const ok = await verifyCallbackSignature(process.env.CONSENTERA_CALLBACK_SECRET!, params);
+```
+
+A callback that **carries** a `sig` with no verifier configured is `unverified`.
+A signature nobody checks is not a control, so the SDK will not quietly ignore
+one the platform bothered to produce. If you have registered no signing secret,
+no `sig` is sent and the state plus the artefact confirmation are the controls.
+
+**The order of checks.** The `state` must come back and must match the one
+stored at create. If it is missing or different, the result is `unverified` and
+nothing is read. Only then is `status` looked at, and only as a hint:
+`granted`/`partial` → the artefact is read back for this session; `denied` →
+`denied`; anything else → `unverified`. The server's `challengeNonce` is not
+part of this: it is the hosted page's own credential, carried on `consent_url`,
+and the return never carries it.
+
+#### How the artefact is confirmed
+
+The SDK reads `GET /consent/artifacts/{artifact_id}?session_id={session_id}`
+through your proxy. **The `session_id` is what gives the answer its meaning:**
+
+| Platform answer | `handleCallback()` |
+|---|---|
+| **200** with the artefact | `completed` — once the artefact's `data_principal_id` equals the one your session create returned |
+| **202** + `Retry-After` — recorded, still being written | waits `Retry-After` inside `artifactWaitMs` (default 15 000), else **`pending`** with `retryAfterMs` |
+| **404** `ARTIFACT_NOT_FOUND` | `unverified` at once: the id was never issued for this session. A forged `artifact_id` looks exactly like this |
+| anything else | `unverified` |
+
+Without the `session_id` the platform answers 404 for a consent whose artefact
+is still being written as well as for an id it never issued, which is why the
+SDK always sends it.
+
+**Why the person is compared.** The platform checks `session_id` only while
+the artefact is still being written. Once it exists, the 200 is returned for
+*any* session id (measured on the platform; walk finding F077). The artefact
+carries no session id. It does carry `data_principal_id`, and the session
+create returned the same field for the person the session is about, so the
+SDK compares the two.
+
+`pending` is **not** a failure and **not** a consent that did not happen: the
+decision is recorded. Read it again after `retryAfterMs`:
+
+```ts
+const r = await ce.consent.getArtifact(artifactId, { sessionId });
+if (r.state === 'pending') setTimeout(retry, r.retryAfterMs);   // 202
+else use(r.artifact);                                           // 200
+// a 404 throws ConsenteraNotFoundError (code ARTIFACT_NOT_FOUND)
+```
+
+### 5. Gate on consent later
+
+```ts
+if (await ce.consent.isAllowed({ data_principal_identifiers: { email } }, 'product_analytics')) {
+  loadAnalytics();
+}
+```
+
+`validate()` returns the platform's whole answer, including
+`data_principal_id`, the platform's id for the person you asked about. Keep it:
+the next call can name the person by `{ data_principal_id }` and send no
+identifier at all.
+
+### Naming a Data Principal
+
+`data_principal_identifiers` is an **open map keyed by your organisation's own
+locked integration key** — the same shape `data_principal` takes on session
+create, validated by the same validator. It is not a fixed vocabulary, so this
+SDK does not enumerate one and does not allow-list: a tenant keyed on
+`{customer_id}` names people by `customer_id`, one keyed on `{email, mobile}`
+by those.
+
+**One spelling, both roads.** The mobile atom is **`mobile`** on session create
+*and* on the lifecycle roads. It used to be `phone` here and `mobile` there,
+folded server-side; F015 removed the fold, so **`phone` is now refused by name**
+— the refusal even tells you the atom to use.
+
+Only the wire KEY differs between the two roads: create spells the object
+`data_principal` (and may mint a person), the lifecycle roads spell it
+`data_principal_identifiers` (resolve-only, never creates anybody).
+
+The refusals you will meet, all from that one validator:
+
+| code | meaning |
+|---|---|
+| `UNKNOWN_IDENTIFIER_FIELD` | a field outside your key, named — and for a vernacular spelling, the atom to use instead |
+| `IDENTIFIER_REQUIRED` | nothing named a person |
+| `INVALID_IDENTIFIER_FORMAT` | a value that cannot be an identifier of its type (a raw 12-digit Aadhaar lives here — send the Aadhaar-linked token) |
+| `SCHEME_NOT_CONFIGURED` | the organisation has not locked how it identifies people yet |
+
+They arrive as `err.code` on a `ConsenteraError` with `err.kind === 'identity'`
+(`'guardian'` for the age/guardian family), so you can branch on the class and
+still read the platform's exact word.
+
+---
+
+## React
+
+```tsx
+'use client';
+import { ConsentEraProvider, useConsentEra, ConsentGate } from '@consentera/consent-sdk/react';
+
+export function App({ children }) {
+  return (
+    <ConsentEraProvider config={{ tenantId: TENANT, proxyEndpoint: '/api/consentera' }}>
+      {children}
+    </ConsentEraProvider>
+  );
+}
+
+function Marketing({ email }: { email: string }) {
+  return (
+    <ConsentGate
+      who={{ data_principal_identifiers: { email } }}
+      purposeCode="marketing_email"
+      fallback={<AskForConsent />}
+    >
+      <MarketingContent />
+    </ConsentGate>
+  );
+}
+```
+
+The built bundle carries `'use client'`, so it works in the Next.js App Router.
+`<ConsentGate>` **fails closed** — unknown, loading and errored all render the
+fallback — and it **re-checks when consent changes**, so a withdrawal anywhere in
+the app closes the gate without a remount.
+
+**No hook throws during render.** When the provider's configuration is refused
+(a secret key in a browser, no endpoint), or there is no provider at all,
+`useConsentEraClient()` returns `client: null`. `useConsentEra()` returns
+`ready: false` and `null` namespaces. `error` says why, and a
+`ConsenteraError` carries its `code`. `<ConsentGate>` renders its fallback. A
+configuration mistake therefore closes the gate instead of blanking the page:
+
+```tsx
+const { consent, error } = useConsentEra();
+if (!consent) return <p>Consent is unavailable: {error?.message}</p>;
+```
+
+---
+
+## The credential model
+
+| credential | where it may live | what it opens |
+|---|---|---|
+| `tiq_live_` / `tiq_test_` secret key | your server only | every consent lifecycle road |
+| `tiq_pub_` site key | a browser bundle | public roads (notice fetch, consent-page config/submit) |
+| consent session id + nonce | the consent page | that one session's render/submit |
+
+**In a browser, lifecycle roads must go through `proxyEndpoint`.** The SDK
+enforces this: `apiKey` with a `window` present is refused at construction, and a
+`df` road with no proxy raises `SECRET_KEY_IN_BROWSER` naming the fix.
+
+If you are certain your code never reaches a browser but a `window` exists anyway
+(a jsdom harness, an SSR shim), `unsafeAllowSecretKeyInBrowser: true` allows it
+and every request warns.
+
+### What the platform must guarantee
+
+This is now enforced by **route membership plus a fail-closed origin binding**,
+not by the four legacy permission names — that mechanism (F017, platform PR
+#1781) supersedes the earlier finding that a site key authorised *zero* roads.
+For a browser to reach the SDK's `public` and `session` roads directly, without a
+proxy, the platform guarantees are:
+
+- **A site key opens a fixed SET of routes by membership**, not by carrying one
+  of `consent.render / widget.render / session.submit / session.render`. Those
+  four permission names are checked by no route (`RequireDFPermission("…")` grep:
+  0 hits) and are no longer how access is decided.
+- **`allowed_domains` on the m2m client must be NON-EMPTY.** The key is bound to
+  its registered origins and refused fail-closed everywhere else, so a leaked
+  site key works nowhere the DF did not list — but a key with an EMPTY
+  `allowed_domains` therefore works **nowhere at all**. Register your origins, or
+  the browser calls 403 with a correct key.
+- **Render and submit need NO credential.** `GET /consent/sessions/{id}/render`,
+  `POST /consent/sessions/{id}/submit` and `GET
+  /consent/sessions/{id}/widget-template` authorise on the **session id + its
+  nonce** — the SDK's `session` road sends no key and no `X-Tenant-Id`, because
+  the session is the capability.
+- The DF read roads (`/df/config`, `/df/purposes`, `/df/notice/purposes`,
+  `/df/notice/template`) are the SDK's `public` road: openable by a site key
+  whose `allowed_domains` includes the calling origin.
+
+What this SDK still enforces on its side: a **secret** key (`tiq_live_` /
+`tiq_test_`) is refused in a browser at construction — that is orthogonal to the
+above and does not change. The `df` lifecycle roads (create session, validate,
+withdraw, …) remain server-to-server and go through `proxyEndpoint` in a browser.
+
+---
+
+## Reliability
+
+Every request carries a deadline, retries safely, and can be cancelled.
+
+```ts
+const ce = new ConsentEraClient({
+  tenantId: TENANT,
+  proxyEndpoint: '/api/consentera',
+  timeoutMs: 10_000,                                  // default
+  retry: { attempts: 3, baseDelayMs: 250, maxDelayMs: 4000 },  // default
+});
+
+// one key per logical operation — a double-clicked Save is ONE consent write
+await ce.consent.update(id, updates, context, 'btn_save', { idempotencyKey: formSubmissionId });
+
+// cancel from your own code
+const ac = new AbortController();
+await ce.consent.validate(who, 'analytics', { signal: ac.signal });
+```
+
+Retries happen on network failure, 5xx and 429, with exponential backoff and full
+jitter, honouring `Retry-After`. The idempotency key is minted **once per logical
+operation** and reused across every retry of it, so a retry can never write twice.
+
+## Errors
+
+```ts
+import { ConsenteraError } from '@consentera/consent-sdk';
+
+try {
+  await ce.consent.createSession({ ... });
+} catch (err) {
+  if (err instanceof ConsenteraError) {
+    err.kind;       // 'identity' | 'guardian' | 'rate_limit' | 'auth' | … (closed set)
+    err.code;       // 'UNKNOWN_IDENTIFIER_FIELD' — the platform's canonical code
+    err.status;     // 400
+    err.requestId;  // quote this in a support ticket
+    err.retryAfterMs;
+  }
+}
+```
+
+Switch on `kind` (closed, exhaustive); read `code` for the platform's exact word.
+
+## Privacy defaults
+
+- **`collectContext: 'minimal'`** by default: platform, device type, browser
+  family, OS family. No UA string, no screen size, no timezone, no page URL, no
+  referrer. `'full'` adds them, with the page URL's **query and fragment removed**;
+  `'none'` sends no context at all.
+- **`beforeSend`** gets the last look at every request body. Return it to send,
+  return `null` to refuse (which raises — it never silently sends nothing).
+- Debug logging **never prints a request or response body**. The body of a session
+  create is the Data Principal's identifiers.
+
+## How the SDK identifies itself
+
+Every request carries the pair agreed across all six Consentera SDKs:
+
+```
+User-Agent:        ConsenteraSDK/2.0.0 (<platform>; <runtime>)
+X-Consentera-SDK:  js/2.0.0
+```
+
+`ConsenteraSDK/<version>` is the form the platform's audit pipeline already
+parses. **In a browser only the second is sent**: `User-Agent` is a forbidden
+fetch header, so the browser drops any attempt to set it — the Node build and
+the CLI send both.
+
+```ts
+new ConsentEraClient({
+  tenantId: TENANT,
+  proxyEndpoint: '/api/consentera',
+  collectContext: 'none',
+  beforeSend: ({ body }) => redactForYourPolicy(body),
+});
+```
+
+## Content Security Policy
+
+The SDK makes no `eval` and inserts no `<script>`. It does inject a `<style>`
+element for the banner and preference centre, so a strict `style-src` needs
+either `'unsafe-inline'` or the SDK's styles disabled (bring your own UI).
+
+The CDN build is at `dist/consentera-consent.min.js` (`unpkg`/`jsdelivr` point
+there). Pin the version and use the published SRI hash.
+
+## Migrating from 1.x
+
+See [CHANGELOG.md](./CHANGELOG.md). In short: `handleCallback()` is async and
+fails closed, a failed consent sync now throws instead of reporting success,
+`apiKey` is refused in a browser, identifiers replaced `data_principal_ref`,
+telemetry is off by default, and the cookie banner (`ConsenteraConsent`, the
+default export) **requires `apiEndpoint`** — there is no default server, and a
+missing one is refused at construction with `ENDPOINT_REQUIRED` (script tag:
+`data-api-endpoint`).
+
+## Licence
+
+MIT — see [LICENSE](./LICENSE).