@dpdpguard/react-native 1.3.0 → 2.0.0

package/src/offline/OfflineCaptureManager.ts

@@ -0,0 +1,249 @@
+import { canonicalCaptureString } from "./captureArtifact";
+import type { Spec as OfflineNativeSpec } from "../NativeDpdpGuardOffline";
+import type {
+	CaptureInput,
+	OfflineCaptureResult,
+	OfflineCaptureSession,
+	OfflineCaptureSyncBody,
+	OfflineCaptureTransport,
+} from "./types";
+
+/** `POST /api/v1/offline/captures` rejects a batch larger than this. */
+export const MAX_SYNC_BATCH = 200;
+
+export interface OfflineCaptureManagerOptions {
+	organizationId: string;
+	/** The enrolled `agentDevices` row id for this device. */
+	deviceId: string;
+	/**
+	 * The native binding. Defaults to the `DpdpGuardOffline` TurboModule;
+	 * inject a fake in tests, or to run the capture flow on a platform
+	 * where the native module isn't installed.
+	 */
+	native?: OfflineNativeSpec;
+}
+
+/**
+ * Device-side offline consent capture — the client half of
+ * `docs/specs/offline-consent-capture.md` §4.
+ *
+ * {@link OfflineCaptureManager.capture} does no network I/O at all: it
+ * builds the `dpdpcca/2` canonical string, has the secure element sign it,
+ * and persists the session to the encrypted local store.
+ * {@link OfflineCaptureManager.syncPending} drains that store when
+ * connectivity returns and evicts every session the server acknowledges.
+ */
+export class OfflineCaptureManager {
+	private readonly organizationId: string;
+	private readonly deviceId: string;
+	private readonly native: OfflineNativeSpec;
+	private sequence = 0;
+
+	constructor(options: OfflineCaptureManagerOptions) {
+		this.organizationId = options.organizationId;
+		this.deviceId = options.deviceId;
+		// The native module is required lazily so that importing this package
+		// on a platform without it (a plain Node test runner, web) doesn't
+		// throw at import time — only constructing a manager without an
+		// injected `native` does.
+		this.native =
+			options.native ??
+			(require("../NativeDpdpGuardOffline").default as OfflineNativeSpec);
+	}
+
+	/**
+	 * Creates the device's secure-element signing key if needed and returns
+	 * its base64 SPKI DER public key, plus whether the key is actually
+	 * hardware-backed. Enroll that public key on `agentDevices` through the
+	 * fleet-enrollment console flow before any capture will verify.
+	 */
+	async enroll(): Promise<{
+		publicKeySPKIBase64: string;
+		hardwareBacked: boolean;
+	}> {
+		const publicKeySPKIBase64 = await this.native.enrollDevice();
+		const hardwareBacked = await this.native.isHardwareBacked();
+		return { publicKeySPKIBase64, hardwareBacked };
+	}
+
+	/**
+	 * Signs and queues one capture. Works at zero bars — nothing here
+	 * touches the network.
+	 */
+	async capture(input: CaptureInput): Promise<OfflineCaptureSession> {
+		const clientSessionId = input.clientSessionId ?? generateUuidV4();
+		const capturedAtClient = input.capturedAtClient ?? Date.now();
+
+		const canonical = canonicalCaptureString({
+			clientSessionId,
+			organizationId: this.organizationId,
+			deviceId: this.deviceId,
+			noticeId: input.noticeId,
+			noticeVersion: input.noticeVersion,
+			noticeLocale: input.noticeLocale,
+			purposeGrants: input.purposeGrants.map((grant) => ({
+				purposeKey: grant.purposeKey,
+				status: grant.status,
+			})),
+			dataTypes: input.dataTypes,
+			principalHandleKind: input.principalHandle?.kind ?? "none",
+			principalHandleValue: input.principalHandle?.value ?? "",
+			capturedAtClient,
+			channel: input.channel,
+		});
+
+		const deviceSignature = await this.native.sign(canonical);
+
+		this.sequence += 1;
+		const session: OfflineCaptureSession = {
+			clientSessionId,
+			organizationId: this.organizationId,
+			deviceId: this.deviceId,
+			noticeId: input.noticeId,
+			noticeVersion: input.noticeVersion,
+			noticeLocale: input.noticeLocale,
+			channel: input.channel,
+			capturedAtClient,
+			captureSequence: this.sequence,
+			purposeGrants: input.purposeGrants,
+			dataTypes: input.dataTypes,
+			canonical,
+			deviceSignature,
+			...(input.principalHandle
+				? { principalHandle: input.principalHandle }
+				: {}),
+			...(input.linkId ? { linkId: input.linkId } : {}),
+		};
+
+		await this.native.saveSession(clientSessionId, JSON.stringify(session));
+		return session;
+	}
+
+	/** Every queued session, oldest capture first. */
+	async pendingSessions(): Promise<OfflineCaptureSession[]> {
+		const raw = await this.native.loadPendingSessions();
+		const sessions: OfflineCaptureSession[] = [];
+		for (const entry of raw) {
+			try {
+				sessions.push(JSON.parse(entry) as OfflineCaptureSession);
+			} catch {
+				// A corrupt entry is skipped rather than failing the whole
+				// drain — the native store reports these separately.
+			}
+		}
+		return sessions.sort((a, b) => a.capturedAtClient - b.capturedAtClient);
+	}
+
+	/**
+	 * Drains the local store through `transport`, in batches of at most
+	 * {@link MAX_SYNC_BATCH}, and evicts every session the server
+	 * acknowledged.
+	 *
+	 * All three statuses are terminal acknowledgements: a `quarantined` or
+	 * `rejected` session is retained *server-side* as evidence (spec §4.4 —
+	 * never silently dropped), so keeping a local copy would only mean
+	 * re-submitting it forever.
+	 *
+	 * Partial batch success is normal and is not an error: inspect the
+	 * returned results rather than assuming a resolved promise means every
+	 * capture committed.
+	 */
+	async syncPending(
+		transport: OfflineCaptureTransport,
+	): Promise<OfflineCaptureResult[]> {
+		const pending = await this.pendingSessions();
+		const results: OfflineCaptureResult[] = [];
+
+		for (let i = 0; i < pending.length; i += MAX_SYNC_BATCH) {
+			const batch = pending.slice(i, i + MAX_SYNC_BATCH);
+			const response = await transport(toSyncBody(batch));
+			const batchResults = response.results ?? [];
+			results.push(...batchResults);
+
+			for (const result of batchResults) {
+				await this.native.removeSession(result.clientSessionId);
+			}
+		}
+
+		return results;
+	}
+
+	/** Drops every queued session without syncing. */
+	clearPending(): Promise<void> {
+		return this.native.removeAllSessions();
+	}
+}
+
+/**
+ * Maps queued sessions to the `POST /api/v1/offline/captures` body.
+ * `organizationId`, `canonical`, and `captureSequence` are local-only — the
+ * server derives the org from the API key and recomputes the canonical
+ * string itself.
+ */
+export function toSyncBody(
+	sessions: OfflineCaptureSession[],
+): OfflineCaptureSyncBody {
+	return {
+		sessions: sessions.map((session) => ({
+			clientSessionId: session.clientSessionId,
+			deviceId: session.deviceId,
+			noticeId: session.noticeId,
+			noticeVersion: session.noticeVersion,
+			noticeLocale: session.noticeLocale,
+			channel: session.channel,
+			capturedAtClient: session.capturedAtClient,
+			deviceSignature: session.deviceSignature,
+			dataTypes: session.dataTypes,
+			purposeGrants: session.purposeGrants,
+			...(session.principalHandle
+				? { principalHandle: session.principalHandle }
+				: {}),
+			...(session.linkId ? { linkId: session.linkId } : {}),
+		})),
+	};
+}
+
+/**
+ * UUIDv4 for `clientSessionId`. This is an idempotency key, not a secret,
+ * but it still prefers a CSPRNG where one exists; the `Math.random`
+ * fallback only runs on a JS engine exposing neither `crypto.randomUUID`
+ * nor `crypto.getRandomValues`.
+ */
+function generateUuidV4(): string {
+	const cryptoObj = (
+		globalThis as {
+			crypto?: {
+				randomUUID?: () => string;
+				getRandomValues?: (array: Uint8Array) => Uint8Array;
+			};
+		}
+	).crypto;
+
+	if (typeof cryptoObj?.randomUUID === "function") {
+		return cryptoObj.randomUUID();
+	}
+
+	const bytes = new Uint8Array(16);
+	if (typeof cryptoObj?.getRandomValues === "function") {
+		cryptoObj.getRandomValues(bytes);
+	} else {
+		for (let i = 0; i < 16; i += 1) {
+			bytes[i] = Math.floor(Math.random() * 256);
+		}
+	}
+
+	bytes[6] = (bytes[6] & 0x0f) | 0x40;
+	bytes[8] = (bytes[8] & 0x3f) | 0x80;
+
+	const hex: string[] = [];
+	for (let i = 0; i < 16; i += 1) {
+		hex.push(bytes[i].toString(16).padStart(2, "0"));
+	}
+	return [
+		hex.slice(0, 4).join(""),
+		hex.slice(4, 6).join(""),
+		hex.slice(6, 8).join(""),
+		hex.slice(8, 10).join(""),
+		hex.slice(10, 16).join(""),
+	].join("-");
+}

package/src/offline/captureArtifact.ts

@@ -0,0 +1,184 @@
+/**
+ * The Cryptographic Consent Artifact canonicalization — `dpdpcca/2`, from
+ * `@dpdpguard/contract`'s `conformance/audit-hash-spec.md` and
+ * `docs/specs/offline-consent-capture.md` §4.2 — pinned byte-for-byte by
+ * `conformance/capture-artifact-vectors.json`.
+ *
+ * This is the one part of offline capture that must be identical across
+ * every SDK and the server: a device signs these exact bytes, and the
+ * server re-derives them at sync. A single byte of drift quarantines a
+ * legitimate consent as `signature_mismatch`. It therefore lives here, in
+ * JavaScript, tested against the golden vectors — the native modules under
+ * `android/` and `ios/` do key storage, signing, and encrypted persistence
+ * only, and never reimplement this string.
+ */
+
+/** Wire values for `offlineCaptureSessions.channel`. */
+export type CaptureChannel = "qr" | "agent_app" | "pos" | "async_link" | "ivr";
+
+/** Per-purpose decision recorded in a capture. */
+export type PurposeGrantStatus = "opt_in" | "opt_out";
+
+/** How the Data Principal was identified at capture time. */
+export type PrincipalHandleKind = "phone_hash" | "uhid" | "cbs_ref" | "none";
+
+export interface PurposeGrant {
+	purposeKey: string;
+	status: PurposeGrantStatus;
+}
+
+/** The exact fields covered by the device signature. */
+export interface CaptureArtifactInput {
+	/** Client-generated UUIDv4; also the sync idempotency key. */
+	clientSessionId: string;
+	organizationId: string;
+	/** The `agentDevices` row whose public key must verify this signature. */
+	deviceId: string;
+	noticeId: string;
+	noticeVersion: number;
+	/** The Eighth Schedule locale actually rendered — s. 5(3) evidence. */
+	noticeLocale: string;
+	purposeGrants: PurposeGrant[];
+	dataTypes: string[];
+	principalHandleKind: PrincipalHandleKind;
+	/**
+	 * The **raw** handle as collected — signed raw so an SDK need not
+	 * reimplement the platform's HMAC. Empty serializes as the literal
+	 * `"null"`.
+	 */
+	principalHandleValue: string;
+	/** Device clock. Context, never authority (spec §4.3). */
+	capturedAtClient: number;
+	channel: CaptureChannel;
+}
+
+/** The literal first token of every canonical string. */
+export const CAPTURE_ARTIFACT_VERSION = "dpdpcca/2";
+
+/**
+ * UTF-8 bytes of `value`. Hand-rolled rather than using `TextEncoder` so
+ * this behaves identically on every JS engine React Native ships with,
+ * including older Hermes builds where `TextEncoder` is absent.
+ */
+export function utf8Bytes(value: string): number[] {
+	const out: number[] = [];
+	for (let i = 0; i < value.length; i += 1) {
+		let codePoint = value.charCodeAt(i);
+
+		// Combine a surrogate pair into its single code point.
+		if (codePoint >= 0xd800 && codePoint <= 0xdbff && i + 1 < value.length) {
+			const low = value.charCodeAt(i + 1);
+			if (low >= 0xdc00 && low <= 0xdfff) {
+				codePoint = (codePoint - 0xd800) * 0x400 + (low - 0xdc00) + 0x10000;
+				i += 1;
+			}
+		}
+
+		if (codePoint < 0x80) {
+			out.push(codePoint);
+		} else if (codePoint < 0x800) {
+			out.push(0xc0 | (codePoint >> 6), 0x80 | (codePoint & 0x3f));
+		} else if (codePoint < 0x10000) {
+			out.push(
+				0xe0 | (codePoint >> 12),
+				0x80 | ((codePoint >> 6) & 0x3f),
+				0x80 | (codePoint & 0x3f),
+			);
+		} else {
+			out.push(
+				0xf0 | (codePoint >> 18),
+				0x80 | ((codePoint >> 12) & 0x3f),
+				0x80 | ((codePoint >> 6) & 0x3f),
+				0x80 | (codePoint & 0x3f),
+			);
+		}
+	}
+	return out;
+}
+
+/** Token length is counted in UTF-8 bytes — not characters, not UTF-16 units. */
+export function utf8ByteLength(value: string): number {
+	return utf8Bytes(value).length;
+}
+
+/**
+ * Byte-wise UTF-8 ordering.
+ *
+ * Not `String.prototype.sort`'s default: that compares UTF-16 code units,
+ * which disagrees with UTF-8 byte order for anything above the BMP (a
+ * surrogate pair sorts below U+E000–U+FFFF, its UTF-8 bytes sort above).
+ * The sorts are load-bearing — a client that listed its purposes in a
+ * different order on retry would otherwise produce a different canonical
+ * string and quarantine a legitimate consent.
+ */
+export function compareUtf8(a: string, b: string): number {
+	const left = utf8Bytes(a);
+	const right = utf8Bytes(b);
+	const shared = Math.min(left.length, right.length);
+	for (let i = 0; i < shared; i += 1) {
+		if (left[i] !== right[i]) return left[i] - right[i];
+	}
+	return left.length - right.length;
+}
+
+function frame(value: string): string {
+	return `${utf8ByteLength(value)}:${value}`;
+}
+
+/**
+ * Builds the canonical string whose UTF-8 bytes the device signs with
+ * ECDSA P-256 / SHA-256.
+ *
+ * Every token is framed as `<utf8ByteLength>:<value>` and joined with `|`;
+ * lists carry an explicit framed count before their framed elements.
+ * `purposeGrants` sorts by `purposeKey` and `dataTypes` sorts by value,
+ * both byte-wise. Neither input array is mutated.
+ *
+ * @throws if two grants share a `purposeKey` — duplicates are rejected at
+ * sync and never collapsed, so failing here turns a guaranteed
+ * server-side rejection into an immediate, debuggable client error.
+ */
+export function canonicalCaptureString(input: CaptureArtifactInput): string {
+	const grants = [...input.purposeGrants].sort((a, b) =>
+		compareUtf8(a.purposeKey, b.purposeKey),
+	);
+
+	for (let i = 1; i < grants.length; i += 1) {
+		if (grants[i].purposeKey === grants[i - 1].purposeKey) {
+			throw new Error(
+				`canonicalCaptureString: duplicate purposeKey "${grants[i].purposeKey}" — duplicates are rejected at sync, never collapsed.`,
+			);
+		}
+	}
+
+	const dataTypes = [...input.dataTypes].sort(compareUtf8);
+
+	const tokens: string[] = [
+		frame(CAPTURE_ARTIFACT_VERSION),
+		frame(input.clientSessionId),
+		frame(input.organizationId),
+		frame(input.deviceId),
+		frame(input.noticeId),
+		frame(String(input.noticeVersion)),
+		frame(input.noticeLocale),
+		frame(String(grants.length)),
+	];
+
+	for (const grant of grants) {
+		tokens.push(frame(grant.purposeKey), frame(grant.status));
+	}
+
+	tokens.push(frame(String(dataTypes.length)));
+	for (const dataType of dataTypes) {
+		tokens.push(frame(dataType));
+	}
+
+	tokens.push(
+		frame(input.principalHandleKind),
+		frame(input.principalHandleValue.length > 0 ? input.principalHandleValue : "null"),
+		frame(String(input.capturedAtClient)),
+		frame(input.channel),
+	);
+
+	return tokens.join("|");
+}

package/src/offline/types.ts

@@ -0,0 +1,134 @@
+import type {
+	CaptureChannel,
+	PrincipalHandleKind,
+	PurposeGrantStatus,
+} from "./captureArtifact";
+
+/** Whether a purpose is one the service cannot run without. */
+export type PurposeCategory = "essential" | "non_essential";
+
+/**
+ * A per-purpose decision as it goes over the wire. Note only `purposeKey`
+ * and `status` are covered by the device signature — `purposeLabel` and
+ * `category` are carried for the server's records and are not part of the
+ * `dpdpcca/2` canonical string.
+ */
+export interface CapturePurposeGrant {
+	purposeKey: string;
+	purposeLabel: string;
+	category: PurposeCategory;
+	status: PurposeGrantStatus;
+}
+
+/** The identity the principal can later withdraw by. */
+export interface PrincipalHandle {
+	kind: PrincipalHandleKind;
+	/**
+	 * The raw handle as collected. Signed raw so an SDK need not
+	 * reimplement the platform's HMAC; a `phone_hash` value is HMAC'd
+	 * per-organization server-side and the raw number is never persisted.
+	 */
+	value: string;
+}
+
+/** What a host app passes to {@link OfflineCaptureManager.capture}. */
+export interface CaptureInput {
+	noticeId: string;
+	noticeVersion: number;
+	/** The Eighth Schedule locale actually rendered to the principal. */
+	noticeLocale: string;
+	/**
+	 * Every purpose the principal was *shown*, opted in or out. Declined
+	 * purposes are submitted too: proving someone was shown marketing and
+	 * refused is what distinguishes granular consent from a notice that
+	 * quietly omitted it.
+	 */
+	purposeGrants: CapturePurposeGrant[];
+	dataTypes: string[];
+	principalHandle?: PrincipalHandle;
+	channel: CaptureChannel;
+	/** Set for QR-originated captures only. */
+	linkId?: string;
+	/** Defaults to a generated UUIDv4. Also the sync idempotency key. */
+	clientSessionId?: string;
+	/** Defaults to `Date.now()`. Context, never authority (spec §4.3). */
+	capturedAtClient?: number;
+}
+
+/**
+ * A signed, persisted capture awaiting sync.
+ *
+ * `canonical` is stored alongside the signature deliberately: the
+ * signature is only meaningful against the exact bytes that were signed,
+ * so keeping them means a session stays re-verifiable even if this SDK
+ * later moves to a newer canonicalization version.
+ */
+export interface OfflineCaptureSession {
+	clientSessionId: string;
+	organizationId: string;
+	deviceId: string;
+	noticeId: string;
+	noticeVersion: number;
+	noticeLocale: string;
+	channel: CaptureChannel;
+	capturedAtClient: number;
+	/** Boot-relative ordering counter — see spec §4.3 on clock trust. */
+	captureSequence: number;
+	purposeGrants: CapturePurposeGrant[];
+	dataTypes: string[];
+	principalHandle?: PrincipalHandle;
+	linkId?: string;
+	/** The exact `dpdpcca/2` string that was signed. */
+	canonical: string;
+	/** base64 of the raw IEEE-P1363 `r||s` ECDSA P-256 signature. */
+	deviceSignature: string;
+}
+
+/** One session's outcome from `POST /api/v1/offline/captures`. */
+export interface OfflineCaptureResult {
+	clientSessionId: string;
+	status: "verified" | "quarantined" | "rejected";
+	consentId?: string;
+	/**
+	 * Present for a non-verified session — `unknown_device`,
+	 * `device_revoked`, `signature_mismatch`, `clock_skew`,
+	 * `notice_unpublished`, `notice_superseded`, or `invalid_session`.
+	 */
+	reason?: string;
+	/**
+	 * Present when a consent receipt was issued. Hand this to the principal
+	 * — it is what makes the consent withdrawable under s. 6(4).
+	 */
+	withdrawalToken?: string;
+}
+
+/** The request body `POST /api/v1/offline/captures` expects. */
+export interface OfflineCaptureSyncBody {
+	sessions: {
+		clientSessionId: string;
+		deviceId: string;
+		noticeId: string;
+		noticeVersion: number;
+		noticeLocale: string;
+		channel: CaptureChannel;
+		capturedAtClient: number;
+		deviceSignature: string;
+		dataTypes: string[];
+		purposeGrants: CapturePurposeGrant[];
+		principalHandle?: PrincipalHandle;
+		linkId?: string;
+	}[];
+}
+
+/**
+ * How a batch actually reaches DPDP Guard.
+ *
+ * `POST /api/v1/offline/captures` is declared `security: [apiKey]` — an
+ * org-scoped service key. This SDK never holds one (see README.md's
+ * "What's here vs. what's not"), so it cannot call that endpoint itself.
+ * The host app supplies this function; in practice it POSTs `body` to its
+ * own backend, which adds the API key and forwards it unchanged.
+ */
+export type OfflineCaptureTransport = (
+	body: OfflineCaptureSyncBody,
+) => Promise<{ results: OfflineCaptureResult[] }>;