@nacre.work/api 0.17.5 → 0.19.0

package/dist/second-factor.d.ts

@@ -0,0 +1,202 @@
+import type { Pool } from 'pg';
+export interface EnrolledFactor {
+    readonly id: string;
+    readonly kind: FactorKind;
+    readonly label: string;
+    readonly createdAt: Date;
+    readonly lastUsedAt: Date | null;
+}
+export interface BegunEnrolment {
+    readonly id: string;
+    /** Shown once, so a person can type it into an app that will not scan. */
+    readonly secret: string;
+    readonly otpauthUrl: string;
+}
+export type FactorKind = 'totp' | 'webauthn';
+/**
+ * Where a WebAuthn ceremony happens, and it needs no new configuration.
+ *
+ * The relying party id is `NACRE_CANONICAL_URL`'s hostname and the origin list
+ * is that URL's origin plus whatever `NACRE_API_ALLOWED_ORIGINS` already
+ * admits — the console is served from the API's own origin unless a deployment
+ * has said otherwise, and if it has said otherwise it has said so there. A
+ * `NACRE_WEBAUTHN_*` variable would be a second answer to a question the
+ * deployment has already answered twice.
+ */
+export interface RelyingParty {
+    /** A registrable domain: `nacre.example.com`, never a URL and never a port. */
+    readonly id: string;
+    /** What the authenticator shows. */
+    readonly name: string;
+    /** Compared for equality. A suffix match would admit `evil-nacre.work`. */
+    readonly origins: readonly string[];
+}
+export interface WebAuthnRegistrationOptions {
+    readonly challenge: string;
+    readonly rp: {
+        readonly id: string;
+        readonly name: string;
+    };
+    readonly user: {
+        readonly id: string;
+        readonly name: string;
+        readonly displayName: string;
+    };
+    readonly algorithms: readonly number[];
+    readonly excludeCredentials: readonly string[];
+    readonly timeoutMs: number;
+}
+export interface WebAuthnAssertionOptions {
+    readonly challenge: string;
+    readonly rpId: string;
+    readonly allowCredentials: readonly string[];
+    readonly timeoutMs: number;
+}
+export interface SecondFactorDeps {
+    readonly pool: Pool;
+    /**
+     * The sealing key, or `undefined` where the deployment configured none.
+     *
+     * **TOTP needs it and WebAuthn does not.** A TOTP secret is shared, so it has
+     * to be kept and therefore sealed; a WebAuthn credential leaves a public key
+     * here and nothing else, so there is nothing a dump could hand over. That is
+     * why `available` became per kind rather than staying one boolean: an
+     * installation with no key can still offer the *stronger* of the two, and
+     * refusing it because the weaker one has no key would be an accident of how
+     * this class was first written.
+     */
+    readonly key: Buffer | undefined;
+    /** What an authenticator shows above the account. */
+    readonly issuer: string;
+    readonly relyingParty: RelyingParty;
+    readonly role?: string;
+    readonly now?: () => Date;
+}
+export declare class SecondFactors {
+    private readonly deps;
+    constructor(deps: SecondFactorDeps);
+    /**
+     * Whether this installation can hold a second factor at all.
+     *
+     * True where *either* kind is offered, which since WebAuthn is every
+     * installation: it needs no sealing key, only the canonical URL every
+     * deployment already sets.
+     */
+    get available(): boolean;
+    /** The kinds this installation offers, so a screen can draw what works. */
+    get kinds(): readonly FactorKind[];
+    private get scope();
+    private get clock();
+    /**
+     * Does this person have to produce one?
+     *
+     * Only confirmed factors count. A secret generated and never proved is a
+     * secret that did not reach an authenticator, and treating it as live is how
+     * somebody locks themselves out at the moment they turn 2FA on.
+     */
+    required(orgId: string, userId: string): Promise<boolean>;
+    list(orgId: string, userId: string): Promise<readonly EnrolledFactor[]>;
+    /**
+     * Start enrolling one. The secret is stored sealed and unconfirmed.
+     *
+     * A second call with the same label replaces the unconfirmed row rather than
+     * refusing: somebody who closed the page before scanning has no way to name
+     * what they abandoned, and the alternative is a label nobody can reuse.
+     */
+    begin(orgId: string, userId: string, label: string): Promise<BegunEnrolment | undefined>;
+    /**
+     * Prove the secret arrived, and hand back the way in without it.
+     *
+     * The recovery codes are minted here rather than on demand for two reasons:
+     * a person who has lost their phone cannot ask for them, and this is the one
+     * moment the product has their attention about it.
+     *
+     * Replacing any codes that already exist — enrolling a second factor is not
+     * a reason to invalidate them, so this only runs when there was none.
+     */
+    confirm(orgId: string, userId: string, id: string, code: string): Promise<readonly string[] | undefined>;
+    /**
+     * A code at sign-in: a six-digit one from an authenticator, or a recovery code.
+     *
+     * Both are accepted here rather than on two endpoints, because from the
+     * outside they answer the same question and a separate route would tell an
+     * attacker which one a person is using.
+     *
+     * The brute-force bound is in Postgres and not in Redis: the rate limiter
+     * fails **open** by design — it is not an authorization control and a cache
+     * restart must not be an outage — and this one is. Six digits is a million,
+     * and a limiter that forgets is a limiter an attacker waits out.
+     */
+    verify(orgId: string, userId: string, code: string): Promise<boolean>;
+    /**
+     * Remove one. The caller has already proved they are this person and holds a
+     * current code — see the handler; removing a factor is exactly what somebody
+     * with a stolen session would do first.
+     */
+    remove(orgId: string, userId: string, id: string): Promise<boolean>;
+    /**
+     * The address, for a notice about this account's factors.
+     *
+     * Here rather than on a users port because this class already reads that
+     * column for the authenticator label, and a second reader of one column is a
+     * second thing to keep scoped correctly.
+     */
+    emailOf(orgId: string, userId: string): Promise<string | undefined>;
+    /** Mint and store a challenge. Returned base64url, which is what the browser wants. */
+    private issueChallenge;
+    /**
+     * Spend one, and refuse a challenge that is not outstanding for this person
+     * and this ceremony.
+     *
+     * The purpose is in the WHERE clause rather than checked afterwards: a
+     * challenge issued for enrolment must not be spendable on a sign-in, or a
+     * session could mint the input to a ceremony it is not in.
+     */
+    private spendChallenge;
+    /**
+     * Start enrolling an authenticator.
+     *
+     * `excludeCredentials` carries what this person has already registered, so an
+     * authenticator they are holding refuses to make a second credential rather
+     * than quietly making one — which is the difference between "you already have
+     * this key" and two rows nobody can tell apart.
+     */
+    beginWebAuthnRegistration(orgId: string, userId: string): Promise<WebAuthnRegistrationOptions | undefined>;
+    /** Every credential id this person has, for `allowCredentials` and `excludeCredentials`. */
+    private credentialIds;
+    /**
+     * Finish enrolling one, and hand back recovery codes if this is the first
+     * factor of any kind.
+     *
+     * Confirmed in the same statement that inserts it, unlike TOTP: there is no
+     * second step to prove the credential reached anything, because producing the
+     * attestation *is* that proof. A TOTP secret can be generated and never
+     * scanned; a WebAuthn credential cannot be registered without the
+     * authenticator having made it.
+     */
+    finishWebAuthnRegistration(orgId: string, userId: string, label: string, response: {
+        readonly attestationObject: Uint8Array;
+        readonly clientDataJSON: Uint8Array;
+        readonly challenge: string;
+    }): Promise<readonly string[] | undefined>;
+    /** The options a sign-in needs, or nothing where this person has no key enrolled. */
+    beginWebAuthnAssertion(orgId: string, userId: string): Promise<WebAuthnAssertionOptions | undefined>;
+    /**
+     * Verify an assertion at sign-in.
+     *
+     * The counter is written back in the same transaction that spent the
+     * challenge, because a counter that is checked and not stored is a counter
+     * that only ever compares against zero — which is the clone detection not
+     * existing rather than being lenient.
+     */
+    verifyWebAuthnAssertion(orgId: string, userId: string, response: {
+        readonly credentialId: string;
+        readonly authenticatorData: Uint8Array;
+        readonly clientDataJSON: Uint8Array;
+        readonly signature: Uint8Array;
+        readonly challenge: string;
+    }): Promise<boolean>;
+    /** How many unspent recovery codes are left, for the screen that says so. */
+    recoveryCodesLeft(orgId: string, userId: string): Promise<number>;
+}
+//# sourceMappingURL=second-factor.d.ts.map

package/dist/second-factor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"second-factor.d.ts","sourceRoot":"","sources":["../src/second-factor.ts"],"names":[],"mappings":"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"}