@fideliosai/server 2026.331.0-canary.0

package/dist/services/plugin-runtime-sandbox.js

@@ -0,0 +1,154 @@
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+import vm from "node:vm";
+export class PluginSandboxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PluginSandboxError";
+    }
+}
+const DEFAULT_TIMEOUT_MS = 2_000;
+const MODULE_PATH_SUFFIXES = ["", ".js", ".mjs", ".cjs", "/index.js", "/index.mjs", "/index.cjs"];
+const DEFAULT_GLOBALS = {
+    console,
+    setTimeout,
+    clearTimeout,
+    setInterval,
+    clearInterval,
+    URL,
+    URLSearchParams,
+    TextEncoder,
+    TextDecoder,
+    AbortController,
+    AbortSignal,
+};
+export function createCapabilityScopedInvoker(manifest, validator) {
+    return {
+        async invoke(operation, fn) {
+            validator.assertOperation(manifest, operation);
+            return await fn();
+        },
+    };
+}
+/**
+ * Load a CommonJS plugin module in a VM context with explicit module import allow-listing.
+ *
+ * Security properties:
+ * - no implicit access to host globals like `process`
+ * - no unrestricted built-in module imports
+ * - relative imports are resolved only inside the plugin root directory
+ */
+export async function loadPluginModuleInSandbox(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const allowedSpecifiers = options.allowedModuleSpecifiers ?? new Set();
+    const entrypointPath = path.resolve(options.entrypointPath);
+    const pluginRoot = path.dirname(entrypointPath);
+    const context = vm.createContext({
+        ...DEFAULT_GLOBALS,
+        ...options.allowedGlobals,
+    });
+    const moduleCache = new Map();
+    const allowedModules = options.allowedModules ?? {};
+    const realPluginRoot = realpathSync(pluginRoot);
+    const loadModuleSync = (modulePath) => {
+        const resolvedPath = resolveModulePathSync(path.resolve(modulePath));
+        const realPath = realpathSync(resolvedPath);
+        if (!isWithinRoot(realPath, realPluginRoot)) {
+            throw new PluginSandboxError(`Import '${modulePath}' escapes plugin root and is not allowed`);
+        }
+        const cached = moduleCache.get(realPath);
+        if (cached)
+            return cached;
+        const code = readModuleSourceSync(realPath);
+        if (looksLikeEsm(code)) {
+            throw new PluginSandboxError("Sandbox loader only supports CommonJS modules. Build plugin worker entrypoints as CJS for sandboxed loading.");
+        }
+        const module = { exports: {} };
+        // Cache the module before execution to preserve CommonJS cycle semantics.
+        moduleCache.set(realPath, module.exports);
+        const requireInSandbox = (specifier) => {
+            if (!specifier.startsWith(".") && !specifier.startsWith("/")) {
+                if (!allowedSpecifiers.has(specifier)) {
+                    throw new PluginSandboxError(`Import denied for module '${specifier}'. Add an explicit sandbox allow-list entry.`);
+                }
+                const binding = allowedModules[specifier];
+                if (!binding) {
+                    throw new PluginSandboxError(`Bare module '${specifier}' is allow-listed but no host binding is registered.`);
+                }
+                return binding;
+            }
+            const candidatePath = path.resolve(path.dirname(realPath), specifier);
+            return loadModuleSync(candidatePath);
+        };
+        // Inject the CJS module arguments into the context so the script can call
+        // the wrapper immediately. This is critical: the timeout in runInContext
+        // only applies during script evaluation. By including the self-invocation
+        // `(fn)(exports, module, ...)` in the script text, the timeout also covers
+        // the actual module body execution — preventing infinite loops from hanging.
+        const sandboxArgs = {
+            __fidelios_exports: module.exports,
+            __fidelios_module: module,
+            __fidelios_require: requireInSandbox,
+            __fidelios_filename: realPath,
+            __fidelios_dirname: path.dirname(realPath),
+        };
+        // Temporarily inject args into the context, run, then remove to avoid pollution.
+        Object.assign(context, sandboxArgs);
+        const wrapped = `(function (exports, module, require, __filename, __dirname) {\n${code}\n})(__fidelios_exports, __fidelios_module, __fidelios_require, __fidelios_filename, __fidelios_dirname)`;
+        const script = new vm.Script(wrapped, { filename: realPath });
+        try {
+            script.runInContext(context, { timeout: timeoutMs });
+        }
+        finally {
+            for (const key of Object.keys(sandboxArgs)) {
+                // eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+                delete context[key];
+            }
+        }
+        const normalizedExports = normalizeModuleExports(module.exports);
+        moduleCache.set(realPath, normalizedExports);
+        return normalizedExports;
+    };
+    const entryExports = loadModuleSync(entrypointPath);
+    return {
+        namespace: { ...entryExports },
+    };
+}
+function resolveModulePathSync(candidatePath) {
+    for (const suffix of MODULE_PATH_SUFFIXES) {
+        const fullPath = `${candidatePath}${suffix}`;
+        if (existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+    throw new PluginSandboxError(`Unable to resolve module import at path '${candidatePath}'`);
+}
+/**
+ * True when `targetPath` is inside `rootPath` (or equals rootPath), false otherwise.
+ * Uses `path.relative` so sibling-prefix paths (e.g. `/root-a` vs `/root`) cannot bypass checks.
+ */
+function isWithinRoot(targetPath, rootPath) {
+    const relative = path.relative(rootPath, targetPath);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function readModuleSourceSync(modulePath) {
+    try {
+        return readFileSync(modulePath, "utf8");
+    }
+    catch (error) {
+        throw new PluginSandboxError(`Failed to read sandbox module '${modulePath}': ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function normalizeModuleExports(exportsValue) {
+    if (typeof exportsValue === "object" && exportsValue !== null) {
+        return exportsValue;
+    }
+    return { default: exportsValue };
+}
+/**
+ * Lightweight guard to reject ESM syntax in the VM CommonJS loader.
+ */
+function looksLikeEsm(code) {
+    return /(^|\n)\s*import\s+/m.test(code) || /(^|\n)\s*export\s+/m.test(code);
+}
+//# sourceMappingURL=plugin-runtime-sandbox.js.map

package/dist/services/plugin-runtime-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-runtime-sandbox.js","sourceRoot":"","sources":["../../src/services/plugin-runtime-sandbox.ts"],"names":[],"mappings":"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"}

package/dist/services/plugin-secrets-handler.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Plugin secrets host-side handler — resolves secret references through the
+ * FideliOS secret provider system.
+ *
+ * When a plugin worker calls `ctx.secrets.resolve(secretRef)`, the JSON-RPC
+ * request arrives at the host with `{ secretRef }`. This module provides the
+ * concrete `HostServices.secrets` adapter that:
+ *
+ * 1. Parses the `secretRef` string to identify the secret.
+ * 2. Looks up the secret record and its latest version in the database.
+ * 3. Delegates to the configured `SecretProviderModule` to decrypt /
+ *    resolve the raw value.
+ * 4. Returns the resolved plaintext value to the worker.
+ *
+ * ## Secret Reference Format
+ *
+ * A `secretRef` is a **secret UUID** — the primary key (`id`) of a row in
+ * the `company_secrets` table. Operators place these UUIDs into plugin
+ * config values; plugin workers resolve them at execution time via
+ * `ctx.secrets.resolve(secretId)`.
+ *
+ * ## Security Invariants
+ *
+ * - Resolved values are **never** logged, persisted, or included in error
+ *   messages (per PLUGIN_SPEC.md §22).
+ * - The handler is capability-gated: only plugins with `secrets.read-ref`
+ *   declared in their manifest may call it (enforced by `host-client-factory`).
+ * - The host handler itself does not cache resolved values. Each call goes
+ *   through the secret provider to honour rotation.
+ *
+ * @see PLUGIN_SPEC.md §22 — Secrets
+ * @see host-client-factory.ts — capability gating
+ * @see services/secrets.ts — secretService used by agent env bindings
+ */
+import type { Db } from "@fideliosai/db";
+/**
+ * Extract secret reference UUIDs from a plugin's configJson, scoped to only
+ * the fields annotated with `format: "secret-ref"` in the schema.
+ *
+ * When no schema is provided, falls back to collecting all UUID-shaped strings
+ * (backwards-compatible for plugins without a declared instanceConfigSchema).
+ */
+export declare function extractSecretRefsFromConfig(configJson: unknown, schema?: Record<string, unknown> | null): Set<string>;
+/**
+ * Input shape for the `secrets.resolve` handler.
+ *
+ * Matches `WorkerToHostMethods["secrets.resolve"][0]` from `protocol.ts`.
+ */
+export interface PluginSecretsResolveParams {
+    /** The secret reference string (a secret UUID). */
+    secretRef: string;
+}
+/**
+ * Options for creating the plugin secrets handler.
+ */
+export interface PluginSecretsHandlerOptions {
+    /** Database connection. */
+    db: Db;
+    /**
+     * The plugin ID using this handler.
+     * Used for logging context only; never included in error payloads
+     * that reach the plugin worker.
+     */
+    pluginId: string;
+}
+/**
+ * The `HostServices.secrets` adapter for the plugin host-client factory.
+ */
+export interface PluginSecretsService {
+    /**
+     * Resolve a secret reference to its current plaintext value.
+     *
+     * @param params - Contains the `secretRef` (UUID of the secret)
+     * @returns The resolved secret value
+     * @throws {Error} If the secret is not found, has no versions, or
+     *   the provider fails to resolve
+     */
+    resolve(params: PluginSecretsResolveParams): Promise<string>;
+}
+export declare function createPluginSecretsHandler(options: PluginSecretsHandlerOptions): PluginSecretsService;
+//# sourceMappingURL=plugin-secrets-handler.d.ts.map

package/dist/services/plugin-secrets-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-secrets-handler.d.ts","sourceRoot":"","sources":["../../src/services/plugin-secrets-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AA8EzC;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,EAAE,OAAO,EACnB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GACtC,GAAG,CAAC,MAAM,CAAC,CAqCb;AAMD;;;;GAIG;AACH,MAAM,WAAW,0BAA0B;IACzC,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,2BAA2B;IAC3B,EAAE,EAAE,EAAE,CAAC;IACP;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,OAAO,CAAC,MAAM,EAAE,0BAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9D;AA0CD,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,2BAA2B,GACnC,oBAAoB,CAyGtB"}

package/dist/services/plugin-secrets-handler.js

@@ -0,0 +1,275 @@
+/**
+ * Plugin secrets host-side handler — resolves secret references through the
+ * FideliOS secret provider system.
+ *
+ * When a plugin worker calls `ctx.secrets.resolve(secretRef)`, the JSON-RPC
+ * request arrives at the host with `{ secretRef }`. This module provides the
+ * concrete `HostServices.secrets` adapter that:
+ *
+ * 1. Parses the `secretRef` string to identify the secret.
+ * 2. Looks up the secret record and its latest version in the database.
+ * 3. Delegates to the configured `SecretProviderModule` to decrypt /
+ *    resolve the raw value.
+ * 4. Returns the resolved plaintext value to the worker.
+ *
+ * ## Secret Reference Format
+ *
+ * A `secretRef` is a **secret UUID** — the primary key (`id`) of a row in
+ * the `company_secrets` table. Operators place these UUIDs into plugin
+ * config values; plugin workers resolve them at execution time via
+ * `ctx.secrets.resolve(secretId)`.
+ *
+ * ## Security Invariants
+ *
+ * - Resolved values are **never** logged, persisted, or included in error
+ *   messages (per PLUGIN_SPEC.md §22).
+ * - The handler is capability-gated: only plugins with `secrets.read-ref`
+ *   declared in their manifest may call it (enforced by `host-client-factory`).
+ * - The host handler itself does not cache resolved values. Each call goes
+ *   through the secret provider to honour rotation.
+ *
+ * @see PLUGIN_SPEC.md §22 — Secrets
+ * @see host-client-factory.ts — capability gating
+ * @see services/secrets.ts — secretService used by agent env bindings
+ */
+import { eq, and } from "drizzle-orm";
+import { companySecrets, companySecretVersions, pluginConfig } from "@fideliosai/db";
+import { getSecretProvider } from "../secrets/provider-registry.js";
+import { pluginRegistryService } from "./plugin-registry.js";
+// ---------------------------------------------------------------------------
+// Error helpers
+// ---------------------------------------------------------------------------
+/**
+ * Create a sanitised error that never leaks secret material.
+ * Only the ref identifier is included; never the resolved value.
+ */
+function secretNotFound(secretRef) {
+    const err = new Error(`Secret not found: ${secretRef}`);
+    err.name = "SecretNotFoundError";
+    return err;
+}
+function secretVersionNotFound(secretRef) {
+    const err = new Error(`No version found for secret: ${secretRef}`);
+    err.name = "SecretVersionNotFoundError";
+    return err;
+}
+function invalidSecretRef(secretRef) {
+    const err = new Error(`Invalid secret reference: ${secretRef}`);
+    err.name = "InvalidSecretRefError";
+    return err;
+}
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+/** UUID v4 regex for validating secretRef format. */
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Check whether a secretRef looks like a valid UUID.
+ */
+function isUuid(value) {
+    return UUID_RE.test(value);
+}
+/**
+ * Collect the property paths (dot-separated keys) whose schema node declares
+ * `format: "secret-ref"`. Only top-level and nested `properties` are walked —
+ * this mirrors the flat/nested object shapes that `JsonSchemaForm` renders.
+ */
+function collectSecretRefPaths(schema) {
+    const paths = new Set();
+    if (!schema || typeof schema !== "object")
+        return paths;
+    function walk(node, prefix) {
+        const props = node.properties;
+        if (!props || typeof props !== "object")
+            return;
+        for (const [key, propSchema] of Object.entries(props)) {
+            if (!propSchema || typeof propSchema !== "object")
+                continue;
+            const path = prefix ? `${prefix}.${key}` : key;
+            if (propSchema.format === "secret-ref") {
+                paths.add(path);
+            }
+            // Recurse into nested object schemas
+            if (propSchema.type === "object") {
+                walk(propSchema, path);
+            }
+        }
+    }
+    walk(schema, "");
+    return paths;
+}
+/**
+ * Extract secret reference UUIDs from a plugin's configJson, scoped to only
+ * the fields annotated with `format: "secret-ref"` in the schema.
+ *
+ * When no schema is provided, falls back to collecting all UUID-shaped strings
+ * (backwards-compatible for plugins without a declared instanceConfigSchema).
+ */
+export function extractSecretRefsFromConfig(configJson, schema) {
+    const refs = new Set();
+    if (configJson == null || typeof configJson !== "object")
+        return refs;
+    const secretPaths = collectSecretRefPaths(schema);
+    // If schema declares secret-ref paths, extract only those values.
+    if (secretPaths.size > 0) {
+        for (const dotPath of secretPaths) {
+            const keys = dotPath.split(".");
+            let current = configJson;
+            for (const k of keys) {
+                if (current == null || typeof current !== "object") {
+                    current = undefined;
+                    break;
+                }
+                current = current[k];
+            }
+            if (typeof current === "string" && isUuid(current)) {
+                refs.add(current);
+            }
+        }
+        return refs;
+    }
+    // Fallback: no schema or no secret-ref annotations — collect all UUIDs.
+    // This preserves backwards compatibility for plugins that omit
+    // instanceConfigSchema.
+    function walkAll(value) {
+        if (typeof value === "string") {
+            if (isUuid(value))
+                refs.add(value);
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value)
+                walkAll(item);
+        }
+        else if (value !== null && typeof value === "object") {
+            for (const v of Object.values(value))
+                walkAll(v);
+        }
+    }
+    walkAll(configJson);
+    return refs;
+}
+/**
+ * Create a `HostServices.secrets` adapter for a specific plugin.
+ *
+ * The returned service looks up secrets by UUID, fetches the latest version
+ * material, and delegates to the appropriate `SecretProviderModule` for
+ * decryption.
+ *
+ * @example
+ * ```ts
+ * const secretsHandler = createPluginSecretsHandler({ db, pluginId });
+ * const handlers = createHostClientHandlers({
+ *   pluginId,
+ *   capabilities: manifest.capabilities,
+ *   services: {
+ *     secrets: secretsHandler,
+ *     // ...
+ *   },
+ * });
+ * ```
+ *
+ * @param options - Database connection and plugin identity
+ * @returns A `PluginSecretsService` suitable for `HostServices.secrets`
+ */
+/** Simple sliding-window rate limiter for secret resolution attempts. */
+function createRateLimiter(maxAttempts, windowMs) {
+    const attempts = new Map();
+    return {
+        check(key) {
+            const now = Date.now();
+            const windowStart = now - windowMs;
+            const existing = (attempts.get(key) ?? []).filter((ts) => ts > windowStart);
+            if (existing.length >= maxAttempts)
+                return false;
+            existing.push(now);
+            attempts.set(key, existing);
+            return true;
+        },
+    };
+}
+export function createPluginSecretsHandler(options) {
+    const { db, pluginId } = options;
+    const registry = pluginRegistryService(db);
+    // Rate limit: max 30 resolution attempts per plugin per minute
+    const rateLimiter = createRateLimiter(30, 60_000);
+    let cachedAllowedRefs = null;
+    let cachedAllowedRefsExpiry = 0;
+    const CONFIG_CACHE_TTL_MS = 30_000; // 30 seconds, matches event bus TTL
+    return {
+        async resolve(params) {
+            const { secretRef } = params;
+            // ---------------------------------------------------------------
+            // 0. Rate limiting — prevent brute-force UUID enumeration
+            // ---------------------------------------------------------------
+            if (!rateLimiter.check(pluginId)) {
+                const err = new Error("Rate limit exceeded for secret resolution");
+                err.name = "RateLimitExceededError";
+                throw err;
+            }
+            // ---------------------------------------------------------------
+            // 1. Validate the ref format
+            // ---------------------------------------------------------------
+            if (!secretRef || typeof secretRef !== "string" || secretRef.trim().length === 0) {
+                throw invalidSecretRef(secretRef ?? "<empty>");
+            }
+            const trimmedRef = secretRef.trim();
+            if (!isUuid(trimmedRef)) {
+                throw invalidSecretRef(trimmedRef);
+            }
+            // ---------------------------------------------------------------
+            // 1b. Scope check — only allow secrets referenced in this plugin's config
+            // ---------------------------------------------------------------
+            const now = Date.now();
+            if (!cachedAllowedRefs || now > cachedAllowedRefsExpiry) {
+                const [configRow, plugin] = await Promise.all([
+                    db
+                        .select()
+                        .from(pluginConfig)
+                        .where(eq(pluginConfig.pluginId, pluginId))
+                        .then((rows) => rows[0] ?? null),
+                    registry.getById(pluginId),
+                ]);
+                const schema = plugin?.manifestJson
+                    ?.instanceConfigSchema;
+                cachedAllowedRefs = extractSecretRefsFromConfig(configRow?.configJson, schema);
+                cachedAllowedRefsExpiry = now + CONFIG_CACHE_TTL_MS;
+            }
+            if (!cachedAllowedRefs.has(trimmedRef)) {
+                // Return "not found" to avoid leaking whether the secret exists
+                throw secretNotFound(trimmedRef);
+            }
+            // ---------------------------------------------------------------
+            // 2. Look up the secret record by UUID
+            // ---------------------------------------------------------------
+            const secret = await db
+                .select()
+                .from(companySecrets)
+                .where(eq(companySecrets.id, trimmedRef))
+                .then((rows) => rows[0] ?? null);
+            if (!secret) {
+                throw secretNotFound(trimmedRef);
+            }
+            // ---------------------------------------------------------------
+            // 3. Fetch the latest version's material
+            // ---------------------------------------------------------------
+            const versionRow = await db
+                .select()
+                .from(companySecretVersions)
+                .where(and(eq(companySecretVersions.secretId, secret.id), eq(companySecretVersions.version, secret.latestVersion)))
+                .then((rows) => rows[0] ?? null);
+            if (!versionRow) {
+                throw secretVersionNotFound(trimmedRef);
+            }
+            // ---------------------------------------------------------------
+            // 4. Resolve through the appropriate secret provider
+            // ---------------------------------------------------------------
+            const provider = getSecretProvider(secret.provider);
+            const resolved = await provider.resolveVersion({
+                material: versionRow.material,
+                externalRef: secret.externalRef,
+            });
+            return resolved;
+        },
+    };
+}
+//# sourceMappingURL=plugin-secrets-handler.js.map

package/dist/services/plugin-secrets-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-secrets-handler.js","sourceRoot":"","sources":["../../src/services/plugin-secrets-handler.ts"],"names":[],"mappings":"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"}

package/dist/services/plugin-state-store.d.ts

@@ -0,0 +1,92 @@
+import type { Db } from "@fideliosai/db";
+import { pluginState } from "@fideliosai/db";
+import type { PluginStateScopeKind, SetPluginState, ListPluginState } from "@fideliosai/shared";
+/**
+ * Plugin State Store — scoped key-value persistence for plugin workers.
+ *
+ * Provides `get`, `set`, `delete`, and `list` operations over the
+ * `plugin_state` table. Each plugin's data is strictly namespaced by
+ * `pluginId` so plugins cannot read or write each other's state.
+ *
+ * This service implements the server-side backing for the `ctx.state` SDK
+ * client exposed to plugin workers. The host is responsible for:
+ * - enforcing `plugin.state.read` capability before calling `get` / `list`
+ * - enforcing `plugin.state.write` capability before calling `set` / `delete`
+ *
+ * @see PLUGIN_SPEC.md §14 — SDK Surface (`ctx.state`)
+ * @see PLUGIN_SPEC.md §15.1 — Capabilities: Plugin State
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_state` table
+ */
+export declare function pluginStateStore(db: Db): {
+    /**
+     * Read a state value.
+     *
+     * Returns the stored JSON value, or `null` if no entry exists for the
+     * given scope and key.
+     *
+     * Requires `plugin.state.read` capability (enforced by the caller).
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param scopeKind - Granularity of the scope
+     * @param scopeId - Identifier for the scoped entity (null for `instance` scope)
+     * @param stateKey - The key to read
+     * @param namespace - Sub-namespace (defaults to `"default"`)
+     */
+    get: (pluginId: string, scopeKind: PluginStateScopeKind, stateKey: string, { scopeId, namespace, }?: {
+        scopeId?: string;
+        namespace?: string;
+    }) => Promise<unknown>;
+    /**
+     * Write (create or replace) a state value.
+     *
+     * Uses an upsert so the caller does not need to check for prior existence.
+     * On conflict (same composite key) the existing row's `value_json` and
+     * `updated_at` are overwritten.
+     *
+     * Requires `plugin.state.write` capability (enforced by the caller).
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param input - Scope key and value to store
+     */
+    set: (pluginId: string, input: SetPluginState) => Promise<void>;
+    /**
+     * Delete a state value.
+     *
+     * No-ops silently if the entry does not exist (idempotent by design).
+     *
+     * Requires `plugin.state.write` capability (enforced by the caller).
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param scopeKind - Granularity of the scope
+     * @param stateKey - The key to delete
+     * @param scopeId - Identifier for the scoped entity (null for `instance` scope)
+     * @param namespace - Sub-namespace (defaults to `"default"`)
+     */
+    delete: (pluginId: string, scopeKind: PluginStateScopeKind, stateKey: string, { scopeId, namespace, }?: {
+        scopeId?: string;
+        namespace?: string;
+    }) => Promise<void>;
+    /**
+     * List all state entries for a plugin, optionally filtered by scope.
+     *
+     * Returns all matching rows as `PluginStateRecord`-shaped objects.
+     * The `valueJson` field contains the stored value.
+     *
+     * Requires `plugin.state.read` capability (enforced by the caller).
+     *
+     * @param pluginId - UUID of the owning plugin
+     * @param filter - Optional scope filters (scopeKind, scopeId, namespace)
+     */
+    list: (pluginId: string, filter?: ListPluginState) => Promise<(typeof pluginState.$inferSelect)[]>;
+    /**
+     * Delete all state entries owned by a plugin.
+     *
+     * Called during plugin uninstall when `removeData = true`. Also useful
+     * for resetting a plugin's state during testing.
+     *
+     * @param pluginId - UUID of the owning plugin
+     */
+    deleteAll: (pluginId: string) => Promise<void>;
+};
+export type PluginStateStore = ReturnType<typeof pluginStateStore>;
+//# sourceMappingURL=plugin-state-store.d.ts.map

package/dist/services/plugin-state-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-state-store.d.ts","sourceRoot":"","sources":["../../src/services/plugin-state-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,EAAW,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACd,eAAe,EAChB,MAAM,oBAAoB,CAAC;AA6C5B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,EAAE;IAoBnC;;;;;;;;;;;;;OAaG;oBAES,MAAM,aACL,oBAAoB,YACrB,MAAM,4BAIb;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAC1C,OAAO,CAAC,OAAO,CAAC;IASnB;;;;;;;;;;;OAWG;oBACmB,MAAM,SAAS,cAAc,KAAG,OAAO,CAAC,IAAI,CAAC;IAgCnE;;;;;;;;;;;;OAYG;uBAES,MAAM,aACL,oBAAoB,YACrB,MAAM,4BAIb;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAC1C,OAAO,CAAC,IAAI,CAAC;IAMhB;;;;;;;;;;OAUG;qBACoB,MAAM,WAAU,eAAe,KAAQ,OAAO,CAAC,CAAA,OAAO,WAAW,CAAC,YAAY,GAAE,CAAC;IAmBxG;;;;;;;OAOG;0BACyB,MAAM,KAAG,OAAO,CAAC,IAAI,CAAC;EAMrD;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC"}