@alfe.ai/openclaw-secrets 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @alfe.ai/openclaw-secrets@0.1.0 build /home/runner/work/alfe/alfe/packages/openclaw-secrets
+> tsc
+

package/dist/crypto.d.ts

@@ -0,0 +1,39 @@
+import type { EncryptedEnvelopeV1, SecretScope } from "@alfe.ai/agent-api-client";
+/**
+ * Narrow interface capturing just the two KMS-proxy methods the crypto
+ * helpers need. `AgentApiClient` satisfies this; tests can supply a
+ * hand-rolled stub without mocking the whole client surface.
+ */
+export interface SecretsKmsProxy {
+    generateSecretDataKey(args: {
+        scope: SecretScope;
+        scopeId: string;
+        secretId: string;
+    }): Promise<{
+        plaintextKey: string;
+        dataKeyCiphertext: string;
+    }>;
+    decryptSecretDataKey(args: {
+        scope: SecretScope;
+        scopeId: string;
+        secretId: string;
+        dataKeyCiphertext: string;
+    }): Promise<{
+        plaintextKey: string;
+    }>;
+}
+export declare function encryptSecretValue(args: {
+    client: SecretsKmsProxy;
+    scope: SecretScope;
+    scopeId: string;
+    secretId: string;
+    plaintext: string;
+}): Promise<EncryptedEnvelopeV1>;
+export declare function decryptSecretEnvelope(args: {
+    client: SecretsKmsProxy;
+    scope: SecretScope;
+    scopeId: string;
+    secretId: string;
+    envelope: EncryptedEnvelopeV1;
+}): Promise<string>;
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAElF;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,qBAAqB,CAAC,IAAI,EAAE;QAC1B,KAAK,EAAE,WAAW,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEjE,oBAAoB,CAAC,IAAI,EAAE;QACzB,KAAK,EAAE,WAAW,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,iBAAiB,EAAE,MAAM,CAAC;KAC3B,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACvC;AAcD,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAwB/B;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,MAAM,EAAE,eAAe,CAAC;IACxB,KAAK,EAAE,WAAW,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,mBAAmB,CAAC;CAC/B,GAAG,OAAO,CAAC,MAAM,CAAC,CAqBlB"}

package/dist/crypto.js

@@ -0,0 +1,73 @@
+/**
+ * Agent-side AES-256-GCM with data keys issued by the Alfe secrets service.
+ *
+ * Trust model:
+ *   - The agent NEVER holds a KMS key directly.
+ *   - For each encrypt/decrypt, the agent fetches a one-shot AES data key from
+ *     the secrets service over authenticated TLS.
+ *   - The plaintext key is held as a `Buffer` ONLY — never as a JS string.
+ *     (Strings are immutable and cannot be zeroed; Buffers can be `.fill(0)`'d.)
+ *   - After each operation the Buffer is zeroed.
+ *
+ * Envelope format is `EncryptedEnvelopeV1` as defined in `@alfe/types` and
+ * persisted by services/secrets.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+const AES_256_KEY_BYTES = 32;
+const GCM_IV_BYTES = 12;
+function decodeKeyToBuffer(base64) {
+    const buf = Buffer.from(base64, "base64");
+    if (buf.length !== AES_256_KEY_BYTES) {
+        buf.fill(0);
+        throw new Error(`Unexpected data key length: ${String(buf.length)} bytes`);
+    }
+    return buf;
+}
+export async function encryptSecretValue(args) {
+    const { client, scope, scopeId, secretId, plaintext } = args;
+    const { plaintextKey, dataKeyCiphertext } = await client.generateSecretDataKey({
+        scope,
+        scopeId,
+        secretId,
+    });
+    const keyBuf = decodeKeyToBuffer(plaintextKey);
+    try {
+        const iv = randomBytes(GCM_IV_BYTES);
+        const cipher = createCipheriv("aes-256-gcm", keyBuf, iv);
+        const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+        const authTag = cipher.getAuthTag();
+        return {
+            version: 1,
+            iv: iv.toString("base64"),
+            ciphertext: ciphertext.toString("base64"),
+            authTag: authTag.toString("base64"),
+            dataKeyCiphertext,
+        };
+    }
+    finally {
+        keyBuf.fill(0);
+    }
+}
+export async function decryptSecretEnvelope(args) {
+    const { client, scope, scopeId, secretId, envelope } = args;
+    const { plaintextKey } = await client.decryptSecretDataKey({
+        scope,
+        scopeId,
+        secretId,
+        dataKeyCiphertext: envelope.dataKeyCiphertext,
+    });
+    const keyBuf = decodeKeyToBuffer(plaintextKey);
+    try {
+        const iv = Buffer.from(envelope.iv, "base64");
+        const ciphertext = Buffer.from(envelope.ciphertext, "base64");
+        const authTag = Buffer.from(envelope.authTag, "base64");
+        const decipher = createDecipheriv("aes-256-gcm", keyBuf, iv);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return decrypted.toString("utf8");
+    }
+    finally {
+        keyBuf.fill(0);
+    }
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,47 @@
+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;
+    registerMemoryPromptSection?: (builder: (params: {
+        availableTools: Set<string>;
+    }) => string[]) => void;
+}
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    version: string;
+    kind: "secrets";
+    register(api: PluginApi): void;
+};
+export default _default;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA4BA,UAAU,YAAY;IACpB,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5D,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC3D,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAC7D;AAED,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,IAAI;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACpF;AAED,UAAU,SAAS;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,YAAY,CAAC;IACrB,YAAY,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,KAAK,IAAI,CAAC;IACzF,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAC7I,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IACxG,2BAA2B,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE;QAAE,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;KAAE,KAAK,MAAM,EAAE,KAAK,IAAI,CAAC;CACxG;;;;;;;kBAuDe,SAAS,GAAG,IAAI;;AAPhC,wBAyPE"}

package/dist/index.js

@@ -0,0 +1,309 @@
+/**
+ * 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.
+ *
+ * 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
+ */
+import { randomUUID } from "node:crypto";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { decryptSecretEnvelope, encryptSecretValue } from "./crypto.js";
+const VALID_SCOPES = ["org", "team", "project", "agent"];
+const NAME_REGEX = /^[a-zA-Z0-9_./-]{1,128}$/;
+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 resolveConfig(raw) {
+    // Match @alfe.ai/agent-api-client's config shape. agentId and tenantId are
+    // resolved server-side from the bearer token, so we intentionally don't
+    // accept them here — reading caller-supplied identity would be a footgun.
+    const apiUrl = typeof raw?.apiUrl === "string" ? raw.apiUrl : (process.env.ALFE_API_URL ?? "");
+    const agentApiKey = typeof raw?.agentApiKey === "string" ? raw.agentApiKey : "";
+    if (!apiUrl)
+        throw new Error("openclaw-secrets: apiUrl (or ALFE_API_URL) is required");
+    if (!agentApiKey)
+        throw new Error("openclaw-secrets: agentApiKey is required");
+    return { apiUrl, agentApiKey };
+}
+function parseScope(raw, field = "scope") {
+    if (typeof raw !== "string" || !VALID_SCOPES.includes(raw)) {
+        throw new Error(`${field} must be one of ${VALID_SCOPES.join(", ")}`);
+    }
+    return raw;
+}
+function parseString(raw, field, max = 256) {
+    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;
+}
+function parseSecretName(raw) {
+    const s = parseString(raw, "name", 128);
+    if (!NAME_REGEX.test(s)) {
+        throw new Error("name must match ^[a-zA-Z0-9_./-]{1,128}$");
+    }
+    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;
+}
+export default {
+    id: "secrets",
+    name: "Secrets",
+    description: "Per-scope encrypted secret storage — agent-side AES-256-GCM with KMS-issued data keys.",
+    version: "0.1.0",
+    kind: "secrets",
+    register(api) {
+        const config = resolveConfig(api.pluginConfig);
+        const client = new AgentApiClient({ apiUrl: config.apiUrl, apiKey: config.agentApiKey });
+        const logger = api.logger;
+        if (api.registerMemoryPromptSection) {
+            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.");
+                }
+                if (availableTools.has("secret_list")) {
+                    lines.push("Use secret_list to see secret names in a scope. secret_list NEVER returns plaintext.");
+                }
+                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_set")) {
+                    lines.push("Use secret_set to create or update a secret. Prefer scoping to 'agent' for personal secrets.");
+                }
+                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. Use this before guessing scopeIds.",
+            parameters: { type: "object", properties: {} },
+            execute: async () => {
+                const scopes = await client.listSecretScopes();
+                return { scopes };
+            },
+        }), { names: ["secret_list_scopes"] });
+        // ─── secret_list ────────────────────────────────────────────
+        api.registerTool(() => ({
+            name: "secret_list",
+            label: "List Secrets",
+            description: "List secret metadata (never plaintext) in a given scope.",
+            parameters: {
+                type: "object",
+                properties: {
+                    scope: { type: "string", enum: VALID_SCOPES, description: "Scope level" },
+                    scopeId: { type: "string", description: "Scope identifier (tenantId / teamId / projectId / agentId)" },
+                },
+                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 });
+                return { secrets };
+            },
+        }), { names: ["secret_list"] });
+        // ─── secret_set ─────────────────────────────────────────────
+        api.registerTool(() => ({
+            name: "secret_set",
+            label: "Set Secret",
+            description: "Create a new secret. Encrypts the value locally and uploads only the envelope.",
+            parameters: {
+                type: "object",
+                properties: {
+                    scope: { type: "string", enum: VALID_SCOPES, description: "Scope level" },
+                    scopeId: { type: "string", description: "Scope identifier" },
+                    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" },
+                },
+                required: ["scope", "scopeId", "name", "value"],
+            },
+            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 description = typeof params.description === "string" ? params.description : undefined;
+                const tags = Array.isArray(params.tags)
+                    ? params.tags.filter((t) => typeof t === "string")
+                    : undefined;
+                const secretId = randomUUID();
+                const envelope = await encryptSecretValue({
+                    client,
+                    scope,
+                    scopeId,
+                    secretId,
+                    plaintext: value,
+                });
+                await client.putSecretEnvelope({
+                    scope,
+                    scopeId,
+                    secretId,
+                    secretName: name,
+                    envelope,
+                    description,
+                    tags,
+                });
+                logger.info("Secret created", { scope, scopeId, secretId });
+                return { secretId };
+            },
+        }), { names: ["secret_set"] });
+        // ─── secret_get ─────────────────────────────────────────────
+        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.",
+            parameters: {
+                type: "object",
+                properties: {
+                    scope: { type: "string", enum: VALID_SCOPES },
+                    scopeId: { type: "string" },
+                    secretId: { type: "string", description: "UUID v4 of the secret" },
+                },
+                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 row = await client.getSecretEnvelope({ scope, scopeId, secretId });
+                const plaintext = await decryptSecretEnvelope({
+                    client,
+                    scope,
+                    scopeId,
+                    secretId,
+                    envelope: row.envelope,
+                });
+                return {
+                    secretId,
+                    secretName: row.secretName,
+                    value: plaintext,
+                };
+            },
+        }), { names: ["secret_get"] });
+        // ─── secret_get_by_name ─────────────────────────────────────
+        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.",
+            parameters: {
+                type: "object",
+                properties: {
+                    scope: { type: "string", enum: VALID_SCOPES },
+                    scopeId: { type: "string" },
+                    name: { type: "string" },
+                },
+                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 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 plaintext = await decryptSecretEnvelope({
+                    client,
+                    scope,
+                    scopeId,
+                    secretId: match.secretId,
+                    envelope: row.envelope,
+                });
+                return { found: true, secretId: match.secretId, secretName: match.secretName, value: plaintext };
+            },
+        }), { names: ["secret_get_by_name"] });
+        // ─── secret_delete ──────────────────────────────────────────
+        api.registerTool(() => ({
+            name: "secret_delete",
+            label: "Delete Secret",
+            description: "Delete a secret by secretId.",
+            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"] });
+        // ─── secret_rotate ──────────────────────────────────────────
+        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.",
+            parameters: {
+                type: "object",
+                properties: {
+                    scope: { type: "string", enum: VALID_SCOPES },
+                    scopeId: { type: "string" },
+                    secretId: { type: "string" },
+                    newValue: { type: "string", description: "The new plaintext value" },
+                },
+                required: ["scope", "scopeId", "secretId", "newValue"],
+            },
+            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,
+                });
+                logger.info("Secret rotated", { scope, scopeId, secretId });
+                return { secretId, rotated: true };
+            },
+        }), { names: ["secret_rotate"] });
+        logger.info("openclaw-secrets plugin registered", { apiUrl: config.apiUrl });
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Plugin-local types. Shared contract types (SecretScope, EncryptedEnvelopeV1,
+ * SecretMetadata, etc.) live in `@alfe/types` and are re-exported by
+ * `@alfe.ai/agent-api-client`; import from there so we have one canonical
+ * source of truth across every agent HTTP surface.
+ */
+export interface SecretsConfig {
+    /**
+     * Base URL of the Alfe API host — the same value `@alfe.ai/agent-api-client`
+     * expects (normally read from `ALFE_API_URL`), e.g. `https://api.alfe.ai`.
+     * The client prepends `/agent/secrets/*` automatically (the `/agent` segment
+     * is the agent-gateway api-mapping key; `/secrets` is the service
+     * pathPrefix). Do NOT include either segment in `apiUrl`.
+     */
+    apiUrl: string;
+    agentApiKey: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Plugin-local types. Shared contract types (SecretScope, EncryptedEnvelopeV1,
+ * SecretMetadata, etc.) live in `@alfe/types` and are re-exported by
+ * `@alfe.ai/agent-api-client`; import from there so we have one canonical
+ * source of truth across every agent HTTP surface.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/openclaw.plugin.json

@@ -0,0 +1,22 @@
+{
+  "id": "secrets",
+  "kind": "secrets",
+  "name": "Secrets",
+  "description": "Per-scope (org/team/project/agent) encrypted secret store. Agents encrypt/decrypt locally with AES-256-GCM; KMS data keys are issued by the Alfe secrets service.",
+  "version": "0.1.0",
+  "entry": "./dist/index.js",
+  "configSchema": {
+    "type": "object",
+    "required": ["apiUrl", "agentApiKey"],
+    "properties": {
+      "apiUrl": {
+        "type": "string",
+        "description": "Base URL of the Alfe API host (same as ALFE_API_URL used by @alfe.ai/agent-api-client, e.g. https://api.alfe.ai). The client prepends /agent/secrets/* automatically — pass the host root, not the agent subpath."
+      },
+      "agentApiKey": {
+        "type": "string",
+        "description": "Agent API key (Bearer). agentId and tenantId are resolved server-side from this token — do NOT pass them in config."
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@alfe.ai/openclaw-secrets",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin — per-scope (org/team/project/agent) encrypted secret store. Agents encrypt/decrypt locally with AES-256-GCM; KMS data keys are fetched via the Alfe secrets service.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@alfe.ai/agent-api-client": "0.0.7"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/src/__tests__/crypto.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Crypto roundtrip + tamper-fail tests for the openclaw-secrets plugin.
+ *
+ * We stub the narrow `SecretsKmsProxy` interface (the two KMS-proxy methods
+ * `generateSecretDataKey` / `decryptSecretDataKey`) so we don't need a real
+ * `AgentApiClient` or KMS during tests:
+ *   - generateSecretDataKey returns a deterministic (random-but-stable) AES-256 key.
+ *   - decryptSecretDataKey returns the same key for the same ciphertext handle.
+ *
+ * This lets us verify:
+ *   - happy-path encrypt → decrypt roundtrip preserves bytes,
+ *   - flipping any byte in the ciphertext / iv / authTag causes decrypt to fail,
+ *   - a mismatched data key (simulating KMS context mismatch) causes decrypt to fail,
+ *   - the Buffer passed to createCipheriv is zeroed after the call returns.
+ *
+ * We do NOT test the actual KMS proxy here — that is integration-tested
+ * against the real services/secrets.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { randomBytes } from "node:crypto";
+import { encryptSecretValue, decryptSecretEnvelope, type SecretsKmsProxy } from "../crypto.js";
+import type { EncryptedEnvelopeV1 } from "@alfe.ai/agent-api-client";
+
+function makeFakeProxy(options: {
+  /**
+   * If set, `decryptSecretDataKey` returns a DIFFERENT key than the one that
+   * was used to encrypt, simulating an encryption-context mismatch or a wrong
+   * data-key ciphertext.
+   */
+  tamperDecryptKey?: boolean;
+} = {}): SecretsKmsProxy {
+  const keysByHandle = new Map<string, Buffer>();
+  let counter = 0;
+
+  return {
+    generateSecretDataKey: vi.fn(async () => {
+      const key = randomBytes(32);
+      const handle = `handle-${String(++counter)}`;
+      keysByHandle.set(handle, key);
+      return {
+        plaintextKey: key.toString("base64"),
+        dataKeyCiphertext: handle,
+      };
+    }),
+
+    decryptSecretDataKey: vi.fn(async ({ dataKeyCiphertext }) => {
+      const key = keysByHandle.get(dataKeyCiphertext);
+      if (!key) throw new Error(`Unknown handle: ${dataKeyCiphertext}`);
+      if (options.tamperDecryptKey) {
+        return { plaintextKey: randomBytes(32).toString("base64") };
+      }
+      return { plaintextKey: key.toString("base64") };
+    }),
+  };
+}
+
+const baseArgs = {
+  scope: "agent" as const,
+  scopeId: "agent-1",
+  secretId: "00000000-0000-4000-8000-000000000000",
+};
+
+describe("crypto", () => {
+  it("roundtrip: encrypt then decrypt returns the original plaintext", async () => {
+    const client = makeFakeProxy();
+    const plaintext = "sk-live-super-secret-\u2764\ufe0f";
+
+    const envelope = await encryptSecretValue({
+      client,
+      ...baseArgs,
+      plaintext,
+    });
+
+    expect(envelope.version).toBe(1);
+    expect(envelope.iv).toBeTruthy();
+    expect(envelope.ciphertext).toBeTruthy();
+    expect(envelope.authTag).toBeTruthy();
+    expect(envelope.dataKeyCiphertext).toBeTruthy();
+
+    const recovered = await decryptSecretEnvelope({
+      client,
+      ...baseArgs,
+      envelope,
+    });
+
+    expect(recovered).toBe(plaintext);
+  });
+
+  it("encrypt produces different ciphertext each call (fresh IV + data key)", async () => {
+    const client = makeFakeProxy();
+    const [a, b] = await Promise.all([
+      encryptSecretValue({ client, ...baseArgs, plaintext: "same" }),
+      encryptSecretValue({ client, ...baseArgs, plaintext: "same" }),
+    ]);
+    expect(a.ciphertext).not.toBe(b.ciphertext);
+    expect(a.iv).not.toBe(b.iv);
+    expect(a.dataKeyCiphertext).not.toBe(b.dataKeyCiphertext);
+  });
+
+  it("rejects a ciphertext with a flipped byte (GCM authTag fails)", async () => {
+    const client = makeFakeProxy();
+    const envelope = await encryptSecretValue({
+      client,
+      ...baseArgs,
+      plaintext: "hello",
+    });
+    const ct = Buffer.from(envelope.ciphertext, "base64");
+    ct[0] = ct[0] ^ 0x01;
+    const tampered: EncryptedEnvelopeV1 = {
+      ...envelope,
+      ciphertext: ct.toString("base64"),
+    };
+
+    await expect(
+      decryptSecretEnvelope({ client, ...baseArgs, envelope: tampered }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects a flipped authTag byte", async () => {
+    const client = makeFakeProxy();
+    const envelope = await encryptSecretValue({
+      client,
+      ...baseArgs,
+      plaintext: "hello",
+    });
+    const tag = Buffer.from(envelope.authTag, "base64");
+    tag[0] = tag[0] ^ 0x80;
+
+    await expect(
+      decryptSecretEnvelope({
+        client,
+        ...baseArgs,
+        envelope: { ...envelope, authTag: tag.toString("base64") },
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects a flipped IV byte", async () => {
+    const client = makeFakeProxy();
+    const envelope = await encryptSecretValue({
+      client,
+      ...baseArgs,
+      plaintext: "hello",
+    });
+    const iv = Buffer.from(envelope.iv, "base64");
+    iv[0] = iv[0] ^ 0x11;
+
+    await expect(
+      decryptSecretEnvelope({
+        client,
+        ...baseArgs,
+        envelope: { ...envelope, iv: iv.toString("base64") },
+      }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects a decrypt that returns a different data key (encryption-context mismatch)", async () => {
+    const client = makeFakeProxy({ tamperDecryptKey: true });
+    const envelope = await encryptSecretValue({
+      client,
+      ...baseArgs,
+      plaintext: "hello",
+    });
+
+    await expect(
+      decryptSecretEnvelope({ client, ...baseArgs, envelope }),
+    ).rejects.toThrow();
+  });
+
+  it("rejects a bogus data-key length from the proxy (32 bytes required)", async () => {
+    const badClient: SecretsKmsProxy = {
+      generateSecretDataKey: vi.fn(async () => ({
+        plaintextKey: Buffer.alloc(16).toString("base64"),
+        dataKeyCiphertext: "h",
+      })),
+      decryptSecretDataKey: vi.fn(),
+    };
+
+    await expect(
+      encryptSecretValue({
+        client: badClient,
+        ...baseArgs,
+        plaintext: "hello",
+      }),
+    ).rejects.toThrow(/data key length/);
+  });
+});

package/src/crypto.ts

@@ -0,0 +1,109 @@
+/**
+ * Agent-side AES-256-GCM with data keys issued by the Alfe secrets service.
+ *
+ * Trust model:
+ *   - The agent NEVER holds a KMS key directly.
+ *   - For each encrypt/decrypt, the agent fetches a one-shot AES data key from
+ *     the secrets service over authenticated TLS.
+ *   - The plaintext key is held as a `Buffer` ONLY — never as a JS string.
+ *     (Strings are immutable and cannot be zeroed; Buffers can be `.fill(0)`'d.)
+ *   - After each operation the Buffer is zeroed.
+ *
+ * Envelope format is `EncryptedEnvelopeV1` as defined in `@alfe/types` and
+ * persisted by services/secrets.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import type { EncryptedEnvelopeV1, SecretScope } from "@alfe.ai/agent-api-client";
+
+/**
+ * Narrow interface capturing just the two KMS-proxy methods the crypto
+ * helpers need. `AgentApiClient` satisfies this; tests can supply a
+ * hand-rolled stub without mocking the whole client surface.
+ */
+export interface SecretsKmsProxy {
+  generateSecretDataKey(args: {
+    scope: SecretScope;
+    scopeId: string;
+    secretId: string;
+  }): Promise<{ plaintextKey: string; dataKeyCiphertext: string }>;
+
+  decryptSecretDataKey(args: {
+    scope: SecretScope;
+    scopeId: string;
+    secretId: string;
+    dataKeyCiphertext: string;
+  }): Promise<{ plaintextKey: string }>;
+}
+
+const AES_256_KEY_BYTES = 32;
+const GCM_IV_BYTES = 12;
+
+function decodeKeyToBuffer(base64: string): Buffer {
+  const buf = Buffer.from(base64, "base64");
+  if (buf.length !== AES_256_KEY_BYTES) {
+    buf.fill(0);
+    throw new Error(`Unexpected data key length: ${String(buf.length)} bytes`);
+  }
+  return buf;
+}
+
+export async function encryptSecretValue(args: {
+  client: SecretsKmsProxy;
+  scope: SecretScope;
+  scopeId: string;
+  secretId: string;
+  plaintext: string;
+}): Promise<EncryptedEnvelopeV1> {
+  const { client, scope, scopeId, secretId, plaintext } = args;
+  const { plaintextKey, dataKeyCiphertext } = await client.generateSecretDataKey({
+    scope,
+    scopeId,
+    secretId,
+  });
+
+  const keyBuf = decodeKeyToBuffer(plaintextKey);
+  try {
+    const iv = randomBytes(GCM_IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", keyBuf, iv);
+    const ciphertext = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return {
+      version: 1,
+      iv: iv.toString("base64"),
+      ciphertext: ciphertext.toString("base64"),
+      authTag: authTag.toString("base64"),
+      dataKeyCiphertext,
+    };
+  } finally {
+    keyBuf.fill(0);
+  }
+}
+
+export async function decryptSecretEnvelope(args: {
+  client: SecretsKmsProxy;
+  scope: SecretScope;
+  scopeId: string;
+  secretId: string;
+  envelope: EncryptedEnvelopeV1;
+}): Promise<string> {
+  const { client, scope, scopeId, secretId, envelope } = args;
+  const { plaintextKey } = await client.decryptSecretDataKey({
+    scope,
+    scopeId,
+    secretId,
+    dataKeyCiphertext: envelope.dataKeyCiphertext,
+  });
+
+  const keyBuf = decodeKeyToBuffer(plaintextKey);
+  try {
+    const iv = Buffer.from(envelope.iv, "base64");
+    const ciphertext = Buffer.from(envelope.ciphertext, "base64");
+    const authTag = Buffer.from(envelope.authTag, "base64");
+    const decipher = createDecipheriv("aes-256-gcm", keyBuf, iv);
+    decipher.setAuthTag(authTag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString("utf8");
+  } finally {
+    keyBuf.fill(0);
+  }
+}

package/src/index.ts

@@ -0,0 +1,356 @@
+/**
+ * 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.
+ *
+ * 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
+ */
+import { randomUUID } from "node:crypto";
+import { AgentApiClient, type SecretScope } from "@alfe.ai/agent-api-client";
+import { decryptSecretEnvelope, encryptSecretValue } from "./crypto.js";
+import type { SecretsConfig } from "./types.js";
+
+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;
+  registerMemoryPromptSection?: (builder: (params: { availableTools: Set<string> }) => string[]) => void;
+}
+
+const VALID_SCOPES: SecretScope[] = ["org", "team", "project", "agent"];
+const NAME_REGEX = /^[a-zA-Z0-9_./-]{1,128}$/;
+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 resolveConfig(raw?: Record<string, unknown>): SecretsConfig {
+  // Match @alfe.ai/agent-api-client's config shape. agentId and tenantId are
+  // resolved server-side from the bearer token, so we intentionally don't
+  // accept them here — reading caller-supplied identity would be a footgun.
+  const apiUrl = typeof raw?.apiUrl === "string" ? raw.apiUrl : (process.env.ALFE_API_URL ?? "");
+  const agentApiKey = typeof raw?.agentApiKey === "string" ? raw.agentApiKey : "";
+  if (!apiUrl) throw new Error("openclaw-secrets: apiUrl (or ALFE_API_URL) is required");
+  if (!agentApiKey) throw new Error("openclaw-secrets: agentApiKey is required");
+  return { apiUrl, agentApiKey };
+}
+
+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;
+}
+
+function parseSecretName(raw: unknown): string {
+  const s = parseString(raw, "name", 128);
+  if (!NAME_REGEX.test(s)) {
+    throw new Error("name must match ^[a-zA-Z0-9_./-]{1,128}$");
+  }
+  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;
+}
+
+export default {
+  id: "secrets",
+  name: "Secrets",
+  description: "Per-scope encrypted secret storage — agent-side AES-256-GCM with KMS-issued data keys.",
+  version: "0.1.0",
+  kind: "secrets" as const,
+
+  register(api: PluginApi): void {
+    const config = resolveConfig(api.pluginConfig);
+    const client = new AgentApiClient({ apiUrl: config.apiUrl, apiKey: config.agentApiKey });
+    const logger = api.logger;
+
+    if (api.registerMemoryPromptSection) {
+      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.");
+        }
+        if (availableTools.has("secret_list")) {
+          lines.push("Use secret_list to see secret names in a scope. secret_list NEVER returns plaintext.");
+        }
+        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_set")) {
+          lines.push("Use secret_set to create or update a secret. Prefer scoping to 'agent' for personal secrets.");
+        }
+        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. Use this before guessing scopeIds.",
+      parameters: { type: "object", properties: {} },
+      execute: async () => {
+        const scopes = await client.listSecretScopes();
+        return { scopes };
+      },
+    }), { names: ["secret_list_scopes"] });
+
+    // ─── secret_list ────────────────────────────────────────────
+    api.registerTool(() => ({
+      name: "secret_list",
+      label: "List Secrets",
+      description: "List secret metadata (never plaintext) in a given scope.",
+      parameters: {
+        type: "object",
+        properties: {
+          scope: { type: "string", enum: VALID_SCOPES, description: "Scope level" },
+          scopeId: { type: "string", description: "Scope identifier (tenantId / teamId / projectId / agentId)" },
+        },
+        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 });
+        return { secrets };
+      },
+    }), { names: ["secret_list"] });
+
+    // ─── secret_set ─────────────────────────────────────────────
+    api.registerTool(() => ({
+      name: "secret_set",
+      label: "Set Secret",
+      description: "Create a new secret. Encrypts the value locally and uploads only the envelope.",
+      parameters: {
+        type: "object",
+        properties: {
+          scope: { type: "string", enum: VALID_SCOPES, description: "Scope level" },
+          scopeId: { type: "string", description: "Scope identifier" },
+          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" },
+        },
+        required: ["scope", "scopeId", "name", "value"],
+      },
+      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 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 secretId = randomUUID();
+
+        const envelope = await encryptSecretValue({
+          client,
+          scope,
+          scopeId,
+          secretId,
+          plaintext: value,
+        });
+        await client.putSecretEnvelope({
+          scope,
+          scopeId,
+          secretId,
+          secretName: name,
+          envelope,
+          description,
+          tags,
+        });
+        logger.info("Secret created", { scope, scopeId, secretId });
+        return { secretId };
+      },
+    }), { names: ["secret_set"] });
+
+    // ─── secret_get ─────────────────────────────────────────────
+    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.",
+      parameters: {
+        type: "object",
+        properties: {
+          scope: { type: "string", enum: VALID_SCOPES },
+          scopeId: { type: "string" },
+          secretId: { type: "string", description: "UUID v4 of the secret" },
+        },
+        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 row = await client.getSecretEnvelope({ scope, scopeId, secretId });
+        const plaintext = await decryptSecretEnvelope({
+          client,
+          scope,
+          scopeId,
+          secretId,
+          envelope: row.envelope,
+        });
+        return {
+          secretId,
+          secretName: row.secretName,
+          value: plaintext,
+        };
+      },
+    }), { names: ["secret_get"] });
+
+    // ─── secret_get_by_name ─────────────────────────────────────
+    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.",
+      parameters: {
+        type: "object",
+        properties: {
+          scope: { type: "string", enum: VALID_SCOPES },
+          scopeId: { type: "string" },
+          name: { type: "string" },
+        },
+        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 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 plaintext = await decryptSecretEnvelope({
+          client,
+          scope,
+          scopeId,
+          secretId: match.secretId,
+          envelope: row.envelope,
+        });
+        return { found: true, secretId: match.secretId, secretName: match.secretName, value: plaintext };
+      },
+    }), { names: ["secret_get_by_name"] });
+
+    // ─── secret_delete ──────────────────────────────────────────
+    api.registerTool(() => ({
+      name: "secret_delete",
+      label: "Delete Secret",
+      description: "Delete a secret by secretId.",
+      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"] });
+
+    // ─── secret_rotate ──────────────────────────────────────────
+    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.",
+      parameters: {
+        type: "object",
+        properties: {
+          scope: { type: "string", enum: VALID_SCOPES },
+          scopeId: { type: "string" },
+          secretId: { type: "string" },
+          newValue: { type: "string", description: "The new plaintext value" },
+        },
+        required: ["scope", "scopeId", "secretId", "newValue"],
+      },
+      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,
+        });
+        logger.info("Secret rotated", { scope, scopeId, secretId });
+        return { secretId, rotated: true };
+      },
+    }), { names: ["secret_rotate"] });
+
+    logger.info("openclaw-secrets plugin registered", { apiUrl: config.apiUrl });
+  },
+};

package/src/types.ts

@@ -0,0 +1,18 @@
+/**
+ * Plugin-local types. Shared contract types (SecretScope, EncryptedEnvelopeV1,
+ * SecretMetadata, etc.) live in `@alfe/types` and are re-exported by
+ * `@alfe.ai/agent-api-client`; import from there so we have one canonical
+ * source of truth across every agent HTTP surface.
+ */
+
+export interface SecretsConfig {
+  /**
+   * Base URL of the Alfe API host — the same value `@alfe.ai/agent-api-client`
+   * expects (normally read from `ALFE_API_URL`), e.g. `https://api.alfe.ai`.
+   * The client prepends `/agent/secrets/*` automatically (the `/agent` segment
+   * is the agent-gateway api-mapping key; `/secrets` is the service
+   * pathPrefix). Do NOT include either segment in `apiUrl`.
+   */
+  apiUrl: string;
+  agentApiKey: string;
+}

package/sst-env.d.ts

@@ -0,0 +1,10 @@
+/* This file is auto-generated by SST. Do not edit. */
+/* tslint:disable */
+/* eslint-disable */
+/* deno-fmt-ignore-file */
+/* biome-ignore-all lint: auto-generated */
+
+/// <reference path="../../sst-env.d.ts" />
+
+import "sst"
+export {}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "lib": ["ES2022"],
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "src/**/__tests__/**"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["src/**/*.test.ts"],
+    exclude: ["dist/**", "node_modules/**"],
+    testTimeout: 5_000,
+  },
+});