@consentera/consent-sdk 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,245 @@
+## Unreleased — renewal request wire correction
+
+Existing `renewBulk(principalId, purposeIds, noticeHash, uiEventId, options)`
+keeps its call signature and maps purpose IDs to the platform's `renewals`
+items. Both renewal methods send top-level `captured_at`; the server does not
+consume a nested `affirmative_action` on these roads. The legacy `uiEventId`
+argument remains accepted but is not a server-stored renewal field. Exported
+request types now describe these actual wire bodies. Response metadata and
+idempotency/cancellation options remain available.
+
+# Changelog
+
+All notable changes to `@consentera/consent-sdk`.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased — callback status contract (not published)
+
+### Changed
+
+- **`handleCallback()` reads the platform's own callback vocabulary.** The
+  platform sets `status` to exactly `granted`, `partial` or `denied`, and
+  `pending=1` on every capture (consent/collection.go:4094-4098, :4243, :4274
+  on platform pre-main). The handler knew `completed|denied|expired|error`
+  instead: it had branches for `expired`, `rejected` and `timeout`, which the
+  platform never sends, did not know `partial`, never read `pending`, and sent
+  any unrecognised or missing status down the success road. Now
+  `readCallbackParams()` returns `claimed_status`
+  (`'granted' | 'partial' | 'denied' | 'unknown'`) and `pending`, the result
+  carries `claimed_status` and `claimed_pending`, and an `unknown` status is
+  `unverified` without an artefact read. `claimedCallbackStatus()` and
+  `CallbackClaimedStatus` are exported.
+- **The redirect return can now verify against the real platform.**
+  `handleCallback()` compared the server's `challengeNonce`, stored at create,
+  with a `nonce`/`state` on the return. The platform's return never carries it:
+  it adds only `session_id`, `artifact_id`, `status`, `pending` and, when signed,
+  `sig` (collection.go:4225-4288). `challengeNonce` is the hosted page's
+  credential and rides `consent_url`. So every genuine redirect came back
+  `unverified`. `createSession` now adds its own random `state` to
+  `callback_url`, the way the mobile SDKs do. The platform builds the return on
+  top of that URL's query, so the state comes back, and `handleCallback()`
+  requires it. The stored record holds `state` and no longer holds the nonce.
+  `CallbackParams.nonce` is now `CallbackParams.state`. A `callback_url` that
+  already carries `state` is refused with `CALLBACK_STATE_RESERVED`, and a
+  relative one with `INVALID_CALLBACK_URL`. A session created before this
+  change, or without a callback, is `unverified` on return. Read it back
+  through your backend.
+- **`CallbackStatus` no longer includes `'expired'`.** Nothing on the platform
+  produced it; a return URL saying `status=expired` is now `unverified`.
+
+## Unreleased — M4 integration
+
+### Changed
+
+- Existing `ConsentManager.renew` and `renewBulk` now return
+  `TransportResponse<RenewResponse>` and `TransportResponse<BulkRenewResponse>`:
+  the HTTP status, response body, request ID and retry delay are preserved.
+  A `202` records durable acceptance without claiming a completed artifact.
+  Retain its `artifact_id` and `session_id` for the existing bound artifact read;
+  do not repeat the renewal POST as a polling operation. A stored
+  `integrity_hash` is returned unchanged when available.
+- Renewal change events invalidate caches for the purposes the response actually
+  renewed, including accepted `202` responses. The event is not artifact-readiness
+  evidence. Bulk requests with no successful renewal emit no change event.
+- **Type migration:** callers that ignore the result can continue to do so, but
+  explicit function assignments returning `Promise<void>` must be updated to
+  the new response type. This is not universal source compatibility.
+
+## [2.0.0] — 2026-09-22
+
+A security and correctness release. **Every breaking change below exists because
+the 1.x behaviour could report success for a consent that was never recorded, or
+put a secret in a public bundle.** Read *Breaking* before upgrading.
+
+### Breaking
+
+- **`apiEndpoint` is required by the cookie SDK (`ConsenteraConsent`, the
+  default export), and there is no default server.** A missing or blank value
+  is refused at construction with `ENDPOINT_REQUIRED` — the code
+  `ConsentEraClient` already used. 1.x silently fell back to a built-in host on
+  the `.io` domain, which the company does not own: it did not resolve, so every
+  such embed failed, and it was one DNS record away from receiving the visitor's
+  consent payload and the site key. The script-tag auto-init now reads
+  `data-api-endpoint` and, without it, logs why and initialises nothing instead
+  of taking the bundle down.
+- **`handleCallback()` / `CallbackHandler.parseCallback()` is now `async` and
+  fails closed.** 1.x read `session_id`, `artifact_id` and `status` from the
+  query string, logged *"Callback verified against stored session"*, and verified
+  **nothing** — it never parsed the record it had stored, never compared the
+  nonce, and returned `completed` for any URL carrying an `artifact_id`. A link
+  to `/consent/done?session_id=x&artifact_id=y` made the SDK answer "completed"
+  with no consent given. It now requires the stored session and its nonce to
+  match, and reaches `completed` **only** by fetching the artefact from the
+  platform and confirming it belongs to that session. Everything else is
+  `unverified`, never `completed`. The synchronous
+  `readCallbackParams()` returns the URL's claims for callers who want them.
+- **The artefact read carries `?session_id=`, and `getArtifact` returns a
+  union** (SDK register WEB-033, WEB-034). `getArtifact(id, { sessionId })`
+  resolves `{ state: 'recorded', artifact }` on a 200 and
+  `{ state: 'pending', pending, retryAfterMs }` on the platform's 202; a 404
+  throws `ConsenteraNotFoundError`. `handleCallback()` reads with the session,
+  so a 404 is `unverified` at once instead of being polled as "maybe pending",
+  and it binds the artefact to the person the session was created for
+  (`data_principal_id`, now kept in the stored session record) instead of to a
+  `consent_session_id` field the platform's artefact does not have.
+- **A failed consent sync throws.** 1.x caught every failure in `syncConsent`,
+  logged it at `warn`, wrote the local cookie anyway, hid the banner and fired
+  `consent_given`. The visitor's decision was lost and the banner never came back
+  to ask again. Now the error propagates, nothing is stored, the banner stays up,
+  and the host is told on the `sync_failed` event and `callbacks.onSyncFailed`.
+- **No fabricated notice.** `getDefaultConfig()` is deleted. When the tenant's
+  configuration cannot be fetched, 1.x rendered a hardcoded "We value your
+  privacy" banner with invented purpose ids and an empty `policy_version`, and
+  collected consent against it. `init()` now rejects and no banner is shown.
+- **`apiKey` is refused in a browser** (`SECRET_KEY_IN_BROWSER`) — at BOTH entry
+  points. The lifecycle client and the cookie SDK (`ConsentEraConsent`, the
+  package default export) now share one guard; before, the cookie SDK had no
+  browser check and shipped a `tiq_live_` secret to `/api/v1/cookie-consent/*`
+  silently — that plane ignores the key, so nothing refused it and nothing
+  failed. Consent
+  lifecycle roads need a Data Fiduciary secret; in a browser they must go through
+  `proxyEndpoint`. `unsafeAllowSecretKeyInBrowser: true` overrides, loudly.
+  1.x's advice — *"prefer site key (public, safe for frontend)"* — was wrong in
+  both directions: a site key authorises no lifecycle road at all (its
+  permissions are replaced with four that no route requires), so the only
+  credential that worked was the secret one.
+- **One error type.** `ConsenteraError` with `kind`, `code`, `status`,
+  `requestId`, `retryAfterMs`, plus subclasses for `instanceof`.
+  `ConsentEraApiError` is an alias of it and `.statusCode` still reads, so most
+  1.x error handling keeps working.
+- **Telemetry is off by default.** `collectContext` defaults to `'minimal'`. 1.x
+  sent `page_url: location.href`, the referrer, the raw User-Agent, screen size
+  and timezone on every mutation with no way to turn it off. `'full'` restores
+  them, with the page URL's query and fragment stripped.
+- **`ConsentStorage.save()` returns `boolean`** (false when nothing durable was
+  written).
+- `peerDependencies.react` is `^18 || ^19`; `engines.node` is `>=20`.
+- The UMD global is `Consentera`. `window.ConsentEraConsent` is still set.
+
+### Added
+
+- **Deadlines, retries and idempotency.** Every request has an
+  `AbortController` timeout (default 10s), retries network failures / 5xx / 429
+  with exponential backoff and full jitter honouring `Retry-After`, and carries
+  **one idempotency key per logical operation** reused across retries.
+  `idempotencyKey`, `signal` and `timeoutMs` are caller-supplyable.
+- **`X-Request-ID` surfaced** on every error.
+- **SDK identification**, as the pair agreed across all six surfaces:
+  `User-Agent: ConsenteraSDK/<version> (<platform>; <runtime>)` plus
+  `X-Consentera-SDK: js/<version>`. In a browser only the second is sent —
+  `User-Agent` is a forbidden fetch header there.
+- **The platform's callback signature is verified.** When a
+  `callback_signing_secret` is registered the platform appends
+  `sig = hex(HMAC_SHA256(secret, session_id|artifact_id|status))`; the SDK
+  checks it through `verifyCallbackSignature`, and a callback that carries a
+  `sig` with no verifier configured is `unverified`. The signing key is the
+  DF's, so in a browser the verifier calls your own server.
+- **`pending`**, a new callback status. The consent artefact is written
+  asynchronously after submit (5.2–10.8 s measured), so the callback road polls
+  with backoff inside a bounded window (`artifactWaitMs`, default 15 s) and
+  reports `pending` when it expires — never `completed` on a 404, and never a
+  failure for a consent that was recorded.
+- **React: no hook throws during render** (SDK register WEB-038). A refused
+  provider configuration, or a missing provider, used to throw out of
+  `useConsentEraClient()` and blank the page. Now `client` is `null` with the
+  reason in `error`, `useConsentEra()` returns `ready: false` and `null`
+  namespaces, and `<ConsentGate>` renders its fallback. Code that called a
+  namespace unconditionally must check it first.
+- **`'use client'`** on the built React bundle — the package now works in the
+  Next.js App Router, where 1.x failed the build.
+- **`beforeSend`** hook: the last look at every request body.
+- **Guarded storage.** `localStorage`/`sessionStorage` throw in private mode,
+  with cookies blocked, and in sandboxed iframes; every access is wrapped and
+  degrades to memory. A cookie over the 4096-byte browser limit is refused
+  loudly instead of being dropped silently.
+- **Popup flow: `openConsentPopup` opens a dialog on your page and hears the
+  message `/collect` actually posts** (SDK register WEB-035). It frames
+  `consent_url` and resolves on `consentera:submitted` / `consentera:declined`
+  from the `/collect` origin and the frame it opened. The result is
+  `{ outcome: 'decided', session_id, artifact_id, status, pending, … }` or
+  `{ outcome: 'dismissed' }`, with a timeout. The first 2.0.0 cut used
+  `window.open` and listened for `consentera:consent-result`, which the
+  platform never sends. A top-level `/collect` posts nothing, and that
+  promise could only end at the timeout or as `unverified`. Your page must be
+  on the session callback's origin (`CALLBACK_ORIGIN_MISMATCH` otherwise) and
+  in the client's Allowed Domains. `readDecisionMessage` is exported for hosts
+  that frame the page themselves.
+- **`tenantId` is optional behind `proxyEndpoint`** (SDK register WEB-036).
+  The Data Fiduciary's server supplies the tenant there and the SDK sends no
+  tenant header, so requiring the value made integrators invent one. It is
+  still required with `apiEndpoint` (`TENANT_ID_REQUIRED`).
+- **`ValidateResponse` is the platform's answer** (SDK register WEB-037):
+  `data_principal_id`, `purpose_id`, `validated_at`, `effective_at`,
+  `legal_basis`, `is_mandatory`, `dpdp_exemption_basis` and `message` are
+  typed, and the `artifact_id` the platform never sends is gone.
+  `purpose_code` is optional, as on the wire. `BulkValidateResponse` gains
+  `total_count`, `allow_count` and `deny_count`.
+- **Type declarations actually ship.** `npm run build` now runs `build:types`;
+  1.x's `build` did not, so the published tarball declared `types` at a path that
+  did not exist. `scripts/verify-pack.sh` asserts it from the tarball.
+- **The ESM and CJS bundles are `.mjs` and `.cjs`.** They were
+  `consentera-consent.esm.js` and `.cjs.js`, and Node decides a file's module
+  system from its EXTENSION plus the package `type`, not from the exports
+  condition that reached it — so with `"type": "commonjs"` **every named import
+  from an ESM project failed**: `SyntaxError: Named export 'CallbackHandler'
+  not found`. Found by installing the tarball, which is now a gate
+  (`scripts/install-smoke.sh`).
+- `exports` carries per-condition `types` (with a `.d.mts` entry for ESM, so the
+  types are no longer "masquerading as CJS"), plus `sideEffects`, `engines`,
+  `unpkg`, `jsdelivr`, `homepage`, `bugs`, `typesVersions`, and README/LICENSE
+  in `files`. `publint` and `@arethetypeswrong/cli` are both clean.
+- ESLint 9 flat config that runs (1.x's `lint` script had no eslint installed and
+  no config file — it printed `eslint: not found`).
+- React tests, a coverage floor, `publint` and `@arethetypeswrong/cli`.
+
+### Fixed
+
+- `useConsentValidation` cancels in-flight checks and drops out-of-order
+  responses. A stale `ALLOW` could overwrite a fresh `DENY` — a consent gate
+  failing **open**.
+- `useConsentValidation` subscribes to `consent.changed`, so `<ConsentGate>`
+  closes on withdrawal without a remount.
+- `useConsentValidation` depends on `who` **by value**. With the object-shaped
+  prop, an inline literal made a new reference every render and the effect
+  re-fired every render — an unbounded request loop.
+- `ConsentEraProvider` no longer calls `setState` during render, and keeps
+  providing context when construction fails, so hooks report the real cause
+  instead of "must be used within `<ConsentEraProvider>`" inside a provider.
+- A 200 response whose body is not JSON is a server error, not a network error.
+- Identifiers are never logged; request/response bodies are never logged.
+- `tsc --strict` is clean, and `build:types` no longer disables the two strict
+  flags that were failing.
+- Idempotency keys and generated ids use `crypto.randomUUID()`, not
+  `Math.random()`.
+- The transport's `public` and `session` road classes are now WIRED — the DF
+  reads ride `public` (site-key-openable) and the session widget template rides
+  `session` (nonce, no credential). Nothing set a road before, so both classes
+  were dead and every DF read demanded a secret it did not need.
+- `getWidgetTemplate()` (`GET /df/widget-template`, a 404 — no such route) is
+  replaced by `getSessionWidgetTemplate(sessionId)` (`GET
+  /consent/sessions/{id}/widget-template`). Use `getNoticeTemplate()` for the
+  notice-authoring template.
+- `getArtifact` encodes the artifact id in the path (it did not; the
+  CallbackHandler copy did).
+
+[2.0.0]: https://github.com/consentera-platform/consentera-sdks/releases/tag/v2.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.