@dpdpguard/react-native 1.1.1 → 1.3.0

package/README.md

@@ -37,10 +37,18 @@ across both hybrid SDKs.
   DPDP Guard's `/api/v1/auth/broker-token`, and hands the resulting
   short-lived access token to the app. `DpdpGuardClient` takes that token
   via `setAccessToken()` / the constructor, nothing more.
-- **No audit-hash or webhook-signature code.** Both require the
-  platform's HMAC secret (`DPDP_AUDIT_HASH_HMAC_SECRET` /
-  a webhook endpoint's own secret) — server-only concerns, irrelevant to
-  and unsafe inside a mobile client.
+- **No keyed audit hash, and no webhook-signature code.** Both require a
+  secret the app must not hold (`DPDP_AUDIT_HASH_HMAC_SECRET` / a webhook
+  endpoint's own secret) — server-only concerns, unsafe inside a mobile
+  client. The *unkeyed* half of the audit hash is available as
+  `canonicalAuditString()` (see [Audit-hash canonicalization](#audit-hash-canonicalization));
+  it needs no secret.
+- **No offline consent capture.** `dpdpguard-ios-sdk` implements the
+  device-side Cryptographic Consent Artifact (`docs/specs/offline-consent-capture.md`
+  §4) on top of Secure Enclave key storage and an encrypted local store.
+  That needs native code, which this package deliberately doesn't have — and
+  a software-only port would produce artifacts that don't prove what the
+  spec's artifacts prove.
 
 ## Usage
 
@@ -78,6 +86,71 @@ Every non-2xx response throws a `DpdpGuardApiError` with a `code` from the
 ADR-002 error catalog (`err.code`, e.g. `"NOT_FOUND"`) and the HTTP
 `status`.
 
+### Types
+
+The wire types are generated from `@dpdpguard/contract`'s `openapi/v1.yaml`
+and re-exported, so you can name what the client returns instead of
+re-declaring it:
+
+```ts
+import type { DsrRequest, Notice, components } from '@dpdpguard/react-native';
+
+const notice: Notice = await client.getNotice(noticeId);
+
+// Endpoints this SDK deliberately doesn't wrap are still typed:
+type GateDecision = components['schemas']['ConsentGateDecision'];
+```
+
+The contract version these were generated from is recorded in
+`src/CONTRACT_VERSION`; `src/contractVersion.test.ts` fails if an install
+drifts off it.
+
+### Endpoints without a facade method
+
+The DPDP Guard API is wider than the Data-Principal surface this SDK
+curates. `call()` reaches the rest, with the same auth, URL joining, and
+`DpdpGuardApiError` mapping as every other method:
+
+```ts
+import type { components } from '@dpdpguard/react-native';
+
+type Decision = components['schemas']['ConsentGateDecision'];
+const { decisions } = await client.call<{ decisions: Decision[] }>(
+  'GET',
+  '/api/v1/consent/gate/decisions?limit=50',
+);
+```
+
+This widens reach, not privilege: the client still sends only the brokered
+principal token, so org-scoped endpoints will correctly 401 from an app.
+
+### Audit-hash canonicalization
+
+`canonicalAuditString()` builds the `|`-joined canonical string that the
+`consentAuditTrail.auditHash` is computed over
+(`@dpdpguard/contract`'s `conformance/audit-hash-spec.md`), checked against
+that package's golden vectors:
+
+```ts
+import { canonicalAuditString } from '@dpdpguard/react-native';
+
+canonicalAuditString({
+  organizationId: 'org_abc123',
+  noticeId: 'notice_v1',
+  noticeVersion: 1,
+  purpose: 'Marketing',
+  dataTypes: ['phone', 'email'], // sorted for you
+  givenAt: 1700000001000,
+  source: 'brokered',
+});
+// 'org_abc123|notice_v1|1|Marketing|email,phone|1700000001000|brokered'
+```
+
+The hash itself is `HMAC-SHA256` of this string under a secret that stays
+server-side, so this package stops at the canonical form — hand it to your
+backend to sign, or use it to check which event a hash your backend
+returned refers to.
+
 ## Contract
 
 Depends on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpdpguard/react-native",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "DPDP Guard React Native SDK - typed HTTP client over the DPDP Guard /api/v1 surface, usable via plain fetch (no native module)",
   "main": "src/index",
   "files": [
@@ -31,6 +31,6 @@
     "typescript": "~5.8"
   },
   "dependencies": {
-    "@dpdpguard/contract": "^1.5.0"
+    "@dpdpguard/contract": "^1.6.0"
   }
 }

package/src/CONTRACT_VERSION

@@ -0,0 +1 @@
+1.6.0

package/src/auditHash.ts

@@ -0,0 +1,63 @@
+/**
+ * ADR-002 D5 audit-hash canonicalization, ported from
+ * `@dpdpguard/contract`'s `conformance/audit-hash-spec.md` and pinned by the
+ * golden vectors in `conformance/audit-hash-vectors.json`.
+ *
+ * **This module deliberately stops at the canonical string.** The full
+ * `auditHash` is `HMAC-SHA256(canonical, DPDP_AUDIT_HASH_HMAC_SECRET)`, and
+ * that secret is server-side-only — the spec's "Key management" section is
+ * explicit that it never leaves DPDP Guard's infrastructure, and anything
+ * shipped in a React Native bundle is extractable from the app binary. So
+ * unlike `dpdpguard-ios-sdk` and `dpdpguard-android-sdk`, which both expose
+ * `computeAuditHash(input, secret)` because a server-side caller may
+ * legitimately hold the key, this package exposes only the unkeyed half.
+ *
+ * What that half is good for: producing the exact bytes your own backend
+ * will sign, and re-deriving the canonical form of a record so you can
+ * check a hash your backend computed refers to the event you think it does.
+ */
+
+/** ADR-004 D5 auth provenance for a consent event. */
+export type ConsentSource = "brokered" | "direct" | "anonymous" | "linked";
+
+/**
+ * The exact fields the canonicalization is computed over. Every field is
+ * always present in the canonical string — an absent {@link source}
+ * serializes as the literal `"null"`, never an omitted position — so this is
+ * a *versioned*, safety-critical algorithm. Changing field order or the
+ * `"null"` sentinel is a major bump requiring fresh DPO sign-off.
+ */
+export interface AuditHashInput {
+	organizationId: string;
+	noticeId: string;
+	noticeVersion: number;
+	purpose: string;
+	dataTypes: string[];
+	/** Unix epoch milliseconds. Client-authoritative per ADR-003 D3. */
+	givenAt: number;
+	source?: ConsentSource | null;
+}
+
+/**
+ * The `|`-joined canonical string for `input`, per the spec's "Canonical
+ * form":
+ *
+ * ```
+ * organizationId|noticeId|noticeVersion|purpose|dataTypes(sorted,joined by ",")|givenAt|source("null" if absent)
+ * ```
+ *
+ * `dataTypes` is sorted lexicographically, so call order never changes the
+ * result. The input array is not mutated.
+ */
+export function canonicalAuditString(input: AuditHashInput): string {
+	const sortedDataTypes = [...input.dataTypes].sort().join(",");
+	return [
+		input.organizationId,
+		input.noticeId,
+		String(input.noticeVersion),
+		input.purpose,
+		sortedDataTypes,
+		String(input.givenAt),
+		input.source ?? "null",
+	].join("|");
+}

package/src/client.ts

@@ -97,6 +97,41 @@ export class DpdpGuardClient {
 		return json as T;
 	}
 
+	/**
+	 * Escape hatch for an `/api/v1` endpoint this client has no facade
+	 * method for — the DPDP Guard API is wider than the Data-Principal
+	 * surface this SDK curates (see "What's here vs. what's not" in
+	 * README.md), and `src/generated/api-types.ts` types all of it.
+	 *
+	 * `dpdpguard-ios-sdk` ships its whole generated `DPDPGuardConsentAPI`
+	 * target next to the hand-written facade so nothing is unreachable;
+	 * this is the equivalent, without a second HTTP stack.
+	 *
+	 * Auth, base-URL joining, and {@link DpdpGuardApiError} mapping are the
+	 * same as every facade method. Note this changes nothing about *which*
+	 * credential the client holds: it still sends only the brokered
+	 * principal token from {@link setAccessToken}, never a service API key,
+	 * so org-scoped endpoints will correctly 401.
+	 *
+	 * @example
+	 * ```ts
+	 * import type { components } from '@dpdpguard/react-native';
+	 *
+	 * type Decision = components['schemas']['ConsentGateDecision'];
+	 * const { decisions } = await client.call<{ decisions: Decision[] }>(
+	 *   'GET',
+	 *   '/api/v1/consent/gate/decisions?limit=50',
+	 * );
+	 * ```
+	 */
+	call<T>(
+		method: string,
+		path: string,
+		options: { body?: unknown; auth?: "none" | "bearer" } = {},
+	): Promise<T> {
+		return this.request<T>(method, path, options);
+	}
+
 	// --- Public reads (no auth) ---
 
 	getOrganization(slug: string): Promise<OrgSummary> {

package/src/generated/api-types.ts

@@ -330,6 +330,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/consent-status": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Look up an org's per-purpose consent state by email (docs/specs/ecommerce-cms-plugins.md, §4).
+         * @description Read-only: a WooCommerce/Shopify plugin's only fact about a customer is an email address from its own storefront — every other consent-reading route requires a dpdpbot-internal consent id or a brokered principal token. This resolves an email to the calling organization's own current per-purpose consent grants, so a plugin can gate a marketing sync in real time. `found: false` (not a 404) means the identifier is not yet a customer of record for this organization — distinct from "known, with no active consent", which is `found: true` and an empty or all-opted-out `purposes` array. Requires the `dpdp_consent_status_lookup_enabled` flag; while it is off, this route behaves as if it doesn't exist (404). Write access to consent stays `POST`/`DELETE /cm/v1/consent` — there is no corresponding write route here (ADR-007 D3).
+         */
+        get: operations["getConsentStatus"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/breaches": {
         parameters: {
             query?: never;
@@ -1939,6 +1959,69 @@ export interface operations {
             };
         };
     };
+    getConsentStatus: {
+        parameters: {
+            query: {
+                email: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description The calling key's organization's consent status for this email. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": {
+                        identifier: string;
+                        /** @enum {string} */
+                        identifierType: "email";
+                        found: boolean;
+                        purposes: {
+                            purposeKey: string;
+                            /** @enum {string} */
+                            category: "essential" | "non_essential";
+                            /** @enum {string} */
+                            status: "opt_in" | "opt_out";
+                            /** @description Epoch ms this purpose was withdrawn, if any. */
+                            withdrawnAt?: number;
+                        }[];
+                    };
+                };
+            };
+            /** @description Missing `email` query parameter. */
+            400: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description Missing or invalid API key. */
+            401: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+            /** @description The `dpdp_consent_status_lookup_enabled` flag is off. */
+            404: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ApiError"];
+                };
+            };
+        };
+    };
     listBreaches: {
         parameters: {
             query?: never;

package/src/index.ts

@@ -4,3 +4,32 @@ export { DpdpGuardApiError, ERROR_CATALOG } from './errorCatalog';
 export type { ApiErrorCode, ErrorCatalogEntry } from './errorCatalog';
 export { hasConsent } from './consentGate';
 export type { ConsentRecord } from './consentGate';
+export { canonicalAuditString } from './auditHash';
+export type { AuditHashInput, ConsentSource } from './auditHash';
+
+// The openapi-typescript output generated from the installed
+// @dpdpguard/contract's openapi/v1.yaml, re-exported so consumers can name
+// the wire types this client returns (and reach endpoints `DpdpGuardClient`
+// deliberately doesn't wrap) instead of re-declaring them by hand. Mirrors
+// dpdpguard-ios-sdk, which exposes its whole generated `DPDPGuardConsentAPI`
+// target alongside the hand-written facade.
+export type {
+	components,
+	operations,
+	paths,
+} from './generated/api-types';
+
+import type { components } from './generated/api-types';
+
+export type OrgSummary = components['schemas']['OrgSummary'];
+export type Notice = components['schemas']['Notice'];
+export type DsrRequest = components['schemas']['DsrRequest'];
+export type Grievance = components['schemas']['Grievance'];
+export type Nomination = components['schemas']['Nomination'];
+export type ApiError = components['schemas']['ApiError'];
+/**
+ * The wire-level consent record from `/cm/v1/consent`. Distinct from this
+ * package's own {@link ConsentRecord}, which is the minimal shape
+ * {@link hasConsent} gates on.
+ */
+export type ApiConsentRecord = components['schemas']['ConsentRecord'];