@capybara-hq/kernel 0.1.0-rc.13 → 0.1.0-rc.15

package/dist/client/client-access.service.js

@@ -0,0 +1,294 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { CLIENT_API_VERSION, EXTENSION_NAME_RE, resolveUiSlots, validateUiContributions, } from "@capybara-hq/plugin-sdk";
+import { Inject, Injectable } from "@nestjs/common";
+import { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { enabledExtensionsQuery } from "../extensions/enabled.js";
+import { STALE_RECONCILE_PERIODS } from "../extensions/lifecycle-topics.js";
+import { CLIENT_EXTENSIONS_SETTING, parseClientExtensions, readClientExtensions, } from "../identity/settings.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { StorageService } from "../storage/storage.service.js";
+import { canUseSlot } from "../ui/registry.js";
+import { CLIENT_DIR, clientContentType, clientRelPath } from "./client-files.js";
+const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+/**
+ * The `component` contributions of a stored extension section (`extension_packages.section`), each
+ * with the catalog slot it resolves to (`resolveUiSlots`: an unknown slot or version is left out,
+ * as the host drops it). The section was validated when the package was imported; an invalid one
+ * (an old format) yields none.
+ */
+function componentsOf(section) {
+    const manifest = isObj(section) ? section.manifest : undefined;
+    if (!isObj(manifest) || !Array.isArray(manifest.ui))
+        return [];
+    if (validateUiContributions(manifest.ui, manifest.permissions).length > 0)
+        return [];
+    return resolveUiSlots(manifest.ui)
+        .resolved.filter((r) => r.contribution.kind === "component" && r.contribution.aliasOf === undefined)
+        .map((r) => ({ id: r.contribution.id, slot: r.slot }));
+}
+/** `/api/v1/client/<plugin>/<build>/<path inside dist/client/>` of a manifest key. */
+export const clientFileUrl = (plugin, build, key) => `/api/v1/client/${plugin}/${build}/${clientRelPath(key)}`;
+const fileRef = (r, key) => ({
+    url: clientFileUrl(r.plugin, r.build, key),
+    integrity: r.integrity[key],
+});
+/** One segment of a client file path as it must appear in the URL (spec §9.1 key charset). */
+const SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+const BUILD_RE = /^[0-9a-f]{64}$/;
+const notFound = () => new ApiError("client.not_found", "Client file not found");
+/**
+ * The content type a client file is served with: the stored type, with the stylesheet's charset
+ * spelled out (`text/css; charset=utf-8`; stylesheets are checked to be UTF-8 when stored).
+ */
+const servedType = (key) => key.endsWith(".css") ? "text/css; charset=utf-8" : clientContentType(key);
+/**
+ * The client file a delivery URL path names, as `{ plugin, build, key }`, or null. `path` is the
+ * raw request path after `/api/v1/client/`, never decoded: every segment must already be made of
+ * `[A-Za-z0-9._-]` and not be `.` or `..`, so an encoded separator (`%2F`, `%5C`), an encoded dot
+ * (`%2e`), a backslash, an empty segment (`//`, a trailing `/`) or a dot segment names nothing.
+ * The key is then `./dist/client/<segments>`: the exact manifest spelling, nothing joined or
+ * normalised.
+ */
+export function parseClientPath(path) {
+    const [plugin, build, ...file] = path.split("/");
+    if (plugin === undefined || !EXTENSION_NAME_RE.test(plugin))
+        return null;
+    if (build === undefined || !BUILD_RE.test(build))
+        return null;
+    if (file.length === 0)
+        return null;
+    if (!file.every((s) => SEGMENT_RE.test(s) && s !== "." && s !== ".."))
+        return null;
+    return { plugin, build, key: `./${CLIENT_DIR}${file.join("/")}` };
+}
+const stopped = (kill, plugin) => !kill.enabled || kill.disabled.includes(plugin);
+/**
+ * Whether the web host runs a build of this client API version (spec §4.2: one version before
+ * 0.1.0). Imports refuse newer ones; a build the host cannot run is never listed in a shell read.
+ */
+const supported = (r) => r.api_version === CLIENT_API_VERSION;
+/**
+ * Who may load which client code (client extensions spec §9.2, §9.3, §10.2), decided from PG on
+ * every request: no process state, nothing cached, so every replica answers the same and a change
+ * (an org switch, an upgrade, the kill switch) applies at once.
+ *
+ * Client code follows the server code that actually runs. A build is **served** when its package
+ * is what a live replica serves for an enabled install (`extension_replica_status.serving_sha256`,
+ * heartbeat within `STALE_RECONCILE_PERIODS` reconcile intervals: the row's own package when
+ * loaded, the older package still running beside a version pending approval or failed) and the
+ * approved permission snapshot covers its client keys (`permissions.client` and every
+ * `ui.component:<id>` of its manifest). So during an upgrade awaiting approval, or after the new
+ * version's migration / setup / import failed, the old build stays served and listed and the new
+ * one is not, until a replica serves it; with no live replica nothing is (fails closed). An org
+ * upload awaiting the super admin has no install, so nothing of it is served. The kill switch
+ * (`clientExtensions`) then stops all builds or those of the listed plugins.
+ */
+let ClientAccess = class ClientAccess {
+    db;
+    config;
+    storage;
+    log;
+    constructor(db, config, storage, log) {
+        this.db = db;
+        this.config = config;
+        this.storage = storage;
+        this.log = log;
+    }
+    /**
+     * The client file a delivery request names (`path`: the raw path after `/api/v1/client/`, see
+     * {@link parseClientPath}) when the account may fetch it ({@link fetchable}) and the build lists
+     * it by that exact key; else 404 `client.not_found` (one answer for every reason, and never the
+     * requested path in the message). The bytes come from object storage under the build's prefix;
+     * the integrity a browser checks them against came from the `extension_client_builds` row.
+     */
+    async file(accountId, superAdmin, path) {
+        const ref = parseClientPath(path);
+        if (ref === null)
+            throw notFound();
+        const build = await this.fetchable(accountId, superAdmin, ref.plugin, ref.build);
+        if (build === null || !build.keys.has(ref.key))
+            throw notFound();
+        this.storage.assertAvailable();
+        const got = await this.storage.deployment().get(build.objectPrefix + clientRelPath(ref.key));
+        if (!got)
+            throw notFound();
+        return {
+            contentType: servedType(ref.key),
+            data: new Uint8Array(await new Response(got.body).arrayBuffer()),
+        };
+    }
+    /**
+     * The served client builds (see the class header) as a query to narrow: one row per (extension,
+     * served build); during a rollout two replicas may serve two builds of one extension.
+     */
+    served(db) {
+        const staleSeconds = STALE_RECONCILE_PERIODS * this.config.get().extensionHost.reconcileIntervalSeconds;
+        return db
+            .selectFrom("extension_installs as i")
+            .innerJoin("extension_client_builds as b", "b.plugin", "i.name")
+            .innerJoin("extension_packages as p", "p.sha256", "b.package_sha256")
+            .innerJoin("extension_permission_snapshots as s", "s.plugin", "i.name")
+            .where("i.desired_state", "=", "enabled")
+            .where(sql `s.permissions -> 'permissions' -> 'client' = 'true'::jsonb`)
+            .where(sql `coalesce(s.permissions -> 'permissions' -> 'ui' -> 'components', '[]'::jsonb) @> coalesce(p.section -> 'manifest' -> 'permissions' -> 'ui' -> 'components', '[]'::jsonb)`)
+            .where((eb) => eb.exists(eb
+            .selectFrom("extension_replica_status as r")
+            .select(sql `1`.as("one"))
+            .whereRef("r.plugin", "=", "i.name")
+            .whereRef("r.serving_sha256", "=", "b.package_sha256")
+            .where("r.heartbeat_at", ">", sql `now() - make_interval(secs => ${staleSeconds})`)))
+            .select([
+            "i.name as plugin",
+            "b.package_sha256 as build",
+            "p.section as section",
+            "b.entry as entry",
+            "b.styles as styles",
+            "b.assets as assets",
+            "b.integrity as integrity",
+            "b.object_prefix as object_prefix",
+            "b.api_version as api_version",
+        ]);
+    }
+    /**
+     * One served build per extension, for the shell reads: the install's current package when a
+     * replica serves it, else the newest build a replica still serves (the old one while the new
+     * version waits for approval or failed).
+     */
+    listed(db) {
+        return this.served(db)
+            .distinctOn("i.name")
+            .orderBy("i.name")
+            .orderBy(sql `(b.package_sha256 = i.sha256) desc`)
+            .orderBy("b.created_at", "desc");
+    }
+    /**
+     * The build `build` of `plugin` when the account may fetch its files, else null; one query, not
+     * cached. It must be served (class header), not stopped by the kill switch, and the account a
+     * member (any role) of a live org where the extension is enabled, or a super admin when the
+     * build's manifest has a `platform.page` component (the admin console loads only those). A
+     * build of a client API version the kernel does not support is never fetchable, as it is never
+     * listed in a shell read.
+     */
+    async fetchable(accountId, superAdmin, plugin, build) {
+        const db = this.db.db;
+        const row = await this.served(db)
+            .where("i.name", "=", plugin)
+            .where("b.package_sha256", "=", build)
+            .select((eb) => [
+            eb
+                .selectFrom("deployment_settings")
+                .select("value")
+                .where("key", "=", CLIENT_EXTENSIONS_SETTING)
+                .as("kill"),
+            // enabled.ts's two sources, per account: a required bootstrap install is on in every org,
+            // otherwise the org's own switch row
+            eb
+                .exists(eb
+                .selectFrom("memberships as m")
+                .innerJoin("orgs as o", "o.id", "m.org_id")
+                .select(sql `1`.as("one"))
+                .where("m.account_id", "=", accountId)
+                .where("o.deleted_at", "is", null)
+                .where((w) => w.or([
+                w("i.required", "=", true),
+                w.exists(w
+                    .selectFrom("extension_org_configs as c")
+                    .select(sql `1`.as("one"))
+                    .whereRef("c.org_id", "=", "m.org_id")
+                    .whereRef("c.plugin", "=", "i.name")
+                    .where("c.enabled", "=", true)),
+            ])))
+                .as("member"),
+        ])
+            .executeTakeFirst();
+        if (row === undefined)
+            return null;
+        const kill = parseClientExtensions(row.kill ?? undefined, this.log);
+        if (stopped(kill, plugin) || !supported(row))
+            return null;
+        const components = componentsOf(row.section);
+        const allowed = row.member === true || (superAdmin && components.some((c) => c.slot.id === "platform.page"));
+        if (!allowed)
+            return null;
+        return {
+            plugin: row.plugin,
+            build: row.build,
+            keys: new Set([...(row.entry !== null ? [row.entry] : []), ...row.styles, ...row.assets]),
+            components: new Set(components.map((c) => c.id)),
+            objectPrefix: row.object_prefix,
+        };
+    }
+    /**
+     * The org's shell read: every extension enabled in the org (`enabled.ts`) with a served client
+     * build ({@link listed}: one per extension), in name order, minus the stopped ones; `components`
+     * are those whose slot the role may use (`canUseSlot`: its `minRole`, never `platform.page`). An
+     * extension with no component left is still listed (its stylesheets and entry still load).
+     */
+    async orgSet(orgId, role) {
+        const db = this.db.db;
+        const [kill, rows] = await Promise.all([
+            readClientExtensions(db, this.log),
+            this.listed(db).where("i.name", "in", enabledExtensionsQuery(db, orgId)).execute(),
+        ]);
+        if (!kill.enabled)
+            return { enabled: false, apiVersion: CLIENT_API_VERSION, items: [] };
+        const items = rows
+            .filter((r) => !stopped(kill, r.plugin) && supported(r))
+            .map((r) => ({
+            plugin: r.plugin,
+            build: r.build,
+            entry: r.entry === null ? null : fileRef(r, r.entry),
+            styles: r.styles.map((k) => fileRef(r, k)),
+            components: componentsOf(r.section)
+                .filter((c) => canUseSlot(c.slot, role))
+                .map((c) => ({ id: c.id, slot: c.slot.id })),
+        }));
+        return { enabled: true, apiVersion: CLIENT_API_VERSION, items };
+    }
+    /**
+     * The admin console's set (spec §9.6): the extensions with a served build (whatever their org
+     * enablement) with at least one `platform.page` component and an entry, only those components
+     * and no stylesheets (the admin console runs no org client code); with `plugin`, at most that one.
+     */
+    async platformSet(plugin) {
+        const db = this.db.db;
+        let q = this.listed(db);
+        if (plugin !== undefined)
+            q = q.where("i.name", "=", plugin);
+        const [kill, rows] = await Promise.all([readClientExtensions(db, this.log), q.execute()]);
+        if (!kill.enabled)
+            return { enabled: false, apiVersion: CLIENT_API_VERSION, items: [] };
+        const items = rows.flatMap((r) => {
+            if (stopped(kill, r.plugin) || !supported(r) || r.entry === null)
+                return [];
+            const components = componentsOf(r.section)
+                .filter((c) => c.slot.id === "platform.page")
+                .map((c) => ({ id: c.id, slot: c.slot.id }));
+            if (components.length === 0)
+                return [];
+            return [
+                { plugin: r.plugin, build: r.build, entry: fileRef(r, r.entry), styles: [], components },
+            ];
+        });
+        return { enabled: true, apiVersion: CLIENT_API_VERSION, items };
+    }
+};
+ClientAccess = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(KernelConfigService)),
+    __param(2, Inject(StorageService)),
+    __param(3, Inject(KERNEL_LOGGER))
+], ClientAccess);
+export { ClientAccess };

package/dist/client/client-builds.service.d.ts

@@ -0,0 +1,109 @@
+import type { PluginClientSection } from "@capybara-hq/plugin-sdk";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { type PrefixedStorage, StorageService } from "../storage/storage.service.js";
+/** A stored client build (`extension_client_builds`); paths are manifest keys. */
+export interface ClientBuildRow {
+    /** The package sha256: the build id. */
+    packageSha256: string;
+    plugin: string;
+    entry: string | null;
+    styles: string[];
+    assets: string[];
+    /** Manifest key -> `sha384-<base64>`, recomputed from the bytes when stored. */
+    integrity: Record<string, string>;
+    /** Manifest key -> bytes. */
+    sizes: Record<string, number>;
+    apiVersion: number;
+    /** Relative to `deployment/`: `platform/client/<plugin>/<sha256>/`. */
+    objectPrefix: string;
+}
+/**
+ * A client build as the review pages show it (client extensions spec §5.4): every file by its
+ * manifest key with its size, in load order (entry, styles, assets), the total and the client API
+ * version.
+ */
+export interface ClientBuildSummary {
+    files: {
+        path: string;
+        bytes: number;
+    }[];
+    totalBytes: number;
+    apiVersion: number;
+}
+/** The summary of a stored build row. */
+export declare function summarizeClientBuild(r: Pick<ClientBuildRow, "entry" | "styles" | "assets" | "sizes" | "apiVersion">): ClientBuildSummary;
+/**
+ * The client builds of extension packages (client extensions spec §9.1): when a package with an
+ * `extension.client` section is stored, its client files are checked (`client-files.ts`) and
+ * written to object storage under `deployment/platform/client/<plugin>/<sha256>/<path inside
+ * dist/client/>`, and one `extension_client_builds` row records the keys, sizes and integrity.
+ * Content-addressed by the package sha256, so storing the same package again is harmless.
+ *
+ * The objects are written before the row's transaction (object storage is never called inside
+ * one). A transaction that rolls back after the objects were written leaves them unreferenced
+ * under the prefix: nothing sweeps them, and the next store of the same package rewrites them
+ * (content-addressed, so they are never wrong, only orphaned). The row references
+ * `extension_packages` (ON DELETE CASCADE); whoever deletes the package row calls
+ * {@link deleteFiles} in `afterCommit`.
+ *
+ * Storing a package's build and deleting its files run under one lock per package sha256
+ * ({@link locked}, `LockService`, never inside a transaction), and the delete first re-checks that
+ * no package row exists: a concurrent store of the same bytes either sees the row gone and writes
+ * everything again, or has recorded the row and the delete leaves its files alone, so a build row
+ * never stays without its files.
+ */
+export declare class ClientBuilds {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly locks;
+    /** Where client files go: the kernel's object storage, or the CLI's own ({@link useCliStorage}). */
+    private storage;
+    constructor(db: KernelDb, txHost: TransactionHost, storage: StorageService, locks: LockService);
+    /**
+     * CLI only (like `PluginImport.useCliStorage`): client files go to the object store the CLI set
+     * up itself (`loadCliObjectStore`); without one, a package with client code is refused with its
+     * `storage.unavailable`. Called once, right after the command's context is created.
+     */
+    useCliStorage(storage: PrefixedStorage): void;
+    /** `storage.unavailable` (503) when client files cannot be stored here. */
+    assertAvailable(): void;
+    /**
+     * Runs `fn` under the lock of package `sha256`'s client build (see the class header): the store
+     * of a package with client code and the delete of its files. Never inside a transaction.
+     */
+    locked<T>(sha256: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Checks the client files of package `sha256` (`files` keyed by their path in the package, see
+     * `checkClientFiles`) and writes them to object storage; returns the row to insert. No
+     * transaction may be open. `storage.unavailable` without an object store; `client.invalid` /
+     * `client.integrity_mismatch` for files that do not match the section.
+     */
+    writeFiles(sha256: string, plugin: string, files: ReadonlyMap<string, Uint8Array>, section: PluginClientSection): Promise<ClientBuildRow>;
+    /**
+     * Inserts the build row (joins the caller's transaction, which also inserts the package row);
+     * does nothing when the row exists.
+     */
+    insert(row: ClientBuildRow): Promise<void>;
+    /**
+     * {@link writeFiles} then {@link insert}, for a package whose `extension_packages` row exists
+     * (storing it again restores missing objects and a missing row). Idempotent by sha256.
+     */
+    extract(sha256: string, plugin: string, files: ReadonlyMap<string, Uint8Array>, section: PluginClientSection): Promise<void>;
+    /** The client build of package `sha256`, or null when it has none. */
+    byPackage(sha256: string): Promise<ClientBuildRow | null>;
+    /** The summaries of the client builds of packages `shas` (a package without one is left out). */
+    summaries(shas: readonly string[]): Promise<Map<string, ClientBuildSummary>>;
+    /**
+     * The client build summaries of the packages the install records of `plugins` name (the running
+     * version's), by plugin; a plugin without an install record or a client build is left out.
+     */
+    installedSummaries(plugins: readonly string[]): Promise<Map<string, ClientBuildSummary>>;
+    /**
+     * Deletes the objects of package `sha256`'s build (call in `afterCommit`, once its package row is
+     * gone): under {@link locked}, and only while no package row exists (a concurrent store of the
+     * same bytes keeps its files). Returns whether it deleted.
+     */
+    deleteFiles(sha256: string, objectPrefix: string): Promise<boolean>;
+}

package/dist/client/client-builds.service.js

@@ -0,0 +1,229 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import { Transactional } from "../infra/database/transactional.decorator.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { StorageService } from "../storage/storage.service.js";
+import { checkClientFiles, clientBuildPrefix, clientContentType, clientRelPath, } from "./client-files.js";
+/** The summary of a stored build row. */
+export function summarizeClientBuild(r) {
+    const files = [...(r.entry !== null ? [r.entry] : []), ...r.styles, ...r.assets].map((path) => ({
+        path,
+        bytes: r.sizes[path] ?? 0,
+    }));
+    return {
+        files,
+        totalBytes: files.reduce((n, f) => n + f.bytes, 0),
+        apiVersion: r.apiVersion,
+    };
+}
+/**
+ * The client builds of extension packages (client extensions spec §9.1): when a package with an
+ * `extension.client` section is stored, its client files are checked (`client-files.ts`) and
+ * written to object storage under `deployment/platform/client/<plugin>/<sha256>/<path inside
+ * dist/client/>`, and one `extension_client_builds` row records the keys, sizes and integrity.
+ * Content-addressed by the package sha256, so storing the same package again is harmless.
+ *
+ * The objects are written before the row's transaction (object storage is never called inside
+ * one). A transaction that rolls back after the objects were written leaves them unreferenced
+ * under the prefix: nothing sweeps them, and the next store of the same package rewrites them
+ * (content-addressed, so they are never wrong, only orphaned). The row references
+ * `extension_packages` (ON DELETE CASCADE); whoever deletes the package row calls
+ * {@link deleteFiles} in `afterCommit`.
+ *
+ * Storing a package's build and deleting its files run under one lock per package sha256
+ * ({@link locked}, `LockService`, never inside a transaction), and the delete first re-checks that
+ * no package row exists: a concurrent store of the same bytes either sees the row gone and writes
+ * everything again, or has recorded the row and the delete leaves its files alone, so a build row
+ * never stays without its files.
+ */
+let ClientBuilds = class ClientBuilds {
+    db;
+    txHost;
+    locks;
+    /** Where client files go: the kernel's object storage, or the CLI's own ({@link useCliStorage}). */
+    storage;
+    constructor(db, txHost, storage, locks) {
+        this.db = db;
+        this.txHost = txHost;
+        this.locks = locks;
+        this.storage = storage;
+    }
+    /**
+     * CLI only (like `PluginImport.useCliStorage`): client files go to the object store the CLI set
+     * up itself (`loadCliObjectStore`); without one, a package with client code is refused with its
+     * `storage.unavailable`. Called once, right after the command's context is created.
+     */
+    useCliStorage(storage) {
+        this.storage = storage;
+    }
+    /** `storage.unavailable` (503) when client files cannot be stored here. */
+    assertAvailable() {
+        this.storage.assertAvailable();
+    }
+    /**
+     * Runs `fn` under the lock of package `sha256`'s client build (see the class header): the store
+     * of a package with client code and the delete of its files. Never inside a transaction.
+     */
+    async locked(sha256, fn) {
+        return this.locks.run(`client-build:${sha256}`, { ttlMs: 60_000, waitMs: 60_000 }, fn);
+    }
+    /**
+     * Checks the client files of package `sha256` (`files` keyed by their path in the package, see
+     * `checkClientFiles`) and writes them to object storage; returns the row to insert. No
+     * transaction may be open. `storage.unavailable` without an object store; `client.invalid` /
+     * `client.integrity_mismatch` for files that do not match the section.
+     */
+    async writeFiles(sha256, plugin, files, section) {
+        this.storage.assertAvailable();
+        const checked = checkClientFiles(section, files);
+        const objectPrefix = clientBuildPrefix(plugin, sha256);
+        const store = this.storage.deployment();
+        for (const f of checked.files) {
+            await store.put(objectPrefix + clientRelPath(f.key), f.data, {
+                contentType: clientContentType(f.key),
+                size: f.size,
+            });
+        }
+        return {
+            packageSha256: sha256,
+            plugin,
+            entry: section.entry ?? null,
+            styles: section.styles ?? [],
+            assets: section.assets ?? [],
+            integrity: Object.fromEntries(checked.files.map((f) => [f.key, f.integrity])),
+            sizes: Object.fromEntries(checked.files.map((f) => [f.key, f.size])),
+            apiVersion: section.apiVersion,
+            objectPrefix,
+        };
+    }
+    /**
+     * Inserts the build row (joins the caller's transaction, which also inserts the package row);
+     * does nothing when the row exists.
+     */
+    async insert(row) {
+        await this.db
+            .insertInto("extension_client_builds")
+            .values({
+            package_sha256: row.packageSha256,
+            plugin: row.plugin,
+            entry: row.entry,
+            styles: row.styles,
+            assets: row.assets,
+            integrity: JSON.stringify(row.integrity),
+            sizes: JSON.stringify(row.sizes),
+            api_version: row.apiVersion,
+            object_prefix: row.objectPrefix,
+        })
+            .onConflict((oc) => oc.column("package_sha256").doNothing())
+            .execute();
+    }
+    /**
+     * {@link writeFiles} then {@link insert}, for a package whose `extension_packages` row exists
+     * (storing it again restores missing objects and a missing row). Idempotent by sha256.
+     */
+    async extract(sha256, plugin, files, section) {
+        await this.insert(await this.writeFiles(sha256, plugin, files, section));
+    }
+    /** The client build of package `sha256`, or null when it has none. */
+    async byPackage(sha256) {
+        const r = await this.db
+            .selectFrom("extension_client_builds")
+            .selectAll()
+            .where("package_sha256", "=", sha256)
+            .executeTakeFirst();
+        if (!r)
+            return null;
+        return {
+            packageSha256: r.package_sha256,
+            plugin: r.plugin,
+            entry: r.entry,
+            styles: r.styles,
+            assets: r.assets,
+            integrity: r.integrity,
+            sizes: r.sizes,
+            apiVersion: r.api_version,
+            objectPrefix: r.object_prefix,
+        };
+    }
+    /** The summaries of the client builds of packages `shas` (a package without one is left out). */
+    async summaries(shas) {
+        const out = new Map();
+        if (shas.length === 0)
+            return out;
+        const rows = await this.db
+            .selectFrom("extension_client_builds")
+            .select(["package_sha256", "entry", "styles", "assets", "sizes", "api_version"])
+            .where("package_sha256", "in", [...new Set(shas)])
+            .execute();
+        for (const r of rows) {
+            out.set(r.package_sha256, summarizeClientBuild({
+                entry: r.entry,
+                styles: r.styles,
+                assets: r.assets,
+                sizes: r.sizes,
+                apiVersion: r.api_version,
+            }));
+        }
+        return out;
+    }
+    /**
+     * The client build summaries of the packages the install records of `plugins` name (the running
+     * version's), by plugin; a plugin without an install record or a client build is left out.
+     */
+    async installedSummaries(plugins) {
+        const out = new Map();
+        if (plugins.length === 0)
+            return out;
+        const installs = await this.db
+            .selectFrom("extension_installs")
+            .select(["name", "sha256"])
+            .where("name", "in", [...new Set(plugins)])
+            .execute();
+        const builds = await this.summaries(installs.map((i) => i.sha256));
+        for (const i of installs) {
+            const b = builds.get(i.sha256);
+            if (b !== undefined)
+                out.set(i.name, b);
+        }
+        return out;
+    }
+    /**
+     * Deletes the objects of package `sha256`'s build (call in `afterCommit`, once its package row is
+     * gone): under {@link locked}, and only while no package row exists (a concurrent store of the
+     * same bytes keeps its files). Returns whether it deleted.
+     */
+    async deleteFiles(sha256, objectPrefix) {
+        return this.locked(sha256, async () => {
+            const again = await this.db
+                .selectFrom("extension_packages")
+                .select("sha256")
+                .where("sha256", "=", sha256)
+                .executeTakeFirst();
+            if (again !== undefined)
+                return false;
+            await this.storage.deployment().deletePrefix(objectPrefix);
+            return true;
+        });
+    }
+};
+__decorate([
+    Transactional()
+], ClientBuilds.prototype, "insert", null);
+ClientBuilds = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(StorageService)),
+    __param(3, Inject(LockService))
+], ClientBuilds);
+export { ClientBuilds };

package/dist/client/client-delivery.controller.d.ts

@@ -0,0 +1,25 @@
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { type Principal } from "../identity/principal.js";
+import { ClientAccess } from "./client-access.service.js";
+/**
+ * Client file delivery (client extensions spec §9.3): `GET /api/v1/client/<plugin>/<build>/<path>`
+ * serves the entry, a stylesheet or an asset of a client build to a signed-in person allowed to load
+ * it ({@link ClientAccess.file}: one PG query per request, nothing cached); anything else is 404
+ * `client.not_found`. The web's document CSP allows scripts from this prefix only, so the route
+ * never redirects (no trailing-slash or case redirect either): a redirect would leave the path the
+ * policy checked.
+ *
+ * The file is named by the raw request path, never by the decoded wildcard parameter: the path is
+ * matched segment by segment against the manifest key's charset, so `..`, encoded separators and
+ * backslashes name nothing.
+ *
+ * Headers: `Cache-Control: private, max-age=31536000, immutable`, `X-Content-Type-Options: nosniff`,
+ * `Cross-Origin-Resource-Policy: same-origin`, the content type of the file's kind
+ * (`text/javascript`, `text/css; charset=utf-8`, the asset type), and for an SVG asset
+ * `Content-Security-Policy: default-src 'none'; sandbox`.
+ */
+export declare class ClientDeliveryController {
+    private readonly access;
+    constructor(access: ClientAccess);
+    file(principal: Principal, req: FastifyRequest, reply: FastifyReply): Promise<void>;
+}