@alfe.ai/openclaw-secrets 0.1.9 → 0.1.11

package/dist/index.js

@@ -2,34 +2,46 @@
  * 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 } from "@alfe.ai/agent-api-client";
+import { AgentApiClient, } 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');
 const VALID_SCOPES = ["org", "team", "project", "agent"];
+const VALID_CATEGORIES = [
+    "login", "api_key", "database", "ssh_key", "certificate",
+    "secure_note", "credit_card", "identity", "wifi", "other",
+];
+const VALID_FORMATS = ["text", "email", "url", "phone", "date", "number", "json"];
+const VALID_SENSITIVITIES = ["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, field = "scope") {
     if (typeof raw !== "string" || !VALID_SCOPES.includes(raw)) {
@@ -53,16 +65,53 @@ function parseSecretName(raw) {
     }
     return s;
 }
+function parseFieldKey(raw) {
+    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) {
     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) {
+    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;
+        const key = parseFieldKey(obj.key);
+        const sensitivity = (() => {
+            if (typeof obj.sensitivity !== "string" || !VALID_SENSITIVITIES.includes(obj.sensitivity)) {
+                throw new Error(`fields[${String(i)}].sensitivity must be 'plaintext' or 'encrypted'`);
+            }
+            return obj.sensitivity;
+        })();
+        const format = (() => {
+            if (obj.format === undefined)
+                return undefined;
+            if (typeof obj.format !== "string" || !VALID_FORMATS.includes(obj.format)) {
+                throw new Error(`fields[${String(i)}].format must be one of ${VALID_FORMATS.join(", ")}`);
+            }
+            return obj.format;
+        })();
+        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",
     register(api) {
@@ -73,16 +122,22 @@ export default {
             api.registerMemoryPromptSection(({ availableTools }) => {
                 const lines = ["## 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;
             });
@@ -91,7 +146,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();
@@ -102,19 +157,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 : 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"] });
@@ -122,60 +183,91 @@ 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
+                    : undefined;
                 const description = typeof params.description === "string" ? params.description : undefined;
                 const tags = Array.isArray(params.tags)
                     ? params.tags.filter((t) => typeof t === "string")
                     : undefined;
+                const reason = typeof params.reason === "string" ? params.reason : undefined;
+                let fields;
+                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"],
             },
@@ -183,118 +275,284 @@ 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"] });
-        // ─── secret_get_by_name ─────────────────────────────────────
+        }), { names: ["secret_get_full"] });
+        // ─── 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"] });
-        // ─── secret_delete ──────────────────────────────────────────
+        }), { names: ["secret_get_field"] });
+        // ─── 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 });
+                const fieldKey = parseFieldKey(params.fieldKey);
+                const sensitivity = (() => {
+                    if (typeof params.sensitivity !== "string" || !VALID_SENSITIVITIES.includes(params.sensitivity)) {
+                        throw new Error(`sensitivity must be one of ${VALID_SENSITIVITIES.join(", ")}`);
+                    }
+                    return params.sensitivity;
+                })();
+                const format = (() => {
+                    if (params.format === undefined)
+                        return undefined;
+                    if (typeof params.format !== "string" || !VALID_FORMATS.includes(params.format)) {
+                        throw new Error(`format must be one of ${VALID_FORMATS.join(", ")}`);
+                    }
+                    return params.format;
+                })();
+                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(() => ({
+            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" },
+                    fieldKey: { type: "string" },
+                },
+                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 fieldKey = parseFieldKey(params.fieldKey);
+                await client.removeSecretField({ scope, scopeId, secretId, fieldKey });
+                logger.info("Field removed", { scope, scopeId, secretId, fieldKey });
                 return { deleted: true };
             },
-        }), { names: ["secret_delete"] });
-        // ─── secret_rotate ──────────────────────────────────────────
+        }), { names: ["secret_remove_field"] });
+        // ─── secret_update_metadata ─────────────────────────────────
         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_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" },
-                    newValue: { type: "string", description: "The new plaintext value" },
+                    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", "newValue"],
+                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 newValue = parseString(params.newValue, "newValue", 65_536);
-                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,
+                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) => typeof t === "string")
+                    : undefined;
+                const category = typeof params.category === "string" ? params.category : 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 : 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");
     },
 };