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

package/dist/channels/connections.service.js

@@ -11,7 +11,7 @@ import { randomUUID } from "node:crypto";
 import { CHANNEL_EXTENSION_POINT, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
-import { configFields, getPath, secretValues } from "../config/fields.js";
+import { configFields, getPath, secretScalars, secretValues } from "../config/fields.js";
 import { queryEnabledPlugins } from "../ctx/create-ctx.js";
 import { createSecrets } from "../ctx/secrets.js";
 import { ApiError } from "../errors.js";
@@ -135,7 +135,7 @@ let ChannelConnections = class ChannelConnections {
     config, events, 
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
     log, txHost, 
-    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
     guides) {
         this.db = db;
         this.orgLock = orgLock;
@@ -336,7 +336,9 @@ let ChannelConnections = class ChannelConnections {
         const id = randomUUID();
         const { plain, secrets } = split(schema, full);
         // the guide the 新建渠道 page showed: the plugin's current one, for the default mode
-        const guideAck = await this.guides.currentAck(input.plugin, "long_connection");
+        const guideAck = await this.guides.currentAck(input.plugin, "channel-connection", {
+            mode: "long_connection",
+        });
         const row = await this.insertIn({
             orgId,
             id,
@@ -440,11 +442,13 @@ let ChannelConnections = class ChannelConnections {
         // A mode switch sets the platform app up for the new mode: the guide of that mode is the one
         // on the page. Only an ack without drift moves on: a drifted one stays until the person
         // confirms through guide-ack, so switching modes never clears the update notice (spec
-        // 2026-11-08-plugin-setup-guides-design.md §6)
+        // 2026-11-09-setup-guides-v2-design.md §11)
         const guideAck = modeChanged &&
             patch.inboundMode !== undefined &&
-            !(await this.guides.ackDrifted(current.plugin, current.guide_ack ?? null))
-            ? await this.guides.currentAck(current.plugin, patch.inboundMode)
+            !(await this.guides.ackDrifted(current.plugin, "channel-connection", current.guide_ack ?? null))
+            ? await this.guides.currentAck(current.plugin, "channel-connection", {
+                mode: patch.inboundMode,
+            })
             : undefined;
         const row = await this.updateIn({
             orgId,
@@ -533,15 +537,21 @@ let ChannelConnections = class ChannelConnections {
     }
     /**
      * 「我已更新应用」: records the plugin's current channel-connection guide for the connection's
-     * mode as the one it is set up with. `hash` is the template hash of the guide the person was
+     * mode as the one it is set up with. `hash` is the drift hash of the guide the person was
      * shown; when the plugin has moved on since, 409 `channel.guide_changed` (show the new guide
-     * first). A plugin without a guide -> 404 `catalog.guide_not_found`.
+     * first). A plugin without a guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
      */
-    async ackGuide(orgId, id, hash, actorAccountId, actorTokenId) {
+    async ackGuide(org, id, hash, actorAccountId, actorTokenId) {
+        const { orgId } = org;
         const current = await this.live(orgId).where("id", "=", id).executeTakeFirst();
         if (!current)
             throw notFound();
-        const ack = await this.guides.currentAck(current.plugin, current.inbound_mode);
+        // the guide read's visibility: an item the org's catalog does not show has no guide to ack
+        const ack = await this.guides.currentAck(current.plugin, "channel-connection", {
+            mode: current.inbound_mode,
+            org,
+        });
         if (ack === null) {
             throw new ApiError("catalog.guide_not_found", "The plugin has no channel setup guide");
         }
@@ -671,6 +681,42 @@ let ChannelConnections = class ChannelConnections {
         for (const r of rows)
             await this.changed(r.id, true);
     }
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a live connection of the org
+     * on `plugin`: the `updated_at` of its row and of its secrets row (ISO), never a value. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`.
+     */
+    async checkRevision(orgId, plugin, id) {
+        const row = await this.live(orgId)
+            .where("id", "=", id)
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        const secretRow = await this.db
+            .selectFrom("secrets")
+            .select("updated_at")
+            .where("namespace", "=", SECRETS_NAMESPACE)
+            .where("org_id", "=", orgId)
+            .where("key", "=", connectionSecretKey(id))
+            .executeTakeFirst();
+        const iso = (d) => new Date(d).toISOString();
+        return `${iso(row.updated_at)}|${secretRow ? iso(secretRow.updated_at) : "-"}`;
+    }
+    /**
+     * For setup checks (setup guides v2 §10.8): the stored secret values of a live connection of the
+     * org on `plugin` (every secret field, decrypted), what a check's result is redacted by. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`. Never echo them.
+     */
+    async checkSecrets(orgId, plugin, id) {
+        const row = await this.live(orgId)
+            .where("id", "=", id)
+            .where("plugin", "=", plugin)
+            .executeTakeFirst();
+        if (!row)
+            throw notFound();
+        return secretScalars(Object.values(await this.readSecrets(orgId, id)));
+    }
     /**
      * The extension implementation and full config a connection needs to run (decrypted secrets
      * included, validated against `connectionSchema`). Connection missing / deleted ->

package/dist/channels/webhook.d.ts

@@ -1,4 +1,6 @@
 import type { ChannelWebhookRequest, ChannelWebhookResponse, Logger } from "@capybara-hq/plugin-sdk";
+import type { Redis } from "ioredis";
+import { LockService } from "../infra/lock/lock.service.js";
 import { ChannelConnections } from "./connections.service.js";
 import { ChannelInbound } from "./inbound.js";
 /**
@@ -19,6 +21,10 @@ export interface ChannelWebhookTimings {
 export declare const CHANNEL_WEBHOOK_TIMINGS: unique symbol;
 /** Most connections whose runtime is cached in one process. */
 export declare const WEBHOOK_RUNTIME_CACHE_MAX = 1000;
+/** How long a connection's last accepted webhook is remembered (`capybara:webhook-received`). */
+export declare const WEBHOOK_SEEN_TTL_SECONDS: number;
+/** When the gateway last accepted a verified webhook for the connection (ISO time, TTL 7 days). */
+export declare const webhookSeenKey: (connectionId: string) => string;
 /**
  * Headers every webhook response carries; a plugin cannot override them (the body is never meant to
  * be rendered or sniffed by a browser).
@@ -49,6 +55,10 @@ export declare const WEBHOOK_SECURITY_HEADERS: Readonly<Record<string, string>>;
  *   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
@@ -60,6 +70,9 @@ export declare class ChannelWebhooks {
     private readonly connections;
     private readonly inbound;
     private readonly log;
+    /** The minute gate of the seen marker (`SET NX` with a TTL). */
+    private readonly locks;
+    private readonly redis;
     private readonly runtimes;
     /** Bumped by {@link invalidateAll}: a fetch started before the bump is not stored. */
     private generation;
@@ -67,12 +80,19 @@ export declare class ChannelWebhooks {
     private readonly handleTimeoutMs;
     /** How long a connection's runtime is reused; 0 disables the cache. */
     private readonly runtimeCacheMs;
-    constructor(connections: Pick<ChannelConnections, "row" | "runtime">, inbound: Pick<ChannelInbound, "onEvent">, log: Pick<Logger, "warn">, timings?: Partial<ChannelWebhookTimings>);
+    constructor(connections: Pick<ChannelConnections, "row" | "runtime">, inbound: Pick<ChannelInbound, "onEvent">, log: Pick<Logger, "warn">, 
+    /** The minute gate of the seen marker (`SET NX` with a TTL). */
+    locks: Pick<LockService, "lease">, redis: Pick<Redis, "set">, timings?: Partial<ChannelWebhookTimings>);
     /** Drops the cached runtime of one connection (on `channel.changed`). */
     invalidate(connectionId: string): void;
     /** Drops every cached runtime (a plugin was replaced, revoked or reloaded). */
     invalidateAll(): void;
     handle(connectionId: string, request: ChannelWebhookRequest, signal: AbortSignal): Promise<ChannelWebhookResponse>;
+    /**
+     * 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).
+     */
+    private markSeen;
     private runtime;
     private respond;
     private respondBefore;

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,101 @@
+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).
+     */
+    orgSet(orgId: string, role: OrgRole): 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(plugin?: string): Promise<ClientExtensionsResponse>;
+}