@capybara-hq/kernel 0.1.0-rc.17 → 0.1.0-rc.18

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

@@ -90,12 +90,13 @@ export declare class ClientAccess {
      * 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): Promise<ClientExtensionsResponse>;
+    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(plugin?: string): Promise<ClientExtensionsResponse>;
+    platformSet(signInId: (plugin: string) => string, plugin?: string): Promise<ClientExtensionsResponse>;
 }

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

@@ -234,8 +234,9 @@ let ClientAccess = class ClientAccess {
      * 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) {
+    async orgSet(orgId, role, signInId) {
         const db = this.db.db;
         const [kill, rows] = await Promise.all([
             readClientExtensions(db, this.log),
@@ -253,6 +254,7 @@ let ClientAccess = class ClientAccess {
             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 };
     }
@@ -261,7 +263,7 @@ let ClientAccess = class ClientAccess {
      * enablement) with at least one `platform.page` component and an entry, only those components
      * and no stylesheets (the admin console runs no org client code); with `plugin`, at most that one.
      */
-    async platformSet(plugin) {
+    async platformSet(signInId, plugin) {
         const db = this.db.db;
         let q = this.listed(db);
         if (plugin !== undefined)
@@ -278,7 +280,14 @@ let ClientAccess = class ClientAccess {
             if (components.length === 0)
                 return [];
             return [
-                { plugin: r.plugin, build: r.build, entry: fileRef(r, r.entry), styles: [], components },
+                {
+                    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 };

package/dist/client/client-sign-in.service.d.ts

@@ -0,0 +1,21 @@
+import type { Keyring } from "../ctx/secrets.js";
+import type { UserPrincipal } from "../identity/principal.js";
+/**
+ * The sign-in ids of the shell reads (client extensions spec §4.2, `ClientApi.signIn`): an opaque
+ * id per plugin that stays the same for one sign-in (one web session, across token refreshes and
+ * every tab of it) and changes on the next sign-in, so client code can do something once per
+ * sign-in. It is `HMAC-SHA256(key, "<sign-in>\0<plugin>")` truncated to 128 bits, the key derived
+ * from the master keyring: not a credential and not reversible to the session id. The plugin name
+ * is an input only so that the id is not the same string in every plugin; that is no isolation
+ * boundary: client code runs with full trust in the page (spec D2) and can read the whole shell
+ * read (or the query cache), which lists every plugin's id. Derived per request from the
+ * principal, no state. A personal token (no session) is its own sign-in. Rotating the master key
+ * changes every id once (client code then treats the session as a new sign-in); during a rolling
+ * restart old and new replicas answer different ids, so it may look like more than one.
+ */
+export declare class ClientSignIn {
+    private readonly key;
+    constructor(keyring: Keyring);
+    /** The id function of the caller's sign-in: plugin name → that plugin's sign-in id. */
+    of(principal: UserPrincipal): (plugin: string) => string;
+}

package/dist/client/client-sign-in.service.js

@@ -0,0 +1,49 @@
+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 { createHmac } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { KEYRING } from "../infra/tokens.js";
+/** The HKDF purpose of the sign-in id key (`capybara:client-sign-in/v1`). */
+const SIGN_IN_KEY_INFO = "client-sign-in/v1";
+/** A sign-in id is 128 bits of the HMAC, base64url (22 characters). */
+const SIGN_IN_ID_BYTES = 16;
+/**
+ * The sign-in ids of the shell reads (client extensions spec §4.2, `ClientApi.signIn`): an opaque
+ * id per plugin that stays the same for one sign-in (one web session, across token refreshes and
+ * every tab of it) and changes on the next sign-in, so client code can do something once per
+ * sign-in. It is `HMAC-SHA256(key, "<sign-in>\0<plugin>")` truncated to 128 bits, the key derived
+ * from the master keyring: not a credential and not reversible to the session id. The plugin name
+ * is an input only so that the id is not the same string in every plugin; that is no isolation
+ * boundary: client code runs with full trust in the page (spec D2) and can read the whole shell
+ * read (or the query cache), which lists every plugin's id. Derived per request from the
+ * principal, no state. A personal token (no session) is its own sign-in. Rotating the master key
+ * changes every id once (client code then treats the session as a new sign-in); during a rolling
+ * restart old and new replicas answer different ids, so it may look like more than one.
+ */
+let ClientSignIn = class ClientSignIn {
+    key;
+    constructor(keyring) {
+        this.key = keyring.deriveKey(SIGN_IN_KEY_INFO).current;
+    }
+    /** The id function of the caller's sign-in: plugin name → that plugin's sign-in id. */
+    of(principal) {
+        const signIn = principal.via === "session" ? `session:${principal.sessionId}` : `pat:${principal.tokenId}`;
+        return (plugin) => createHmac("sha256", this.key)
+            .update(`${signIn}\0${plugin}`)
+            .digest()
+            .subarray(0, SIGN_IN_ID_BYTES)
+            .toString("base64url");
+    }
+};
+ClientSignIn = __decorate([
+    Injectable(),
+    __param(0, Inject(KEYRING))
+], ClientSignIn);
+export { ClientSignIn };

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

@@ -4,18 +4,21 @@ 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";
+import { ClientSignIn } from "./client-sign-in.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;
+ * client build, their file URLs and integrity, the components the caller's role may use and the
+ * caller's sign-in id per plugin (`ClientSignIn`);
  * `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);
+    private readonly signIn;
+    constructor(access: ClientAccess, reports: ClientReports, signIn: ClientSignIn);
     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
@@ -34,7 +37,8 @@ export declare class OrgClientController {
 export declare class AdminClientController {
     private readonly access;
     private readonly reports;
-    constructor(access: ClientAccess, reports: ClientReports);
+    private readonly signIn;
+    constructor(access: ClientAccess, reports: ClientReports, signIn: ClientSignIn);
     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:

package/dist/client/client.controller.js

@@ -16,6 +16,7 @@ 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";
+import { ClientSignIn } from "./client-sign-in.service.js";
 class AdminClientQueryDto extends createZodDto(AdminClientQuery, "AdminClientQuery") {
 }
 class ReportBodyDto extends createZodDto(ReportBody, "ClientReportBody") {
@@ -24,20 +25,23 @@ 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;
+ * client build, their file URLs and integrity, the components the caller's role may use and the
+ * caller's sign-in id per plugin (`ClientSignIn`);
  * `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) {
+    signIn;
+    constructor(access, reports, signIn) {
         this.access = access;
         this.reports = reports;
+        this.signIn = signIn;
     }
     async list(principal, org) {
-        requireUser(principal);
-        return this.access.orgSet(org.orgId, org.role);
+        const user = requireUser(principal);
+        return this.access.orgSet(org.orgId, org.role, this.signIn.of(user));
     }
     /**
      * `POST /api/v1/orgs/:orgId/ui/client/reports` (spec §10.4), `ui.use`, a person, 20 per minute
@@ -69,7 +73,8 @@ __decorate([
 OrgClientController = __decorate([
     Controller("api/v1/orgs/:orgId/ui/client"),
     __param(0, Inject(ClientAccess)),
-    __param(1, Inject(ClientReports))
+    __param(1, Inject(ClientReports)),
+    __param(2, Inject(ClientSignIn))
 ], OrgClientController);
 export { OrgClientController };
 /**
@@ -81,13 +86,15 @@ export { OrgClientController };
 let AdminClientController = class AdminClientController {
     access;
     reports;
-    constructor(access, reports) {
+    signIn;
+    constructor(access, reports, signIn) {
         this.access = access;
         this.reports = reports;
+        this.signIn = signIn;
     }
     async list(principal, q) {
-        requireUser(principal);
-        return this.access.platformSet(q.plugin);
+        const user = requireUser(principal);
+        return this.access.platformSet(this.signIn.of(user), q.plugin);
     }
     /**
      * `POST /api/v1/admin/ui/client/reports` (spec §10.4), super admins, 20 per minute per account:
@@ -116,6 +123,7 @@ AdminClientController = __decorate([
     Controller("api/v1/admin/ui/client"),
     SuperAdmin(),
     __param(0, Inject(ClientAccess)),
-    __param(1, Inject(ClientReports))
+    __param(1, Inject(ClientReports)),
+    __param(2, Inject(ClientSignIn))
 ], AdminClientController);
 export { AdminClientController };

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

@@ -1,7 +1,8 @@
 /**
  * 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).
+ * delivery route and the shell reads, whose controllers the api role lists; {@link ClientSignIn}:
+ * the per-plugin sign-in ids of those reads).
  */
 export declare class ClientModule {
 }

package/dist/client/client.module.js

@@ -9,18 +9,20 @@ 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";
+import { ClientSignIn } from "./client-sign-in.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).
+ * delivery route and the shell reads, whose controllers the api role lists; {@link ClientSignIn}:
+ * the per-plugin sign-in ids of those reads).
  */
 let ClientModule = class ClientModule {
 };
 ClientModule = __decorate([
     Module({
         imports: [StorageModule],
-        providers: [ClientBuilds, ClientAccess, ClientReports],
-        exports: [ClientBuilds, ClientAccess, ClientReports],
+        providers: [ClientBuilds, ClientAccess, ClientReports, ClientSignIn],
+        exports: [ClientBuilds, ClientAccess, ClientReports, ClientSignIn],
     })
 ], ClientModule);
 export { ClientModule };

package/dist/client/client.schemas.d.ts

@@ -22,6 +22,12 @@ export interface ClientExtensionItem {
         id: string;
         slot: UiSlotId;
     }[];
+    /**
+     * The viewer's sign-in id for this plugin (`ClientApi.signIn.id`, spec §4.2): opaque, the same
+     * for every read of one sign-in and different after the next one; a different string per plugin,
+     * not a secret between plugins (client code is full trust and reads the whole set).
+     */
+    signInId: string;
 }
 /** The shell read (spec §9.2). */
 export interface ClientExtensionsResponse {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/kernel",
-  "version": "0.1.0-rc.17",
+  "version": "0.1.0-rc.18",
   "description": "Capybara kernel: config, database, plugin host and HTTP API of the Capybara agent platform",
   "license": "Apache-2.0",
   "repository": {