@necessarysdk/react-native 0.0.0-stage → 0.1.5

package/lib/protocol.d.ts

@@ -0,0 +1,24 @@
+/** 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 declare 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 declare 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 declare function protocolStepFor(error: ApiException, options: {
+    deviceSession: boolean;
+}): ProtocolStep;
+/** How long a 429 asks the client to wait, in milliseconds, when that is short enough to wait. */
+export declare function protocolWait(error: ApiException): number | null;

package/lib/protocol.js

@@ -0,0 +1,50 @@
+"use strict";
+/** What the client does about the protocol errors of the public guide's section 4. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.protocolMaxWaitSeconds = exports.ProtocolStep = void 0;
+exports.protocolStepFor = protocolStepFor;
+exports.protocolWait = protocolWait;
+/**
+ * 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.
+ */
+var ProtocolStep;
+(function (ProtocolStep) {
+    ProtocolStep["askAgain"] = "askAgain";
+    ProtocolStep["proveAgain"] = "proveAgain";
+    ProtocolStep["registerAgain"] = "registerAgain";
+    ProtocolStep["waitThenRetry"] = "waitThenRetry";
+    ProtocolStep["stop"] = "stop";
+})(ProtocolStep || (exports.ProtocolStep = ProtocolStep = {}));
+/** The longest wait the client sits through before it retries a 429 itself; a longer one goes to the app. */
+exports.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.
+ */
+function protocolStepFor(error, options) {
+    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. */
+function protocolWait(error) {
+    const seconds = error.details?.['retry_after_seconds'];
+    if (error.statusCode !== 429 ||
+        typeof seconds !== 'number' ||
+        !Number.isFinite(seconds) ||
+        seconds < 0 ||
+        seconds > exports.protocolMaxWaitSeconds) {
+        return null;
+    }
+    return Math.round(seconds * 1000);
+}

package/lib/reinstallHint.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The reinstall hint: a SHA-256 of the platform's per-app device identifier, which the backend
+ * keys before storing. Client input, never proof.
+ */
+export declare class ReinstallHint {
+    readonly kind: string;
+    readonly value: string;
+    constructor(value: {
+        kind: string;
+        value: string;
+    });
+    toJSON(): Record<string, unknown>;
+}
+export declare class ReinstallHintReader {
+    private readonly platform;
+    private readonly identifier;
+    /** [platform] and [identifier] replace the phone's in tests. */
+    constructor(options?: {
+        platform?: () => string;
+        identifier?: () => Promise<string>;
+    });
+    read(): Promise<ReinstallHint | null>;
+}

package/lib/reinstallHint.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * The reinstall hint: a SHA-256 of the platform's per-app device identifier, which the backend
+ * keys before storing. Client input, never proof.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReinstallHintReader = exports.ReinstallHint = void 0;
+const bytes_1 = require("./util/bytes");
+const native_1 = require("./util/native");
+class ReinstallHint {
+    constructor(value) {
+        this.kind = value.kind;
+        this.value = value.value;
+    }
+    toJSON() {
+        return { kind: this.kind, value: this.value };
+    }
+}
+exports.ReinstallHint = ReinstallHint;
+class ReinstallHintReader {
+    /** [platform] and [identifier] replace the phone's in tests. */
+    constructor(options = {}) {
+        this.platform = options.platform ?? native_1.currentPlatform;
+        this.identifier =
+            options.identifier ??
+                (async () => {
+                    const native = (0, native_1.installationKeyModule)();
+                    return native === null ? '' : await native.reinstallHintIdentifier();
+                });
+    }
+    async read() {
+        // The phone's per-app identifier: ANDROID_ID, or the identifier for vendor on iOS.
+        let kind;
+        let platform;
+        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 = (0, bytes_1.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;
+    }
+}
+exports.ReinstallHintReader = ReinstallHintReader;

package/lib/report.d.ts

@@ -0,0 +1,62 @@
+/** The scan (the public guide, section 2): your backend's challenge, the measurements it asks for, and the report the installation key signs. */
+import type { NativeIntegrityCollector } from './collector';
+import type { InstallationIdentity } from './installationKey';
+/** The most a backend takes: a report of 65,536 bytes of JSON (the measurement contract, section 1). */
+export declare const reportByteLimit = 65536;
+/**
+ * The lists a report may shorten, by measurement -- each beside the `truncated` flag that says the
+ * phone had more (the measurement contract, section 6).
+ */
+export declare const shortenableLists: Readonly<Record<string, readonly string[]>>;
+/**
+ * [report] made to fit [reportByteLimit]: the longest list it may shorten is halved, and marked
+ * `truncated`, until it fits. A report that cannot fit is never cut anywhere else: the answer is an
+ * error naming the limit.
+ */
+export declare function fitReport(report: Record<string, unknown>): Record<string, unknown>;
+/** A challenge for a scan, as your backend sent it. */
+export declare class ScanChallenge {
+    readonly challengeId: string;
+    readonly nonce: string;
+    readonly platform: string;
+    /** The measurements the report must answer. */
+    readonly requiredProbes: string[];
+    /** The personal measurements asked for, answered only where the app enabled them; none from a backend that names none. */
+    readonly optionalProbes: string[];
+    /** The challenge whole. */
+    readonly answer: Record<string, unknown>;
+    constructor(value: {
+        challengeId: string;
+        nonce: string;
+        platform: string;
+        requiredProbes: string[];
+        optionalProbes: string[];
+        answer: Record<string, unknown>;
+    });
+    static fromJson(value: Record<string, unknown>): ScanChallenge;
+}
+/** A report as the installation key signed it. */
+export declare class SignedReport {
+    /** The report, as signed. */
+    readonly report: Record<string, unknown>;
+    /** `report_payload`: the base64url of the report's JSON bytes. */
+    readonly payload: string;
+    /** `report_signature`. */
+    readonly signature: string;
+    constructor(value: {
+        report: Record<string, unknown>;
+        payload: string;
+        signature: string;
+    });
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Measures what [challenge] asks for -- and, of the personal measurements it asks for, those in
+ * [enabledMeasurements] -- and signs the report with [identity]'s key.
+ */
+export declare function collectReport(args: {
+    challenge: ScanChallenge;
+    identity: InstallationIdentity;
+    collector: NativeIntegrityCollector;
+    enabledMeasurements: string[];
+}): Promise<SignedReport>;

package/lib/report.js

@@ -0,0 +1,140 @@
+"use strict";
+/** The scan (the public guide, section 2): your backend's challenge, the measurements it asks for, and the report the installation key signs. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SignedReport = exports.ScanChallenge = exports.shortenableLists = exports.reportByteLimit = void 0;
+exports.fitReport = fitReport;
+exports.collectReport = collectReport;
+const errors_1 = require("./errors");
+const bytes_1 = require("./util/bytes");
+const native_1 = require("./util/native");
+/** The most a backend takes: a report of 65,536 bytes of JSON (the measurement contract, section 1). */
+exports.reportByteLimit = 65536;
+/**
+ * The lists a report may shorten, by measurement -- each beside the `truncated` flag that says the
+ * phone had more (the measurement contract, section 6).
+ */
+exports.shortenableLists = {
+    accessibility: ['services', 'settings_only'],
+    notification_access: ['listeners'],
+    other_access: ['device_admins', 'remote_access_apps'],
+};
+/**
+ * [report] made to fit [reportByteLimit]: the longest list it may shorten is halved, and marked
+ * `truncated`, until it fits. A report that cannot fit is never cut anywhere else: the answer is an
+ * error naming the limit.
+ */
+function fitReport(report) {
+    const probes = { ...report['probe_results'] };
+    const fitted = { ...report, probe_results: probes };
+    const size = () => (0, bytes_1.utf8Encode)(JSON.stringify(fitted)).length;
+    for (let bytes = size(); bytes > exports.reportByteLimit; bytes = size()) {
+        let probe = null;
+        let field = null;
+        let longest = 0;
+        for (const [name, fields] of Object.entries(exports.shortenableLists)) {
+            const result = probes[name];
+            for (const list of fields) {
+                const items = (0, native_1.isObject)(result) ? result[list] : undefined;
+                if (Array.isArray(items) && items.length > longest) {
+                    probe = name;
+                    field = list;
+                    longest = items.length;
+                }
+            }
+        }
+        if (probe === null || field === null) {
+            throw new errors_1.ApiException(`The report would be ${bytes} bytes; a backend takes at most ${exports.reportByteLimit}.`, {
+                code: 'report_too_large',
+                details: { bytes, limit: exports.reportByteLimit },
+            });
+        }
+        const shortened = { ...probes[probe] };
+        shortened[field] = shortened[field].slice(0, Math.floor(longest / 2));
+        shortened['truncated'] = true;
+        probes[probe] = shortened;
+    }
+    return fitted;
+}
+/** A challenge for a scan, as your backend sent it. */
+class ScanChallenge {
+    constructor(value) {
+        this.challengeId = value.challengeId;
+        this.nonce = value.nonce;
+        this.platform = value.platform;
+        this.requiredProbes = value.requiredProbes;
+        this.optionalProbes = value.optionalProbes;
+        this.answer = value.answer;
+    }
+    static fromJson(value) {
+        const names = (list) => (Array.isArray(list) ? list.map((item) => String(item)) : []);
+        const text = (field) => {
+            const item = value[field];
+            if (typeof item !== 'string') {
+                throw new TypeError(`The scan challenge has no ${field}.`);
+            }
+            return item;
+        };
+        return new ScanChallenge({
+            challengeId: text('challenge_id'),
+            nonce: text('nonce'),
+            platform: text('platform'),
+            requiredProbes: names(value['required_probes']),
+            optionalProbes: names(value['optional_probes']),
+            answer: value,
+        });
+    }
+}
+exports.ScanChallenge = ScanChallenge;
+/** A report as the installation key signed it. */
+class SignedReport {
+    constructor(value) {
+        this.report = value.report;
+        this.payload = value.payload;
+        this.signature = value.signature;
+    }
+    toJSON() {
+        return { report_payload: this.payload, report_signature: this.signature };
+    }
+}
+exports.SignedReport = SignedReport;
+/**
+ * Measures what [challenge] asks for -- and, of the personal measurements it asks for, those in
+ * [enabledMeasurements] -- and signs the report with [identity]'s key.
+ */
+async function collectReport(args) {
+    const { challenge, identity, collector, enabledMeasurements } = args;
+    const native = await collector.collect({
+        requiredProbes: challenge.requiredProbes,
+        challengeNonce: challenge.nonce,
+        enabledMeasurements,
+        optionalProbes: challenge.optionalProbes,
+    });
+    if (!(0, native_1.isObject)(native['probes'])) {
+        throw new errors_1.ApiException('The native collector returned no probe map.', {
+            code: 'invalid_native_integrity_result',
+        });
+    }
+    if (native['platform'] !== challenge.platform || native['challenge_nonce_echo'] !== challenge.nonce) {
+        throw new errors_1.ApiException('The native integrity response did not match the server challenge.', {
+            code: 'integrity_challenge_binding_failed',
+        });
+    }
+    const version = native['collector_version'];
+    if (version != null && typeof version !== 'number') {
+        throw new TypeError('The native collector returned an invalid collector_version.');
+    }
+    const report = fitReport({
+        challenge_id: challenge.challengeId,
+        challenge_nonce: challenge.nonce,
+        installation_id: identity.installationId,
+        platform: challenge.platform,
+        collector_version: typeof version === 'number' ? Math.trunc(version) : 1,
+        collected_at: Math.floor(Date.now() / 1000),
+        probe_results: { ...native['probes'] },
+        // The personal measurements this app enabled, whether or not this scan asked for them.
+        enabled_measurements: enabledMeasurements,
+        version: 1,
+    });
+    const payload = (0, bytes_1.base64UrlNoPadding)((0, bytes_1.utf8Encode)(JSON.stringify(report)));
+    return new SignedReport({ report, payload, signature: await identity.signPayload(payload) });
+}

package/lib/requestProof.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Request proofs (the public guide, section 3): the installation key signs each request, so a
+ * copied session token is useless without the key; with step-up on the person approves one
+ * request with the step-up key, and with the app PIN on a request carries the backend's proof of
+ * the PIN. Also the description of the one request a scan is to approve (section 2).
+ */
+import type { InstallationIdentity } from './installationKey';
+export { base64UrlNoPadding } from './util/bytes';
+/** Where [freshNonce] takes its bytes: the platform's secure random source, replaced in tests. */
+export declare let secureRandomBytes: (count: number) => Promise<Uint8Array>;
+/** Replaces the secure random source -- for tests, which run where no phone is. */
+export declare function setSecureRandomSource(source: (count: number) => Promise<Uint8Array>): void;
+/** 32 random bytes from the platform's secure source. */
+export declare function freshNonce(): Promise<Uint8Array>;
+/**
+ * The person's approval of one request: the step-up key's [factor], and [sign], which has the
+ * step-up key sign a payload -- the phone asks the person (NativeStepUpKey.sign).
+ */
+export interface StepUpApproval {
+    factor: string;
+    sign: (payload: string) => Promise<string>;
+}
+export interface RequestProofFields {
+    bearerToken: string;
+    method: string;
+    path: string;
+    encodedBody: string;
+    payload: string;
+    signature: string;
+    timestamp: number;
+    nonce: string;
+    stepUpPayload?: string | null;
+    stepUpSignature?: string | null;
+    appPinProof?: string | null;
+    integrityReport?: string | null;
+}
+/**
+ * What the installation key signed for one request -- with step-up, what the step-up key signed;
+ * with the app PIN, the backend's proof of it; for a request a scan approves, that scan's report --
+ * and the headers that carry them beside `Authorization: Bearer`.
+ */
+export declare class RequestProof {
+    readonly bearerToken: string;
+    /** The request the proof was signed for: its method, its path with the query, and the exact body. */
+    readonly method: string;
+    readonly path: string;
+    readonly encodedBody: string;
+    /** `X-Access-Proof`: the base64url of the proof's JSON bytes. */
+    readonly payload: string;
+    /** `X-Access-Signature`. */
+    readonly signature: string;
+    readonly timestamp: number;
+    readonly nonce: string;
+    /** `X-Step-Up-Proof` and `X-Step-Up-Signature`, for a request the person approved. */
+    readonly stepUpPayload: string | null;
+    readonly stepUpSignature: string | null;
+    /** `X-App-PIN-Proof`: the backend's proof that the person entered the app PIN for this request. */
+    readonly appPinProof: string | null;
+    /** `X-Integrity-Report`: the report of the scan made for this request alone (the public guide, section 2). */
+    readonly integrityReport: string | null;
+    constructor(fields: RequestProofFields);
+    get headers(): Record<string, string>;
+    /** This request, unlocked by the backend's [proof] of the app PIN. */
+    withAppPinProof(proof: string): RequestProof;
+    /** This request, naming [reportId], the scan made for it alone. */
+    withIntegrityReport(reportId: string): RequestProof;
+    private with;
+}
+/**
+ * What the app sends to have its backend check the app PIN for one request: the PIN, and that
+ * request as its request proof signs it -- method, path, query, the hash of the body sent and the
+ * request proof's nonce.
+ */
+export declare function appPinProofRequest(args: {
+    pin: string;
+    method: string;
+    path: string;
+    encodedBody: string;
+    nonce: string;
+}): Record<string, unknown>;
+/**
+ * The step-up proof, version 2, that the step-up key signs for one request: the base64url of its
+ * JSON, the members in this order. [nonce] is the request proof's nonce for the same request, so
+ * the approval is used up with it.
+ */
+export declare function stepUpProof(args: {
+    installationId: string;
+    accessToken: string;
+    method: string;
+    path: string;
+    encodedBody: string;
+    factor: string;
+    nonce: string;
+    timestamp: number;
+}): string;
+/**
+ * Signs [method] [path] with [encodedBody] under [bearerToken]: proof version 2, which signs the
+ * query string too, exactly as sent. A GET signs an empty body. With [stepUp], the step-up key signs
+ * first -- the phone asks the person -- and the request proof after, with the same nonce, so the
+ * time the person takes does not count against the request proof's clock window.
+ * [installationId], [timestamp] and [nonce] replace what the request proof would otherwise carry,
+ * for the shared test vectors and for testing a backend's refusals.
+ */
+export declare function signRequest(args: {
+    identity: InstallationIdentity;
+    method: string;
+    path: string;
+    bearerToken: string;
+    encodedBody?: string;
+    stepUp?: StepUpApproval | null;
+    installationId?: string | null;
+    timestamp?: number | null;
+    nonce?: Uint8Array | readonly number[] | null;
+}): Promise<RequestProof>;
+/** The one request a scan is to approve, described exactly as it will be sent: what the challenge names as its `operation`. */
+export declare function describeOperation(method: string, path: string, encodedBody: string): Record<string, unknown>;