@necessarysdk/react-native 0.0.0-stage → 0.1.6

package/src/errors.ts

@@ -0,0 +1,71 @@
+/** The failures the SDK reports. */
+
+/**
+ * A failure of the phone's keystore or of a prompt: [code] says which -- `KEY_UNAVAILABLE` (the
+ * keystore could not be reached for the installation key; no key was made over it: try again, or
+ * reset()), `STEPUP_KEY_INVALIDATED` (the key can never sign again: re-enrol),
+ * `STEPUP_KEY_UNAVAILABLE` (the keystore could not say whether the key is usable, or could not be
+ * reached; it was kept: try again, or re-enrol), `STEPUP_CANCELLED`, `STEPUP_REENROL_PENDING` and
+ * the like -- and [message] says it in words, followed by everything that failed beneath it
+ * (`[cause: ...]`) down to the keystore's own answer wherever the phone gives one.
+ */
+export class NativeKeyException extends Error {
+  /** What failed, for the app to act on. */
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'NativeKeyException';
+    this.code = code;
+  }
+
+  override toString(): string {
+    return `${this.message} [${this.code}]`;
+  }
+}
+
+/**
+ * A refusal from your backend, or a request that did not reach it: the backend's
+ * `{"error": {"code", "message", "details"}}` (the guide, section 4), with the HTTP status.
+ */
+export class ApiException extends Error {
+  /** The HTTP status, when the backend answered. */
+  readonly statusCode?: number;
+
+  /** The backend's `code`: what the app acts on. */
+  readonly code?: string;
+
+  /** The backend's `details`, such as `retry_after_seconds`. */
+  readonly details?: Record<string, unknown>;
+
+  constructor(
+    message: string,
+    options: { statusCode?: number; code?: string; details?: Record<string, unknown> } = {},
+  ) {
+    super(message);
+    this.name = 'ApiException';
+    this.statusCode = options.statusCode;
+    this.code = options.code;
+    this.details = options.details;
+  }
+
+  override toString(): string {
+    return this.message;
+  }
+}
+
+/**
+ * A call that DeviceTrust.reset or DeviceTrust.close ended while it ran: what it found belongs to
+ * an installation that is gone, or to a client that is closed, so nothing of it was kept. After a
+ * reset, call again.
+ */
+export class InterruptedCallException extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'InterruptedCallException';
+  }
+
+  override toString(): string {
+    return this.message;
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Device integrity for React Native apps: the client half of the public integration guide. A key
+ * the SDK never exports, signed measurements of the phone and the app, and request proofs; the
+ * app's backend decides what they mean.
+ */
+
+export * from './client';
+export * from './collector';
+export * from './deviceTrust';
+export * from './errors';
+export * from './installationKey';
+export * from './installationStore';
+export * from './protocol';
+export * from './reinstallHint';
+export * from './report';
+export * from './requestProof';
+export * from './secureScreen';
+export * from './stepUpKey';
+export * from './transport';

package/src/installationKey.ts

@@ -0,0 +1,223 @@
+/**
+ * The installation key: one non-exportable P-256 key per installation, made and held by the
+ * phone's keystore -- StrongBox or the trusted execution environment, the Secure Enclave, or
+ * where that refuses the Keychain.
+ */
+
+import { NativeKeyException } from './errors';
+import { sha256Hex } from './util/bytes';
+import { installationKeyModule, isObject, nativeFailure } from './util/native';
+
+/** A P-256 public key as a JWK: `kty`, `crv`, `alg`, `x`, `y`. */
+export type PublicJwk = Record<string, unknown>;
+
+/** The members of [jwk] in the order the phone writes them: kty, crv, alg, x, y, then any other. */
+export function orderedJwk(jwk: Record<string, unknown>): PublicJwk {
+  const ordered: PublicJwk = {};
+  for (const name of ['kty', 'crv', 'alg', 'x', 'y']) {
+    if (name in jwk) {
+      ordered[name] = jwk[name];
+    }
+  }
+  for (const [name, value] of Object.entries(jwk)) {
+    if (!(name in ordered)) {
+      ordered[name] = value;
+    }
+  }
+  return ordered;
+}
+
+/** RFC 7638 thumbprint of an EC public JWK, in lowercase hex: the same form a backend derives. */
+export function jwkThumbprint(jwk: PublicJwk): string {
+  // RFC 7638 canonical member order for an EC public JWK.
+  return sha256Hex(JSON.stringify({ crv: jwk['crv'], kty: 'EC', x: jwk['x'], y: jwk['y'] }));
+}
+
+export class NativeKeyMetadata {
+  readonly publicKey: PublicJwk;
+  readonly algorithm: string;
+  readonly keyAlias: string;
+  readonly provider: string;
+  readonly securityLevel: string;
+  readonly hardwareBacked: boolean;
+  readonly privateKeyExportable: boolean;
+  readonly signatureFormat: string;
+  readonly created: boolean;
+
+  constructor(value: {
+    publicKey: PublicJwk;
+    algorithm: string;
+    keyAlias: string;
+    provider: string;
+    securityLevel: string;
+    hardwareBacked: boolean;
+    privateKeyExportable: boolean;
+    signatureFormat: string;
+    created: boolean;
+  }) {
+    this.publicKey = value.publicKey;
+    this.algorithm = value.algorithm;
+    this.keyAlias = value.keyAlias;
+    this.provider = value.provider;
+    this.securityLevel = value.securityLevel;
+    this.hardwareBacked = value.hardwareBacked;
+    this.privateKeyExportable = value.privateKeyExportable;
+    this.signatureFormat = value.signatureFormat;
+    this.created = value.created;
+  }
+
+  static fromPlatform(value: Record<string, unknown>): NativeKeyMetadata {
+    const rawPublicKey = value['public_key'];
+    if (!isObject(rawPublicKey)) {
+      throw new TypeError('The native key provider returned no public key.');
+    }
+    const publicKey = orderedJwk(rawPublicKey);
+
+    const requiredString = (field: string): string => {
+      const item = value[field];
+      if (typeof item !== 'string' || item.length === 0) {
+        throw new TypeError(`The native key provider returned an invalid ${field}.`);
+      }
+      return item;
+    };
+    const requiredBool = (field: string): boolean => {
+      const item = value[field];
+      if (typeof item !== 'boolean') {
+        throw new TypeError(`The native key provider returned an invalid ${field}.`);
+      }
+      return item;
+    };
+
+    if (
+      publicKey['kty'] !== 'EC' ||
+      publicKey['crv'] !== 'P-256' ||
+      publicKey['alg'] !== 'ES256' ||
+      typeof publicKey['x'] !== 'string' ||
+      typeof publicKey['y'] !== 'string'
+    ) {
+      throw new TypeError('The native key provider did not return an EC P-256 public JWK.');
+    }
+
+    return new NativeKeyMetadata({
+      publicKey,
+      algorithm: requiredString('algorithm'),
+      keyAlias: requiredString('key_alias'),
+      provider: requiredString('provider'),
+      securityLevel: requiredString('security_level'),
+      hardwareBacked: requiredBool('hardware_backed'),
+      privateKeyExportable: requiredBool('private_key_exportable'),
+      signatureFormat: requiredString('signature_format'),
+      created: requiredBool('created'),
+    });
+  }
+}
+
+const KEY_MODULE_MISSING = new NativeKeyException(
+  'NATIVE_KEY_PLUGIN_MISSING',
+  "The SDK's installation-key module is not linked into this app: rebuild the app.",
+);
+
+export class NativeInstallationKey {
+  async getOrCreateKey(): Promise<NativeKeyMetadata> {
+    const native = installationKeyModule();
+    if (native === null) {
+      throw KEY_MODULE_MISSING;
+    }
+    let value: unknown;
+    try {
+      value = await native.getOrCreateKey();
+    } catch (error) {
+      throw nativeFailure(error, 'The native key provider failed.');
+    }
+    if (!isObject(value)) {
+      throw new NativeKeyException('EMPTY_NATIVE_RESPONSE', 'The native key provider returned no key metadata.');
+    }
+    return NativeKeyMetadata.fromPlatform(value);
+  }
+
+  async signPayload(payloadBase64Url: string): Promise<string> {
+    const native = installationKeyModule();
+    if (native === null) {
+      throw KEY_MODULE_MISSING;
+    }
+    let signature: unknown;
+    try {
+      signature = await native.sign(payloadBase64Url);
+    } catch (error) {
+      throw nativeFailure(error, 'The native key provider could not sign the challenge.');
+    }
+    if (typeof signature !== 'string' || signature.length === 0) {
+      throw new NativeKeyException('EMPTY_NATIVE_SIGNATURE', 'The native key provider returned no signature.');
+    }
+    return signature;
+  }
+
+  async deleteKey(): Promise<void> {
+    const native = installationKeyModule();
+    if (native === null) {
+      throw KEY_MODULE_MISSING;
+    }
+    try {
+      await native.deleteKey();
+    } catch (error) {
+      throw nativeFailure(error, 'The native installation key could not be deleted.');
+    }
+  }
+}
+
+export class InstallationIdentity {
+  readonly installationId: string;
+  readonly nativeKey: NativeInstallationKey;
+  readonly metadata: NativeKeyMetadata;
+
+  constructor(value: { installationId: string; nativeKey: NativeInstallationKey; metadata: NativeKeyMetadata }) {
+    this.installationId = value.installationId;
+    this.nativeKey = value.nativeKey;
+    this.metadata = value.metadata;
+  }
+
+  get publicKeyJson(): PublicJwk {
+    return this.metadata.publicKey;
+  }
+  get algorithm(): string {
+    return this.metadata.algorithm;
+  }
+  get keyAlias(): string {
+    return this.metadata.keyAlias;
+  }
+  get provider(): string {
+    return this.metadata.provider;
+  }
+  get securityLevel(): string {
+    return this.metadata.securityLevel;
+  }
+  get hardwareBacked(): boolean {
+    return this.metadata.hardwareBacked;
+  }
+  get privateKeyExportable(): boolean {
+    return this.metadata.privateKeyExportable;
+  }
+  get signatureFormat(): string {
+    return this.metadata.signatureFormat;
+  }
+  get createdThisLaunch(): boolean {
+    return this.metadata.created;
+  }
+
+  /** The key's RFC 7638 thumbprint, in lowercase hex. */
+  get keyThumbprint(): string {
+    return jwkThumbprint(this.publicKeyJson);
+  }
+
+  signPayload(payloadBase64Url: string): Promise<string> {
+    return this.nativeKey.signPayload(payloadBase64Url);
+  }
+
+  withInstallationId(canonicalInstallationId: string): InstallationIdentity {
+    return new InstallationIdentity({
+      installationId: canonicalInstallationId,
+      nativeKey: this.nativeKey,
+      metadata: this.metadata,
+    });
+  }
+}

package/src/installationStore.ts

@@ -0,0 +1,143 @@
+/**
+ * Where the SDK keeps the installation ID: in the platform's secure storage beside the key -- on
+ * iOS in the Keychain, on this device only, readable after the first unlock; elsewhere encrypted
+ * under a key the platform keystore holds.
+ */
+
+import { NativeKeyException } from './errors';
+import { nativeFailure, storageModule } from './util/native';
+import { secureRandomBytes } from './requestProof';
+import { InstallationIdentity, NativeInstallationKey } from './installationKey';
+
+/** The secure storage the store writes to: replaced in tests. */
+export interface SecureStorage {
+  read(key: string): Promise<string | null>;
+  write(key: string, value: string): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+
+const STORAGE_MODULE_MISSING = (): NativeKeyException =>
+  new NativeKeyException(
+    'NATIVE_STORAGE_PLUGIN_MISSING',
+    "The SDK's storage module is not linked into this app: rebuild the app.",
+  );
+
+/** The phone's secure storage, through the SDK's native module. */
+export class NativeSecureStorage implements SecureStorage {
+  async read(key: string): Promise<string | null> {
+    const native = storageModule();
+    if (native === null) throw STORAGE_MODULE_MISSING();
+    try {
+      const value = await native.read(key);
+      return typeof value === 'string' ? value : null;
+    } catch (error) {
+      throw nativeFailure(error, 'The secure storage could not be read.');
+    }
+  }
+
+  async write(key: string, value: string): Promise<void> {
+    const native = storageModule();
+    if (native === null) throw STORAGE_MODULE_MISSING();
+    try {
+      await native.write(key, value);
+    } catch (error) {
+      throw nativeFailure(error, 'The secure storage could not be written.');
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    const native = storageModule();
+    if (native === null) throw STORAGE_MODULE_MISSING();
+    try {
+      await native.remove(key);
+    } catch (error) {
+      throw nativeFailure(error, 'The secure storage could not be cleared.');
+    }
+  }
+}
+
+/** A random (version 4) UUID, from the platform's secure random source. */
+export async function randomUuid(): Promise<string> {
+  const bytes = await secureRandomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40;
+  bytes[8] = (bytes[8] & 0x3f) | 0x80;
+  const hexBytes = Array.from(bytes, (byte) => (byte < 16 ? '0' : '') + byte.toString(16));
+  return [
+    hexBytes.slice(0, 4).join(''),
+    hexBytes.slice(4, 6).join(''),
+    hexBytes.slice(6, 8).join(''),
+    hexBytes.slice(8, 10).join(''),
+    hexBytes.slice(10, 16).join(''),
+  ].join('-');
+}
+
+export class InstallationStore {
+  static readonly installationIdKey = 'recognition.installation_id.v2';
+  static readonly stepUpReenrolKey = 'recognition.stepup_reenrol_pending.v1';
+
+  readonly key: NativeInstallationKey;
+  protected readonly storage: SecureStorage;
+  private loading: Promise<InstallationIdentity> | null = null;
+
+  constructor(options: { key?: NativeInstallationKey; storage?: SecureStorage } = {}) {
+    this.key = options.key ?? new NativeInstallationKey();
+    this.storage = options.storage ?? new NativeSecureStorage();
+  }
+
+  /**
+   * The installation: its key, made on first use, and its ID. A key made now
+   * ([InstallationIdentity.createdThisLaunch]) is a new installation, so it gets a new ID even where
+   * one was stored: that ID belongs to the key that was lost, and a backend refuses a known ID under
+   * another key. Calls at once share one load, so that one key never gets two IDs.
+   */
+  loadOrCreate(): Promise<InstallationIdentity> {
+    const running = this.loading;
+    if (running !== null) {
+      return running;
+    }
+    const loading: Promise<InstallationIdentity> = this.load().finally(() => {
+      if (this.loading === loading) {
+        this.loading = null;
+      }
+    });
+    this.loading = loading;
+    return loading;
+  }
+
+  private async load(): Promise<InstallationIdentity> {
+    const stored = await this.storage.read(InstallationStore.installationIdKey);
+    const metadata = await this.key.getOrCreateKey();
+    let installationId = stored ?? '';
+    if (installationId.length === 0 || metadata.created) {
+      installationId = await randomUuid();
+      await this.saveInstallationId(installationId);
+    }
+    return new InstallationIdentity({ installationId, nativeKey: this.key, metadata });
+  }
+
+  /**
+   * Keeps the installation your backend answered for this key, which may not be the ID proposed.
+   * Only this opaque ID is stored here; the private key never leaves the platform's keystore.
+   */
+  saveInstallationId(installationId: string): Promise<void> {
+    return this.storage.write(InstallationStore.installationIdKey, installationId);
+  }
+
+  /** Whether a step-up key was replaced and the backend has not yet taken the new one (DeviceTrust.reenrolStepUp) -- kept across restarts. */
+  async stepUpReenrolPending(): Promise<boolean> {
+    return (await this.storage.read(InstallationStore.stepUpReenrolKey)) !== null;
+  }
+
+  setStepUpReenrolPending(pending: boolean): Promise<void> {
+    return pending
+      ? this.storage.write(InstallationStore.stepUpReenrolKey, '1')
+      : this.storage.delete(InstallationStore.stepUpReenrolKey);
+  }
+
+  /** Deletes the key and the installation ID: the next start is a new installation. */
+  async clear(): Promise<void> {
+    await this.key.deleteKey();
+    await this.storage.delete(InstallationStore.installationIdKey);
+    await this.storage.delete(InstallationStore.stepUpReenrolKey);
+  }
+}

package/src/native/NativeNecessaryInstallationKey.ts

@@ -0,0 +1,12 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/** The installation key, in the phone's keystore: made on first use, never exported. */
+export interface Spec extends TurboModule {
+  getOrCreateKey(): Promise<Object>;
+  sign(payload: string): Promise<string>;
+  deleteKey(): Promise<boolean>;
+  reinstallHintIdentifier(): Promise<string>;
+}
+
+export default TurboModuleRegistry.get<Spec>('NecessaryInstallationKey');

package/src/native/NativeNecessaryIntegrity.ts

@@ -0,0 +1,15 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/** The collector: measures what a challenge asks for and the app enabled, and nothing else. */
+export interface Spec extends TurboModule {
+  collect(
+    requiredProbes: string[],
+    challengeNonce: string,
+    optionalProbes: string[],
+    enabledMeasurements: string[],
+  ): Promise<Object>;
+  requestLocationPermission(): Promise<string>;
+}
+
+export default TurboModuleRegistry.get<Spec>('NecessaryIntegrity');

package/src/native/NativeNecessarySecureScreen.ts

@@ -0,0 +1,9 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/** Protection of the app's window while a secret is typed. */
+export interface Spec extends TurboModule {
+  protect(on: boolean): Promise<Object>;
+}
+
+export default TurboModuleRegistry.get<Spec>('NecessarySecureScreen');

package/src/native/NativeNecessaryStepUpKey.ts

@@ -0,0 +1,11 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/** The step-up key: a second key that the person must unlock with the screen lock. */
+export interface Spec extends TurboModule {
+  getOrCreateKey(factor: string, mode: string, windowSeconds: number): Promise<Object>;
+  sign(payload: string, reason: string, mode: string): Promise<string>;
+  deleteKey(): Promise<boolean>;
+}
+
+export default TurboModuleRegistry.get<Spec>('NecessaryStepUpKey');

package/src/native/NativeNecessaryStorage.ts

@@ -0,0 +1,16 @@
+import type { TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+/**
+ * The phone's secure storage for the installation ID and the pending step-up re-enrolment (the
+ * Keychain, readable after the first unlock, on this device only; values encrypted under a key in
+ * the platform keystore), and the platform's secure random source.
+ */
+export interface Spec extends TurboModule {
+  read(key: string): Promise<string | null>;
+  write(key: string, value: string): Promise<boolean>;
+  remove(key: string): Promise<boolean>;
+  randomBytes(count: number): Promise<string>;
+}
+
+export default TurboModuleRegistry.get<Spec>('NecessaryStorage');

package/src/protocol.ts

@@ -0,0 +1,52 @@
+/** What the client does about the protocol errors of the public guide's section 4. */
+
+import { ApiException } from './errors';
+
+/**
+ * What the client does about a refusal from your backend's API: the protocol errors of the
+ * integration guide's section 4, each acted on once. Any other refusal goes to the app as it came.
+ */
+export enum ProtocolStep {
+  askAgain = 'askAgain',
+  proveAgain = 'proveAgain',
+  registerAgain = 'registerAgain',
+  waitThenRetry = 'waitThenRetry',
+  stop = 'stop',
+}
+
+/** The longest wait the client sits through before it retries a 429 itself; a longer one goes to the app. */
+export const protocolMaxWaitSeconds = 10;
+
+/**
+ * [deviceSession]: the request ran under the session from /v1/installations/verify, which the
+ * client can renew by proving its key again; an account session is the app's to renew.
+ */
+export function protocolStepFor(error: ApiException, options: { deviceSession: boolean }): ProtocolStep {
+  switch (error.code) {
+    case 'challenge_expired':
+    case 'challenge_used':
+    case 'integrity_challenge_expired':
+    case 'integrity_challenge_replay':
+      return ProtocolStep.askAgain;
+    case 'expired_token':
+      return options.deviceSession ? ProtocolStep.proveAgain : ProtocolStep.stop;
+    case 'installation_not_found':
+      return ProtocolStep.registerAgain;
+  }
+  return protocolWait(error) === null ? ProtocolStep.stop : ProtocolStep.waitThenRetry;
+}
+
+/** How long a 429 asks the client to wait, in milliseconds, when that is short enough to wait. */
+export function protocolWait(error: ApiException): number | null {
+  const seconds = error.details?.['retry_after_seconds'];
+  if (
+    error.statusCode !== 429 ||
+    typeof seconds !== 'number' ||
+    !Number.isFinite(seconds) ||
+    seconds < 0 ||
+    seconds > protocolMaxWaitSeconds
+  ) {
+    return null;
+  }
+  return Math.round(seconds * 1000);
+}

package/src/reinstallHint.ts

@@ -0,0 +1,69 @@
+/**
+ * The reinstall hint: a SHA-256 of the platform's per-app device identifier, which the backend
+ * keys before storing. Client input, never proof.
+ */
+
+import { sha256Hex } from './util/bytes';
+import { currentPlatform, installationKeyModule } from './util/native';
+
+export class ReinstallHint {
+  readonly kind: string;
+  readonly value: string;
+
+  constructor(value: { kind: string; value: string }) {
+    this.kind = value.kind;
+    this.value = value.value;
+  }
+
+  toJSON(): Record<string, unknown> {
+    return { kind: this.kind, value: this.value };
+  }
+}
+
+export class ReinstallHintReader {
+  private readonly platform: () => string;
+  private readonly identifier: () => Promise<string>;
+
+  /** [platform] and [identifier] replace the phone's in tests. */
+  constructor(options: { platform?: () => string; identifier?: () => Promise<string> } = {}) {
+    this.platform = options.platform ?? currentPlatform;
+    this.identifier =
+      options.identifier ??
+      (async () => {
+        const native = installationKeyModule();
+        return native === null ? '' : await native.reinstallHintIdentifier();
+      });
+  }
+
+  async read(): Promise<ReinstallHint | null> {
+    // The phone's per-app identifier: ANDROID_ID, or the identifier for vendor on iOS.
+    let kind: string;
+    let platform: string;
+    try {
+      platform = this.platform();
+    } catch {
+      return null;
+    }
+    switch (platform) {
+      case 'android':
+        kind = 'android_id';
+        break;
+      case 'ios':
+        kind = 'idfv';
+        break;
+      default:
+        return null;
+    }
+    try {
+      const value = ((await this.identifier()) ?? '').trim().toLowerCase();
+      if (value.length === 0) {
+        return null;
+      }
+      const digest = sha256Hex(`device-recognition-hint-v1|${kind}|${value}`);
+      return new ReinstallHint({ kind: `${kind}_sha256`, value: digest });
+    } catch {
+      // A missing hint must never stop cryptographic installation identity.
+    }
+    return null;
+  }
+}