@dpdpguard/react-native 1.2.0 → 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
 
@@ -97,6 +105,52 @@ 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.2.0",
+  "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": [

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/index.ts

@@ -4,6 +4,8 @@ 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