@tollwyn/baukasten 0.0.2 → 1.2.3

package/dist/server/accounts.d.ts

@@ -0,0 +1,128 @@
+import type { StripeMode } from './config.js';
+import type { Db, Queryable, Secrets } from './ports.js';
+export declare const SESSION_DAYS = 30;
+export declare const LINK_SECONDS: {
+    readonly verify: number;
+    readonly reset: 3600;
+    readonly change_email: number;
+};
+export type LinkPurpose = keyof typeof LINK_SECONDS;
+/** An account as the product sees it, through the locals of a request or the API. */
+export interface Account {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    hasPassword: boolean;
+    /** The terms accepted at sign-up, named by their day, and when. */
+    termsVersion: string;
+    termsAcceptedAt: Date;
+    /** The referral tag of the link the account came by; `ohne` without one. */
+    via: string;
+    createdAt: Date;
+}
+export interface SignUp {
+    email: string;
+    termsVersion: string;
+    via: string;
+    /** The mode of Stripe the product runs in now. */
+    stripeMode: StripeMode;
+}
+export interface ApiKey {
+    id: string;
+    name: string;
+    /** The start of the key, to tell keys apart. */
+    prefix: string;
+    createdAt: Date;
+}
+export interface LinkUse {
+    accountId: string;
+    hasPassword: boolean;
+    newEmail: string | null;
+}
+export type EmailChange = {
+    kind: 'changed';
+    accountId: string;
+    oldEmail: string;
+    newEmail: string;
+} | {
+    kind: 'invalid';
+} | {
+    kind: 'taken';
+};
+/** What the product deletes of an account, in the transaction of the deletion. */
+export type DeleteHook = (tx: Queryable, accountId: string) => Promise<void>;
+export declare class EmailTaken extends Error {
+    name: string;
+    constructor();
+}
+export declare function normalizeEmail(email: string): string;
+/** How the database keeps a token, a link or a key. */
+export declare function sha256(secret: string): Buffer;
+export type Accounts = ReturnType<typeof createAccounts>;
+export declare function createAccounts(db: Db, secrets: Secrets): {
+    /** Signing up accepts the current terms: the account keeps their name and the time. */
+    create: (input: SignUp & {
+        password: string | null;
+    }) => Promise<Account>;
+    /** The sign-up of the API: account and first key together, or neither. */
+    createWithKey: (input: SignUp & {
+        keyName: string;
+        keyPrefix: string;
+    }) => Promise<{
+        account: Account;
+        key: string;
+    }>;
+    findByEmail(email: string): Promise<Account | null>;
+    /** The account of an address and password; one scrypt, whatever the answer. */
+    authenticate(email: string, password: string): Promise<Account | null>;
+    /** Whether `current` is the password (an account without one needs none), then sets `next`. */
+    changePassword(accountId: string, current: string | null, next: string): Promise<boolean>;
+    createSession(accountId: string): Promise<string>;
+    forSession(token: string): Promise<Account | null>;
+    endSession(token: string): Promise<void>;
+    endOtherSessions(accountId: string, keep: string): Promise<void>;
+    issueLink: (accountId: string, purpose: "verify" | "reset") => Promise<string>;
+    /** A link that makes `newEmail` the address of the account, sent to that address. */
+    issueEmailChange: (accountId: string, newEmail: string) => Promise<string>;
+    /** Looks at a link without using it, for the page that asks to confirm. */
+    peekLink(token: string, purpose: LinkPurpose): Promise<LinkUse | null>;
+    /**
+     * Confirms the address with its link, once. An account without a password (from the API) may
+     * set one here; an account that has one keeps it, whoever holds the link. The other open links
+     * of this kind go.
+     */
+    confirmEmail: (token: string, password: string | null) => Promise<LinkUse | null>;
+    /**
+     * Sets a new password with its link, once: the link proves the address, every session ends
+     * and the other reset links go. When it confirms the address for the first time, the keys go
+     * too: whoever signed up over the API with an address not theirs got a key at once, and the
+     * owner of the address now takes the account. The id of the account, or null for a link that
+     * is not usable.
+     */
+    resetPassword(token: string, password: string): Promise<string | null>;
+    /**
+     * Makes the confirmed address the address of the account and voids every other open link of
+     * the account, so that links sent to the old address stop working. An address another account
+     * took in between leaves the link unused.
+     */
+    confirmEmailChange(token: string): Promise<EmailChange>;
+    createApiKey: (accountId: string, name: string, prefix: string) => Promise<{
+        key: string;
+        apiKey: ApiKey;
+    }>;
+    listApiKeys(accountId: string): Promise<ApiKey[]>;
+    /** False when the account has no such key. */
+    revokeApiKey(accountId: string, keyId: string): Promise<boolean>;
+    forApiKey(key: string): Promise<{
+        account: Account;
+        keyId: string;
+    } | null>;
+    /**
+     * Deletes what is personal in one transaction: first the data of the product through its hook,
+     * then sessions, links and keys; the row stays without address and password, for the numbers
+     * and the books. A failing hook changes nothing.
+     */
+    delete: (accountId: string, hook: DeleteHook) => Promise<void>;
+    /** Removes expired sessions and links; it runs on login, never on a timer. */
+    removeExpired(): Promise<void>;
+};

package/dist/server/accounts.js

@@ -0,0 +1,282 @@
+// A secret leaves this module once, when it is made; the database keeps its SHA-256, a password its
+// scrypt. Expiry is the clock of the database.
+import { createHash } from 'node:crypto';
+export const SESSION_DAYS = 30;
+const HOUR_S = 3_600;
+export const LINK_SECONDS = {
+    verify: 48 * HOUR_S,
+    reset: HOUR_S,
+    change_email: 24 * HOUR_S
+};
+export class EmailTaken extends Error {
+    name = 'EmailTaken';
+    constructor() {
+        super('an account with this email address exists');
+    }
+}
+const COLUMNS = `a.id, a.email, a.email_verified_at, a.password_hash, a.terms_version,
+	a.terms_accepted_at, a.via, a.created_at`;
+/** Accounts that are not deleted; a deleted one keeps its row without an address. */
+const LIVE = 'a.deleted_at IS NULL';
+function toAccount(row) {
+    return {
+        id: row.id,
+        email: row.email,
+        emailVerified: row.email_verified_at !== null,
+        hasPassword: row.password_hash !== null,
+        termsVersion: row.terms_version,
+        termsAcceptedAt: row.terms_accepted_at,
+        via: row.via,
+        createdAt: row.created_at
+    };
+}
+const toKey = (row) => ({
+    id: row.id,
+    name: row.name,
+    prefix: row.prefix,
+    createdAt: row.created_at
+});
+const toUse = (row) => ({
+    accountId: row.account_id,
+    hasPassword: row.has_password,
+    newEmail: row.new_email
+});
+export function normalizeEmail(email) {
+    return email.trim().toLowerCase();
+}
+/** How the database keeps a token, a link or a key. */
+export function sha256(secret) {
+    return createHash('sha256').update(secret).digest();
+}
+function first(rows, what) {
+    const [row] = rows;
+    if (row === undefined)
+        throw new Error(`${what} gave no row`);
+    return row;
+}
+const isUniqueViolation = (error) => error instanceof Error && Reflect.get(error, 'code') === '23505';
+const USABLE = `t.token_hash = $1 AND t.purpose = $2 AND t.used_at IS NULL AND t.expires_at > now()
+	AND a.id = t.account_id AND ${LIVE}`;
+export function createAccounts(db, secrets) {
+    /**
+     * A login with an address that has no account, or an account without a password, checks the
+     * password against this hash: every login costs one scrypt and takes the same time.
+     */
+    let absent;
+    async function insertAccount(tx, input) {
+        const hash = input.password === null ? null : await secrets.hashPassword(input.password);
+        try {
+            const rows = await tx.query(`INSERT INTO baukasten.accounts AS a
+					(email, password_hash, terms_version, terms_accepted_at, via, stripe_mode)
+				 VALUES ($1, $2, $3, now(), $4, $5) RETURNING ${COLUMNS}`, [normalizeEmail(input.email), hash, input.termsVersion, input.via, input.stripeMode]);
+            return toAccount(first(rows, 'creating an account'));
+        }
+        catch (error) {
+            if (isUniqueViolation(error))
+                throw new EmailTaken();
+            throw error;
+        }
+    }
+    async function insertKey(tx, input) {
+        const key = `${input.prefix}_${secrets.token()}`;
+        const rows = await tx.query(`INSERT INTO baukasten.api_keys (account_id, name, key_hash, prefix) VALUES ($1, $2, $3, $4)
+			 RETURNING id, name, prefix, created_at`, 
+        // The prefix of the product, its underscore and six characters of the secret.
+        [input.accountId, input.name, sha256(key), key.slice(0, input.prefix.length + 7)]);
+        return { key, apiKey: toKey(first(rows, 'creating a key')) };
+    }
+    async function consume(tx, token, purpose) {
+        const [row] = await tx.query(`UPDATE baukasten.links t SET used_at = now() FROM baukasten.accounts a WHERE ${USABLE}
+			 RETURNING t.account_id, a.password_hash IS NOT NULL AS has_password, t.new_email`, [sha256(token), purpose]);
+        return row === undefined ? null : toUse(row);
+    }
+    async function insertLink(accountId, purpose, newEmail) {
+        const token = secrets.token();
+        await db.query(`INSERT INTO baukasten.links (token_hash, account_id, purpose, new_email, expires_at)
+			 VALUES ($1, $2, $3, $4, now() + make_interval(secs => $5))`, [sha256(token), accountId, purpose, newEmail, LINK_SECONDS[purpose]]);
+        return token;
+    }
+    return {
+        /** Signing up accepts the current terms: the account keeps their name and the time. */
+        create: (input) => insertAccount(db, input),
+        /** The sign-up of the API: account and first key together, or neither. */
+        createWithKey: (input) => db.transaction(async (tx) => {
+            const account = await insertAccount(tx, { ...input, password: null });
+            const { key } = await insertKey(tx, {
+                accountId: account.id,
+                name: input.keyName,
+                prefix: input.keyPrefix
+            });
+            return { account, key };
+        }),
+        async findByEmail(email) {
+            const [row] = await db.query(`SELECT ${COLUMNS} FROM baukasten.accounts a WHERE a.email = $1 AND ${LIVE}`, [normalizeEmail(email)]);
+            return row === undefined ? null : toAccount(row);
+        },
+        /** The account of an address and password; one scrypt, whatever the answer. */
+        async authenticate(email, password) {
+            const [row] = await db.query(`SELECT ${COLUMNS} FROM baukasten.accounts a WHERE a.email = $1 AND ${LIVE}`, [normalizeEmail(email)]);
+            absent ??= secrets.hashPassword(secrets.token());
+            const stored = row?.password_hash ?? (await absent);
+            const fits = await secrets.verifyPassword(password, stored);
+            return row !== undefined && row.password_hash !== null && fits ? toAccount(row) : null;
+        },
+        /** Whether `current` is the password (an account without one needs none), then sets `next`. */
+        async changePassword(accountId, current, next) {
+            const [row] = await db.query(`SELECT a.password_hash FROM baukasten.accounts a WHERE a.id = $1 AND ${LIVE}`, [accountId]);
+            if (row === undefined)
+                return false;
+            if (row.password_hash !== null) {
+                if (current === null || !(await secrets.verifyPassword(current, row.password_hash))) {
+                    return false;
+                }
+            }
+            const hash = await secrets.hashPassword(next);
+            await db.transaction(async (tx) => {
+                await tx.query('UPDATE baukasten.accounts SET password_hash = $2 WHERE id = $1', [
+                    accountId,
+                    hash
+                ]);
+                // A reset link asked for before would set a password again behind the new one.
+                await tx.query("DELETE FROM baukasten.links WHERE account_id = $1 AND purpose = 'reset' AND used_at IS NULL", [accountId]);
+            });
+            return true;
+        },
+        async createSession(accountId) {
+            const token = secrets.token();
+            await db.query(`INSERT INTO baukasten.sessions (token_hash, account_id, expires_at)
+				 VALUES ($1, $2, now() + make_interval(days => $3))`, [sha256(token), accountId, SESSION_DAYS]);
+            return token;
+        },
+        async forSession(token) {
+            const [row] = await db.query(`SELECT ${COLUMNS} FROM baukasten.sessions s JOIN baukasten.accounts a ON a.id = s.account_id
+				 WHERE s.token_hash = $1 AND s.expires_at > now() AND ${LIVE}`, [sha256(token)]);
+            return row === undefined ? null : toAccount(row);
+        },
+        async endSession(token) {
+            await db.query('DELETE FROM baukasten.sessions WHERE token_hash = $1', [sha256(token)]);
+        },
+        async endOtherSessions(accountId, keep) {
+            await db.query('DELETE FROM baukasten.sessions WHERE account_id = $1 AND token_hash <> $2', [
+                accountId,
+                sha256(keep)
+            ]);
+        },
+        issueLink: (accountId, purpose) => insertLink(accountId, purpose, null),
+        /** A link that makes `newEmail` the address of the account, sent to that address. */
+        issueEmailChange: (accountId, newEmail) => insertLink(accountId, 'change_email', normalizeEmail(newEmail)),
+        /** Looks at a link without using it, for the page that asks to confirm. */
+        async peekLink(token, purpose) {
+            const [row] = await db.query(`SELECT t.account_id, a.password_hash IS NOT NULL AS has_password, t.new_email
+				 FROM baukasten.links t, baukasten.accounts a WHERE ${USABLE}`, [sha256(token), purpose]);
+            return row === undefined ? null : toUse(row);
+        },
+        /**
+         * Confirms the address with its link, once. An account without a password (from the API) may
+         * set one here; an account that has one keeps it, whoever holds the link. The other open links
+         * of this kind go.
+         */
+        confirmEmail: (token, password) => db.transaction(async (tx) => {
+            const use = await consume(tx, token, 'verify');
+            if (use === null)
+                return null;
+            const hash = !use.hasPassword && password !== null ? await secrets.hashPassword(password) : null;
+            await tx.query(`UPDATE baukasten.accounts SET email_verified_at = coalesce(email_verified_at, now()),
+					 password_hash = coalesce(password_hash, $2) WHERE id = $1`, [use.accountId, hash]);
+            await tx.query("DELETE FROM baukasten.links WHERE account_id = $1 AND purpose = 'verify' AND used_at IS NULL", [use.accountId]);
+            return use;
+        }),
+        /**
+         * Sets a new password with its link, once: the link proves the address, every session ends
+         * and the other reset links go. When it confirms the address for the first time, the keys go
+         * too: whoever signed up over the API with an address not theirs got a key at once, and the
+         * owner of the address now takes the account. The id of the account, or null for a link that
+         * is not usable.
+         */
+        async resetPassword(token, password) {
+            const hash = await secrets.hashPassword(password);
+            return db.transaction(async (tx) => {
+                const use = await consume(tx, token, 'reset');
+                if (use === null)
+                    return null;
+                await tx.query(`UPDATE baukasten.api_keys SET revoked_at = now()
+					 WHERE account_id = $1 AND revoked_at IS NULL AND EXISTS (
+						SELECT 1 FROM baukasten.accounts WHERE id = $1 AND email_verified_at IS NULL)`, [use.accountId]);
+                await tx.query(`UPDATE baukasten.accounts SET password_hash = $2,
+					 email_verified_at = coalesce(email_verified_at, now()) WHERE id = $1`, [use.accountId, hash]);
+                await tx.query('DELETE FROM baukasten.sessions WHERE account_id = $1', [use.accountId]);
+                await tx.query("DELETE FROM baukasten.links WHERE account_id = $1 AND purpose = 'reset' AND used_at IS NULL", [use.accountId]);
+                return use.accountId;
+            });
+        },
+        /**
+         * Makes the confirmed address the address of the account and voids every other open link of
+         * the account, so that links sent to the old address stop working. An address another account
+         * took in between leaves the link unused.
+         */
+        async confirmEmailChange(token) {
+            try {
+                return await db.transaction(async (tx) => {
+                    const use = await consume(tx, token, 'change_email');
+                    if (use === null || use.newEmail === null)
+                        return { kind: 'invalid' };
+                    const { email } = first(await tx.query('SELECT email FROM baukasten.accounts WHERE id = $1', [use.accountId]), 'the account of a link');
+                    await tx.query('UPDATE baukasten.accounts SET email = $2, email_verified_at = now() WHERE id = $1', [use.accountId, use.newEmail]);
+                    await tx.query('DELETE FROM baukasten.links WHERE account_id = $1 AND used_at IS NULL', [
+                        use.accountId
+                    ]);
+                    return {
+                        kind: 'changed',
+                        accountId: use.accountId,
+                        oldEmail: email,
+                        newEmail: use.newEmail
+                    };
+                });
+            }
+            catch (error) {
+                if (isUniqueViolation(error))
+                    return { kind: 'taken' };
+                throw error;
+            }
+        },
+        createApiKey: (accountId, name, prefix) => insertKey(db, { accountId, name, prefix }),
+        async listApiKeys(accountId) {
+            const rows = await db.query(`SELECT id, name, prefix, created_at FROM baukasten.api_keys
+				 WHERE account_id = $1 AND revoked_at IS NULL ORDER BY created_at, id`, [accountId]);
+            return rows.map(toKey);
+        },
+        /** False when the account has no such key. */
+        async revokeApiKey(accountId, keyId) {
+            const rows = await db.query(`UPDATE baukasten.api_keys SET revoked_at = now()
+				 WHERE id = $1 AND account_id = $2 AND revoked_at IS NULL RETURNING id`, [keyId, accountId]);
+            return rows.length > 0;
+        },
+        async forApiKey(key) {
+            const [row] = await db.query(`SELECT ${COLUMNS}, k.id AS key_id FROM baukasten.api_keys k
+				 JOIN baukasten.accounts a ON a.id = k.account_id
+				 WHERE k.key_hash = $1 AND k.revoked_at IS NULL AND ${LIVE}`, [sha256(key)]);
+            return row === undefined ? null : { account: toAccount(row), keyId: row.key_id };
+        },
+        /**
+         * Deletes what is personal in one transaction: first the data of the product through its hook,
+         * then sessions, links and keys; the row stays without address and password, for the numbers
+         * and the books. A failing hook changes nothing.
+         */
+        delete: (accountId, hook) => db.transaction(async (tx) => {
+            // The webhook of Stripe locks the account as well: one that comes now waits, and then
+            // finds it deleted, instead of writing data of the product to it.
+            await tx.query('SELECT 1 FROM baukasten.accounts WHERE id = $1 FOR UPDATE', [accountId]);
+            await hook(tx, accountId);
+            for (const table of ['sessions', 'links', 'api_keys']) {
+                await tx.query(`DELETE FROM baukasten.${table} WHERE account_id = $1`, [accountId]);
+            }
+            await tx.query(`UPDATE baukasten.accounts SET email = NULL, password_hash = NULL,
+					 email_verified_at = NULL, deleted_at = now() WHERE id = $1 AND deleted_at IS NULL`, [accountId]);
+        }),
+        /** Removes expired sessions and links; it runs on login, never on a timer. */
+        async removeExpired() {
+            await db.query('DELETE FROM baukasten.sessions WHERE expires_at <= now()');
+            await db.query('DELETE FROM baukasten.links WHERE expires_at <= now()');
+        }
+    };
+}

package/dist/server/adapter/db.d.ts

@@ -0,0 +1,5 @@
+import type { Log } from '../log.js';
+import type { Db } from '../ports.js';
+export declare function createDb(databaseUrl: string, log: Log, options?: {
+    idleTimeoutMillis?: number;
+}): Db;

package/dist/server/adapter/db.js

@@ -0,0 +1,63 @@
+import pg from 'pg';
+/** An idle connection closes soon, so that Neon can suspend after the work is done. */
+const IDLE_TIMEOUT_MS = 10_000;
+export function createDb(databaseUrl, log, options = {}) {
+    const pool = new pg.Pool({
+        connectionString: databaseUrl,
+        max: 5,
+        idleTimeoutMillis: options.idleTimeoutMillis ?? IDLE_TIMEOUT_MS,
+        connectionTimeoutMillis: 5_000
+    });
+    let opened = 0;
+    pool.on('connect', () => {
+        opened += 1;
+    });
+    // An idle connection that breaks (Neon suspended it, a restart) must not end the process; the
+    // next query opens a new one.
+    pool.on('error', (error) => log.warn('database: an idle connection failed', { error }));
+    return {
+        async query(sql, params) {
+            return (await pool.query(sql, params)).rows;
+        },
+        withTimeout: (ms) => ({
+            async query(sql, params) {
+                // pg reads query_timeout per query, its types know it only for the pool; a query that
+                // runs out fails, and the pool drops its connection.
+                const config = {
+                    text: sql,
+                    values: params,
+                    query_timeout: ms
+                };
+                return (await pool.query(config)).rows;
+            }
+        }),
+        async transaction(fn) {
+            const client = await pool.connect();
+            let broken;
+            try {
+                await client.query('BEGIN');
+                const result = await fn({
+                    query: async (sql, params) => (await client.query(sql, params)).rows
+                });
+                await client.query('COMMIT');
+                return result;
+            }
+            catch (error) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch (rollback) {
+                    // The connection is broken: it goes away instead of back to the pool.
+                    broken = rollback instanceof Error ? rollback : new Error(String(rollback));
+                    log.warn('database: a rollback failed, the connection is dropped', { error: broken });
+                }
+                throw error;
+            }
+            finally {
+                client.release(broken);
+            }
+        },
+        connectionsOpened: () => opened,
+        close: () => pool.end()
+    };
+}

package/dist/server/adapter/log.d.ts

@@ -0,0 +1,3 @@
+export declare const log: import("../log.js").Log;
+/** Ends the process once every line written before is out, even through a pipe that writes later. */
+export declare function exitAfterLog(code: number): Promise<never>;

package/dist/server/adapter/log.js

@@ -0,0 +1,12 @@
+import { createLog } from '../log.js';
+export const log = createLog({
+    level: process.env.LOG_LEVEL,
+    write: (line) => process.stdout.write(line),
+    now: () => new Date()
+});
+/** Ends the process once every line written before is out, even through a pipe that writes later. */
+export function exitAfterLog(code) {
+    return new Promise(() => {
+        process.stdout.write('', () => process.exit(code));
+    });
+}

package/dist/server/adapter/mailer.d.ts

@@ -0,0 +1,4 @@
+import type { Mail as MailConfig } from '../config.js';
+import type { Log } from '../log.js';
+import type { Mailer } from '../ports.js';
+export declare function createMailer(config: MailConfig, name: string, log: Log): Mailer;

package/dist/server/adapter/mailer.js

@@ -0,0 +1,56 @@
+// Plain SMTP without a login: the relay of the fleet lies inside the network of the products and
+// sends on over TLS. Only a mail in the local log, without SMTP, puts an address into the log.
+import nodemailer from 'nodemailer';
+import { MailFailed } from '../mail.js';
+/** What SMTP calls a failure; nodemailer adds it to its errors. */
+function failure(error) {
+    const field = (name) => typeof error === 'object' && error !== null ? Reflect.get(error, name) : undefined;
+    const code = field('code');
+    const responseCode = field('responseCode');
+    const command = field('command');
+    return new MailFailed({
+        code: typeof code === 'string' ? code : 'error',
+        ...(typeof responseCode === 'number' ? { responseCode } : {}),
+        ...(typeof command === 'string' ? { command } : {})
+    });
+}
+export function createMailer(config, name, log) {
+    switch (config.kind) {
+        case 'log':
+            return {
+                send(mail) {
+                    log.info('mail not sent: SMTP is not configured', { ...mail });
+                    return Promise.resolve();
+                },
+                check: () => Promise.resolve()
+            };
+        case 'smtp': {
+            const transport = nodemailer.createTransport({
+                host: config.host,
+                port: config.port,
+                connectionTimeout: 10_000,
+                greetingTimeout: 10_000,
+                socketTimeout: 20_000
+            });
+            const from = { name, address: config.from };
+            return {
+                async send(mail) {
+                    try {
+                        await transport.sendMail({ from, to: mail.to, subject: mail.subject, text: mail.text });
+                    }
+                    catch (error) {
+                        throw failure(error);
+                    }
+                },
+                async check() {
+                    try {
+                        await transport.verify();
+                    }
+                    catch (error) {
+                        throw failure(error);
+                    }
+                }
+            };
+        }
+    }
+}

package/dist/server/adapter/migrate.d.ts

@@ -0,0 +1,21 @@
+import { type Layer, type MigrationStatus } from '../migrations.js';
+import type { Queryable } from '../ports.js';
+export interface MigrationSources {
+    baukasten: readonly {
+        name: string;
+        sql: string;
+    }[];
+    /** The folder of the product's migrations; a product without one has none. */
+    product: string;
+}
+export type ByLayer = Record<Layer, string[]>;
+/** What a run applied, and what the database had ahead of this version. */
+export interface MigrateResult {
+    applied: ByLayer;
+    ahead: ByLayer;
+}
+export type Art = 'webapp' | 'shopify';
+export declare function migrationSources(root: string, art: Art): MigrationSources;
+/** What the database still needs of this version and what forbids migrating it, for /health/deep. */
+export declare function migrationStatus(db: Queryable, sources: MigrationSources): Promise<MigrationStatus>;
+export declare function migrate(databaseUrl: string, sources: MigrationSources): Promise<MigrateResult>;