@alfe.ai/openclaw-secrets 0.2.23 → 0.2.25

package/src/index.ts

@@ -1,624 +0,0 @@
-/**
- * openclaw-secrets — OpenClaw plugin for per-scope encrypted secret storage.
- *
- * Trust model:
- *   - Secret VALUES (encrypted fields) are encrypted and decrypted ON THIS
- *     AGENT using AES-256-GCM with KMS-issued data keys. The backend never
- *     sees plaintext for encrypted fields.
- *   - Plaintext fields ride the wire as-is (they're not secret material —
- *     things like email, URL, username; the suspicious-key denylist on the
- *     server rejects obvious mistakes).
- *   - Per-field encryption: each encrypted field has its own data key,
- *     bound by KMS encryption context to (tenantId, scope, scopeId,
- *     secretId, fieldKey). Cross-field swap attacks fail at decrypt.
- *
- * Tools:
- *   - secret_list_scopes    — enumerate scopes the agent can access
- *   - secret_list           — list secret metadata in a scope (with optional filters)
- *   - secret_set            — create a secret with one or more fields
- *   - secret_get            — legacy wrapper: returns the `value` field's plaintext as a string
- *   - secret_get_full       — full aggregate with all fields (plaintext + decrypted encrypted)
- *   - secret_get_field      — fetch and decrypt one field by key
- *   - secret_set_field      — add OR rotate one field
- *   - secret_remove_field   — remove one field row
- *   - secret_update_metadata — name/description/tags/category PATCH
- *   - secret_search         — facet GSI search by category/tag/fieldKey
- *   - secret_get_history    — bounded changelog read (metadata only, never values)
- *   - secret_delete         — delete a secret
- */
-import { randomUUID } from "node:crypto";
-import {
-  AgentApiClient,
-  installToolErrorCapture,
-  type SecretScope,
-  type SecretCategory,
-  type FieldFormat,
-  type FieldSensitivity,
-  type Field,
-} from "@alfe.ai/agent-api-client";
-import { resolveConfig as resolveAlfeConfig } from "@alfe.ai/config";
-import { decryptSecretEnvelope, encryptSecretValue } from "./crypto.js";
-import { createRequire } from 'node:module';
-const require = createRequire(import.meta.url);
-const pkg = require('../package.json') as { version: string };
-
-interface PluginLogger {
-  info: (msg: string, ctx?: Record<string, unknown>) => void;
-  debug: (msg: string, ctx?: Record<string, unknown>) => void;
-  warn: (msg: string, ctx?: Record<string, unknown>) => void;
-  error: (msg: string, ctx?: Record<string, unknown>) => void;
-}
-
-interface ToolContext {
-  agentId?: string;
-  sessionKey?: string;
-  sessionId?: string;
-  messageChannel?: string;
-}
-
-interface Tool {
-  name: string;
-  label: string;
-  description: string;
-  parameters: Record<string, unknown>;
-  execute: (toolCallId: string, params: Record<string, unknown>) => Promise<unknown>;
-}
-
-interface PluginApi {
-  pluginConfig?: Record<string, unknown>;
-  config: Record<string, unknown>;
-  logger: PluginLogger;
-  registerTool: (factory: (ctx: ToolContext) => Tool, opts?: { names?: string[] }) => void;
-  registerHook?: (events: string | string[], handler: (...args: unknown[]) => unknown, opts?: { name?: string; description?: string }) => void;
-  on?: (hookName: string, handler: (...args: unknown[]) => unknown, opts?: { priority?: number }) => void;
-  registerMemoryPromptSupplement?: (builder: (params: { availableTools: Set<string> }) => string[]) => void;
-}
-
-const VALID_SCOPES: SecretScope[] = ["org", "team", "project", "agent"];
-const VALID_CATEGORIES: SecretCategory[] = [
-  "login", "api_key", "database", "ssh_key", "certificate",
-  "secure_note", "credit_card", "identity", "wifi", "other",
-];
-const VALID_FORMATS: FieldFormat[] = ["text", "email", "url", "phone", "date", "number", "json"];
-const VALID_SENSITIVITIES: FieldSensitivity[] = ["plaintext", "encrypted"];
-const FIELD_KEY_REGEX = /^[a-zA-Z0-9_./-]{1,64}$/;
-const UUID_V4 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-
-function parseScope(raw: unknown, field = "scope"): SecretScope {
-  if (typeof raw !== "string" || !VALID_SCOPES.includes(raw as SecretScope)) {
-    throw new Error(`${field} must be one of ${VALID_SCOPES.join(", ")}`);
-  }
-  return raw as SecretScope;
-}
-
-function parseString(raw: unknown, field: string, max = 256): string {
-  if (typeof raw !== "string" || raw.length === 0) {
-    throw new Error(`${field} is required`);
-  }
-  if (raw.length > max) {
-    throw new Error(`${field} must be ${String(max)} characters or fewer`);
-  }
-  return raw;
-}
-
-// Re-export the local-friendly type alias so the rest of the file
-// continues to refer to ToolContext (which has agentId? on it). The
-// scope-resolve helper is structurally compatible.
-import { resolveScopeId, SCOPE_ID_DESCRIPTION } from "./scope-resolve.js";
-
-function parseSecretName(raw: unknown): string {
-  // `name` is a free-form, user-friendly label (not an identifier) — allow any
-  // non-empty string up to 128 chars. The unique identifier is `secretId`.
-  return parseString(raw, "name", 128);
-}
-
-function parseFieldKey(raw: unknown): string {
-  const s = parseString(raw, "key", 64);
-  if (!FIELD_KEY_REGEX.test(s)) {
-    throw new Error("field key must match ^[a-zA-Z0-9_./-]{1,64}$");
-  }
-  return s;
-}
-
-function parseSecretId(raw: unknown): string {
-  const s = parseString(raw, "secretId", 64);
-  if (!UUID_V4.test(s)) throw new Error("secretId must be a UUID v4");
-  return s;
-}
-
-function parseFields(raw: unknown): Field[] {
-  if (!Array.isArray(raw) || raw.length === 0) {
-    throw new Error("fields must be a non-empty array");
-  }
-  if (raw.length > 32) throw new Error("fields cannot exceed 32 entries");
-  return raw.map((f, i) => {
-    if (typeof f !== "object" || f === null) throw new Error(`fields[${String(i)}] must be an object`);
-    const obj = f as Record<string, unknown>;
-    const key = parseFieldKey(obj.key);
-    const sensitivity = (() => {
-      if (typeof obj.sensitivity !== "string" || !VALID_SENSITIVITIES.includes(obj.sensitivity as FieldSensitivity)) {
-        throw new Error(`fields[${String(i)}].sensitivity must be 'plaintext' or 'encrypted'`);
-      }
-      return obj.sensitivity as FieldSensitivity;
-    })();
-    const format = (() => {
-      if (obj.format === undefined) return undefined;
-      if (typeof obj.format !== "string" || !VALID_FORMATS.includes(obj.format as FieldFormat)) {
-        throw new Error(`fields[${String(i)}].format must be one of ${VALID_FORMATS.join(", ")}`);
-      }
-      return obj.format as FieldFormat;
-    })();
-    if (typeof obj.value !== "string") throw new Error(`fields[${String(i)}].value must be a string`);
-    return { key, sensitivity, format, value: obj.value };
-  });
-}
-
-export default {
-  id: "@alfe.ai/openclaw-secrets",
-  name: "Secrets",
-  description: "Per-scope encrypted secret storage with multi-field aggregates, per-field rotation, and audit history.",
-  version: pkg.version,
-  kind: "secrets" as const,
-
-  register(api: PluginApi): void {
-    // First thing, before any registerTool call: tool failures emit a
-    // deterministic [ERROR] line the gateway's runtime-output monitor captures
-    // to Sentry. See @alfe.ai/agent-api-client tool-error-capture.
-    installToolErrorCapture(api, { plugin: "openclaw-secrets" });
-    const alfeConfig = resolveAlfeConfig();
-    const client = new AgentApiClient({ apiUrl: alfeConfig.apiUrl, apiKey: alfeConfig.apiKey });
-    const logger = api.logger;
-
-    if (api.registerMemoryPromptSupplement) {
-      api.registerMemoryPromptSupplement(({ availableTools }) => {
-        const lines: string[] = ["## Secrets"];
-        if (availableTools.has("secret_list_scopes")) {
-          lines.push("Use secret_list_scopes to discover scopes (org/team/project/agent) you can manage secrets in.");
-        }
-        if (availableTools.has("secret_list")) {
-          lines.push("Use secret_list to see secret metadata in a scope (filters: category, tag, fieldKey). Never returns values.");
-        }
-        if (availableTools.has("secret_get_full")) {
-          lines.push("Use secret_get_full to fetch a secret with all fields decrypted. Output is SENSITIVE — do not echo or log.");
-        }
-        if (availableTools.has("secret_get_field")) {
-          lines.push("Use secret_get_field to fetch one specific field's value (cheaper than secret_get_full when you only need one).");
-        }
-        if (availableTools.has("secret_set")) {
-          lines.push("Use secret_set to create a secret with one or more fields. Each field has sensitivity (plaintext/encrypted).");
-        }
-        if (availableTools.has("secret_set_field")) {
-          lines.push("Use secret_set_field to add a new field OR rotate an existing one — the same call handles both.");
-        }
-        return lines;
-      });
-    }
-
-    // ─── secret_list_scopes ─────────────────────────────────────
-    api.registerTool(() => ({
-      name: "secret_list_scopes",
-      label: "List Secret Scopes",
-      description: "List scopes (org/team/project/agent) the agent can manage secrets in. The returned `scopeId` values are the IDs to pass into the other secret tools — never pass the literal word \"agent\" as a scopeId; for agent scope, omit scopeId and the runtime will fill in the current agent's ID.",
-      parameters: { type: "object", properties: {} },
-      execute: async () => {
-        const scopes = await client.listSecretScopes();
-        return { scopes };
-      },
-    }), { names: ["secret_list_scopes"] });
-
-    // ─── secret_list ────────────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_list",
-      label: "List Secrets",
-      description: "List secret metadata in a scope. Optional category/tag/fieldKey filters route through the byFacet GSI.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          category: { type: "string", enum: VALID_CATEGORIES },
-          tag: { type: "string" },
-          fieldKey: { type: "string" },
-        },
-        required: ["scope"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const category = typeof params.category === "string" ? params.category as SecretCategory : undefined;
-        const tag = typeof params.tag === "string" ? params.tag : undefined;
-        const fieldKey = typeof params.fieldKey === "string" ? params.fieldKey : undefined;
-        const secrets = await client.listSecrets({ scope, scopeId, category, tag, fieldKey });
-        return { secrets };
-      },
-    }), { names: ["secret_list"] });
-
-    // ─── secret_set ─────────────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_set",
-      label: "Set Secret",
-      description: "Create a new secret with one or more fields. Encrypted fields are sealed locally before upload.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          name: { type: "string", description: "Human-readable secret name (unique within scope)" },
-          category: { type: "string", enum: VALID_CATEGORIES, description: "Defaults to 'other'" },
-          description: { type: "string" },
-          tags: { type: "array", items: { type: "string" } },
-          fields: {
-            type: "array",
-            description: "Fields to include. Each: { key, sensitivity (plaintext|encrypted), format?, value }",
-            items: {
-              type: "object",
-              properties: {
-                key: { type: "string" },
-                sensitivity: { type: "string", enum: VALID_SENSITIVITIES },
-                format: { type: "string", enum: VALID_FORMATS },
-                value: { type: "string" },
-              },
-              required: ["key", "sensitivity", "value"],
-            },
-          },
-          // Backwards-compat shorthand: { value: "..." } synthesises one
-          // encrypted field with key="value".
-          value: { type: "string", description: "Shorthand for fields=[{ key: 'value', sensitivity: 'encrypted', value }]" },
-          reason: { type: "string" },
-        },
-        required: ["scope", "name"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const name = parseSecretName(params.name);
-        const category = typeof params.category === "string"
-          ? params.category as SecretCategory
-          : undefined;
-        const description = typeof params.description === "string" ? params.description : undefined;
-        const tags = Array.isArray(params.tags)
-          ? params.tags.filter((t): t is string => typeof t === "string")
-          : undefined;
-        const reason = typeof params.reason === "string" ? params.reason : undefined;
-
-        let fields: Field[];
-        if (Array.isArray(params.fields)) {
-          fields = parseFields(params.fields);
-        } else if (typeof params.value === "string") {
-          fields = [{ key: "value", sensitivity: "encrypted", value: params.value }];
-        } else {
-          throw new Error("either `fields` or `value` is required");
-        }
-
-        const secretId = randomUUID();
-
-        // Pre-seal each encrypted field with its own data key.
-        const sealed = await Promise.all(fields.map(async (f) => {
-          if (f.sensitivity === "encrypted") {
-            const envelope = await encryptSecretValue({
-              client, scope, scopeId, secretId, fieldKey: f.key, plaintext: f.value,
-            });
-            return { ...f, value: undefined, envelope };
-          }
-          return f;
-        }));
-
-        await client.createSecret({
-          scope, scopeId, secretId,
-          secretName: name,
-          category, description, tags, reason,
-          fields: sealed,
-        });
-        logger.info("Secret created", { scope, scopeId, secretId, fieldCount: fields.length });
-        return { secretId };
-      },
-    }), { names: ["secret_set"] });
-
-    // ─── secret_get (legacy: returns `value` field plaintext as a string) ──
-    api.registerTool((ctx) => ({
-      name: "secret_get",
-      label: "Get Secret (Legacy)",
-      description: "Fetch and decrypt the `value`-keyed field. The output is SENSITIVE; do not echo or log.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-        },
-        required: ["scope", "secretId"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        const field = await client.getSecretField({ scope, scopeId, secretId, fieldKey: "value" });
-        if (field.sensitivity === "plaintext") {
-          return { secretId, value: field.value };
-        }
-        if (!field.envelope) throw new Error("encrypted field has no envelope");
-        const plaintext = await decryptSecretEnvelope({
-          client, scope, scopeId, secretId, fieldKey: "value", envelope: field.envelope,
-        });
-        return { secretId, value: plaintext };
-      },
-    }), { names: ["secret_get"] });
-
-    // ─── secret_get_full ────────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_get_full",
-      label: "Get Secret (All Fields)",
-      description: "Fetch the secret aggregate with all fields decrypted. Output is SENSITIVE.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-        },
-        required: ["scope", "secretId"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        const { aggregate, envelopes } = await client.getSecret({ scope, scopeId, secretId });
-
-        const decryptedFields = await Promise.all(aggregate.fields.map(async (f) => {
-          if (f.sensitivity === "plaintext") {
-            return { key: f.key, sensitivity: f.sensitivity, format: f.format, value: f.value };
-          }
-          const envelope = envelopes.find((e) => e.key === f.key)?.envelope;
-          if (!envelope) return { key: f.key, sensitivity: f.sensitivity, format: f.format, error: "envelope missing" };
-          const plaintext = await decryptSecretEnvelope({
-            client, scope, scopeId, secretId, fieldKey: f.key, envelope,
-          });
-          return { key: f.key, sensitivity: f.sensitivity, format: f.format, value: plaintext };
-        }));
-
-        return {
-          secretId,
-          secretName: aggregate.secretName,
-          description: aggregate.description,
-          tags: aggregate.tags,
-          category: aggregate.category,
-          fields: decryptedFields,
-        };
-      },
-    }), { names: ["secret_get_full"] });
-
-    // ─── secret_get_field ───────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_get_field",
-      label: "Get Secret Field",
-      description: "Fetch and decrypt one field by key. Cheaper than secret_get_full when you only need one piece.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-          fieldKey: { type: "string" },
-        },
-        required: ["scope", "secretId", "fieldKey"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        const fieldKey = parseFieldKey(params.fieldKey);
-        const field = await client.getSecretField({ scope, scopeId, secretId, fieldKey });
-        if (field.sensitivity === "plaintext") {
-          return { key: field.key, sensitivity: field.sensitivity, format: field.format, value: field.value };
-        }
-        if (!field.envelope) throw new Error("encrypted field has no envelope");
-        const plaintext = await decryptSecretEnvelope({
-          client, scope, scopeId, secretId, fieldKey, envelope: field.envelope,
-        });
-        return { key: field.key, sensitivity: field.sensitivity, format: field.format, value: plaintext };
-      },
-    }), { names: ["secret_get_field"] });
-
-    // ─── secret_set_field ───────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_set_field",
-      label: "Set Secret Field",
-      description: "Add OR rotate one field. Same key as existing = rotate; new key = add. Encrypted fields are sealed locally.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-          fieldKey: { type: "string" },
-          sensitivity: { type: "string", enum: VALID_SENSITIVITIES },
-          format: { type: "string", enum: VALID_FORMATS },
-          value: { type: "string" },
-          reason: { type: "string" },
-        },
-        required: ["scope", "secretId", "fieldKey", "sensitivity", "value"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        const fieldKey = parseFieldKey(params.fieldKey);
-        const sensitivity = (() => {
-          if (typeof params.sensitivity !== "string" || !VALID_SENSITIVITIES.includes(params.sensitivity as FieldSensitivity)) {
-            throw new Error(`sensitivity must be one of ${VALID_SENSITIVITIES.join(", ")}`);
-          }
-          return params.sensitivity as FieldSensitivity;
-        })();
-        const format = (() => {
-          if (params.format === undefined) return undefined;
-          if (typeof params.format !== "string" || !VALID_FORMATS.includes(params.format as FieldFormat)) {
-            throw new Error(`format must be one of ${VALID_FORMATS.join(", ")}`);
-          }
-          return params.format as FieldFormat;
-        })();
-        const value = parseString(params.value, "value", 16384);
-        const reason = typeof params.reason === "string" ? params.reason : undefined;
-
-        if (sensitivity === "encrypted") {
-          const envelope = await encryptSecretValue({
-            client, scope, scopeId, secretId, fieldKey, plaintext: value,
-          });
-          const result = await client.setSecretField({
-            scope, scopeId, secretId, fieldKey,
-            sensitivity, format, envelope, reason,
-          });
-          logger.info("Encrypted field upserted", { scope, scopeId, secretId, fieldKey, rotated: result.rotated });
-          return result;
-        }
-
-        const result = await client.setSecretField({
-          scope, scopeId, secretId, fieldKey,
-          sensitivity, format, value, reason,
-        });
-        logger.info("Plaintext field upserted", { scope, scopeId, secretId, fieldKey, rotated: result.rotated });
-        return result;
-      },
-    }), { names: ["secret_set_field"] });
-
-    // ─── secret_remove_field ────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_remove_field",
-      label: "Remove Secret Field",
-      description: "Remove one field from a secret. Other fields untouched.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-          fieldKey: { type: "string" },
-        },
-        required: ["scope", "secretId", "fieldKey"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        const fieldKey = parseFieldKey(params.fieldKey);
-        await client.removeSecretField({ scope, scopeId, secretId, fieldKey });
-        logger.info("Field removed", { scope, scopeId, secretId, fieldKey });
-        return { deleted: true };
-      },
-    }), { names: ["secret_remove_field"] });
-
-    // ─── secret_update_metadata ─────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_update_metadata",
-      label: "Update Secret Metadata",
-      description: "Patch secret-level metadata (name, description, tags, category). Does not touch fields.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-          secretName: { type: "string" },
-          description: { type: "string" },
-          tags: { type: "array", items: { type: "string" } },
-          category: { type: "string", enum: VALID_CATEGORIES },
-          reason: { type: "string" },
-        },
-        required: ["scope", "secretId"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        const secretName = typeof params.secretName === "string" ? parseSecretName(params.secretName) : undefined;
-        const description = typeof params.description === "string" ? params.description : undefined;
-        const tags = Array.isArray(params.tags)
-          ? params.tags.filter((t): t is string => typeof t === "string")
-          : undefined;
-        const category = typeof params.category === "string" ? params.category as SecretCategory : undefined;
-        const reason = typeof params.reason === "string" ? params.reason : undefined;
-        return client.updateSecretMetadata({
-          scope, scopeId, secretId, secretName, description, tags, category, reason,
-        });
-      },
-    }), { names: ["secret_update_metadata"] });
-
-    // ─── secret_search ──────────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_search",
-      label: "Search Secrets",
-      description: "Find secrets by category, tag, or field key via the byFacet GSI.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          category: { type: "string", enum: VALID_CATEGORIES },
-          tag: { type: "string" },
-          fieldKey: { type: "string" },
-        },
-        required: ["scope"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const category = typeof params.category === "string" ? params.category as SecretCategory : undefined;
-        const tag = typeof params.tag === "string" ? params.tag : undefined;
-        const fieldKey = typeof params.fieldKey === "string" ? params.fieldKey : undefined;
-        const secrets = await client.listSecrets({ scope, scopeId, category, tag, fieldKey });
-        return { secrets };
-      },
-    }), { names: ["secret_search"] });
-
-    // ─── secret_get_history ─────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_get_history",
-      label: "Get Secret History",
-      description: "Bounded changelog read — metadata-only audit entries (no field values).",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-          limit: { type: "number" },
-          cursor: { type: "string" },
-        },
-        required: ["scope", "secretId"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        const limit = typeof params.limit === "number" ? params.limit : undefined;
-        const cursor = typeof params.cursor === "string" ? params.cursor : undefined;
-        return client.getSecretHistory({ scope, scopeId, secretId, limit, cursor });
-      },
-    }), { names: ["secret_get_history"] });
-
-    // ─── secret_delete ──────────────────────────────────────────
-    api.registerTool((ctx) => ({
-      name: "secret_delete",
-      label: "Delete Secret",
-      description: "Delete a secret and all its fields, tags, and changelog rows.",
-      parameters: {
-        type: "object",
-        properties: {
-          scope: { type: "string", enum: VALID_SCOPES },
-          scopeId: { type: "string", description: SCOPE_ID_DESCRIPTION },
-          secretId: { type: "string" },
-        },
-        required: ["scope", "secretId"],
-      },
-      execute: async (_id, params) => {
-        const scope = parseScope(params.scope);
-        const scopeId = resolveScopeId(scope, params, ctx);
-        const secretId = parseSecretId(params.secretId);
-        await client.deleteSecret({ scope, scopeId, secretId });
-        logger.info("Secret deleted", { scope, scopeId, secretId });
-        return { deleted: true };
-      },
-    }), { names: ["secret_delete"] });
-
-    logger.info("openclaw-secrets plugin registered");
-  },
-};

package/src/scope-resolve.ts

@@ -1,62 +0,0 @@
-import type { SecretScope } from "@alfe.ai/agent-api-client";
-
-export interface ToolContextLike {
-  agentId?: string;
-}
-
-/**
- * Resolve `scopeId` for a tool call.
- *
- * For `scope === "agent"` the canonical value is the current agent's own ID.
- * Agents only ever operate on their own per-agent scope (the server enforces
- * via requireAgentSelfScope). We accept three inputs and normalise to the
- * agent's ID:
- *
- *   - omitted or empty                 → fill from ctx.agentId
- *   - the literal string "agent"        → fill from ctx.agentId (LLM mistake)
- *   - a real ID (e.g. "agt_…")          → use as-is
- *
- * Other scopes (org/team/project) require an explicit scopeId from the
- * `secret_list_scopes` tool — they have no sensible default.
- */
-export function resolveScopeId(
-  scope: SecretScope,
-  params: Record<string, unknown>,
-  ctx: ToolContextLike,
-): string {
-  if (scope === "agent") {
-    const explicit =
-      typeof params.scopeId === "string" &&
-      params.scopeId !== "agent" &&
-      params.scopeId.length > 0
-        ? params.scopeId
-        : undefined;
-    const fallback = ctx.agentId;
-    // Prefer the runtime's canonical agentId. If the LLM supplied an id that
-    // matches it case-insensitively (e.g. a lowercased ULID), normalise to the
-    // canonical casing so the server's exact-match self-scope check passes.
-    if (
-      fallback &&
-      (!explicit || explicit.toLowerCase() === fallback.toLowerCase())
-    ) {
-      return fallback;
-    }
-    const resolved = explicit ?? fallback ?? "";
-    if (!resolved) {
-      throw new Error(
-        "agent scope requires either ctx.agentId from the runtime or an explicit agent scopeId from secret_list_scopes",
-      );
-    }
-    return resolved;
-  }
-  if (typeof params.scopeId !== "string" || params.scopeId.length === 0) {
-    throw new Error("scopeId is required");
-  }
-  if (params.scopeId.length > 256) {
-    throw new Error("scopeId must be 256 characters or fewer");
-  }
-  return params.scopeId;
-}
-
-export const SCOPE_ID_DESCRIPTION =
-  "For org/team/project scope: the concrete ID from `secret_list_scopes`. For agent scope: optional — defaults to the current agent's own ID. Never pass the literal word \"agent\" as the ID; pass the real agent ID (or omit it).";