@tollwyn/baukasten 0.0.2 → 1.2.2

package/dist/server/endpoints.js

@@ -0,0 +1,159 @@
+import { z } from 'zod';
+import { EmailTaken } from './accounts.js';
+import { ApiError, bearerKey, readBody, respond } from './api.js';
+import { emailField } from './fields.js';
+import { LIMITS } from './limits.js';
+import { sendLink, signUp } from './services.js';
+import { VIA_MAX, VIA_PATTERN } from './via.js';
+export const API_PATHS = {
+    signup: '/api/v1/signup',
+    account: '/api/v1/account',
+    checkout: '/api/v1/billing/checkout',
+    portal: '/api/v1/billing/portal'
+};
+export const API_METHODS = {
+    [API_PATHS.signup]: 'POST',
+    [API_PATHS.account]: 'GET',
+    [API_PATHS.checkout]: 'POST',
+    [API_PATHS.portal]: 'POST'
+};
+const isApiPath = (path) => Object.hasOwn(API_METHODS, path);
+const BACK = '/account';
+export function accountJson(account) {
+    return {
+        id: account.id,
+        email: account.email,
+        email_verified: account.emailVerified,
+        created_at: account.createdAt.toISOString()
+    };
+}
+function tooMany(s, seconds) {
+    return new ApiError(429, 'rate_limited', s.messages.api.rateLimited(seconds), {
+        headers: { 'retry-after': String(seconds) }
+    });
+}
+/** The account of the bearer key, counted against the limit of the key. */
+export async function apiAccount(s, event) {
+    const prefix = s.product.accounts.keyPrefix;
+    const key = bearerKey(event.request.headers, prefix);
+    const found = key === null ? null : await s.accounts.forApiKey(key);
+    if (found === null) {
+        throw new ApiError(401, 'unauthorized', s.messages.api.unauthorized(`${prefix}_…`));
+    }
+    const seconds = s.limits.take(`api:${found.keyId}`, LIMITS.api);
+    if (seconds > 0)
+        throw tooMany(s, seconds);
+    return found;
+}
+/** The body of the sign-up, every problem in the language of the product. */
+export function signupBody(m, terms) {
+    return z.object({
+        email: emailField(m),
+        accept_terms: z.literal(true, m.api.acceptTerms(terms)),
+        acting_for_business: z.literal(true, m.api.actingForBusiness),
+        via: z.string(m.api.via).max(VIA_MAX, m.api.via).regex(VIA_PATTERN, m.api.via).optional()
+    }, m.api.notAnObject);
+}
+async function signup(s, event) {
+    const m = s.messages;
+    const body = await readBody(event.request, signupBody(m, `${s.config.publicOrigin}/terms`), m);
+    const seconds = s.limits.take(`signup:${s.address(event)}`, LIMITS.signup);
+    if (seconds > 0)
+        throw tooMany(s, seconds);
+    let created;
+    try {
+        created = await s.accounts.createWithKey({
+            // An agent that signs up names the referral tag of the link it came by, or none.
+            ...signUp(s, body.email, body.via ?? null),
+            keyName: m.api.firstKey,
+            keyPrefix: s.product.accounts.keyPrefix
+        });
+    }
+    catch (error) {
+        if (error instanceof EmailTaken)
+            throw new ApiError(409, 'email_taken', m.api.emailTaken);
+        throw error;
+    }
+    // A failed mail is in the log and does not fail the sign-up: the key works without it. Whoever
+    // holds the address still gets in with «Forgot your password?», which confirms the address and
+    // revokes the keys made before.
+    await sendLink(s, created.account, { purpose: 'verify' });
+    return Response.json({ api_key: created.key, account: accountJson(created.account) }, { status: 201 });
+}
+/**
+ * The body of a Checkout over the API: a price of the catalog by its lookup key, and a quantity,
+ * which the price decides on (checkout below).
+ */
+export function checkoutBody(m) {
+    return z.object({ price: z.string(m.api.price), quantity: z.unknown().optional() }, m.api.notAnObject);
+}
+function invalid(m, path, message) {
+    return new ApiError(422, 'invalid_request', m.api.invalidRequest, {
+        details: [{ path, message }]
+    });
+}
+function withStripe(s) {
+    if (s.config.stripe.kind === 'none') {
+        throw new ApiError(503, 'not_configured', s.messages.stripe.notConfigured);
+    }
+}
+async function checkout(s, event) {
+    const m = s.messages;
+    const { account } = await apiAccount(s, event);
+    const body = await readBody(event.request, checkoutBody(m), m);
+    const product = s.product.catalog.products.find((p) => p.prices.some((price) => price.lookupKey === body.price));
+    if (product === undefined)
+        throw invalid(m, 'price', m.api.price);
+    const max = product.kind === 'subscription' && product.quantity !== undefined ? product.quantity.max : 1;
+    const quantity = body.quantity;
+    if (quantity === undefined)
+        return opened(s, account, { price: body.price });
+    if (typeof quantity !== 'number' ||
+        !Number.isInteger(quantity) ||
+        quantity < 1 ||
+        quantity > max) {
+        throw invalid(m, 'quantity', m.api.quantity(max));
+    }
+    return opened(s, account, { price: body.price, quantity });
+}
+async function opened(s, account, order) {
+    withStripe(s);
+    const page = await s.billing.checkout(account, { ...order, success: BACK, cancel: BACK });
+    switch (page.kind) {
+        case 'subscribed':
+            throw new ApiError(409, 'subscribed', s.messages.api.subscribed);
+        case 'open':
+            return Response.json({ url: page.url });
+    }
+}
+async function portal(s, event) {
+    const { account } = await apiAccount(s, event);
+    withStripe(s);
+    if (!(await s.billing.hasCustomer(account.id))) {
+        throw new ApiError(409, 'no_customer', s.messages.api.noCustomer);
+    }
+    return Response.json({ url: await s.billing.portal(account, BACK) });
+}
+/** The answer of a path of the baukasten's API, or null for any other path. */
+export function serveApi(s, event) {
+    const path = event.url.pathname;
+    if (!isApiPath(path))
+        return null;
+    return respond(s.log, s.messages, async () => {
+        if (event.request.method !== API_METHODS[path]) {
+            throw new ApiError(405, 'method_not_allowed', s.messages.api.methodNotAllowed, {
+                headers: { allow: API_METHODS[path] }
+            });
+        }
+        switch (path) {
+            case API_PATHS.signup:
+                return signup(s, event);
+            case API_PATHS.account:
+                return Response.json(accountJson((await apiAccount(s, event)).account));
+            case API_PATHS.checkout:
+                return checkout(s, event);
+            case API_PATHS.portal:
+                return portal(s, event);
+        }
+    });
+}

package/dist/server/fields.d.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+import type { Messages } from './messages.js';
+export declare const emailField: (m: Messages) => z.ZodPipe<z.ZodString, z.ZodEmail>;
+export declare const passwordField: (m: Messages) => z.ZodString;
+/** A text field of a submitted form; a missing one is empty, as an empty field. */
+export declare function field(form: FormData, name: string): string;
+export declare function problem(schema: z.ZodType, value: unknown): string | null;

package/dist/server/fields.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+// Every rule names its message: what Zod says by itself is English, whatever the product speaks.
+export const emailField = (m) => z.string(m.email.invalid).trim().max(254, m.email.tooLong).pipe(z.email(m.email.invalid));
+export const passwordField = (m) => z.string(m.password.tooShort).min(10, m.password.tooShort).max(200, m.password.tooLong);
+/** A text field of a submitted form; a missing one is empty, as an empty field. */
+export function field(form, name) {
+    const value = form.get(name);
+    return typeof value === 'string' ? value : '';
+}
+export function problem(schema, value) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return null;
+    const [first] = result.error.issues;
+    if (first === undefined)
+        throw new Error('a failed parse without an issue');
+    return first.message;
+}

package/dist/server/headers.d.ts

@@ -0,0 +1 @@
+export declare const SECURITY_HEADERS: Readonly<Record<string, string>>;

package/dist/server/headers.js

@@ -0,0 +1,9 @@
+// The security headers of every response. The server of a product (start.ts) sets them before any
+// handler, so that the static files carry them too; the handle sets them as well, for the dev
+// server. The content security policy comes from SvelteKit (SVELTEKIT_OPTIONS), per page.
+export const SECURITY_HEADERS = {
+    'x-content-type-options': 'nosniff',
+    'x-frame-options': 'DENY',
+    'referrer-policy': 'strict-origin-when-cross-origin',
+    'cross-origin-opener-policy': 'same-origin'
+};

package/dist/server/health.d.ts

@@ -0,0 +1,34 @@
+import type { Catalog } from '../product.js';
+import { type Shop } from './catalog.js';
+import { type Log } from './log.js';
+import type { MigrationStatus } from './migrations.js';
+import type { Mailer, Queryable, StripeApi } from './ports.js';
+/** A check resolves when all is well; CheckFailed carries a short reason without hosts or secrets. */
+export type Check = () => Promise<void>;
+export declare class CheckFailed extends Error {
+    name: string;
+}
+/**
+ * Per check `ok` or `fail: <reason>`, never a `status` key of its own: the delivery service looks
+ * for the overall `"status":"ok"`.
+ */
+export interface HealthReport {
+    status: 'ok' | 'fail';
+    checks: Record<string, string>;
+}
+export declare const CHECK_TIMEOUT_MS = 5000;
+export declare function deepHealth(options: {
+    checks: Record<string, Check>;
+    now: () => number;
+    log: Log;
+    timeoutMs?: number;
+}): () => Promise<HealthReport>;
+/** The database answers, and neither layer has a migration pending or a problem. */
+export declare function databaseCheck(db: Queryable, status: () => Promise<MigrationStatus>, log: Log): Check;
+/** The relay of the fleet greets; its time limit is that of every check. */
+export declare function mailCheck(mailer: Mailer, log: Log): Check;
+/**
+ * Stripe takes the key, the catalog and the default portal are as the migration sets them up, and
+ * no webhook endpoint of another product gets the events of this one.
+ */
+export declare function stripeCheck(stripe: StripeApi, catalog: Catalog, shop: Shop, log: Log): Check;

package/dist/server/health.js

@@ -0,0 +1,116 @@
+import { StripeFailed } from './billing.js';
+import { catalogDifferences, foreignWebhooks } from './catalog.js';
+import { describeError } from './log.js';
+import { MailFailed } from './mail.js';
+export class CheckFailed extends Error {
+    name = 'CheckFailed';
+}
+export const CHECK_TIMEOUT_MS = 5_000;
+const OK_FOR_MS = 60_000;
+const FAIL_FOR_MS = 5_000;
+async function within(check, timeoutMs) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new CheckFailed('timeout')), timeoutMs);
+    });
+    try {
+        await Promise.race([check(), timeout]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export function deepHealth(options) {
+    const { checks, now, log } = options;
+    const timeoutMs = options.timeoutMs ?? CHECK_TIMEOUT_MS;
+    let running = null;
+    let remembered = null;
+    async function one(name, check) {
+        try {
+            await within(check, timeoutMs);
+            return 'ok';
+        }
+        catch (error) {
+            if (error instanceof CheckFailed)
+                return `fail: ${error.message}`;
+            log.error('health check failed', { check: name, error });
+            return 'fail: error';
+        }
+    }
+    async function run() {
+        const results = await Promise.all(Object.entries(checks).map(async ([name, check]) => [name, await one(name, check)]));
+        const report = {
+            status: results.every(([, result]) => result === 'ok') ? 'ok' : 'fail',
+            checks: Object.fromEntries(results)
+        };
+        remembered = { report, until: now() + (report.status === 'ok' ? OK_FOR_MS : FAIL_FOR_MS) };
+        return report;
+    }
+    return () => {
+        if (remembered !== null && now() < remembered.until)
+            return Promise.resolve(remembered.report);
+        running ??= run().finally(() => {
+            running = null;
+        });
+        return running;
+    };
+}
+/** The database answers, and neither layer has a migration pending or a problem. */
+export function databaseCheck(db, status, log) {
+    return async () => {
+        try {
+            await db.query('SELECT 1');
+        }
+        catch (error) {
+            log.error('database unreachable', { error });
+            const code = describeError(error).code;
+            // A SQLSTATE such as 28P01 names the kind of failure and carries no secret.
+            throw new CheckFailed(typeof code === 'string' && /^[0-9A-Z]{5}$/.test(code) ? `error ${code}` : 'unreachable');
+        }
+        const { pending, problems } = await status();
+        if (problems.length > 0)
+            throw new CheckFailed(problems.join('; '));
+        if (pending.length > 0)
+            throw new CheckFailed(`migrations pending: ${pending.join(', ')}`);
+    };
+}
+/** The relay of the fleet greets; its time limit is that of every check. */
+export function mailCheck(mailer, log) {
+    return async () => {
+        try {
+            await mailer.check();
+        }
+        catch (error) {
+            log.error('mail relay unreachable', { error });
+            // The code of SMTP, such as ECONNECTION, names the kind of failure and no host.
+            throw new CheckFailed(error instanceof MailFailed ? `error ${error.code}` : 'unreachable');
+        }
+    };
+}
+/**
+ * Stripe takes the key, the catalog and the default portal are as the migration sets them up, and
+ * no webhook endpoint of another product gets the events of this one.
+ */
+export function stripeCheck(stripe, catalog, shop, log) {
+    return async () => {
+        let differences;
+        let foreign;
+        try {
+            [differences, foreign] = await Promise.all([
+                catalogDifferences(stripe, catalog, shop),
+                foreignWebhooks(stripe, shop.origin)
+            ]);
+        }
+        catch (error) {
+            log.error('stripe unreachable', { error });
+            // What Stripe called the failure, such as authentication_error, names no key.
+            throw new CheckFailed(error instanceof StripeFailed ? `error ${error.kind}` : 'unreachable');
+        }
+        if (foreign.length > 0) {
+            log.error('stripe: webhook endpoints of another product', { endpoints: foreign });
+            throw new CheckFailed(`foreign webhook endpoints: ${foreign.length}`);
+        }
+        if (differences.length > 0)
+            throw new CheckFailed(`catalog differs: ${differences.join(', ')}`);
+    };
+}

package/dist/server/hook.d.ts

@@ -0,0 +1,92 @@
+import type { Handle, HandleServerError, RequestEvent, ServerInit } from '@sveltejs/kit';
+import type { z } from 'zod';
+import type { Product, ProductEnv } from '../product.js';
+import { type Account } from './accounts.js';
+import { type CheckoutPage, type Order, type Purchase, type SubscriptionChange } from './billing.js';
+import { type Config } from './config.js';
+import { type Limits } from './limits.js';
+import type { Log } from './log.js';
+import { type OpenApiDocument } from './openapi.js';
+import { type Pages } from './pages.js';
+import type { Db, Mailer, Queryable } from './ports.js';
+import type { ProductNumbers } from './sales.js';
+export interface Context<E extends ProductEnv = ProductEnv> {
+    config: Config<E>;
+    db: Db;
+    log: Log;
+    /** The sending of the baukasten, for the product's own mails. */
+    mail: Mailer;
+    /** The counters of the baukasten, for the limits of the product's own routes. */
+    limits: Limits;
+}
+/** What the baukasten calls in the product. */
+export interface Hooks<E extends ProductEnv = ProductEnv> {
+    /**
+     * The checks of the product in GET /health/deep, by name; `database`, `mail` and `stripe` are the
+     * baukasten's.
+     */
+    checks?: Record<string, (context: Context<E>) => Promise<void>>;
+    /** Once the configuration is read, before the first request: the product starts its runs. */
+    start?: (context: Context<E>) => Promise<void> | void;
+    /** On SIGTERM, after the last request and before the pool closes: it stops its runs. */
+    stop?: (context: Context<E>) => Promise<void> | void;
+    /**
+     * Deletes the product's data of an account, in the transaction that deletes the account; the
+     * baukasten then deletes what it keeps of it, and the row stays without the address.
+     */
+    deleteAccount?: (tx: Queryable, accountId: string) => Promise<void>;
+    /**
+     * Stripe reported a change of a subscription, and this is its state now, read back from Stripe. In
+     * the transaction of the webhook, which applies each event once; a failure rolls it back, and
+     * Stripe sends the event again. The product derives its plans and entitlements here.
+     */
+    subscriptionChanged?: (tx: Queryable, change: SubscriptionChange) => Promise<void>;
+    /**
+     * A purchase was paid, once per purchase, in the transaction of the webhook. A product with a
+     * balance books it here.
+     */
+    purchasePaid?: (tx: Queryable, purchase: Purchase) => Promise<void>;
+    /**
+     * Further numbers for GET /vertrieb/zahlen, by name, each counted per account id; the baukasten
+     * adds them up per referral tag. An account the product does not name has none of that number.
+     */
+    salesNumbers?: (db: Queryable) => Promise<ProductNumbers>;
+}
+export interface Kit<E extends ProductEnv = ProductEnv> {
+    /**
+     * The `init` of the hooks. SvelteKit runs it in `vite build` too, to prerender pages, with
+     * `building` of `$app/environment` set: then it reads nothing and opens nothing, since the image is
+     * built without a single variable.
+     */
+    init(building: boolean): ServerInit;
+    handle: Handle;
+    handleError: HandleServerError;
+    /** Pool, configuration, log, mail and limits of the running product; only after `init`. */
+    context(): Context<E>;
+    /** `load` and `actions` of the pages of the baukasten, for the stubs under src/routes. */
+    pages: Pages;
+    /** The address of the client of a request; the product counts its own limits by it. */
+    clientAddress(event: RequestEvent): string;
+    /** The helpers of the product's own API, in the shape of the baukasten's. */
+    api: {
+        /** Runs a handler: an ApiError becomes its answer, anything else a logged 500. */
+        respond(handler: () => Promise<Response>): Promise<Response>;
+        /** The JSON body of a request, parsed with `schema`: else 400 or 422 with each problem. */
+        body<S extends z.ZodType>(request: Request, schema: S): Promise<z.output<S>>;
+        /** The account of the bearer key: else 401, and 429 past the limit of the key. */
+        account(event: RequestEvent): Promise<Account>;
+    };
+    /** The OpenAPI document of the product with the paths of the baukasten merged in. */
+    openApi(document: OpenApiDocument): OpenApiDocument;
+    /** Payment through Stripe, for the pages of the product. */
+    billing: {
+        /**
+         * A Checkout page for a price of the catalog, by its lookup key: a subscription, or a purchase.
+         * An account with a running subscription gets none; the customer portal changes it.
+         */
+        checkout(account: Account, order: Order): Promise<CheckoutPage>;
+        /** The customer portal of the account, which leads back to the path `back`. */
+        portal(account: Account, back: string): Promise<string>;
+    };
+}
+export declare function baukasten<E extends ProductEnv>(product: Product<E>, hooks?: Hooks<E>): Kit<E>;