@necessarysdk/react-native 0.0.0-stage → 0.1.5

package/lib/collector.js

@@ -0,0 +1,49 @@
+"use strict";
+/** The native integrity collector: measures what a challenge asks for and the app enabled, and nothing else. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NativeIntegrityCollector = void 0;
+const errors_1 = require("./errors");
+const native_1 = require("./util/native");
+const INTEGRITY_MODULE_MISSING = () => new errors_1.NativeKeyException('NATIVE_INTEGRITY_PLUGIN_MISSING', "The SDK's integrity module is not linked into this app: rebuild the app.");
+class NativeIntegrityCollector {
+    /**
+     * [enabledMeasurements]: the personal measurements this app's developers allow; with
+     * [optionalProbes], what the backend asks for, the collector measures only what is in both.
+     */
+    async collect(args) {
+        const native = (0, native_1.integrityModule)();
+        if (native === null) {
+            throw INTEGRITY_MODULE_MISSING();
+        }
+        let value;
+        try {
+            // What the server asks for and what this app allows; the native collector measures only what
+            // is in both.
+            value = await native.collect(args.requiredProbes, args.challengeNonce, args.optionalProbes ?? [], args.enabledMeasurements);
+        }
+        catch (error) {
+            throw (0, native_1.nativeFailure)(error, 'The native integrity collector failed.');
+        }
+        if (!(0, native_1.isObject)(value)) {
+            throw new errors_1.NativeKeyException('EMPTY_INTEGRITY_RESPONSE', 'The native integrity collector returned no measurements.');
+        }
+        return value;
+    }
+    /**
+     * Asks the person for the OS location permission and returns what the app now holds: precise,
+     * approximate or none. Only the app asks, from its own screen; a scan never prompts.
+     */
+    async requestLocationPermission() {
+        const native = (0, native_1.integrityModule)();
+        if (native === null) {
+            throw INTEGRITY_MODULE_MISSING();
+        }
+        try {
+            return (await native.requestLocationPermission()) ?? 'none';
+        }
+        catch (error) {
+            throw (0, native_1.nativeFailure)(error, 'The location permission request failed.');
+        }
+    }
+}
+exports.NativeIntegrityCollector = NativeIntegrityCollector;

package/lib/deviceTrust.d.ts

@@ -0,0 +1,253 @@
+/**
+ * DeviceTrust: the one object an app configures -- its backend, the personal measurements it
+ * enables, step-up and the app PIN -- and what it asks of it: start, scan, and sign a request (the
+ * public guide).
+ */
+import { DeviceTrustClient } from './client';
+import { NativeIntegrityCollector } from './collector';
+import { NativeKeyException } from './errors';
+import type { InstallationIdentity } from './installationKey';
+import { InstallationStore } from './installationStore';
+import { ReinstallHintReader } from './reinstallHint';
+import { type ScanChallenge, type SignedReport } from './report';
+import { RequestProof } from './requestProof';
+import { NativeStepUpKey, StepUpKeyMetadata, StepUpOptions } from './stepUpKey';
+import { type DeviceTrustTransport, type JsonObject } from './transport';
+/**
+ * The personal measurements an app may enable (the public guide, section 8). Each is collected
+ * only when the backend asks for it as well -- the location only with the person's permission too.
+ */
+export declare const PersonalMeasurement: {
+    readonly localAddresses: "local_addresses";
+    readonly accessibility: "accessibility";
+    readonly notificationAccess: "notification_access";
+    readonly otherAccess: "other_access";
+    readonly screenCapture: "screen_capture";
+    readonly location: "location";
+    readonly mockLocation: "mock_location";
+};
+/** The name the report and the backend use for one personal measurement. */
+export type PersonalMeasurement = (typeof PersonalMeasurement)[keyof typeof PersonalMeasurement];
+/** Every personal measurement, in the guide's order. */
+export declare const personalMeasurements: readonly PersonalMeasurement[];
+/** Where the backend takes the app PIN's two calls (the public guide, section 4). */
+export declare class AppPinOptions {
+    readonly path: string;
+    readonly proofPath: string;
+    constructor(options?: {
+        path?: string;
+        proofPath?: string;
+    });
+}
+/** One scan: the challenge it answered, the report as signed, and the backend's answer, whole. */
+export declare class ScanResult {
+    readonly challenge: ScanChallenge;
+    readonly report: SignedReport;
+    readonly answer: JsonObject;
+    constructor(value: {
+        challenge: ScanChallenge;
+        report: SignedReport;
+        answer: JsonObject;
+    });
+    /** The stored report (`integrity.report_id`), which a scan made for one request sends back with that request. */
+    get reportId(): string | null;
+}
+export interface DeviceTrustOptions {
+    /** What this app enables; the backend asks for what it needs of them. */
+    personalMeasurements?: Iterable<PersonalMeasurement>;
+    /** How the step-up key is made, or null for no step-up. */
+    stepUp?: StepUpOptions | null;
+    /** The app PIN's calls, or null for no app PIN. */
+    appPin?: AppPinOptions | null;
+    /** Every registration's answer, whole, awaited before the installation goes on. */
+    onRegistered?: ((answer: JsonObject) => void | Promise<void>) | null;
+}
+/** The same, with the parts tests replace. */
+export interface DeviceTrustParts extends DeviceTrustOptions {
+    store?: InstallationStore;
+    collector?: NativeIntegrityCollector;
+    hintReader?: ReinstallHintReader;
+    stepUpKey?: NativeStepUpKey;
+    /** The phone's platform, `android` or `ios`, for the registration. */
+    platform?: () => string;
+}
+export declare class DeviceTrust {
+    /** The guide's calls, for an app that makes them itself. */
+    readonly client: DeviceTrustClient;
+    /**
+     * What this app enables; the backend asks for what it needs of them. The app may change it
+     * whenever the person does -- in a privacy setting, say: the next scan measures what it holds
+     * then, and the installation, its session and its step-up key stay as they are.
+     */
+    personalMeasurements: Set<PersonalMeasurement>;
+    /** How the step-up key is made, or null for no step-up. An app that takes these from its backend sets them before [start]. */
+    stepUp: StepUpOptions | null;
+    /** The app PIN's calls, or null for no app PIN. */
+    readonly appPin: AppPinOptions | null;
+    /**
+     * Every registration's answer, whole -- also those made again inside a scan, when the backend had
+     * lost the installation -- awaited before the installation goes on.
+     */
+    readonly onRegistered: ((answer: JsonObject) => void | Promise<void>) | null;
+    private readonly store;
+    private readonly collector;
+    private readonly hintReader;
+    private readonly stepUpKeyNative;
+    private identityValue;
+    private session;
+    private loading;
+    private starting;
+    private proving;
+    private readonly scanning;
+    private generation;
+    private resetting;
+    private saving;
+    private reenrolling;
+    private readonly mutations;
+    private offeredStepUpKey;
+    private hint;
+    private hintRead;
+    /** Why step-up is off on this phone although the app turned it on -- no screen lock, say -- or null. */
+    stepUpUnavailable: NativeKeyException | null;
+    /** Talks to your backend over JSON and HTTPS under [baseUrl], the SDK's default API (the public guide, section 4). */
+    constructor(options: DeviceTrustOptions & {
+        baseUrl: string;
+    });
+    /** The same over the app's own [transport]. */
+    constructor(options: DeviceTrustParts & {
+        transport: DeviceTrustTransport;
+    });
+    /** The same over the app's own [transport]; [parts] replace the native ones in tests. */
+    static over(transport: DeviceTrustTransport, parts?: DeviceTrustParts): DeviceTrust;
+    get identity(): InstallationIdentity | null;
+    /** The installation session from proving the key, or null before [start]. */
+    get installationSession(): string | null;
+    /** The step-up key offered at the last registration. */
+    get stepUpKey(): StepUpKeyMetadata | null;
+    /** The wire names of [personalMeasurements], in the guide's order. */
+    get enabledMeasurements(): string[];
+    /**
+     * The installation: its key, made on first use, and its ID. A key made now is a new installation
+     * ([InstallationIdentity.createdThisLaunch]): whatever the app kept for the one before belongs to
+     * that one. Calls at once share one load, so one key gets one ID.
+     */
+    loadIdentity(): Promise<InstallationIdentity>;
+    private load;
+    /**
+     * A persistent write or a key change for the installation [generation]: refused before it starts
+     * when reset() or close() has ended that installation, and waited for by a reset that began while
+     * it ran. The order is the whole guarantee: endCalls() moves the generation on at once, in the
+     * same turn as reset() is called, so a write asked for after that throws here without writing;
+     * one asked for before is in [mutations], which the reset waits for before it deletes anything.
+     */
+    private mutate;
+    /** Throws when reset() or close() ended the installation [generation] belongs to: a call keeps nothing of one that is gone. */
+    private current;
+    /**
+     * Loads or makes the key, registers it -- with the step-up key, when step-up is on -- and proves
+     * the installation holds it: the installation session. A refusal outside the guide's protocol
+     * errors goes to the app as it came. A second call while one runs gets its result.
+     */
+    start(): Promise<InstallationIdentity>;
+    private startOnce;
+    /** A new installation session: the key's challenge, answered. A second call while one runs gets its result. */
+    prove(): Promise<string>;
+    /**
+     * Deletes the key, the installation ID (InstallationStore.clear) and the step-up key, and forgets
+     * the session: the next start is a new installation, linked to this one by nothing it holds.
+     * Calls still running end with InterruptedCallException and keep nothing; calls made from now on
+     * wait for the deletion, and never join one made before.
+     */
+    reset(): Promise<void>;
+    /** Moves on to the next installation: the calls running now keep nothing, and the next ones start afresh. */
+    private endCalls;
+    private proveOnce;
+    private register;
+    /**
+     * Whether the backend holds the step-up key offered: it takes one only when it first registers an
+     * installation, so a key made later -- after the screen lock was removed and set again, say -- it
+     * takes by re-enrolment alone. Its answer says so (`stepup_key_matches`, or for an installation
+     * new to it `stepup_key_registered`); until it holds this key, approvals wait for reenrolStepUp,
+     * across restarts too. A registration without a key, the phone unable to make one, leaves any key
+     * made later waiting the same way. A backend whose answer says nothing is taken at its word unless
+     * a re-enrolment is pending.
+     */
+    private settleStepUpKey;
+    /**
+     * The step-up key as [stepUp] asks: an existing key is kept as it is. Step-up is optional, so a
+     * key the phone cannot make leaves it off. Its use waits for the backend's answer
+     * (settleStepUpKey).
+     */
+    private prepareStepUpKey;
+    /** A step-up key a re-enrolment replaces: one that can never sign again, or one the keystore cannot vouch for. */
+    private static replaceableKey;
+    /** What approvals answer while the backend does not hold the step-up key. */
+    private static reenrolPending;
+    /**
+     * A scan: under the installation session -- or, for a scan that approves one [operation]
+     * ([describeOperation]), under the app's account [session] for this installation, the one that
+     * will send that request. The guide's protocol errors are acted on once; an account session is
+     * the app's to renew. A second call for the same scan while one runs gets its result; a scan
+     * whose answer was lost is simply asked for again.
+     */
+    scan(options?: {
+        session?: string | null;
+        operation?: Record<string, unknown> | null;
+    }): Promise<ScanResult>;
+    private scanWithProtocol;
+    private scanOnce;
+    /**
+     * Signs one request to your backend under [bearer], your account session: [body] is sent exactly
+     * as given. With [stepUp] the person approves it with the step-up key -- the phone asks, saying
+     * [reason]; with [appPin] the backend checks the PIN for it first; [reportId] names the scan made
+     * for it alone. Send it with RequestProof.headers beside `Authorization: Bearer`, or with [send];
+     * each proof serves this request once.
+     */
+    signRequest(args: {
+        method: string;
+        path: string;
+        bearer: string;
+        body?: string;
+        stepUp?: boolean;
+        reason?: string;
+        appPin?: string | null;
+        reportId?: string | null;
+    }): Promise<RequestProof>;
+    /**
+     * Re-enrols the step-up key under the account [session], with the person's own
+     * [reauthentication] -- the account's password, say: `{password: ...}`. For a key the phone has
+     * lost or can no longer use -- the screen lock removed (`STEPUP_KEY_INVALIDATED`) -- or one made
+     * for other options: the person unlocks the new key to sign its proof, the phone showing
+     * [reason], and the backend takes it for that account alone (the public guide, section 3).
+     * Approvals use it from then on. A key replaced before the backend took the new one -- the person
+     * cancelled, the password was wrong, the answer was lost -- leaves step-up waiting: approvals
+     * answer `STEPUP_REENROL_PENDING`, across restarts too, until a call of this succeeds.
+     */
+    reenrolStepUp(args: {
+        session: string;
+        reauthentication?: Record<string, unknown>;
+        reason?: string;
+    }): Promise<JsonObject>;
+    private reenrolStepUpOnce;
+    /** Sends [proof]'s request through the SDK's transport. */
+    send(proof: RequestProof): Promise<JsonObject>;
+    /**
+     * Sets the account's app PIN under the account [session], with the person's own
+     * [reauthentication] -- the account's password, say: `{password: ...}`.
+     */
+    setAppPin(args: {
+        session: string;
+        pin: string;
+        reauthentication?: Record<string, unknown>;
+    }): Promise<JsonObject>;
+    /**
+     * Asks the person for the location permission, for the location measurements: from a button on
+     * the app's own screen, since a scan never asks. Answers `precise`, `approximate` or `none`.
+     */
+    requestLocationPermission(): Promise<string>;
+    /**
+     * Closes the transport. Calls still running end with InterruptedCallException, or with the
+     * transport's own failure, and keep nothing; the key and the installation stay as they are.
+     */
+    close(): void;
+}