@alfe.ai/openclaw-secrets 0.1.9 → 0.1.11

package/src/index.ts

@@ -2,27 +2,39 @@
  * openclaw-secrets — OpenClaw plugin for per-scope encrypted secret storage.
  *
  * Trust model:
- *   - Secret values are encrypted and decrypted ON THIS AGENT using AES-256-GCM.
- *   - Data keys are issued per-secret by the Alfe secrets service; plaintext keys
- *     are held as Buffers only, used once, and zeroed immediately.
- *   - The backend never sees plaintext secret values (the dashboard can set values
- *     through a server-side encrypt path but cannot read them back).
- *
- * All HTTP traffic goes through `@alfe.ai/agent-api-client` — the single
- * canonical agent-side HTTP client — so routes, auth, and response unwrapping
- * stay in lockstep with every other agent endpoint.
+ *   - 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_set           — create a new secret (mints UUID, encrypts, uploads envelope)
- *   - secret_get           — fetch + decrypt plaintext by secretId
- *   - secret_get_by_name   — list then get (convenience)
- *   - secret_list          — list metadata in a scope (never plaintext)
- *   - secret_list_scopes   — enumerate scopes the agent can access
- *   - secret_delete        — delete a secret
- *   - secret_rotate        — re-encrypt with a fresh data key
+ *   - 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, type SecretScope } from "@alfe.ai/agent-api-client";
+import {
+  AgentApiClient,
+  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';
@@ -62,10 +74,16 @@ interface PluginApi {
 }
 
 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 NAME_REGEX = /^[a-zA-Z0-9_./-]{1,128}$/;
+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(", ")}`);
@@ -91,16 +109,51 @@ function parseSecretName(raw: unknown): string {
   return s;
 }
 
+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: "secrets",
   name: "Secrets",
-  description: "Per-scope encrypted secret storage — agent-side AES-256-GCM with KMS-issued data keys.",
+  description: "Per-scope encrypted secret storage with multi-field aggregates, per-field rotation, and audit history.",
   version: pkg.version,
   kind: "secrets" as const,
 
@@ -113,16 +166,22 @@ export default {
       api.registerMemoryPromptSection(({ availableTools }) => {
         const lines: string[] = ["## Secrets"];
         if (availableTools.has("secret_list_scopes")) {
-          lines.push("Use secret_list_scopes to discover which scopes (org/team/project/agent) you can manage secrets in.");
+          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 names in a scope. secret_list NEVER returns plaintext.");
+          lines.push("Use secret_list to see secret metadata in a scope (filters: category, tag, fieldKey). Never returns values.");
         }
-        if (availableTools.has("secret_get")) {
-          lines.push("Use secret_get to retrieve a plaintext secret value. The output is SENSITIVE — do not echo it to the user or log it.");
+        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 or update a secret. Prefer scoping to 'agent' for personal secrets.");
+          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;
       });
@@ -132,7 +191,7 @@ export default {
     api.registerTool(() => ({
       name: "secret_list_scopes",
       label: "List Secret Scopes",
-      description: "List scopes (org/team/project/agent) the agent can manage secrets in. Use this before guessing scopeIds.",
+      description: "List scopes (org/team/project/agent) the agent can manage secrets in.",
       parameters: { type: "object", properties: {} },
       execute: async () => {
         const scopes = await client.listSecretScopes();
@@ -144,19 +203,25 @@ export default {
     api.registerTool(() => ({
       name: "secret_list",
       label: "List Secrets",
-      description: "List secret metadata (never plaintext) in a given scope.",
+      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, description: "Scope level" },
-          scopeId: { type: "string", description: "Scope identifier (tenantId / teamId / projectId / agentId)" },
+          scope: { type: "string", enum: VALID_SCOPES },
+          scopeId: { type: "string" },
+          category: { type: "string", enum: VALID_CATEGORIES },
+          tag: { type: "string" },
+          fieldKey: { type: "string" },
         },
         required: ["scope", "scopeId"],
       },
       execute: async (_id, params) => {
         const scope = parseScope(params.scope);
         const scopeId = parseString(params.scopeId, "scopeId");
-        const secrets = await client.listSecrets({ scope, scopeId });
+        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"] });
@@ -165,62 +230,94 @@ export default {
     api.registerTool(() => ({
       name: "secret_set",
       label: "Set Secret",
-      description: "Create a new secret. Encrypts the value locally and uploads only the envelope.",
+      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, description: "Scope level" },
-          scopeId: { type: "string", description: "Scope identifier" },
+          scope: { type: "string", enum: VALID_SCOPES },
+          scopeId: { type: "string" },
           name: { type: "string", description: "Human-readable secret name (unique within scope)" },
-          value: { type: "string", description: "Secret plaintext value (encrypted before upload)" },
-          description: { type: "string", description: "Optional description" },
-          tags: { type: "array", items: { type: "string" }, description: "Optional tags" },
+          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", "scopeId", "name", "value"],
+        required: ["scope", "scopeId", "name"],
       },
       execute: async (_id, params) => {
         const scope = parseScope(params.scope);
         const scopeId = parseString(params.scopeId, "scopeId");
         const name = parseSecretName(params.name);
-        const value = parseString(params.value, "value", 65_536);
+        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();
 
-        const envelope = await encryptSecretValue({
-          client,
-          scope,
-          scopeId,
-          secretId,
-          plaintext: value,
-        });
-        await client.putSecretEnvelope({
-          scope,
-          scopeId,
-          secretId,
+        // 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,
-          envelope,
-          description,
-          tags,
+          category, description, tags, reason,
+          fields: sealed,
         });
-        logger.info("Secret created", { scope, scopeId, secretId });
+        logger.info("Secret created", { scope, scopeId, secretId, fieldCount: fields.length });
         return { secretId };
       },
     }), { names: ["secret_set"] });
 
-    // ─── secret_get ─────────────────────────────────────────────
+    // ─── secret_get (legacy: returns `value` field plaintext as a string) ──
     api.registerTool(() => ({
       name: "secret_get",
-      label: "Get Secret",
-      description: "Fetch and decrypt a secret by secretId. The return value is SENSITIVE; do not echo or log it.",
+      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" },
-          secretId: { type: "string", description: "UUID v4 of the secret" },
+          secretId: { type: "string" },
         },
         required: ["scope", "scopeId", "secretId"],
       },
@@ -228,121 +325,292 @@ export default {
         const scope = parseScope(params.scope);
         const scopeId = parseString(params.scopeId, "scopeId");
         const secretId = parseSecretId(params.secretId);
-        const row = await client.getSecretEnvelope({ scope, scopeId, 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,
-          envelope: row.envelope,
+          client, scope, scopeId, secretId, fieldKey: "value", envelope: field.envelope,
         });
+        return { secretId, value: plaintext };
+      },
+    }), { names: ["secret_get"] });
+
+    // ─── secret_get_full ────────────────────────────────────────
+    api.registerTool(() => ({
+      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" },
+          secretId: { type: "string" },
+        },
+        required: ["scope", "scopeId", "secretId"],
+      },
+      execute: async (_id, params) => {
+        const scope = parseScope(params.scope);
+        const scopeId = parseString(params.scopeId, "scopeId");
+        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: row.secretName,
-          value: plaintext,
+          secretName: aggregate.secretName,
+          description: aggregate.description,
+          tags: aggregate.tags,
+          category: aggregate.category,
+          fields: decryptedFields,
         };
       },
-    }), { names: ["secret_get"] });
+    }), { names: ["secret_get_full"] });
 
-    // ─── secret_get_by_name ─────────────────────────────────────
+    // ─── secret_get_field ───────────────────────────────────────
     api.registerTool(() => ({
-      name: "secret_get_by_name",
-      label: "Get Secret By Name",
-      description: "Fetch a secret by its human-readable name. Convenience wrapper around secret_list + secret_get.",
+      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" },
-          name: { type: "string" },
+          secretId: { type: "string" },
+          fieldKey: { type: "string" },
         },
-        required: ["scope", "scopeId", "name"],
+        required: ["scope", "scopeId", "secretId", "fieldKey"],
       },
       execute: async (_id, params) => {
         const scope = parseScope(params.scope);
         const scopeId = parseString(params.scopeId, "scopeId");
-        const name = parseSecretName(params.name);
-        const secrets = await client.listSecrets({ scope, scopeId });
-        const match = secrets.find((s) => s.secretName === name);
-        if (!match) return { found: false };
-        const row = await client.getSecretEnvelope({ scope, scopeId, secretId: match.secretId });
+        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: match.secretId,
-          envelope: row.envelope,
+          client, scope, scopeId, secretId, fieldKey, envelope: field.envelope,
         });
-        return { found: true, secretId: match.secretId, secretName: match.secretName, value: plaintext };
+        return { key: field.key, sensitivity: field.sensitivity, format: field.format, value: plaintext };
       },
-    }), { names: ["secret_get_by_name"] });
+    }), { names: ["secret_get_field"] });
 
-    // ─── secret_delete ──────────────────────────────────────────
+    // ─── secret_set_field ───────────────────────────────────────
     api.registerTool(() => ({
-      name: "secret_delete",
-      label: "Delete Secret",
-      description: "Delete a secret by secretId.",
+      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" },
           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", "scopeId", "secretId"],
+        required: ["scope", "scopeId", "secretId", "fieldKey", "sensitivity", "value"],
       },
       execute: async (_id, params) => {
         const scope = parseScope(params.scope);
         const scopeId = parseString(params.scopeId, "scopeId");
         const secretId = parseSecretId(params.secretId);
-        await client.deleteSecret({ scope, scopeId, secretId });
-        logger.info("Secret deleted", { scope, scopeId, secretId });
-        return { deleted: true };
+        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_delete"] });
+    }), { names: ["secret_set_field"] });
 
-    // ─── secret_rotate ──────────────────────────────────────────
+    // ─── secret_remove_field ────────────────────────────────────
     api.registerTool(() => ({
-      name: "secret_rotate",
-      label: "Rotate Secret",
-      description: "Replace an existing secret's value with a new one. Issues a fresh data key and re-encrypts.",
+      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" },
           secretId: { type: "string" },
-          newValue: { type: "string", description: "The new plaintext value" },
+          fieldKey: { type: "string" },
         },
-        required: ["scope", "scopeId", "secretId", "newValue"],
+        required: ["scope", "scopeId", "secretId", "fieldKey"],
       },
       execute: async (_id, params) => {
         const scope = parseScope(params.scope);
         const scopeId = parseString(params.scopeId, "scopeId");
         const secretId = parseSecretId(params.secretId);
-        const newValue = parseString(params.newValue, "newValue", 65_536);
+        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"] });
 
-        const existing = await client.getSecretEnvelope({ scope, scopeId, secretId });
-        const envelope = await encryptSecretValue({
-          client,
-          scope,
-          scopeId,
-          secretId,
-          plaintext: newValue,
-        });
-        await client.putSecretEnvelope({
-          scope,
-          scopeId,
-          secretId,
-          secretName: existing.secretName,
-          envelope,
-          description: existing.description,
-          tags: existing.tags,
+    // ─── secret_update_metadata ─────────────────────────────────
+    api.registerTool(() => ({
+      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" },
+          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", "scopeId", "secretId"],
+      },
+      execute: async (_id, params) => {
+        const scope = parseScope(params.scope);
+        const scopeId = parseString(params.scopeId, "scopeId");
+        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,
         });
-        logger.info("Secret rotated", { scope, scopeId, secretId });
-        return { secretId, rotated: true };
       },
-    }), { names: ["secret_rotate"] });
+    }), { names: ["secret_update_metadata"] });
+
+    // ─── secret_search ──────────────────────────────────────────
+    api.registerTool(() => ({
+      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" },
+          category: { type: "string", enum: VALID_CATEGORIES },
+          tag: { type: "string" },
+          fieldKey: { type: "string" },
+        },
+        required: ["scope", "scopeId"],
+      },
+      execute: async (_id, params) => {
+        const scope = parseScope(params.scope);
+        const scopeId = parseString(params.scopeId, "scopeId");
+        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(() => ({
+      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" },
+          secretId: { type: "string" },
+          limit: { type: "number" },
+          cursor: { type: "string" },
+        },
+        required: ["scope", "scopeId", "secretId"],
+      },
+      execute: async (_id, params) => {
+        const scope = parseScope(params.scope);
+        const scopeId = parseString(params.scopeId, "scopeId");
+        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(() => ({
+      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" },
+          secretId: { type: "string" },
+        },
+        required: ["scope", "scopeId", "secretId"],
+      },
+      execute: async (_id, params) => {
+        const scope = parseScope(params.scope);
+        const scopeId = parseString(params.scopeId, "scopeId");
+        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");
   },