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

package/dist/client/client-delivery.controller.js

@@ -0,0 +1,66 @@
+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 { Controller, Get, Inject, Req, Res } from "@nestjs/common";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { ClientAccess } from "./client-access.service.js";
+/** The route prefix, as the raw request path starts with it. */
+const PREFIX = "/api/v1/client/";
+/** A build's files never change (the package sha256 is in the URL); only its viewers may cache them. */
+const IMMUTABLE_PRIVATE = "private, max-age=31536000, immutable";
+/**
+ * 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`.
+ */
+let ClientDeliveryController = class ClientDeliveryController {
+    access;
+    constructor(access) {
+        this.access = access;
+    }
+    async file(principal, req, reply) {
+        const p = requireUser(principal);
+        const raw = req.raw.url ?? "";
+        const q = raw.indexOf("?");
+        const path = q < 0 ? raw : raw.slice(0, q);
+        const f = await this.access.file(p.account.id, p.account.isSuperAdmin, path.startsWith(PREFIX) ? path.slice(PREFIX.length) : "");
+        reply
+            .header("content-type", f.contentType)
+            .header("cache-control", IMMUTABLE_PRIVATE)
+            .header("x-content-type-options", "nosniff")
+            .header("cross-origin-resource-policy", "same-origin");
+        if (f.contentType === "image/svg+xml") {
+            reply.header("content-security-policy", "default-src 'none'; sandbox");
+        }
+        await reply.send(Buffer.from(f.data.buffer, f.data.byteOffset, f.data.byteLength));
+    }
+};
+__decorate([
+    Get(":plugin/:build/*"),
+    __param(0, CurrentPrincipal()),
+    __param(1, Req()),
+    __param(2, Res())
+], ClientDeliveryController.prototype, "file", null);
+ClientDeliveryController = __decorate([
+    Controller("api/v1/client"),
+    __param(0, Inject(ClientAccess))
+], ClientDeliveryController);
+export { ClientDeliveryController };

package/dist/client/client-files.d.ts

@@ -0,0 +1,48 @@
+import { type PluginClientSection } from "@capybara-hq/plugin-sdk";
+/**
+ * The client files of a plugin package (client extensions spec §4.1, §9.1), checked against its
+ * `extension.client` section: the import review and the store both run {@link checkClientFiles} on
+ * the bytes they hold, so nothing reaches object storage, and no integrity reaches a browser, that
+ * was not recomputed from the bytes.
+ *
+ * Files are known only by their manifest key (`./dist/client/<path>`): the object key and, later,
+ * the delivery lookup use the exact key, never a decoded or joined path. Every segment of a key is
+ * made of `[A-Za-z0-9._-]` only (no `%`, space, `?`, `#`, backslash or non-ASCII character, which a
+ * browser would encode or split), is not `.` or `..`, and the file name has a stem: refused here
+ * even when the SDK validator lets it through.
+ */
+/** The directory of client files inside the package (relative to the package root). */
+export declare const CLIENT_DIR = "dist/client/";
+/** The object prefix of a build, relative to `deployment/`: `platform/client/<plugin>/<sha256>/`. */
+export declare const clientBuildPrefix: (plugin: string, sha256: string) => string;
+/** The path of a manifest key inside `dist/client/` (`./dist/client/styles/a.css` -> `styles/a.css`). */
+export declare const clientRelPath: (key: string) => string;
+/** The content type a client file is stored and served with (by its manifest key). */
+export declare function clientContentType(key: string): string;
+/** One checked client file. */
+export interface CheckedClientFile {
+    /** The manifest key (`./dist/client/...`). */
+    key: string;
+    data: Uint8Array;
+    size: number;
+    /** `sha384-<base64>`, equal to the section's value. */
+    integrity: string;
+}
+/** The checked client files of a section, in section order (entry, styles, assets). */
+export interface CheckedClient {
+    files: CheckedClientFile[];
+    total: number;
+}
+/**
+ * Checks the client files of a package against its section and returns them. `files` holds the
+ * package's files keyed by their path relative to the package root (`dist/client/client.mjs`);
+ * files outside `dist/client/` are ignored. Refuses the whole package with:
+ * - `client.invalid` (details `[{ file, reason }]`): the section fails `validateClientSection`
+ *   (file `plugin.json`), a key cannot be looked up exactly, a listed file is missing, a file
+ *   under `dist/client/` is not listed, a size limit is exceeded, or a stylesheet fails the CSS
+ *   check (`clientCssProblem` from `@capybara-hq/plugin-sdk`);
+ * - `client.integrity_mismatch` (details `[{ file }]`): a file's sha384 is not the section's;
+ * - `client.api_unsupported` (details `[{ apiVersion, supported }]`): the section's `apiVersion`
+ *   is newer than the kernel's `CLIENT_API_VERSION` (the host could not run it).
+ */
+export declare function checkClientFiles(section: PluginClientSection, files: ReadonlyMap<string, Uint8Array>): CheckedClient;

package/dist/client/client-files.js

@@ -0,0 +1,136 @@
+import { createHash } from "node:crypto";
+import { CLIENT_API_VERSION, CLIENT_ASSET_TYPES, CLIENT_ENTRY_PATH, CLIENT_LIMITS, clientCssProblem, validateClientSection, } from "@capybara-hq/plugin-sdk";
+import { ApiError } from "../errors.js";
+/**
+ * The client files of a plugin package (client extensions spec §4.1, §9.1), checked against its
+ * `extension.client` section: the import review and the store both run {@link checkClientFiles} on
+ * the bytes they hold, so nothing reaches object storage, and no integrity reaches a browser, that
+ * was not recomputed from the bytes.
+ *
+ * Files are known only by their manifest key (`./dist/client/<path>`): the object key and, later,
+ * the delivery lookup use the exact key, never a decoded or joined path. Every segment of a key is
+ * made of `[A-Za-z0-9._-]` only (no `%`, space, `?`, `#`, backslash or non-ASCII character, which a
+ * browser would encode or split), is not `.` or `..`, and the file name has a stem: refused here
+ * even when the SDK validator lets it through.
+ */
+/** The directory of client files inside the package (relative to the package root). */
+export const CLIENT_DIR = "dist/client/";
+const KEY_PREFIX = `./${CLIENT_DIR}`;
+/** The object prefix of a build, relative to `deployment/`: `platform/client/<plugin>/<sha256>/`. */
+export const clientBuildPrefix = (plugin, sha256) => `platform/client/${plugin}/${sha256}/`;
+/** The path of a manifest key inside `dist/client/` (`./dist/client/styles/a.css` -> `styles/a.css`). */
+export const clientRelPath = (key) => key.slice(KEY_PREFIX.length);
+/** The content type a client file is stored and served with (by its manifest key). */
+export function clientContentType(key) {
+    if (key === CLIENT_ENTRY_PATH)
+        return "text/javascript";
+    if (key.endsWith(".css"))
+        return "text/css";
+    const dot = key.lastIndexOf(".");
+    return CLIENT_ASSET_TYPES[key.slice(dot).toLowerCase()] ?? "application/octet-stream";
+}
+const invalid = (file, reason) => new ApiError("client.invalid", `The plugin's client file ${file} is invalid: ${reason}`, [
+    { file, reason },
+]);
+/** One segment of a client file key: plain characters only (no decoding is ever needed). */
+const SEGMENT_RE = /^[A-Za-z0-9._-]+$/;
+/** Why a manifest key cannot be stored and looked up by its exact spelling, or undefined. */
+function keyProblem(key) {
+    if (!key.startsWith(KEY_PREFIX))
+        return `it must be under ${KEY_PREFIX}`;
+    const segs = clientRelPath(key).split("/");
+    if (segs.some((s) => s === "" || s === "." || s === "..")) {
+        return "the path has an empty, . or .. segment";
+    }
+    if (!segs.every((s) => SEGMENT_RE.test(s))) {
+        return "the path may use only letters, digits, . _ - and / (no %, spaces, ? or #)";
+    }
+    const name = segs[segs.length - 1];
+    if (name.lastIndexOf(".") <= 0)
+        return "the file name has an empty stem or no extension";
+    return undefined;
+}
+const sha384 = (data) => `sha384-${createHash("sha384").update(data).digest("base64")}`;
+const utf8 = (data) => {
+    try {
+        return new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Checks the client files of a package against its section and returns them. `files` holds the
+ * package's files keyed by their path relative to the package root (`dist/client/client.mjs`);
+ * files outside `dist/client/` are ignored. Refuses the whole package with:
+ * - `client.invalid` (details `[{ file, reason }]`): the section fails `validateClientSection`
+ *   (file `plugin.json`), a key cannot be looked up exactly, a listed file is missing, a file
+ *   under `dist/client/` is not listed, a size limit is exceeded, or a stylesheet fails the CSS
+ *   check (`clientCssProblem` from `@capybara-hq/plugin-sdk`);
+ * - `client.integrity_mismatch` (details `[{ file }]`): a file's sha384 is not the section's;
+ * - `client.api_unsupported` (details `[{ apiVersion, supported }]`): the section's `apiVersion`
+ *   is newer than the kernel's `CLIENT_API_VERSION` (the host could not run it).
+ */
+export function checkClientFiles(section, files) {
+    const sectionIssues = validateClientSection(section);
+    if (sectionIssues.length > 0) {
+        throw invalid("plugin.json", sectionIssues[0]);
+    }
+    if (section.apiVersion > CLIENT_API_VERSION) {
+        throw new ApiError("client.api_unsupported", `The plugin's client code was built for client API ${section.apiVersion}; this deployment ` +
+            `supports ${CLIENT_API_VERSION}. Upgrade Capybara, or build the plugin against ` +
+            `@capybara-hq/plugin-client for client API ${CLIENT_API_VERSION}.`, [{ apiVersion: section.apiVersion, supported: CLIENT_API_VERSION }]);
+    }
+    const styles = section.styles ?? [];
+    const keys = [
+        ...(section.entry !== undefined ? [section.entry] : []),
+        ...styles,
+        ...(section.assets ?? []),
+    ];
+    for (const key of keys) {
+        const problem = keyProblem(key);
+        if (problem !== undefined)
+            throw invalid(key, problem);
+    }
+    const listed = new Set(keys);
+    // the URLs a stylesheet may use: ../assets/<path> of a listed asset
+    const assetPaths = new Set((section.assets ?? []).map((k) => k.slice(`${KEY_PREFIX}assets/`.length)));
+    for (const path of [...files.keys()].sort()) {
+        if (path.startsWith(CLIENT_DIR) && !listed.has(`./${path}`)) {
+            throw invalid(`./${path}`, "the file is not listed in the plugin's client section");
+        }
+    }
+    const out = [];
+    let total = 0;
+    for (const key of keys) {
+        const data = files.get(key.slice(2));
+        if (data === undefined)
+            throw invalid(key, "the file is missing from the package");
+        const size = data.byteLength;
+        const limit = key === section.entry
+            ? CLIENT_LIMITS.entryBytes
+            : styles.includes(key)
+                ? CLIENT_LIMITS.styleBytes
+                : CLIENT_LIMITS.assetBytes;
+        if (size > limit)
+            throw invalid(key, `the file is ${size} bytes; the limit is ${limit}`);
+        total += size;
+        const integrity = sha384(data);
+        if (integrity !== section.integrity[key]) {
+            throw new ApiError("client.integrity_mismatch", `The plugin's client file ${key} does not match the integrity recorded in its plugin.json`, [{ file: key }]);
+        }
+        if (styles.includes(key)) {
+            const css = utf8(data);
+            if (css === undefined)
+                throw invalid(key, "the stylesheet is not valid UTF-8 text");
+            const problem = clientCssProblem(css, assetPaths);
+            if (problem !== undefined)
+                throw invalid(key, problem);
+        }
+        out.push({ key, data, size, integrity });
+    }
+    if (total > CLIENT_LIMITS.totalBytes) {
+        throw invalid("plugin.json", `the client files are ${total} bytes in total; the limit is ${CLIENT_LIMITS.totalBytes}`);
+    }
+    return { files: out, total };
+}

package/dist/client/client-reports.cron.d.ts

@@ -0,0 +1,13 @@
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { ClientReports } from "./client-reports.service.js";
+/** The daily prune of client reports (`@LockedCron`). */
+export declare const CLIENT_REPORTS_PRUNE_JOB = "client-reports-prune";
+/** Deletes client reports not seen for 30 days (spec §10.4), once per tick across replicas; the worker role's. */
+export declare class ClientReportsCron {
+    private readonly reports;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(reports: ClientReports, lockService: LockService, log: KernelLogger);
+    prune(): Promise<void>;
+}

package/dist/client/client-reports.cron.js

@@ -0,0 +1,42 @@
+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 { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { ClientReports } from "./client-reports.service.js";
+/** The daily prune of client reports (`@LockedCron`). */
+export const CLIENT_REPORTS_PRUNE_JOB = "client-reports-prune";
+/** Deletes client reports not seen for 30 days (spec §10.4), once per tick across replicas; the worker role's. */
+let ClientReportsCron = class ClientReportsCron {
+    reports;
+    lockService;
+    log;
+    constructor(reports, lockService, log) {
+        this.reports = reports;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async prune() {
+        const n = await this.reports.prune();
+        if (n > 0)
+            this.log.info("client reports pruned", { count: n });
+    }
+};
+__decorate([
+    LockedCron("50 3 * * *", { name: CLIENT_REPORTS_PRUNE_JOB })
+], ClientReportsCron.prototype, "prune", null);
+ClientReportsCron = __decorate([
+    Injectable(),
+    __param(0, Inject(ClientReports)),
+    __param(1, Inject(LockService)),
+    __param(2, Inject(KERNEL_LOGGER))
+], ClientReportsCron);
+export { ClientReportsCron };

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

@@ -0,0 +1,30 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { TransactionHost } from "../infra/database/transaction-host.js";
+import type { ReportBodyInput } from "./client.schemas.js";
+import { ClientAccess } from "./client-access.service.js";
+/** Reports older than this (by `last_at`) are deleted by the daily prune (spec §10.4). */
+export declare const REPORT_RETENTION_DAYS = 30;
+/**
+ * Crash and load reports of client code (client extensions spec §10.4): one row per (plugin,
+ * build, org, contribution, kind), upserted so a crash loop is one row with a count. A report is
+ * accepted only for a build the reporter could fetch ({@link ClientAccess.fetchable}), in an org
+ * an extension enabled there, and a `contribution` that is null or a component of that build's
+ * manifest, so nobody writes rows about plugins or orgs they cannot see and the key bounds the
+ * rows (a made-up contribution cannot add one); anything else is the same 404
+ * `client.not_found` the delivery route answers.
+ */
+export declare class ClientReports {
+    private readonly db;
+    readonly txHost: TransactionHost;
+    private readonly access;
+    constructor(db: KernelDb, txHost: TransactionHost, access: ClientAccess);
+    /** A report from a workspace page of org `orgId`. */
+    recordForOrg(accountId: string, orgId: string, body: ReportBodyInput): Promise<void>;
+    /** A report from the admin console (no org; super admins only, the caller checks that). */
+    recordForAdmin(accountId: string, body: ReportBodyInput): Promise<void>;
+    /** The build must be fetchable and the contribution null or one of its components. */
+    private check;
+    private upsert;
+    /** Deletes the reports last seen more than {@link REPORT_RETENTION_DAYS} days ago; the count. */
+    prune(): Promise<number>;
+}

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

@@ -0,0 +1,102 @@
+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 { sql } from "kysely";
+import { ApiError } from "../errors.js";
+import { enabledExtensionsQuery } from "../extensions/enabled.js";
+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 { ClientAccess } from "./client-access.service.js";
+/** Reports older than this (by `last_at`) are deleted by the daily prune (spec §10.4). */
+export const REPORT_RETENTION_DAYS = 30;
+/**
+ * Crash and load reports of client code (client extensions spec §10.4): one row per (plugin,
+ * build, org, contribution, kind), upserted so a crash loop is one row with a count. A report is
+ * accepted only for a build the reporter could fetch ({@link ClientAccess.fetchable}), in an org
+ * an extension enabled there, and a `contribution` that is null or a component of that build's
+ * manifest, so nobody writes rows about plugins or orgs they cannot see and the key bounds the
+ * rows (a made-up contribution cannot add one); anything else is the same 404
+ * `client.not_found` the delivery route answers.
+ */
+let ClientReports = class ClientReports {
+    db;
+    txHost;
+    access;
+    constructor(db, txHost, access) {
+        this.db = db;
+        this.txHost = txHost;
+        this.access = access;
+    }
+    /** A report from a workspace page of org `orgId`. */
+    async recordForOrg(accountId, orgId, body) {
+        const enabled = await this.db.db
+            .selectFrom(enabledExtensionsQuery(this.db.db, orgId).as("en"))
+            .select("en.plugin")
+            .where("en.plugin", "=", body.plugin)
+            .executeTakeFirst();
+        if (enabled === undefined)
+            throw notFound();
+        await this.check(accountId, false, body);
+        await this.upsert(orgId, body);
+    }
+    /** A report from the admin console (no org; super admins only, the caller checks that). */
+    async recordForAdmin(accountId, body) {
+        await this.check(accountId, true, body);
+        await this.upsert(null, body);
+    }
+    /** The build must be fetchable and the contribution null or one of its components. */
+    async check(accountId, superAdmin, b) {
+        const build = await this.access.fetchable(accountId, superAdmin, b.plugin, b.build);
+        if (build === null)
+            throw notFound();
+        if (b.contribution !== null && !build.components.has(b.contribution))
+            throw notFound();
+    }
+    async upsert(orgId, b) {
+        await this.db.db
+            .insertInto("extension_client_reports")
+            .values({
+            plugin: b.plugin,
+            build: b.build,
+            org_id: orgId,
+            contribution: b.contribution,
+            kind: b.kind,
+            last_message: b.message,
+        })
+            .onConflict((oc) => oc
+            .expression(sql `plugin, build, (coalesce(org_id, '')), (coalesce(contribution, '')), kind`)
+            .doUpdateSet({
+            count: sql `extension_client_reports.count + 1`,
+            last_at: sql `now()`,
+            last_message: b.message,
+        }))
+            .execute();
+    }
+    /** Deletes the reports last seen more than {@link REPORT_RETENTION_DAYS} days ago; the count. */
+    async prune() {
+        const r = await this.db.db
+            .deleteFrom("extension_client_reports")
+            .where("last_at", "<", sql `now() - make_interval(days => ${REPORT_RETENTION_DAYS})`)
+            .executeTakeFirst();
+        return Number(r.numDeletedRows);
+    }
+};
+__decorate([
+    Transactional()
+], ClientReports.prototype, "upsert", null);
+ClientReports = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(TransactionHost)),
+    __param(2, Inject(ClientAccess))
+], ClientReports);
+export { ClientReports };
+const notFound = () => new ApiError("client.not_found", "Client file not found");

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

@@ -0,0 +1,45 @@
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { AdminClientQuery, type ClientExtensionsResponse, ReportBody } from "./client.schemas.js";
+import { ClientAccess } from "./client-access.service.js";
+import { ClientReports } from "./client-reports.service.js";
+/**
+ * The workspace shell read of client extensions (client extensions spec §9.2), `ui.use` (guest and
+ * up; a person, not a service token): `GET /api/v1/orgs/:orgId/ui/client` →
+ * {@link ClientExtensionsResponse}: the extensions enabled in the org that run with an approved
+ * client build, their file URLs and integrity, and the components the caller's role may use;
+ * `enabled: false` with no items under the kill switch. `no-store`: the set changes with an org
+ * switch, an upgrade or the kill switch.
+ */
+export declare class OrgClientController {
+    private readonly access;
+    private readonly reports;
+    constructor(access: ClientAccess, reports: ClientReports);
+    list(principal: Principal, org: OrgContext): Promise<ClientExtensionsResponse>;
+    /**
+     * `POST /api/v1/orgs/:orgId/ui/client/reports` (spec §10.4), `ui.use`, a person, 20 per minute
+     * per account (`client-reports`): a crash or load report of client code → 204. 404
+     * `client.not_found` for an extension not on in the org or a build the caller cannot fetch; 400
+     * for a message over 500 characters.
+     */
+    report(principal: Principal, org: OrgContext, body: z.infer<typeof ReportBody>): Promise<void>;
+}
+/**
+ * The admin console's client set (spec §9.6), super admins only: `GET /api/v1/admin/ui/client
+ * ?plugin=` → {@link ClientExtensionsResponse} with only `platform.page` components and no
+ * stylesheets (the admin console runs no org client code); with `plugin`, at most that one (the
+ * page `/admin/p/<plugin>/<id>` reads its own). `no-store`.
+ */
+export declare class AdminClientController {
+    private readonly access;
+    private readonly reports;
+    constructor(access: ClientAccess, reports: ClientReports);
+    list(principal: Principal, q: z.infer<typeof AdminClientQuery>): Promise<ClientExtensionsResponse>;
+    /**
+     * `POST /api/v1/admin/ui/client/reports` (spec §10.4), super admins, 20 per minute per account:
+     * a report from an admin page (stored with no org) → 204; 404 `client.not_found` for a build
+     * that has no `platform.page` component or is not served.
+     */
+    report(principal: Principal, body: z.infer<typeof ReportBody>): Promise<void>;
+}

package/dist/client/client.controller.js

@@ -0,0 +1,121 @@
+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 { Controller, Get, Header, HttpCode, Inject, Post } from "@nestjs/common";
+import { CurrentPrincipal, requireUser, SuperAdmin, } from "../identity/principal.js";
+import { Throttled } from "../infra/throttler/throttler.guard.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { AdminClientQuery, ReportBody } from "./client.schemas.js";
+import { ClientAccess } from "./client-access.service.js";
+import { ClientReports } from "./client-reports.service.js";
+class AdminClientQueryDto extends createZodDto(AdminClientQuery, "AdminClientQuery") {
+}
+class ReportBodyDto extends createZodDto(ReportBody, "ClientReportBody") {
+}
+/**
+ * The workspace shell read of client extensions (client extensions spec §9.2), `ui.use` (guest and
+ * up; a person, not a service token): `GET /api/v1/orgs/:orgId/ui/client` →
+ * {@link ClientExtensionsResponse}: the extensions enabled in the org that run with an approved
+ * client build, their file URLs and integrity, and the components the caller's role may use;
+ * `enabled: false` with no items under the kill switch. `no-store`: the set changes with an org
+ * switch, an upgrade or the kill switch.
+ */
+let OrgClientController = class OrgClientController {
+    access;
+    reports;
+    constructor(access, reports) {
+        this.access = access;
+        this.reports = reports;
+    }
+    async list(principal, org) {
+        requireUser(principal);
+        return this.access.orgSet(org.orgId, org.role);
+    }
+    /**
+     * `POST /api/v1/orgs/:orgId/ui/client/reports` (spec §10.4), `ui.use`, a person, 20 per minute
+     * per account (`client-reports`): a crash or load report of client code → 204. 404
+     * `client.not_found` for an extension not on in the org or a build the caller cannot fetch; 400
+     * for a message over 500 characters.
+     */
+    async report(principal, org, body) {
+        const user = requireUser(principal);
+        await this.reports.recordForOrg(user.account.id, org.orgId, body);
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("ui.use"),
+    Header("cache-control", "no-store"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg())
+], OrgClientController.prototype, "list", null);
+__decorate([
+    Post("reports"),
+    OrgAction("ui.use"),
+    HttpCode(204),
+    Throttled("client-reports"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZBody(ReportBodyDto))
+], OrgClientController.prototype, "report", null);
+OrgClientController = __decorate([
+    Controller("api/v1/orgs/:orgId/ui/client"),
+    __param(0, Inject(ClientAccess)),
+    __param(1, Inject(ClientReports))
+], OrgClientController);
+export { OrgClientController };
+/**
+ * The admin console's client set (spec §9.6), super admins only: `GET /api/v1/admin/ui/client
+ * ?plugin=` → {@link ClientExtensionsResponse} with only `platform.page` components and no
+ * stylesheets (the admin console runs no org client code); with `plugin`, at most that one (the
+ * page `/admin/p/<plugin>/<id>` reads its own). `no-store`.
+ */
+let AdminClientController = class AdminClientController {
+    access;
+    reports;
+    constructor(access, reports) {
+        this.access = access;
+        this.reports = reports;
+    }
+    async list(principal, q) {
+        requireUser(principal);
+        return this.access.platformSet(q.plugin);
+    }
+    /**
+     * `POST /api/v1/admin/ui/client/reports` (spec §10.4), super admins, 20 per minute per account:
+     * a report from an admin page (stored with no org) → 204; 404 `client.not_found` for a build
+     * that has no `platform.page` component or is not served.
+     */
+    async report(principal, body) {
+        const user = requireUser(principal);
+        await this.reports.recordForAdmin(user.account.id, body);
+    }
+};
+__decorate([
+    Get(),
+    Header("cache-control", "no-store"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZQuery(AdminClientQueryDto))
+], AdminClientController.prototype, "list", null);
+__decorate([
+    Post("reports"),
+    HttpCode(204),
+    Throttled("client-reports"),
+    __param(0, CurrentPrincipal()),
+    __param(1, ZBody(ReportBodyDto))
+], AdminClientController.prototype, "report", null);
+AdminClientController = __decorate([
+    Controller("api/v1/admin/ui/client"),
+    SuperAdmin(),
+    __param(0, Inject(ClientAccess)),
+    __param(1, Inject(ClientReports))
+], AdminClientController);
+export { AdminClientController };

package/dist/client/client.module.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Client extensions (spec 2026-11-09-client-extensions-design.md): the client builds stored with
+ * extension packages ({@link ClientBuilds}) and who may load them ({@link ClientAccess}: the
+ * delivery route and the shell reads, whose controllers the api role lists).
+ */
+export declare class ClientModule {
+}

package/dist/client/client.module.js

@@ -0,0 +1,26 @@
+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;
+};
+import { Module } from "@nestjs/common";
+import { StorageModule } from "../storage/storage.module.js";
+import { ClientAccess } from "./client-access.service.js";
+import { ClientBuilds } from "./client-builds.service.js";
+import { ClientReports } from "./client-reports.service.js";
+/**
+ * Client extensions (spec 2026-11-09-client-extensions-design.md): the client builds stored with
+ * extension packages ({@link ClientBuilds}) and who may load them ({@link ClientAccess}: the
+ * delivery route and the shell reads, whose controllers the api role lists).
+ */
+let ClientModule = class ClientModule {
+};
+ClientModule = __decorate([
+    Module({
+        imports: [StorageModule],
+        providers: [ClientBuilds, ClientAccess, ClientReports],
+        exports: [ClientBuilds, ClientAccess, ClientReports],
+    })
+], ClientModule);
+export { ClientModule };