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

package/dist/extensions/guide-places.js

@@ -0,0 +1,152 @@
+// The kernel side of the setup guide places (spec 2026-11-09-setup-guides-v2-design.md §6.3, §9):
+// the SDK registry (`SETUP_GUIDE_PLACE_INFO`) says which modes, audiences and variables a place
+// has; this module adds, per place, the org action each audience needs, the target lookup (a live
+// object of the org on the guide's plugin, else 404) and the variable values with the reason a
+// known variable has no value. No value ever comes from a target's config, a secret, a token or a
+// client id: only names, ids, versions and the two URL settings.
+import { SETUP_GUIDE_PLACE_INFO, } from "@capybara-hq/plugin-sdk";
+import { webhookBase, webhookUrlOf } from "../channels/webhook-url.js";
+import { ApiError } from "../errors.js";
+import { OAUTH_CALLBACK_PATH } from "../tools/oauth/flow-paths.js";
+/** The org action each audience of a place needs besides `catalog.read` (spec §9.1). */
+export const PLACE_ACTIONS = {
+    "channel-connection": { admin: "channels.manage" },
+    "connector-template": { admin: "connectors.manage", member: "connectors.use" },
+};
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const invalidQuery = (path, message) => new ApiError("validation_failed", "Request validation failed", [{ path, message }]);
+/** The target parameters each place takes; another place's parameter is 400. */
+const TARGET_PARAMS = {
+    "channel-connection": ["connectionId", "name"],
+    "connector-template": ["connectorId"],
+};
+/**
+ * The variable values of a place for one rendering (spec §6.3): the common ones, then the place's
+ * own from its target. Throws 400 `validation_failed` for another place's target parameter and 404
+ * (`channel.not_found`, `connector.not_found`) for a target that is not a live object of the org on
+ * the guide's plugin.
+ */
+export async function resolvePlace(ctx) {
+    const place = ctx.guide.place;
+    for (const key of Object.keys(ctx.query)) {
+        if (ctx.query[key] !== undefined && !TARGET_PARAMS[place].includes(key)) {
+            throw invalidQuery(key, `${key} is not a target of a ${place} guide`);
+        }
+    }
+    const publicUrl = ctx.config.http.publicUrl?.replace(/\/+$/, "") ?? null;
+    const values = {
+        publicUrl,
+        orgName: ctx.org?.name ?? null,
+        pluginName: ctx.item.name,
+        pluginVersion: ctx.item.version,
+    };
+    const reasons = {};
+    const signIn = publicUrl === null
+        ? null
+        : `${publicUrl}/api/v1/auth/sso/${encodeURIComponent(ctx.item.name)}/callback`;
+    let target = null;
+    let storedMode = null;
+    if (place === "channel-connection") {
+        const connection = ctx.query.connectionId === undefined
+            ? undefined
+            : await liveConnection(ctx, ctx.query.connectionId);
+        const base = webhookBase(ctx.config);
+        values.webhookUrl =
+            connection !== undefined && base !== undefined ? webhookUrlOf(base, connection.id) : null;
+        reasons.webhookUrl = connection === undefined ? "not_saved" : "webhook_base";
+        values.signInCallbackUrl = signIn;
+        const typed = ctx.query.name?.trim();
+        values.connectionName =
+            connection?.name ?? (typed === undefined || typed === "" ? null : typed);
+        reasons.connectionName = "no_name";
+        if (connection !== undefined) {
+            target = { kind: "channel-connection", id: connection.id };
+            storedMode = connection.inbound_mode;
+        }
+    }
+    else {
+        const connector = ctx.query.connectorId === undefined
+            ? undefined
+            : await liveConnector(ctx, ctx.query.connectorId);
+        values.oauthCallbackUrl = publicUrl === null ? null : `${publicUrl}${OAUTH_CALLBACK_PATH}`;
+        values.signInCallbackUrl = signIn;
+        values.templateId = ctx.guide.template ?? null;
+        values.templateName = await templateName(ctx);
+        values.connectorName = connector?.name ?? null;
+        reasons.connectorName = "no_connector";
+        if (connector !== undefined)
+            target = { kind: "connector", id: connector.id };
+    }
+    reasons.publicUrl = "public_url";
+    reasons.signInCallbackUrl = "public_url";
+    reasons.oauthCallbackUrl = "public_url";
+    reasons.orgName = "no_org";
+    // keep only the reasons of variables that are the place's and have no value
+    const known = SETUP_GUIDE_PLACE_INFO[place].variables;
+    for (const name of Object.keys(reasons)) {
+        if (!Object.hasOwn(known, name) || values[name] !== null)
+            delete reasons[name];
+    }
+    return { values, reasons, target, storedMode };
+}
+/** A live connection of the org on the guide's plugin; otherwise `channel.not_found`. */
+async function liveConnection(ctx, id) {
+    const notFound = () => new ApiError("channel.not_found", "Channel connection not found");
+    if (ctx.org === null || !UUID_RE.test(id))
+        throw notFound();
+    const c = await ctx.db
+        .selectFrom("channel_connections")
+        .select(["id", "name", "inbound_mode"])
+        .where("id", "=", id)
+        .where("org_id", "=", ctx.org.orgId)
+        .where("plugin", "=", ctx.item.name)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    if (!c)
+        throw notFound();
+    return c;
+}
+/**
+ * A live connector of the org made from the guide's template (`connectors.platform_template_id` ->
+ * the platform component of the item's template, org-owned plugins included); otherwise
+ * `connector.not_found`, also for a custom connector or one made from another template.
+ */
+async function liveConnector(ctx, id) {
+    const notFound = () => new ApiError("connector.not_found", "Connector not found");
+    const template = ctx.guide.template;
+    if (ctx.org === null || template === undefined || !UUID_RE.test(id))
+        throw notFound();
+    const c = await ctx.db
+        .selectFrom("connectors as c")
+        .innerJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+        .select(["c.id", "c.name"])
+        .where("c.id", "=", id)
+        .where("c.org_id", "=", ctx.org.orgId)
+        .where("c.deleted_at", "is", null)
+        .where("t.catalog_item_id", "=", ctx.item.id)
+        .where("t.template_id", "=", template)
+        .executeTakeFirst();
+    if (!c)
+        throw notFound();
+    return c;
+}
+/**
+ * The template's display name in the document's language, from the platform component made from
+ * it at import (`platform_connector_templates.file`); the template id when there is none.
+ */
+async function templateName(ctx) {
+    const id = ctx.guide.template;
+    if (id === undefined)
+        return null;
+    const row = await ctx.db
+        .selectFrom("platform_connector_templates")
+        .select("file")
+        .where("catalog_item_id", "=", ctx.item.id)
+        .where("template_id", "=", id)
+        .where("deleted_at", "is", null)
+        .executeTakeFirst();
+    const name = row?.file
+        ?.displayName;
+    const localized = ctx.locale === "zh" ? name?.zh : name?.en;
+    return typeof localized === "string" && localized !== "" ? localized : id;
+}

package/dist/extensions/hooks.d.ts

@@ -1,6 +1,7 @@
 import { type AvailableHook, type HookHandler, type HookOptions, type HookPayloads, type Logger, type PolicyHook } from "@capybara-hq/plugin-sdk";
 import type { KernelConfig } from "../config/schema.js";
 import type { LockService } from "../infra/lock/lock.service.js";
+import { type EffectiveConfig } from "./effective-config.js";
 import { type InflightTracker } from "./inflight.js";
 /** Default of `hooks.timeoutMs` (used when a host is built without kernel config, e.g. in tests). */
 export declare const DEFAULT_HOOK_TIMEOUT_MS = 5000;
@@ -27,8 +28,8 @@ export type HookOutcome = {
     cause: "deny" | "hook_error" | "timeout";
     detail?: string;
     /**
-     * R10: the hooks could not run at all (organization lookup or payload copy failed); `plugin` is
-     * only the first policy plugin on the mount, not the cause.
+     * R10: the hooks could not run at all (organization lookup, config read or payload copy
+     * failed); `plugin` is only the first policy plugin on the mount, not the cause.
      */
     preflight?: true;
     /**
@@ -36,7 +37,21 @@ export type HookOutcome = {
      * approved, but is not loaded on this replica: the call fails closed without running any hook.
      */
     notLoaded?: true;
+    /**
+     * Layering spec A §6: `plugin` has a policy hook on this mount but its effective config is not
+     * valid in the organization, so it behaves as if not loaded: the call fails closed without
+     * running any policy hook.
+     */
+    needsConfig?: true;
 };
+/**
+ * Thrown by a `usage.report` handler wrapper (see {@link HookRegistry.handlers}) instead of calling
+ * a handler whose extension's effective config is not valid in the payload's organization.
+ */
+export declare class HookNeedsConfigError extends Error {
+    readonly plugin: string;
+    constructor(plugin: string);
+}
 /** A hook a plugin instance registered through `ctx.hooks.on` (kept on the instance, like tools). */
 export interface RegisteredHook {
     mount: AvailableHook;
@@ -80,7 +95,12 @@ export declare const HOOK_DETAIL_MAX_CHARS = 2048;
  *    If a plugin the organization enabled is expected to run policy hooks on the mount (deployment
  *    state, `expectedPolicy`) but is not loaded on this replica, deny with a generic reason
  *    (`hook_error`, `notLoaded`) without running any policy hook (M-1: fail closed). Observe hooks
- *    of plugins that are not loaded are simply missing.
+ *    of plugins that are not loaded are simply missing. Then each enabled plugin with a hook on the
+ *    mount gets its effective config for the organization (layering spec A §6; one read per plugin
+ *    and call, failing like the lookup above). A plugin whose config is not valid behaves as one
+ *    that is not loaded: with a policy hook on the mount the call is denied (`hook_error`,
+ *    `needsConfig`) without running any policy hook, and its observe hooks are skipped. Every
+ *    hook is called with `{ config }` as its third argument.
  * 3. Policy hooks run serially by plugin name (registration order within a plugin), each limited
  *    by `hooks.timeoutMs` (read on every run, hot). `{ deny }`, an error or a timeout stops the chain
  *    and denies (`deny` / `hook_error` / `timeout`). A policy hook cut off by its instance being
@@ -112,6 +132,12 @@ export declare class HookRegistry {
          */
         expectedPolicy?(mount: PolicyHook): readonly string[];
         enabledPlugins(orgId: string): Promise<Set<string>>;
+        /**
+         * The effective deployment config of a plugin for an organization (`EffectiveConfigs.get`):
+         * passed to every hook call, and no hook of the plugin runs for the organization when it is
+         * not valid.
+         */
+        effectiveConfig(orgId: string, plugin: string): Promise<EffectiveConfig>;
         /** The warn-once markers (`lease`: set unless present, with a TTL). */
         locks: Pick<LockService, "lease">;
         config: () => {
@@ -132,7 +158,9 @@ export declare class HookRegistry {
     private unloadedPolicy;
     /**
      * `usage.report` handlers by plugin name (delivered by the usage queue, not by {@link run}); each
-     * call runs through the instance's `inflight.run`.
+     * call runs through the instance's `inflight.run` with the plugin's effective config for the
+     * payload's organization, and throws {@link HookNeedsConfigError} without calling the handler
+     * when that config is not valid (layering spec A §6).
      */
     handlers(mount: "usage.report"): {
         plugin: string;
@@ -146,6 +174,11 @@ export declare class HookRegistry {
      * admin.
      */
     private notLoadedDenial;
+    /**
+     * The layering spec A §6 denial: `needy` (sorted) are enabled policy plugins whose effective
+     * config is not valid in the organization. Generic model-visible reason, as for M-1.
+     */
+    private needsConfigDenial;
     /** Active entries of a mount point, sorted by plugin name (stable: registration order within). */
     private entries;
     /** One plugin's policy hooks in registration order; reruns once on a newer generation if revoked. */

package/dist/extensions/hooks.js

@@ -1,4 +1,5 @@
 import { HOOKS_AVAILABLE, POLICY_HOOKS, } from "@capybara-hq/plugin-sdk";
+import { NEEDS_CONFIG_REASON } from "./effective-config.js";
 import { ExtensionUnloadedError } from "./inflight.js";
 /** Default of `hooks.timeoutMs` (used when a host is built without kernel config, e.g. in tests). */
 export const DEFAULT_HOOK_TIMEOUT_MS = 5000;
@@ -13,6 +14,18 @@ export const OBSERVE_INFLIGHT_MAX = 64;
 export const EMPTY_DENY_REASON = "(no reason given)";
 /** Warnings about a plugin's hooks are logged at most once per plugin, mount and kind in this window. */
 const WARN_WINDOW_MS = 60_000;
+/**
+ * Thrown by a `usage.report` handler wrapper (see {@link HookRegistry.handlers}) instead of calling
+ * a handler whose extension's effective config is not valid in the payload's organization.
+ */
+export class HookNeedsConfigError extends Error {
+    plugin;
+    constructor(plugin) {
+        super(`extension ${plugin} ${NEEDS_CONFIG_REASON}`);
+        this.plugin = plugin;
+        this.name = "HookNeedsConfigError";
+    }
+}
 const AVAILABLE = new Set(HOOKS_AVAILABLE);
 const POLICY = new Set(POLICY_HOOKS);
 /** Error text that never throws itself (a hostile `message` getter or `toString`). */
@@ -110,7 +123,12 @@ const clipDetail = (s) => clipText(s, HOOK_DETAIL_MAX_CHARS);
  *    If a plugin the organization enabled is expected to run policy hooks on the mount (deployment
  *    state, `expectedPolicy`) but is not loaded on this replica, deny with a generic reason
  *    (`hook_error`, `notLoaded`) without running any policy hook (M-1: fail closed). Observe hooks
- *    of plugins that are not loaded are simply missing.
+ *    of plugins that are not loaded are simply missing. Then each enabled plugin with a hook on the
+ *    mount gets its effective config for the organization (layering spec A §6; one read per plugin
+ *    and call, failing like the lookup above). A plugin whose config is not valid behaves as one
+ *    that is not loaded: with a policy hook on the mount the call is denied (`hook_error`,
+ *    `needsConfig`) without running any policy hook, and its observe hooks are skipped. Every
+ *    hook is called with `{ config }` as its third argument.
  * 3. Policy hooks run serially by plugin name (registration order within a plugin), each limited
  *    by `hooks.timeoutMs` (read on every run, hot). `{ deny }`, an error or a timeout stops the chain
  *    and denies (`deny` / `hook_error` / `timeout`). A policy hook cut off by its instance being
@@ -156,13 +174,18 @@ export class HookRegistry {
     }
     /**
      * `usage.report` handlers by plugin name (delivered by the usage queue, not by {@link run}); each
-     * call runs through the instance's `inflight.run`.
+     * call runs through the instance's `inflight.run` with the plugin's effective config for the
+     * payload's organization, and throws {@link HookNeedsConfigError} without calling the handler
+     * when that config is not valid (layering spec A §6).
      */
     handlers(mount) {
         return this.entries(mount).map(({ src, hook }) => ({
             plugin: src.name,
             handler: (payload, signal) => src.inflight.run(signal, async (s) => {
-                await hook.handler(payload, s);
+                const effective = await this.d.effectiveConfig(payload.orgId, src.name);
+                if (!effective.ok)
+                    throw new HookNeedsConfigError(src.name);
+                await hook.handler(payload, s, { config: effective.config });
             }),
         }));
     }
@@ -177,6 +200,8 @@ export class HookRegistry {
         let enabled;
         let frozen;
         let missing;
+        /** Effective config per enabled plugin with a hook here; null = not valid in the org. */
+        const configs = new Map();
         try {
             const abort = abortOf(signal);
             try {
@@ -194,6 +219,19 @@ export class HookRegistry {
             }
             if (!all.some((e) => enabled.has(e.src.name)))
                 return { allowed: true };
+            for (const name of new Set(all.map((e) => e.src.name).filter((n) => enabled.has(n)))) {
+                const abortCfg = abortOf(signal);
+                try {
+                    const e = await Promise.race([
+                        this.d.effectiveConfig(payload.orgId, name),
+                        abortCfg.aborted,
+                    ]);
+                    configs.set(name, e.ok ? { config: e.config } : null);
+                }
+                finally {
+                    abortCfg.cleanup();
+                }
+            }
             // Cost: one clone + deep-freeze per call. The model.request payload carries no media bytes
             // (hookRequestOf, I-3), so it stays small. Freezing in place would freeze the logged object.
             // The clone is skipped when has() is false or no enabled plugin has a hook on this mount.
@@ -207,7 +245,7 @@ export class HookRegistry {
             if (firstPolicy !== undefined) {
                 // R10: no plugin ran; the named plugin is only the first policy plugin on this mount, so
                 // the detail says so instead of blaming it
-                const detail = clipDetail(`Hooks could not run (organization lookup or payload copy failed) before any plugin was called; ${firstPolicy} is named only as the first policy plugin on ${mount}: ${raw}`);
+                const detail = clipDetail(`Hooks could not run (organization lookup, config read or payload copy failed) before any plugin was called; ${firstPolicy} is named only as the first policy plugin on ${mount}: ${raw}`);
                 this.d.log.warn("plugin hooks could not run; denying the call", {
                     mount,
                     firstPolicyPlugin: firstPolicy,
@@ -227,9 +265,19 @@ export class HookRegistry {
             }
             return { allowed: true };
         }
-        const active = all.filter((e) => enabled.has(e.src.name));
+        const active = all.filter((e) => enabled.has(e.src.name) && configs.get(e.src.name));
         const timeoutMs = this.d.config().hooks.timeoutMs;
-        let outcome = missing.length > 0 ? this.notLoadedDenial(mount, missing) : { allowed: true };
+        // spec A §6: a policy plugin without a valid config in the org behaves as one not loaded
+        const needy = [
+            ...new Set(all
+                .filter((e) => e.hook.mode === "policy" && configs.get(e.src.name) === null)
+                .map((e) => e.src.name)),
+        ];
+        let outcome = missing.length > 0
+            ? this.notLoadedDenial(mount, missing)
+            : needy.length > 0
+                ? this.needsConfigDenial(mount, needy)
+                : { allowed: true };
         // policy hooks grouped per plugin (entries are sorted, so groups are contiguous)
         const groups = [];
         for (const e of active) {
@@ -242,7 +290,8 @@ export class HookRegistry {
                 groups.push({ src: e.src, hooks: [e.hook] });
         }
         for (const g of outcome.allowed ? groups : []) {
-            const denied = await this.runPolicies(mount, g.src, g.hooks, frozen, signal, timeoutMs);
+            const call = configs.get(g.src.name);
+            const denied = await this.runPolicies(mount, g.src, g.hooks, frozen, call, signal, timeoutMs);
             if (denied) {
                 outcome = denied;
                 break;
@@ -251,8 +300,10 @@ export class HookRegistry {
         // observe hooks are resolved again now: if the plugin was upgraded while the policy hooks ran,
         // the current generation observes (the retiring one no longer accepts calls)
         for (const e of this.entries(mount)) {
-            if (e.hook.mode === "observe" && enabled.has(e.src.name)) {
-                this.dispatchObserve(mount, e.src, e.hook, frozen, signal);
+            const call = configs.get(e.src.name);
+            // no config read for it (not valid in the org, or a plugin that appeared meanwhile): skipped
+            if (e.hook.mode === "observe" && enabled.has(e.src.name) && call) {
+                this.dispatchObserve(mount, e.src, e.hook, frozen, call, signal);
             }
         }
         return outcome;
@@ -277,6 +328,21 @@ export class HookRegistry {
             notLoaded: true,
         };
     }
+    /**
+     * The layering spec A §6 denial: `needy` (sorted) are enabled policy plugins whose effective
+     * config is not valid in the organization. Generic model-visible reason, as for M-1.
+     */
+    needsConfigDenial(mount, needy) {
+        const plugin = needy[0];
+        return {
+            allowed: false,
+            plugin,
+            reason: unavailableReason(plugin),
+            cause: "hook_error",
+            detail: `extension ${needy.join(", ")} declares a policy hook on ${mount} but ${NEEDS_CONFIG_REASON}; the call was denied without running any policy hook`,
+            needsConfig: true,
+        };
+    }
     /** Active entries of a mount point, sorted by plugin name (stable: registration order within). */
     entries(mount) {
         return this.d
@@ -285,14 +351,14 @@ export class HookRegistry {
             .sort((a, b) => (a.src.name < b.src.name ? -1 : a.src.name > b.src.name ? 1 : 0));
     }
     /** One plugin's policy hooks in registration order; reruns once on a newer generation if revoked. */
-    async runPolicies(mount, src, hooks, payload, signal, timeoutMs, rerun = false) {
+    async runPolicies(mount, src, hooks, payload, call, signal, timeoutMs, rerun = false) {
         const plugin = src.name;
         for (const hook of hooks) {
             if (signal.aborted)
                 throw signal.reason;
             let r;
             try {
-                r = await src.inflight.run(signal, (s) => this.call(hook, payload, s, timeoutMs));
+                r = await src.inflight.run(signal, (s) => this.call(hook, payload, call, s, timeoutMs));
             }
             catch (err) {
                 if (signal.aborted)
@@ -301,7 +367,7 @@ export class HookRegistry {
                     const cur = this.d.current(plugin);
                     if (!rerun && cur && cur !== src) {
                         const again = cur.hooks.filter((h) => h.mount === mount && h.mode === "policy");
-                        return this.runPolicies(mount, cur, again, payload, signal, timeoutMs, true);
+                        return this.runPolicies(mount, cur, again, payload, call, signal, timeoutMs, true);
                     }
                 }
                 r = { kind: "error", message: errMsg(err) };
@@ -338,7 +404,7 @@ export class HookRegistry {
         return undefined;
     }
     /** Fire-and-forget observe call through the instance's in-flight tracker, capped per plugin. */
-    dispatchObserve(mount, src, hook, payload, signal) {
+    dispatchObserve(mount, src, hook, payload, call, signal) {
         const plugin = src.name;
         const n = this.observing.get(plugin) ?? 0;
         if (n >= OBSERVE_INFLIGHT_MAX) {
@@ -349,7 +415,7 @@ export class HookRegistry {
         this.observing.set(plugin, n + 1);
         void (async () => {
             try {
-                const r = await src.inflight.run(signal, (s) => this.call(hook, payload, s, timeoutMs));
+                const r = await src.inflight.run(signal, (s) => this.call(hook, payload, call, s, timeoutMs));
                 if (r.kind === "error" || r.kind === "timeout") {
                     await this.warnOnce(plugin, mount, "failed", "plugin observe hook failed; the call continued", r.kind === "timeout" ? `timed out after ${timeoutMs} ms` : r.message);
                 }
@@ -371,7 +437,7 @@ export class HookRegistry {
      * Calls one handler with its own signal (aborted on timeout or when `s` aborts). Rejects with
      * `s.reason` when `s` aborts first, so callers can tell an abort from a hook failure.
      */
-    async call(hook, payload, s, timeoutMs) {
+    async call(hook, payload, call, s, timeoutMs) {
         const ac = new AbortController();
         const onAbort = () => ac.abort(s.reason);
         if (s.aborted)
@@ -385,7 +451,7 @@ export class HookRegistry {
                 timer = setTimeout(() => resolve("timeout"), timeoutMs);
             });
             const handled = Promise.resolve()
-                .then(() => hook.handler(payload, ac.signal))
+                .then(() => hook.handler(payload, ac.signal, { config: call.config }))
                 .then((v) => ({ v }), (err) => ({ err }));
             const result = await Promise.race([handled, timedOut, abort.aborted]);
             if (result === "timeout") {