@capybara-hq/kernel 0.1.0-rc.14 → 0.1.0-rc.16

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>;
+}

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>;
+}