@necessarysdk/react-native 0.0.0-stage → 0.1.5

package/src/stepUpKey.ts

@@ -0,0 +1,238 @@
+/**
+ * The step-up key (the public guide, section 3): a second key that the person must unlock, the
+ * options it is made with, and its re-enrolment proof.
+ */
+
+import { NativeKeyException } from './errors';
+import { base64UrlNoPadding, utf8Encode } from './util/bytes';
+import { isObject, nativeFailure, stepUpKeyModule } from './util/native';
+import { jwkThumbprint, orderedJwk, type PublicJwk } from './installationKey';
+
+/**
+ * The optional step-up key as the native side reports it. [factor], [mode] and [windowSeconds]
+ * describe what the platform keystore actually enforces (read back from the key itself), which
+ * on Android 9 and 10 is a short hardware window rather than per-use.
+ */
+export class StepUpKeyMetadata {
+  readonly publicKey: PublicJwk;
+  readonly factor: string;
+  readonly mode: string;
+  readonly windowSeconds: number;
+  readonly securityLevel: string;
+  readonly hardwareBacked: boolean;
+  readonly created: boolean;
+
+  constructor(value: {
+    publicKey: PublicJwk;
+    factor: string;
+    mode: string;
+    windowSeconds: number;
+    securityLevel: string;
+    hardwareBacked: boolean;
+    created: boolean;
+  }) {
+    this.publicKey = value.publicKey;
+    this.factor = value.factor;
+    this.mode = value.mode;
+    this.windowSeconds = value.windowSeconds;
+    this.securityLevel = value.securityLevel;
+    this.hardwareBacked = value.hardwareBacked;
+    this.created = value.created;
+  }
+
+  get authJson(): Record<string, unknown> {
+    return { factor: this.factor, mode: this.mode, window_seconds: this.windowSeconds };
+  }
+
+  get description(): string {
+    return this.mode === 'per_use'
+      ? `${this.factor}, per-use`
+      : `${this.factor}, ${this.windowSeconds}s hardware window`;
+  }
+
+  /** RFC 7638 thumbprint, the same form the server derives from the JWK. */
+  get thumbprint(): string {
+    return jwkThumbprint(this.publicKey);
+  }
+
+  static fromPlatform(value: Record<string, unknown>): StepUpKeyMetadata {
+    const rawPublicKey = value['public_key'];
+    const rawAuth = value['auth'];
+    if (!isObject(rawPublicKey) || !isObject(rawAuth)) {
+      throw new TypeError('The native step-up key provider returned no public key or auth.');
+    }
+    const publicKey = orderedJwk(rawPublicKey);
+    if (
+      publicKey['kty'] !== 'EC' ||
+      publicKey['crv'] !== 'P-256' ||
+      publicKey['alg'] !== 'ES256' ||
+      typeof publicKey['x'] !== 'string' ||
+      typeof publicKey['y'] !== 'string'
+    ) {
+      throw new TypeError('The native step-up key provider did not return an EC P-256 public JWK.');
+    }
+    const factor = rawAuth['factor'];
+    const mode = rawAuth['mode'];
+    const window = rawAuth['window_seconds'];
+    if (typeof factor !== 'string' || typeof mode !== 'string' || typeof window !== 'number' || !Number.isInteger(window)) {
+      throw new TypeError('The native step-up key provider returned an invalid auth description.');
+    }
+    const securityLevel = value['security_level'];
+    return new StepUpKeyMetadata({
+      publicKey,
+      factor,
+      mode,
+      windowSeconds: window,
+      securityLevel: typeof securityLevel === 'string' ? securityLevel : 'unknown',
+      hardwareBacked: value['hardware_backed'] === true,
+      created: value['created'] === true,
+    });
+  }
+}
+
+/** Where a backend takes a re-enrolled step-up key by default (the public guide, section 4). */
+export const stepUpReenrolPath = '/v1/installations/stepup-key';
+
+/**
+ * How the app wants its step-up key made (the public guide, section 3): [factor] `passcode` or
+ * `biometric`; [mode] `per_use`, or `windowed` with [windowSeconds] from 1. Android 9 and 10 cannot
+ * make a per-use passcode key and make a windowed one; iOS makes per-use keys only. [reenrolPath]
+ * is where the backend takes a new key (DeviceTrust.reenrolStepUp).
+ */
+export class StepUpOptions {
+  readonly factor: string;
+  readonly mode: string;
+  readonly windowSeconds: number;
+  readonly reenrolPath: string;
+
+  constructor(options: { factor?: string; mode?: string; windowSeconds?: number; reenrolPath?: string } = {}) {
+    this.factor = options.factor ?? 'passcode';
+    this.mode = options.mode ?? 'per_use';
+    this.windowSeconds = options.windowSeconds ?? 0;
+    this.reenrolPath = options.reenrolPath ?? stepUpReenrolPath;
+  }
+
+  /**
+   * A key made with other values, or already made: whether it satisfies these options -- the same
+   * factor (a backend refuses any other), and a per-use key or a window no longer than this one. A
+   * per-use key satisfies windowed options.
+   */
+  accepts(key: StepUpKeyMetadata): boolean {
+    return (
+      key.factor === this.factor &&
+      (key.mode === 'per_use' || (this.mode === 'windowed' && key.windowSeconds <= this.windowSeconds))
+    );
+  }
+
+  get description(): string {
+    return `${this.factor}, ${this.mode === 'per_use' ? 'per-use' : `${this.windowSeconds}s window`}`;
+  }
+}
+
+/**
+ * The proof a new step-up key signs at re-enrolment: the base64url of its JSON, the members in this
+ * order. [nonce] is the request proof's nonce of the re-enrolment request.
+ */
+export function stepUpReenrolProof(args: {
+  installationId: string;
+  stepUpKeyThumbprint: string;
+  nonce: string;
+  timestamp: number;
+}): string {
+  return base64UrlNoPadding(
+    utf8Encode(
+      JSON.stringify({
+        version: 1,
+        purpose: 'stepup_reenrol',
+        installation_id: args.installationId,
+        stepup_key_thumbprint: args.stepUpKeyThumbprint,
+        nonce: args.nonce,
+        timestamp: args.timestamp,
+      }),
+    ),
+  );
+}
+
+/**
+ * Whether a step-up key [options] do not accept is replaced before the next registration: only
+ * where the new key can then be bound -- by a re-enrolment ([replaceMismatched]), which binds it
+ * with the person's re-authentication, or by this installation's first registration, which binds
+ * the key it is offered. A known installation's registration never binds an offered key; it only
+ * says whether it matches, so replacing the key there orphans the one the server holds: on a phone
+ * that cannot make the key the options ask for (Android 9 makes no per-use passcode key), the
+ * registration that follows every re-enrolment would replace the key the server had just bound,
+ * and step-up would stay unavailable.
+ */
+export function replacesStepUpKey(
+  key: StepUpKeyMetadata,
+  options: StepUpOptions,
+  flags: { replaceMismatched: boolean; knownInstallation: boolean },
+): boolean {
+  return !key.created && !options.accepts(key) && (flags.replaceMismatched || !flags.knownInstallation);
+}
+
+const STEPUP_MODULE_MISSING = (): NativeKeyException =>
+  new NativeKeyException(
+    'NATIVE_STEPUP_PLUGIN_MISSING',
+    "The SDK's step-up key module is not linked into this app: rebuild the app.",
+  );
+
+export class NativeStepUpKey {
+  /** The mode the app asks for, which decides whether a windowed key first tries to sign inside an open hardware window. */
+  configuredMode: string;
+
+  constructor(options: { configuredMode?: string } = {}) {
+    this.configuredMode = options.configuredMode ?? 'per_use';
+  }
+
+  /**
+   * Returns the existing key as the keystore enforces it, or creates one with these values: an
+   * existing key is never changed, so a caller that needs other values deletes it first.
+   */
+  async getOrCreateKey(args: { factor: string; mode: string; windowSeconds: number }): Promise<StepUpKeyMetadata> {
+    const native = stepUpKeyModule();
+    if (native === null) {
+      throw STEPUP_MODULE_MISSING();
+    }
+    let value: unknown;
+    try {
+      value = await native.getOrCreateKey(args.factor, args.mode, args.windowSeconds);
+    } catch (error) {
+      throw nativeFailure(error, 'The native step-up key provider failed.');
+    }
+    if (!isObject(value)) {
+      throw new NativeKeyException('EMPTY_NATIVE_RESPONSE', 'The native step-up key provider returned no key metadata.');
+    }
+    return StepUpKeyMetadata.fromPlatform(value);
+  }
+
+  /** Shows the system passcode (or biometric) prompt and completes when the person answers it. A cancelled prompt is STEPUP_CANCELLED. */
+  async sign(payloadBase64Url: string, options: { reason: string }): Promise<string> {
+    const native = stepUpKeyModule();
+    if (native === null) {
+      throw STEPUP_MODULE_MISSING();
+    }
+    let signature: unknown;
+    try {
+      signature = await native.sign(payloadBase64Url, options.reason, this.configuredMode);
+    } catch (error) {
+      throw nativeFailure(error, 'The step-up key could not sign.');
+    }
+    if (typeof signature !== 'string' || signature.length === 0) {
+      throw new NativeKeyException('EMPTY_NATIVE_SIGNATURE', 'The step-up key returned no signature.');
+    }
+    return signature;
+  }
+
+  async deleteKey(): Promise<void> {
+    const native = stepUpKeyModule();
+    if (native === null) {
+      throw STEPUP_MODULE_MISSING();
+    }
+    try {
+      await native.deleteKey();
+    } catch (error) {
+      throw nativeFailure(error, 'The step-up key could not be deleted.');
+    }
+  }
+}

package/src/transport.ts

@@ -0,0 +1,145 @@
+/**
+ * How the SDK's messages reach your backend: by default over HTTPS, under the base URL your app
+ * sets (the public guide, section 4).
+ */
+
+import { ApiException } from './errors';
+import { isReleaseBuild } from './util/release';
+import { normalizedTarget } from './util/target';
+
+export type JsonObject = Record<string, unknown>;
+
+export interface SendOptions {
+  /** Sent exactly as given: it is what a request proof hashes. A GET sends no body. */
+  encodedBody?: string | null;
+  bearerToken?: string | null;
+  headers?: Record<string, string>;
+}
+
+/**
+ * Sends one request to your backend and answers its JSON object. A refusal is thrown as an
+ * [ApiException] with the backend's `code`, `message` and `details` (the public guide, section 4,
+ * Errors).
+ */
+export interface DeviceTrustTransport {
+  send(method: string, path: string, options?: SendOptions): Promise<JsonObject>;
+  close(): void;
+}
+
+function isObject(value: unknown): value is JsonObject {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * JSON over HTTPS under [baseUrl]. A release build refuses any other scheme, so a mistyped
+ * endpoint fails loudly instead of sending tokens in the clear.
+ */
+export class HttpTransport implements DeviceTrustTransport {
+  readonly baseUrl: string;
+  /** How long one call may take, in milliseconds. */
+  readonly timeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+  private readonly running = new Set<AbortController>();
+  private closed = false;
+
+  constructor(baseUrl: string, options: { timeoutMs?: number; fetch?: typeof fetch } = {}) {
+    this.baseUrl = baseUrl;
+    this.timeoutMs = options.timeoutMs ?? 15000;
+    this.fetchImpl = options.fetch ?? ((input, init) => fetch(input, init));
+  }
+
+  private get base(): string {
+    if (this.baseUrl.length === 0) {
+      throw new ApiException('No API base URL was set for the backend.', { code: 'api_base_url_missing' });
+    }
+    if (isReleaseBuild() && !this.baseUrl.toLowerCase().startsWith('https://')) {
+      throw new ApiException('The API base URL must be an https:// URL in a release build.', {
+        code: 'api_base_url_insecure',
+      });
+    }
+    return this.baseUrl.endsWith('/') ? this.baseUrl.substring(0, this.baseUrl.length - 1) : this.baseUrl;
+  }
+
+  async send(method: string, path: string, options: SendOptions = {}): Promise<JsonObject> {
+    const url = `${this.base}${normalizedTarget(path)}`;
+    if (this.closed) {
+      throw new ApiException('HTTP connection failed: the transport is closed.');
+    }
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+      ...(options.bearerToken != null ? { Authorization: `Bearer ${options.bearerToken}` } : {}),
+      ...(options.headers ?? {}),
+    };
+    const controller = new AbortController();
+    this.running.add(controller);
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, this.timeoutMs);
+    let status: number;
+    let text: string;
+    try {
+      const response = await this.fetchImpl(url, {
+        method,
+        headers,
+        body: method === 'GET' ? undefined : options.encodedBody ?? '{}',
+        signal: controller.signal,
+      });
+      status = response.status;
+      text = await response.text();
+    } catch (error) {
+      if (timedOut) {
+        throw new ApiException('The server did not respond before the timeout.');
+      }
+      if (this.closed) {
+        throw new ApiException('HTTP connection failed: the transport is closed.');
+      }
+      const words = error instanceof Error ? error.message : String(error);
+      throw new ApiException(`Network connection failed: ${words}`);
+    } finally {
+      clearTimeout(timer);
+      this.running.delete(controller);
+    }
+
+    let decoded: JsonObject = {};
+    if (text.trim().length > 0) {
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(text);
+      } catch {
+        parsed = undefined;
+      }
+      if (!isObject(parsed)) {
+        throw new ApiException('The server returned a non-JSON response.', { statusCode: status });
+      }
+      decoded = parsed;
+    }
+
+    if (status < 200 || status >= 300) {
+      const error = decoded['error'];
+      const refusal = isObject(error) ? error : null;
+      const details = refusal?.['details'];
+      const message = refusal?.['message'];
+      const code = refusal?.['code'];
+      throw new ApiException(
+        typeof message === 'string' ? message : `The server rejected the request (${status}).`,
+        {
+          statusCode: status,
+          code: typeof code === 'string' ? code : undefined,
+          details: isObject(details) ? details : undefined,
+        },
+      );
+    }
+    return decoded;
+  }
+
+  close(): void {
+    this.closed = true;
+    for (const controller of this.running) {
+      controller.abort();
+    }
+    this.running.clear();
+  }
+}

package/src/util/bytes.ts

@@ -0,0 +1,194 @@
+/**
+ * Bytes, the same on the phone and in Node: UTF-8, base64url without padding and SHA-256, written
+ * here so that nothing depends on what a JavaScript engine happens to provide.
+ */
+
+/** The UTF-8 bytes of [text]; a lone surrogate becomes U+FFFD, as every UTF-8 encoder writes it. */
+export function utf8Encode(text: string): Uint8Array {
+  const out: number[] = [];
+  for (let i = 0; i < text.length; i++) {
+    let code = text.charCodeAt(i);
+    if (code >= 0xd800 && code <= 0xdbff && i + 1 < text.length) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        code = 0x10000 + ((code - 0xd800) << 10) + (next - 0xdc00);
+        i++;
+      } else {
+        code = 0xfffd;
+      }
+    } else if (code >= 0xd800 && code <= 0xdfff) {
+      code = 0xfffd;
+    }
+    if (code < 0x80) {
+      out.push(code);
+    } else if (code < 0x800) {
+      out.push(0xc0 | (code >> 6), 0x80 | (code & 0x3f));
+    } else if (code < 0x10000) {
+      out.push(0xe0 | (code >> 12), 0x80 | ((code >> 6) & 0x3f), 0x80 | (code & 0x3f));
+    } else {
+      out.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+/** The text of UTF-8 [bytes]; a malformed sequence becomes U+FFFD. */
+export function utf8Decode(bytes: Uint8Array): string {
+  let out = '';
+  let i = 0;
+  while (i < bytes.length) {
+    const b0 = bytes[i];
+    let code = 0xfffd;
+    let length = 1;
+    if (b0 < 0x80) {
+      code = b0;
+    } else if (b0 >= 0xc2 && b0 < 0xe0 && i + 1 < bytes.length && (bytes[i + 1] & 0xc0) === 0x80) {
+      code = ((b0 & 0x1f) << 6) | (bytes[i + 1] & 0x3f);
+      length = 2;
+    } else if (
+      b0 >= 0xe0 && b0 < 0xf0 && i + 2 < bytes.length &&
+      (bytes[i + 1] & 0xc0) === 0x80 && (bytes[i + 2] & 0xc0) === 0x80
+    ) {
+      const value = ((b0 & 0x0f) << 12) | ((bytes[i + 1] & 0x3f) << 6) | (bytes[i + 2] & 0x3f);
+      if (value >= 0x800 && (value < 0xd800 || value > 0xdfff)) {
+        code = value;
+        length = 3;
+      }
+    } else if (
+      b0 >= 0xf0 && b0 < 0xf5 && i + 3 < bytes.length &&
+      (bytes[i + 1] & 0xc0) === 0x80 && (bytes[i + 2] & 0xc0) === 0x80 && (bytes[i + 3] & 0xc0) === 0x80
+    ) {
+      const value =
+        ((b0 & 0x07) << 18) | ((bytes[i + 1] & 0x3f) << 12) | ((bytes[i + 2] & 0x3f) << 6) | (bytes[i + 3] & 0x3f);
+      if (value >= 0x10000 && value <= 0x10ffff) {
+        code = value;
+        length = 4;
+      }
+    }
+    if (code > 0xffff) {
+      code -= 0x10000;
+      out += String.fromCharCode(0xd800 + (code >> 10), 0xdc00 + (code & 0x3ff));
+    } else {
+      out += String.fromCharCode(code);
+    }
+    i += length;
+  }
+  return out;
+}
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+
+/** Base64url without padding: how every binary value travels. */
+export function base64UrlNoPadding(bytes: Uint8Array | readonly number[]): string {
+  let out = '';
+  let i = 0;
+  for (; i + 2 < bytes.length; i += 3) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + ALPHABET[n & 63];
+  }
+  const rest = bytes.length - i;
+  if (rest === 1) {
+    const n = bytes[i] << 16;
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63];
+  } else if (rest === 2) {
+    const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+    out += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63];
+  }
+  return out;
+}
+
+/** The bytes of base64url [text], with or without padding; throws on any other character. */
+export function base64UrlDecode(text: string): Uint8Array {
+  const clean = text.replace(/=+$/, '');
+  const out: number[] = [];
+  let buffer = 0;
+  let bits = 0;
+  for (const char of clean) {
+    const value = ALPHABET.indexOf(char === '+' ? '-' : char === '/' ? '_' : char);
+    if (value < 0) {
+      throw new TypeError(`Not base64url: ${JSON.stringify(text)}`);
+    }
+    buffer = (buffer << 6) | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out.push((buffer >> bits) & 0xff);
+    }
+  }
+  return Uint8Array.from(out);
+}
+
+const K = new Uint32Array([
+  0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+  0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+  0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+  0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+  0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+  0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+  0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+  0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+
+/** The SHA-256 digest of [bytes]. */
+export function sha256(bytes: Uint8Array): Uint8Array {
+  const h = new Uint32Array([
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+  ]);
+  const bitLength = bytes.length * 8;
+  const padded = new Uint8Array(((bytes.length + 9 + 63) >> 6) << 6);
+  padded.set(bytes);
+  padded[bytes.length] = 0x80;
+  const view = new DataView(padded.buffer);
+  view.setUint32(padded.length - 8, Math.floor(bitLength / 0x100000000));
+  view.setUint32(padded.length - 4, bitLength >>> 0);
+  const w = new Uint32Array(64);
+  for (let offset = 0; offset < padded.length; offset += 64) {
+    for (let t = 0; t < 16; t++) {
+      w[t] = view.getUint32(offset + t * 4);
+    }
+    for (let t = 16; t < 64; t++) {
+      const x = w[t - 15];
+      const y = w[t - 2];
+      const s0 = ((x >>> 7) | (x << 25)) ^ ((x >>> 18) | (x << 14)) ^ (x >>> 3);
+      const s1 = ((y >>> 17) | (y << 15)) ^ ((y >>> 19) | (y << 13)) ^ (y >>> 10);
+      w[t] = (w[t - 16] + s0 + w[t - 7] + s1) >>> 0;
+    }
+    let a = h[0], b = h[1], c = h[2], d = h[3], e = h[4], f = h[5], g = h[6], k = h[7];
+    for (let t = 0; t < 64; t++) {
+      const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
+      const ch = (e & f) ^ (~e & g);
+      const t1 = (k + S1 + ch + K[t] + w[t]) >>> 0;
+      const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
+      const maj = (a & b) ^ (a & c) ^ (b & c);
+      const t2 = (S0 + maj) >>> 0;
+      k = g; g = f; f = e; e = (d + t1) >>> 0; d = c; c = b; b = a; a = (t1 + t2) >>> 0;
+    }
+    h[0] = (h[0] + a) >>> 0; h[1] = (h[1] + b) >>> 0; h[2] = (h[2] + c) >>> 0; h[3] = (h[3] + d) >>> 0;
+    h[4] = (h[4] + e) >>> 0; h[5] = (h[5] + f) >>> 0; h[6] = (h[6] + g) >>> 0; h[7] = (h[7] + k) >>> 0;
+  }
+  const out = new Uint8Array(32);
+  const outView = new DataView(out.buffer);
+  for (let i = 0; i < 8; i++) {
+    outView.setUint32(i * 4, h[i]);
+  }
+  return out;
+}
+
+/** Lowercase hex of [bytes]. */
+export function hex(bytes: Uint8Array): string {
+  let out = '';
+  for (const byte of bytes) {
+    out += (byte < 16 ? '0' : '') + byte.toString(16);
+  }
+  return out;
+}
+
+/** The SHA-256 of [text]'s UTF-8 bytes, in lowercase hex. */
+export function sha256Hex(text: string): string {
+  return hex(sha256(utf8Encode(text)));
+}

package/src/util/native.ts

@@ -0,0 +1,56 @@
+/**
+ * The SDK's native modules, loaded when first used -- so that tests, which replace them, never
+ * load React Native -- and their failures as [NativeKeyException]s.
+ */
+
+import { NativeKeyException } from '../errors';
+import type { Spec as InstallationKeySpec } from '../native/NativeNecessaryInstallationKey';
+import type { Spec as IntegritySpec } from '../native/NativeNecessaryIntegrity';
+import type { Spec as SecureScreenSpec } from '../native/NativeNecessarySecureScreen';
+import type { Spec as StepUpKeySpec } from '../native/NativeNecessaryStepUpKey';
+import type { Spec as StorageSpec } from '../native/NativeNecessaryStorage';
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+export function installationKeyModule(): InstallationKeySpec | null {
+  return require('../native/NativeNecessaryInstallationKey').default ?? null;
+}
+
+export function integrityModule(): IntegritySpec | null {
+  return require('../native/NativeNecessaryIntegrity').default ?? null;
+}
+
+export function stepUpKeyModule(): StepUpKeySpec | null {
+  return require('../native/NativeNecessaryStepUpKey').default ?? null;
+}
+
+export function secureScreenModule(): SecureScreenSpec | null {
+  return require('../native/NativeNecessarySecureScreen').default ?? null;
+}
+
+export function storageModule(): StorageSpec | null {
+  return require('../native/NativeNecessaryStorage').default ?? null;
+}
+
+/** The phone's platform, as the guide names it: `android` or `ios`. */
+export function currentPlatform(): string {
+  return require('react-native').Platform.OS as string;
+}
+/* eslint-enable @typescript-eslint/no-require-imports */
+
+/** A native module's refusal, with the code and the words it gave. */
+export function nativeFailure(error: unknown, fallback: string): NativeKeyException {
+  if (error instanceof NativeKeyException) {
+    return error;
+  }
+  const failure = (typeof error === 'object' && error !== null ? error : {}) as {
+    code?: unknown;
+    message?: unknown;
+  };
+  const code = typeof failure.code === 'string' && failure.code.length > 0 ? failure.code : 'NATIVE_ERROR';
+  const message = typeof failure.message === 'string' && failure.message.length > 0 ? failure.message : fallback;
+  return new NativeKeyException(code, message);
+}
+
+export function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/util/release.ts

@@ -0,0 +1,6 @@
+declare const __DEV__: boolean | undefined;
+
+/** Whether this is a release build: React Native's `__DEV__` false. Tests in Node have none. */
+export function isReleaseBuild(): boolean {
+  return typeof __DEV__ !== 'undefined' && __DEV__ === false;
+}