@nacre.work/api 0.17.4 → 0.18.0

package/dist/recovery.d.ts

@@ -0,0 +1,91 @@
+import { type Mailer } from '@nacre.work/core';
+import type { Pool } from 'pg';
+/**
+ * Recovering a password, by email, without a `psql` session.
+ *
+ * ## The hole this closes
+ *
+ * `POST /v1/users/{id}/password` is an **administrator** setting somebody
+ * else's. The person who forgot theirs had no route, and on a
+ * single-administrator installation — which the open core mostly is — the
+ * administrator who forgot theirs had no route that did not go through the
+ * database. That is the model-offers-it-and-the-product-gives-no-route shape
+ * this repository keeps closing.
+ *
+ * ## Why the token carries its organization
+ *
+ * `<org_id>.<secret>`. Redemption therefore knows the tenant before it reads
+ * anything, so this table is read through `withOrg` like every other and the
+ * one path a stranger can reach unauthenticated opens no cross-tenant read.
+ *
+ * Migration 0008 says `users` gets no `authenticating` policy "as a decision
+ * rather than an omission"; this keeps that decision rather than arguing with
+ * it. The organization id is not a secret from the person holding the link —
+ * it is in their own `/v1/me` — and the half beside it is.
+ *
+ * ## What a reset does not do
+ *
+ * **It does not touch a second factor.** If it did, an email account would be a
+ * way around one, which is the whole thing a second factor exists to not be.
+ * Somebody who resets a password still produces a code afterwards.
+ *
+ * It *does* end every other session: a reset is what somebody does when they
+ * think their password is known, and leaving the refresh tokens alive would
+ * leave whoever knows it signed in.
+ */
+/** An hour. Long enough to reach an inbox, short enough to be worth stealing. */
+export declare const RESET_TTL_SECONDS = 3600;
+/**
+ * The shortest password this will accept from a person choosing their own.
+ *
+ * Length and nothing else — no composition rule. A rule demanding a digit and a
+ * symbol produces `Password1!` and a person who writes it down; length is the
+ * only requirement that reliably buys entropy. The passwords this product
+ * *generates* are six words and a number, and are longer than this.
+ */
+export declare const MIN_PASSWORD_LENGTH = 12;
+export interface RecoveryDeps {
+    readonly pool: Pool;
+    readonly mailer: Mailer;
+    /** Where the link points. From configuration, never from a request header. */
+    readonly consoleBase: string;
+    readonly role?: string;
+    readonly now?: () => Date;
+}
+export type Redemption = 'reset' | 'refused' | 'too-short';
+export declare class PasswordRecovery {
+    private readonly deps;
+    constructor(deps: RecoveryDeps);
+    private get scope();
+    private get clock();
+    /**
+     * Send a link, or do nothing, and answer the same either way.
+     *
+     * The caller writes one `204` whatever happened here. An address that has an
+     * account and one that does not must be indistinguishable, or this endpoint
+     * becomes the account-enumeration oracle that the sign-in path is careful not
+     * to be — and it is reachable without a credential.
+     *
+     * An address in two organizations is the same silence, for the reason the
+     * login path gives: telling somebody how many tenants an address appears in
+     * is telling them about tenants.
+     */
+    request(email: string): Promise<void>;
+    /**
+     * Spend a link and set the password, or refuse.
+     *
+     * The spend is the UPDATE that finds it, so two requests cannot both succeed
+     * — a read followed by a write is a race with a stolen link on the other side
+     * of it.
+     */
+    redeem(token: string, password: string): Promise<Redemption>;
+    /**
+     * The one user this address names, or nothing.
+     *
+     * The same shape the login path uses, and for the same reasons: two matches
+     * is silence rather than a choice, and the scan stops at two so the cost does
+     * not grow with how many tenants a deployment has.
+     */
+    private findUser;
+}
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4B,KAAK,MAAM,EAAW,MAAM,kBAAkB,CAAA;AACjF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAA;AAIrC,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAC1B;AAED,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAA;AAE1D,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,YAAY;IAE/C,OAAO,KAAK,KAAK,GAEhB;IAED,OAAO,KAAK,KAAK,GAEhB;IAED;;;;;;;;;;;OAWG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkD3C;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuElE;;;;;;OAMG;YACW,QAAQ;CAgCvB"}

package/dist/recovery.js

@@ -0,0 +1,199 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { consoleUrl, hashPassword, withOrg } from '@nacre.work/core';
+/**
+ * Recovering a password, by email, without a `psql` session.
+ *
+ * ## The hole this closes
+ *
+ * `POST /v1/users/{id}/password` is an **administrator** setting somebody
+ * else's. The person who forgot theirs had no route, and on a
+ * single-administrator installation — which the open core mostly is — the
+ * administrator who forgot theirs had no route that did not go through the
+ * database. That is the model-offers-it-and-the-product-gives-no-route shape
+ * this repository keeps closing.
+ *
+ * ## Why the token carries its organization
+ *
+ * `<org_id>.<secret>`. Redemption therefore knows the tenant before it reads
+ * anything, so this table is read through `withOrg` like every other and the
+ * one path a stranger can reach unauthenticated opens no cross-tenant read.
+ *
+ * Migration 0008 says `users` gets no `authenticating` policy "as a decision
+ * rather than an omission"; this keeps that decision rather than arguing with
+ * it. The organization id is not a secret from the person holding the link —
+ * it is in their own `/v1/me` — and the half beside it is.
+ *
+ * ## What a reset does not do
+ *
+ * **It does not touch a second factor.** If it did, an email account would be a
+ * way around one, which is the whole thing a second factor exists to not be.
+ * Somebody who resets a password still produces a code afterwards.
+ *
+ * It *does* end every other session: a reset is what somebody does when they
+ * think their password is known, and leaving the refresh tokens alive would
+ * leave whoever knows it signed in.
+ */
+/** An hour. Long enough to reach an inbox, short enough to be worth stealing. */
+export const RESET_TTL_SECONDS = 3600;
+/**
+ * The shortest password this will accept from a person choosing their own.
+ *
+ * Length and nothing else — no composition rule. A rule demanding a digit and a
+ * symbol produces `Password1!` and a person who writes it down; length is the
+ * only requirement that reliably buys entropy. The passwords this product
+ * *generates* are six words and a number, and are longer than this.
+ */
+export const MIN_PASSWORD_LENGTH = 12;
+const digest = (token) => createHash('sha256').update(token).digest('hex');
+export class PasswordRecovery {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get scope() {
+        return this.deps.role === undefined ? {} : { role: this.deps.role };
+    }
+    get clock() {
+        return this.deps.now?.() ?? new Date();
+    }
+    /**
+     * Send a link, or do nothing, and answer the same either way.
+     *
+     * The caller writes one `204` whatever happened here. An address that has an
+     * account and one that does not must be indistinguishable, or this endpoint
+     * becomes the account-enumeration oracle that the sign-in path is careful not
+     * to be — and it is reachable without a credential.
+     *
+     * An address in two organizations is the same silence, for the reason the
+     * login path gives: telling somebody how many tenants an address appears in
+     * is telling them about tenants.
+     */
+    async request(email) {
+        const address = email.trim().toLowerCase();
+        if (address === '')
+            return;
+        const found = await this.findUser(address);
+        if (found === undefined)
+            return;
+        const secret = randomBytes(32).toString('base64url');
+        const token = `${found.orgId}.${secret}`;
+        const expiresAt = new Date(this.clock.getTime() + RESET_TTL_SECONDS * 1000);
+        await withOrg(this.deps.pool, found.orgId, async (client) => {
+            // Any older link this person holds stops working. Two live links is two
+            // things to steal for one account, and somebody asking again is
+            // somebody who does not have the first.
+            await client.query(`UPDATE password_reset_tokens SET used_at = now()
+            WHERE org_id = $1 AND user_id = $2 AND used_at IS NULL`, [found.orgId, found.userId]);
+            await client.query(`INSERT INTO password_reset_tokens (org_id, user_id, token_hash, expires_at)
+           VALUES ($1, $2, $3, $4)`, [found.orgId, found.userId, digest(token), expiresAt]);
+        }, this.scope);
+        const link = consoleUrl(this.deps.consoleBase, `#/reset?token=${encodeURIComponent(token)}`);
+        await this.deps.mailer.send({
+            to: address,
+            subject: 'Reset your Nacre password',
+            text: [
+                'Somebody asked to reset the password for this address.',
+                '',
+                link,
+                '',
+                `The link works once and expires in ${String(Math.round(RESET_TTL_SECONDS / 60))} minutes.`,
+                'If it was not you, nothing has changed and you can ignore this message.',
+                '',
+                'Resetting a password does not remove a second factor: you will still be',
+                'asked for a code afterwards.',
+            ].join('\n'),
+        });
+    }
+    /**
+     * Spend a link and set the password, or refuse.
+     *
+     * The spend is the UPDATE that finds it, so two requests cannot both succeed
+     * — a read followed by a write is a race with a stolen link on the other side
+     * of it.
+     */
+    async redeem(token, password) {
+        if (password.length < MIN_PASSWORD_LENGTH)
+            return 'too-short';
+        const [orgId, secret] = token.split('.');
+        if (orgId === undefined || secret === undefined || !UUID.test(orgId))
+            return 'refused';
+        const hash = await hashPassword(password);
+        const address = await withOrg(this.deps.pool, orgId, async (client) => {
+            const { rows } = await client.query(`UPDATE password_reset_tokens SET used_at = now()
+            WHERE org_id = $1 AND token_hash = $2 AND used_at IS NULL AND expires_at > now()
+        RETURNING user_id`, [orgId, digest(token)]);
+            const userId = rows[0]?.user_id;
+            if (userId === undefined)
+                return undefined;
+            const { rows: people } = await client.query('SELECT email, disabled_at FROM users WHERE org_id = $1 AND id = $2', [orgId, userId]);
+            const person = people[0];
+            // A disabled account is refused, and the token is spent anyway: it was
+            // issued before the account was disabled, and leaving it live would be
+            // a link that starts working again if the account is ever re-enabled.
+            if (person === undefined || person.disabled_at !== null)
+                return undefined;
+            await client.query('UPDATE users SET password_hash = $2 WHERE id = $1', [userId, hash]);
+            // Every other session ends. A reset is what somebody does when they
+            // think their password is known, and leaving the refresh tokens alive
+            // would leave whoever knows it signed in.
+            await client.query(`UPDATE refresh_tokens SET revoked_at = now()
+            WHERE org_id = $1 AND user_id = $2 AND revoked_at IS NULL`, [orgId, userId]);
+            return person.email;
+        }, this.scope);
+        if (address === undefined)
+            return 'refused';
+        // A notice, not a confirmation: the person who receives this and did not do
+        // it is the one who needs to know, and they need to know now.
+        await this.deps.mailer
+            .send({
+            to: address,
+            subject: 'Your Nacre password was changed',
+            text: [
+                'The password for this address has just been changed using a recovery link.',
+                '',
+                'Every other session was signed out. Any second factor on the account is',
+                'untouched and is still required.',
+                '',
+                'If this was not you, whoever did it can read your mail — change the',
+                'password again from a device you trust and tell your administrator.',
+            ].join('\n'),
+        })
+            // Dropped rather than raised: the password *is* changed, and refusing the
+            // request over a notice would be worse than a notice that did not arrive.
+            .catch(() => undefined);
+        return 'reset';
+    }
+    /**
+     * The one user this address names, or nothing.
+     *
+     * The same shape the login path uses, and for the same reasons: two matches
+     * is silence rather than a choice, and the scan stops at two so the cost does
+     * not grow with how many tenants a deployment has.
+     */
+    async findUser(email) {
+        const client = await this.deps.pool.connect();
+        let orgIds;
+        try {
+            const { rows } = await client.query('SELECT id FROM organizations WHERE deleted_at IS NULL');
+            orgIds = rows.map((row) => row.id);
+        }
+        finally {
+            client.release();
+        }
+        const found = [];
+        for (const orgId of orgIds) {
+            const row = await withOrg(this.deps.pool, orgId, async (scoped) => {
+                const { rows } = await scoped.query(`SELECT id FROM users
+              WHERE org_id = $1 AND email = $2 AND disabled_at IS NULL AND password_hash IS NOT NULL`, [orgId, email]);
+                return rows[0];
+            }, this.scope);
+            if (row !== undefined)
+                found.push({ orgId, userId: row.id });
+            if (found.length > 1)
+                return undefined;
+        }
+        return found[0];
+    }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
+//# sourceMappingURL=recovery.js.map

package/dist/recovery.js.map

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

package/dist/second-factor.d.ts

@@ -0,0 +1,89 @@
+import type { Pool } from 'pg';
+export interface EnrolledFactor {
+    readonly id: string;
+    readonly kind: 'totp';
+    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 interface SecondFactorDeps {
+    readonly pool: Pool;
+    /** `undefined` when the deployment configured no key; see the header. */
+    readonly key: Buffer | undefined;
+    /** What an authenticator shows above the account. */
+    readonly issuer: string;
+    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. */
+    get available(): boolean;
+    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>;
+    /** 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":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,IAAI,CAAA;AA+B9B,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;IACxB,QAAQ,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC5B;AAUD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;IACnB,yEAAyE;IACzE,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAC1B;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,gBAAgB;IAEnD,iEAAiE;IACjE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,OAAO,KAAK,KAAK,GAEhB;IAED,OAAO,KAAK,KAAK,GAEhB;IAED;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBzD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,cAAc,EAAE,CAAC;IA+B7E;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IA+C9F;;;;;;;;;OASG;IACG,OAAO,CACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAmDzC;;;;;;;;;;;OAWG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsE3E;;;;OAIG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA+BzE;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAezE,6EAA6E;IACvE,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAexE"}

package/dist/second-factor.js

@@ -0,0 +1,267 @@
+import { generateRecoveryCode, generateTotpSecret, hashRecoveryCode, openTotpSecret, otpauthUrl, RECOVERY_CODE_COUNT, sealTotpSecret, verifyTotp, withOrg, } from '@nacre.work/core';
+/**
+ * The second factor, as far as the API is concerned.
+ *
+ * `packages/core/totp.ts` is the arithmetic and knows nothing about a database;
+ * this is the storage, the replay bound and the brute-force bound. The split is
+ * the same one `passwords.ts` has: an algorithm that can be checked against a
+ * standard's own vectors, and a store that can be checked against a real
+ * PostgreSQL.
+ *
+ * ## What a second factor decides
+ *
+ * Whether a session starts. Nothing here is read by `authz/`, and a token
+ * minted after a correct code reaches exactly what the same token reaches
+ * without one — the permitted set is computed per request from `grants`, as it
+ * is for every other principal.
+ *
+ * ## Unconfigured is a supported state
+ *
+ * With no `NACRE_2FA_KEY` there is no key to seal a secret with, so
+ * enrolment is refused and every read answers "no factor". Not a degraded mode
+ * that stores secrets in the clear until somebody notices: a product that
+ * half-does a second factor is worse than one that does none, because the
+ * operator believes something.
+ */
+/** Five wrong codes and this factor stops answering for a while. */
+const MAX_FAILURES = 5;
+const LOCK_SECONDS = 15 * 60;
+export class SecondFactors {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Whether this installation can hold a second factor at all. */
+    get available() {
+        return this.deps.key !== undefined;
+    }
+    get scope() {
+        return this.deps.role === undefined ? {} : { role: this.deps.role };
+    }
+    get clock() {
+        return this.deps.now?.() ?? new Date();
+    }
+    /**
+     * 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.
+     */
+    async required(orgId, userId) {
+        if (!this.available)
+            return false;
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            const { rows } = await client.query(`SELECT count(*)::text AS count FROM user_second_factors
+            WHERE org_id = $1 AND user_id = $2 AND confirmed_at IS NOT NULL`, [orgId, userId]);
+            return Number(rows[0]?.count ?? '0') > 0;
+        }, this.scope);
+    }
+    async list(orgId, userId) {
+        if (!this.available)
+            return [];
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            const { rows } = await client.query(`SELECT id, kind, label, created_at, last_used_at
+             FROM user_second_factors
+            WHERE org_id = $1 AND user_id = $2 AND confirmed_at IS NOT NULL
+            ORDER BY created_at, id`, [orgId, userId]);
+            return rows.map((row) => ({
+                id: row.id,
+                kind: row.kind,
+                label: row.label,
+                createdAt: row.created_at,
+                lastUsedAt: row.last_used_at,
+            }));
+        }, this.scope);
+    }
+    /**
+     * 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.
+     */
+    async begin(orgId, userId, label) {
+        const key = this.deps.key;
+        if (key === undefined)
+            return undefined;
+        const secret = generateTotpSecret();
+        const sealed = sealTotpSecret(secret, key);
+        const begun = await withOrg(this.deps.pool, orgId, async (client) => {
+            // The address, for the label an authenticator shows. Read here rather
+            // than passed in: `AuthContext` carries the principal's id and not
+            // their address, and a handler that had to fetch one would be a second
+            // place that knows how to find a user.
+            const { rows: people } = await client.query('SELECT email FROM users WHERE org_id = $1 AND id = $2', [orgId, userId]);
+            const account = people[0]?.email;
+            if (account === undefined)
+                return undefined;
+            await client.query(`DELETE FROM user_second_factors
+            WHERE org_id = $1 AND user_id = $2 AND label = $3 AND confirmed_at IS NULL`, [orgId, userId, label]);
+            const { rows } = await client.query(`INSERT INTO user_second_factors (org_id, user_id, kind, secret, label)
+           VALUES ($1, $2, 'totp', $3, $4)
+           RETURNING id`, [orgId, userId, sealed, label]);
+            const id = rows[0]?.id;
+            return id === undefined ? undefined : { id, account };
+        }, this.scope);
+        if (begun === undefined)
+            return undefined;
+        return {
+            id: begun.id,
+            secret,
+            otpauthUrl: otpauthUrl({ issuer: this.deps.issuer, account: begun.account, secret }),
+        };
+    }
+    /**
+     * 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.
+     */
+    async confirm(orgId, userId, id, code) {
+        const key = this.deps.key;
+        if (key === undefined)
+            return undefined;
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            const { rows } = await client.query(`SELECT id, secret, last_step, failed_attempts, locked_until
+             FROM user_second_factors
+            WHERE org_id = $1 AND user_id = $2 AND id = $3 AND confirmed_at IS NULL
+              FOR UPDATE`, [orgId, userId, id]);
+            const row = rows[0];
+            if (row === undefined)
+                return undefined;
+            const verified = verifyTotp(openTotpSecret(row.secret, key), code, {
+                at: this.clock,
+                after: row.last_step === null ? null : Number(row.last_step),
+            });
+            if (verified === undefined)
+                return undefined;
+            await client.query(`UPDATE user_second_factors
+              SET confirmed_at = now(), last_step = $2, last_used_at = now(), failed_attempts = 0
+            WHERE id = $1`, [row.id, String(verified.step)]);
+            const { rows: existing } = await client.query(`SELECT count(*)::text AS count FROM user_recovery_codes
+            WHERE org_id = $1 AND user_id = $2 AND used_at IS NULL`, [orgId, userId]);
+            if (Number(existing[0]?.count ?? '0') > 0)
+                return [];
+            const codes = Array.from({ length: RECOVERY_CODE_COUNT }, () => generateRecoveryCode());
+            for (const one of codes) {
+                await client.query(`INSERT INTO user_recovery_codes (org_id, user_id, code_hash) VALUES ($1, $2, $3)`, [orgId, userId, hashRecoveryCode(one)]);
+            }
+            return codes;
+        }, this.scope);
+    }
+    /**
+     * 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.
+     */
+    async verify(orgId, userId, code) {
+        const key = this.deps.key;
+        if (key === undefined)
+            return false;
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            // A recovery code first, and spent by the UPDATE itself: a read then a
+            // write would let two requests spend one code.
+            const spent = await client.query(`UPDATE user_recovery_codes
+              SET used_at = now()
+            WHERE org_id = $1 AND user_id = $2 AND code_hash = $3 AND used_at IS NULL`, [orgId, userId, hashRecoveryCode(code)]);
+            if ((spent.rowCount ?? 0) > 0)
+                return true;
+            const { rows } = await client.query(`SELECT id, secret, last_step, failed_attempts, locked_until
+             FROM user_second_factors
+            WHERE org_id = $1 AND user_id = $2 AND confirmed_at IS NOT NULL
+            ORDER BY created_at
+              FOR UPDATE`, [orgId, userId]);
+            const now = this.clock;
+            for (const row of rows) {
+                if (row.locked_until !== null && row.locked_until > now)
+                    continue;
+                const verified = verifyTotp(openTotpSecret(row.secret, key), code, {
+                    at: now,
+                    after: row.last_step === null ? null : Number(row.last_step),
+                });
+                if (verified === undefined)
+                    continue;
+                await client.query(`UPDATE user_second_factors
+                SET last_step = $2, last_used_at = now(), failed_attempts = 0, locked_until = NULL
+              WHERE id = $1`, [row.id, String(verified.step)]);
+                return true;
+            }
+            // Counted against every factor this person holds, because the attacker
+            // is guessing at the person and not at a device.
+            for (const row of rows) {
+                const failures = row.failed_attempts + 1;
+                // Every parameter cast, because `$2` is read twice — once as the new
+                // value and once in the comparison — and Postgres infers a type from
+                // each use. Uncast it raises `text versus integer` at run time and at
+                // no other time, which is a query that type-checks, passes a mock and
+                // fails against the database. Found by running it.
+                await client.query(`UPDATE user_second_factors
+                SET failed_attempts = $2::int,
+                    locked_until = CASE
+                      WHEN $2::int >= $3::int THEN now() + make_interval(secs => $4::int)
+                      ELSE locked_until
+                    END
+              WHERE id = $1`, [row.id, failures, MAX_FAILURES, LOCK_SECONDS]);
+            }
+            return false;
+        }, this.scope);
+    }
+    /**
+     * 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.
+     */
+    async remove(orgId, userId, id) {
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            const done = await client.query(`DELETE FROM user_second_factors WHERE org_id = $1 AND user_id = $2 AND id = $3`, [orgId, userId, id]);
+            if ((done.rowCount ?? 0) === 0)
+                return false;
+            // The codes go with the last factor. Recovery codes are the way past a
+            // second factor, so leaving them behind an account that no longer has
+            // one is a set of long-lived credentials nobody remembers holding.
+            const { rows } = await client.query(`SELECT count(*)::text AS count FROM user_second_factors
+            WHERE org_id = $1 AND user_id = $2 AND confirmed_at IS NOT NULL`, [orgId, userId]);
+            if (Number(rows[0]?.count ?? '0') === 0) {
+                await client.query(`DELETE FROM user_recovery_codes WHERE org_id = $1 AND user_id = $2`, [
+                    orgId,
+                    userId,
+                ]);
+            }
+            return true;
+        }, this.scope);
+    }
+    /**
+     * 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.
+     */
+    async emailOf(orgId, userId) {
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            const { rows } = await client.query('SELECT email FROM users WHERE org_id = $1 AND id = $2', [orgId, userId]);
+            return rows[0]?.email;
+        }, this.scope);
+    }
+    /** How many unspent recovery codes are left, for the screen that says so. */
+    async recoveryCodesLeft(orgId, userId) {
+        return withOrg(this.deps.pool, orgId, async (client) => {
+            const { rows } = await client.query(`SELECT count(*)::text AS count FROM user_recovery_codes
+            WHERE org_id = $1 AND user_id = $2 AND used_at IS NULL`, [orgId, userId]);
+            return Number(rows[0]?.count ?? '0');
+        }, this.scope);
+    }
+}
+//# sourceMappingURL=second-factor.js.map