@capybara-hq/kernel 0.1.0-rc.2 → 0.1.0-rc.20

package/dist/channels/webhook.js

@@ -10,7 +10,8 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable, Optional } from "@nestjs/common";
 import { ApiError, errorBody } from "../errors.js";
 import { ExtensionUnloadedError } from "../extensions/inflight.js";
-import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { KERNEL_LOGGER, REDIS } from "../infra/tokens.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
 /**
@@ -24,6 +25,12 @@ export const WEBHOOK_RUNTIME_CACHE_MS = 5_000;
 export const CHANNEL_WEBHOOK_TIMINGS = Symbol("CHANNEL_WEBHOOK_TIMINGS");
 /** Most connections whose runtime is cached in one process. */
 export const WEBHOOK_RUNTIME_CACHE_MAX = 1_000;
+/** How long a connection's last accepted webhook is remembered (`capybara:webhook-received`). */
+export const WEBHOOK_SEEN_TTL_SECONDS = 7 * 24 * 3600;
+/** When the gateway last accepted a verified webhook for the connection (ISO time, TTL 7 days). */
+export const webhookSeenKey = (connectionId) => `capk:channel-webhook-seen:${connectionId}`;
+/** The minute gate of {@link webhookSeenKey}: the marker is written at most once a minute. */
+const webhookSeenMinuteKey = (connectionId, minute) => `capk:channel-webhook-seen-min:${connectionId}:${minute}`;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /**
  * Headers every webhook response carries; a plugin cannot override them (the body is never meant to
@@ -99,6 +106,10 @@ function raceAbort(p, signal) {
  *   for it (`extensionHost.drainSeconds`) before `dispose`; past that the call is aborted → 503
  *   `channel.webhook_retry`.
  * Every response carries {@link WEBHOOK_SECURITY_HEADERS}.
+ * - An accepted `events` result (every event handed to `onEvent`) sets the marker
+ *   {@link webhookSeenKey} (the setup check `capybara:webhook-received`), at most once a minute per
+ *   connection (`LockService.lease`, `SET NX` with a 60 s TTL, on a minute key), in Redis with a TTL, never in PG; a Redis error
+ *   never fails the request.
  *
  * The decrypted runtime (plugin implementation + config) is cached per connection for a few seconds
  * (bounded, process local), so unauthenticated requests stay cheap before the signature check. It is
@@ -110,6 +121,8 @@ let ChannelWebhooks = class ChannelWebhooks {
     connections;
     inbound;
     log;
+    locks;
+    redis;
     runtimes = new Map();
     /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
     generation = 0;
@@ -117,10 +130,14 @@ let ChannelWebhooks = class ChannelWebhooks {
     handleTimeoutMs;
     /** How long a connection's runtime is reused; 0 disables the cache. */
     runtimeCacheMs;
-    constructor(connections, inbound, log, timings = {}) {
+    constructor(connections, inbound, log, 
+    /** The minute gate of the seen marker (`SET NX` with a TTL). */
+    locks, redis, timings = {}) {
         this.connections = connections;
         this.inbound = inbound;
         this.log = log;
+        this.locks = locks;
+        this.redis = redis;
         this.handleTimeoutMs = timings.handleTimeoutMs ?? WEBHOOK_HANDLE_TIMEOUT_MS;
         this.runtimeCacheMs = timings.runtimeCacheMs ?? WEBHOOK_RUNTIME_CACHE_MS;
     }
@@ -136,6 +153,21 @@ let ChannelWebhooks = class ChannelWebhooks {
     async handle(connectionId, request, signal) {
         return secure(await this.respond(connectionId, request, signal));
     }
+    /**
+     * Records that a verified webhook arrived for the connection: the minute gate first (`NX`), then
+     * the marker, both with a TTL. Failures are logged and swallowed (the platform got its ack).
+     */
+    async markSeen(connectionId) {
+        try {
+            const minute = Math.floor(Date.now() / 60_000);
+            if (!(await this.locks.lease(webhookSeenMinuteKey(connectionId, minute), "1", 60_000)))
+                return;
+            await this.redis.set(webhookSeenKey(connectionId), new Date().toISOString(), "EX", WEBHOOK_SEEN_TTL_SECONDS);
+        }
+        catch (err) {
+            this.log.warn("cannot record the channel webhook marker", { connectionId, err });
+        }
+    }
     async runtime(connectionId, deadline) {
         const ttl = this.runtimeCacheMs;
         const now = Date.now();
@@ -255,6 +287,7 @@ let ChannelWebhooks = class ChannelWebhooks {
                         return retryLater();
                     }
                 }
+                await this.markSeen(connectionId);
                 return sanitize(result.ack);
             }
         }
@@ -267,8 +300,10 @@ ChannelWebhooks = __decorate([
     __param(0, Inject(ChannelConnections)),
     __param(1, Inject(ChannelInbound)),
     __param(2, Inject(KERNEL_LOGGER)),
-    __param(3, Optional()),
-    __param(3, Inject(CHANNEL_WEBHOOK_TIMINGS))
+    __param(3, Inject(LockService)),
+    __param(4, Inject(REDIS)),
+    __param(5, Optional()),
+    __param(5, Inject(CHANNEL_WEBHOOK_TIMINGS))
 ], ChannelWebhooks);
 export { ChannelWebhooks };
 /** Generic codes for the statuses a plugin may reject with (same as the HTTP error filter's). */

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

@@ -0,0 +1,102 @@
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import type { OrgRole } from "../orgs/roles.js";
+import { StorageService } from "../storage/storage.service.js";
+import type { ClientExtensionsResponse } from "./client.schemas.js";
+/** A client build the caller may fetch files of (the row the delivery route serves from). */
+export interface FetchableBuild {
+    plugin: string;
+    build: string;
+    /** Every manifest key of the build: the entry, the styles and the assets. */
+    keys: ReadonlySet<string>;
+    /** The ids of the build's `component` contributions (whatever their slot's role gate). */
+    components: ReadonlySet<string>;
+    /** Relative to `deployment/`: `platform/client/<plugin>/<sha256>/`. */
+    objectPrefix: string;
+}
+/** `/api/v1/client/<plugin>/<build>/<path inside dist/client/>` of a manifest key. */
+export declare const clientFileUrl: (plugin: string, build: string, key: string) => string;
+/** A served client file: its bytes and the headers that depend on it. */
+export interface ClientFile {
+    contentType: string;
+    data: Uint8Array;
+}
+/**
+ * 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 declare function parseClientPath(path: string): {
+    plugin: string;
+    build: string;
+    key: string;
+} | null;
+/**
+ * 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.
+ */
+export declare class ClientAccess {
+    private readonly db;
+    private readonly config;
+    private readonly storage;
+    private readonly log;
+    constructor(db: KernelDb, config: Pick<KernelConfigService, "get">, storage: StorageService, log: Pick<KernelLogger, "warn">);
+    /**
+     * 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.
+     */
+    file(accountId: string, superAdmin: boolean, path: string): Promise<ClientFile>;
+    /**
+     * 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.
+     */
+    private served;
+    /**
+     * 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).
+     */
+    private listed;
+    /**
+     * 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.
+     */
+    fetchable(accountId: string, superAdmin: boolean, plugin: string, build: string): Promise<FetchableBuild | null>;
+    /**
+     * 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).
+     * `signInId` gives each item the viewer's sign-in id for that plugin (`ClientSignIn`).
+     */
+    orgSet(orgId: string, role: OrgRole, signInId: (plugin: string) => string): Promise<ClientExtensionsResponse>;
+    /**
+     * 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.
+     */
+    platformSet(signInId: (plugin: string) => string, plugin?: string): Promise<ClientExtensionsResponse>;
+}

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

@@ -0,0 +1,303 @@
+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).
+     * `signInId` gives each item the viewer's sign-in id for that plugin (`ClientSignIn`).
+     */
+    async orgSet(orgId, role, signInId) {
+        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 })),
+            signInId: signInId(r.plugin),
+        }));
+        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(signInId, 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,
+                    signInId: signInId(r.plugin),
+                },
+            ];
+        });
+        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>;
+}