@pikku/core 0.12.1 → 0.12.3

package/dist/wirings/rpc/rpc-runner.js

@@ -1,7 +1,7 @@
 import { runPikkuFunc } from '../../function/function-runner.js';
 import { pikkuState } from '../../pikku-state.js';
 import { ForbiddenError } from '../../errors/errors.js';
-import { PikkuError } from '../../errors/error-handler.js';
+import { PikkuError, addError } from '../../errors/error-handler.js';
 import { parseVersionedId } from '../../version.js';
 import { encryptJSON } from '../../crypto-utils.js';
 export class RPCNotFoundError extends PikkuError {
@@ -11,29 +11,33 @@ export class RPCNotFoundError extends PikkuError {
         this.rpcName = rpcName;
     }
 }
-import { runAIAgent } from '../ai-agent/ai-agent-runner.js';
+addError(RPCNotFoundError, {
+    status: 404,
+    mcpCode: -32601,
+    message: 'RPC function not found.',
+});
+import { runAIAgent, resumeAIAgentSync } from '../ai-agent/ai-agent-runner.js';
 import { streamAIAgent, resumeAIAgent } from '../ai-agent/ai-agent-stream.js';
-import { approveAIAgent } from '../ai-agent/ai-agent-registry.js';
 /**
  * Resolve a namespaced function reference to package and function names
  * Uses pikkuState to look up the namespace -> package mapping
  */
-const resolveNamespace = (namespacedFunction) => {
+export const resolveNamespace = (namespacedFunction) => {
     const colonIndex = namespacedFunction.indexOf(':');
     if (colonIndex === -1) {
         return null;
     }
     const namespace = namespacedFunction.substring(0, colonIndex);
     const functionName = namespacedFunction.substring(colonIndex + 1);
-    const addons = pikkuState(null, 'rpc', 'addons');
+    const addons = pikkuState(null, 'addons', 'packages');
     const pkgConfig = addons.get(namespace);
     if (!pkgConfig) {
         return null;
     }
     return {
-        namespace,
         package: pkgConfig.package,
         function: functionName,
+        addonConfig: pkgConfig,
     };
 };
 const getPikkuFunctionName = (rpcName) => {
@@ -72,7 +76,7 @@ export class ContextAwareRPCService {
             functionMeta = pikkuState(null, 'function', 'meta')[funcName];
         }
         if (!functionMeta) {
-            throw new Error(`Function not found: ${funcName}`);
+            throw new RPCNotFoundError(funcName);
         }
         if (!functionMeta.expose) {
             throw new ForbiddenError();
@@ -125,9 +129,11 @@ export class ContextAwareRPCService {
                 `Available functions: ${Object.keys(addonFunctionMeta).join(', ') || '(none)'}`);
         }
         const funcName = funcMeta.pikkuFuncId || resolved.function;
-        const addonConfig = pikkuState(null, 'rpc', 'addons').get(resolved.namespace);
-        const auth = addonConfig?.auth ?? this.options.requiresAuth;
-        const tags = [...(addonConfig?.tags ?? []), ...(funcMeta.tags ?? [])];
+        const auth = resolved.addonConfig?.auth ?? this.options.requiresAuth;
+        const tags = [
+            ...(resolved.addonConfig?.tags ?? []),
+            ...(funcMeta.tags ?? []),
+        ];
         // Execute the function using runPikkuFunc with the addon package's state
         // We use the parent services (this.services) since addon packages share services
         // Pass the function's tags so tag-based middleware/permissions are applied
@@ -153,6 +159,9 @@ export class ContextAwareRPCService {
                 }
                 : undefined,
         };
+        if (rpcName.includes(':')) {
+            return this.invokeAddonFunction(rpcName, data, mergedWire);
+        }
         return runPikkuFunc('rpc', rpcName, getPikkuFunctionName(rpcName), {
             auth: this.options.requiresAuth,
             singletonServices: this.services,
@@ -182,6 +191,10 @@ export class ContextAwareRPCService {
                     runId: result.runId,
                     result: result.object ?? result.text,
                     usage: result.usage,
+                    ...(result.status === 'suspended' && {
+                        status: 'suspended',
+                        pendingApprovals: result.pendingApprovals,
+                    }),
                 };
             },
             stream: async (agentName, input, options) => {
@@ -197,9 +210,18 @@ export class ContextAwareRPCService {
                 await resumeAIAgent({ runId, ...input }, channel, { sessionService: this.options.sessionService }, options);
             },
             approve: async (runId, approvals, expectedAgentName) => {
-                if (!this.services.aiRunState)
-                    throw new Error('AIRunStateService not available');
-                return approveAIAgent(this.services.aiRunState, runId, approvals, expectedAgentName);
+                const result = await resumeAIAgentSync(runId, approvals, {
+                    sessionService: this.options.sessionService,
+                }, expectedAgentName);
+                return {
+                    runId: result.runId,
+                    result: result.object ?? result.text,
+                    usage: result.usage,
+                    ...(result.status === 'suspended' && {
+                        status: 'suspended',
+                        pendingApprovals: result.pendingApprovals,
+                    }),
+                };
             },
         };
     }
@@ -211,7 +233,7 @@ export class ContextAwareRPCService {
         const colonIndex = funcName.indexOf(':');
         if (colonIndex !== -1) {
             const namespace = funcName.substring(0, colonIndex);
-            const addons = pikkuState(null, 'rpc', 'addons');
+            const addons = pikkuState(null, 'addons', 'packages');
             const pkgConfig = addons.get(namespace);
             endpoint = pkgConfig?.rpcEndpoint;
         }

package/dist/wirings/rpc/rpc-types.d.ts

@@ -34,7 +34,12 @@ export interface RPCHandler<Input, Output> {
  * Resolved function reference from namespace
  */
 export interface ResolvedFunction {
-    namespace: string;
     package: string;
     function: string;
+    addonConfig: {
+        package: string;
+        auth?: boolean;
+        tags?: string[];
+        rpcEndpoint?: string;
+    };
 }

package/dist/wirings/rpc/wire-addon.d.ts

@@ -3,6 +3,7 @@ export type WireAddonConfig = {
     package: string;
     rpcEndpoint?: string;
     auth?: boolean;
+    mcp?: boolean;
     tags?: string[];
     secretOverrides?: Record<string, string>;
     variableOverrides?: Record<string, string>;

package/dist/wirings/rpc/wire-addon.js

@@ -1,6 +1,6 @@
 import { pikkuState } from '../../pikku-state.js';
 export const wireAddon = (config) => {
-    pikkuState(null, 'rpc', 'addons').set(config.name, {
+    pikkuState(null, 'addons', 'packages').set(config.name, {
         package: config.package,
         rpcEndpoint: config.rpcEndpoint,
         auth: config.auth,

package/dist/wirings/scheduler/scheduler-runner.js

@@ -72,6 +72,7 @@ export async function runScheduledTask({ name, session, }) {
             tags: task.tags,
             wire,
             sessionService: userSession,
+            packageName: meta.packageName,
         });
     }
     catch (e) {

package/dist/wirings/workflow/graph/graph-validation.d.ts

@@ -0,0 +1,3 @@
+export declare function computeEntryNodeIds(nodes: Record<string, any>): string[];
+export declare function validateWorkflowWiring(nodes: Record<string, any>, toolNames: string[]): string[];
+export declare function generateMermaidDiagram(workflowName: string, nodes: Record<string, any>, entryNodeIds: string[]): string;

package/dist/wirings/workflow/graph/graph-validation.js

@@ -0,0 +1,175 @@
+import { pikkuState } from '../../../pikku-state.js';
+import { resolveNamespace } from '../../rpc/rpc-runner.js';
+function normalizeTargets(value) {
+    if (!value)
+        return [];
+    if (typeof value === 'string')
+        return [value];
+    if (Array.isArray(value))
+        return value.filter((v) => typeof v === 'string');
+    if (typeof value === 'object') {
+        const targets = [];
+        for (const v of Object.values(value)) {
+            targets.push(...normalizeTargets(v));
+        }
+        return targets;
+    }
+    return [];
+}
+function collectRefs(value, refs) {
+    if (typeof value === 'object' &&
+        value !== null &&
+        '$ref' in value &&
+        typeof value.$ref === 'string') {
+        refs.add(value.$ref);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            collectRefs(item, refs);
+        return;
+    }
+    if (typeof value === 'object' && value !== null) {
+        for (const v of Object.values(value))
+            collectRefs(v, refs);
+    }
+}
+function resolveToolMeta(toolName) {
+    const resolved = toolName.includes(':') ? resolveNamespace(toolName) : null;
+    if (resolved) {
+        const fnMeta = pikkuState(resolved.package, 'function', 'meta')[resolved.function];
+        const schemas = pikkuState(resolved.package, 'misc', 'schemas');
+        return fnMeta ? { fnMeta, schemas } : null;
+    }
+    const rpcMeta = pikkuState(null, 'rpc', 'meta');
+    const pikkuFuncId = rpcMeta[toolName];
+    if (!pikkuFuncId)
+        return null;
+    const fnMeta = pikkuState(null, 'function', 'meta')[pikkuFuncId];
+    const schemas = pikkuState(null, 'misc', 'schemas');
+    return fnMeta ? { fnMeta, schemas } : null;
+}
+export function computeEntryNodeIds(nodes) {
+    const referenced = new Set();
+    for (const node of Object.values(nodes)) {
+        if (node.next) {
+            for (const target of normalizeTargets(node.next)) {
+                referenced.add(target);
+            }
+        }
+        if (node.onError) {
+            for (const target of normalizeTargets(node.onError)) {
+                referenced.add(target);
+            }
+        }
+    }
+    return Object.keys(nodes).filter((id) => !referenced.has(id));
+}
+export function validateWorkflowWiring(nodes, toolNames) {
+    const errors = [];
+    const nodeIds = new Set(Object.keys(nodes));
+    const toolSet = new Set(toolNames);
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        if (!node.rpcName) {
+            errors.push(`Node '${nodeId}' is missing 'rpcName'`);
+            continue;
+        }
+        if (!toolSet.has(node.rpcName)) {
+            errors.push(`Node '${nodeId}' references unknown tool '${node.rpcName}'. Available tools: ${toolNames.join(', ')}`);
+            continue;
+        }
+        const nextTargets = normalizeTargets(node.next);
+        for (const target of nextTargets) {
+            if (!nodeIds.has(target)) {
+                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'next'`);
+            }
+        }
+        const errorTargets = normalizeTargets(node.onError);
+        for (const target of errorTargets) {
+            if (!nodeIds.has(target)) {
+                errors.push(`Node '${nodeId}' routes to unknown node '${target}' in 'onError'`);
+            }
+        }
+        if (!node.input)
+            continue;
+        const refs = new Set();
+        collectRefs(node.input, refs);
+        for (const ref of refs) {
+            if (ref === 'trigger' || ref === '$item') {
+                const targetMeta = resolveToolMeta(node.rpcName);
+                if (targetMeta?.fnMeta?.inputSchemaName) {
+                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
+                    if (targetSchema?.properties) {
+                        for (const [field, fieldValue] of Object.entries(node.input)) {
+                            if (typeof fieldValue === 'object' &&
+                                fieldValue !== null &&
+                                fieldValue.$ref === ref &&
+                                !fieldValue.path) {
+                                const targetType = targetSchema.properties[field]?.type;
+                                if (targetType && targetType !== 'object') {
+                                    errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but references the whole ${ref} object without a path. Use { $ref: "${ref}", path: "${field}" } to extract the field.`);
+                                }
+                            }
+                        }
+                    }
+                }
+                continue;
+            }
+            if (!nodeIds.has(ref)) {
+                errors.push(`Node '${nodeId}' references unknown node '${ref}' in input`);
+                continue;
+            }
+            const sourceNode = nodes[ref];
+            if (!sourceNode?.rpcName)
+                continue;
+            const sourceMeta = resolveToolMeta(sourceNode.rpcName);
+            if (!sourceMeta?.fnMeta?.outputSchemaName)
+                continue;
+            const sourceSchema = sourceMeta.schemas.get(sourceMeta.fnMeta.outputSchemaName);
+            if (!sourceSchema?.properties)
+                continue;
+            for (const [field, fieldValue] of Object.entries(node.input)) {
+                if (typeof fieldValue === 'object' &&
+                    fieldValue !== null &&
+                    fieldValue.$ref === ref &&
+                    fieldValue.path) {
+                    const pathRoot = fieldValue.path.split('.')[0];
+                    if (sourceSchema.properties &&
+                        !(pathRoot in sourceSchema.properties)) {
+                        errors.push(`Node '${nodeId}' input field '${field}' references path '${fieldValue.path}' but node '${ref}' (${sourceNode.rpcName}) output has no property '${pathRoot}'`);
+                        continue;
+                    }
+                    const targetMeta = resolveToolMeta(node.rpcName);
+                    if (!targetMeta?.fnMeta?.inputSchemaName)
+                        continue;
+                    const targetSchema = targetMeta.schemas.get(targetMeta.fnMeta.inputSchemaName);
+                    if (!targetSchema?.properties?.[field])
+                        continue;
+                    const sourceType = sourceSchema.properties[pathRoot]?.type;
+                    const targetType = targetSchema.properties[field].type;
+                    if (sourceType && targetType && sourceType !== targetType) {
+                        errors.push(`Node '${nodeId}' input field '${field}' expects type '${targetType}', but node '${ref}' output field '${pathRoot}' is type '${sourceType}'`);
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+export function generateMermaidDiagram(workflowName, nodes, entryNodeIds) {
+    const lines = ['graph TD'];
+    for (const [nodeId, node] of Object.entries(nodes)) {
+        const label = node.rpcName || nodeId;
+        const isEntry = entryNodeIds.includes(nodeId);
+        lines.push(`  ${nodeId}${isEntry ? '([' : '['}${label}${isEntry ? '])' : ']'}`);
+        const nextTargets = normalizeTargets(node.next);
+        for (const target of nextTargets) {
+            lines.push(`  ${nodeId} --> ${target}`);
+        }
+        const errorTargets = normalizeTargets(node.onError);
+        for (const target of errorTargets) {
+            lines.push(`  ${nodeId} -.->|error| ${target}`);
+        }
+    }
+    return lines.join('\n');
+}

package/dist/wirings/workflow/graph/index.d.ts

@@ -2,3 +2,4 @@ export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runW
 export { template } from './template.js';
 export type { TemplateString } from './template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './wire-workflow-graph.js';
+export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';

package/dist/wirings/workflow/graph/index.js

@@ -1,3 +1,4 @@
 export { continueGraph, executeGraphStep, onGraphNodeComplete, runFromMeta, runWorkflowGraph, } from './graph-runner.js';
 export { template } from './template.js';
 export { pikkuWorkflowGraph, } from './wire-workflow-graph.js';
+export { validateWorkflowWiring, computeEntryNodeIds, generateMermaidDiagram, } from './graph-validation.js';

package/dist/wirings/workflow/index.d.ts

@@ -6,5 +6,5 @@ export { addWorkflow } from './dsl/workflow-runner.js';
 export { template, type TemplateString } from './graph/template.js';
 export { pikkuWorkflowGraph, type PikkuWorkflowGraphConfig, type PikkuWorkflowGraphResult, } from './graph/wire-workflow-graph.js';
 export { workflow, workflowStart, workflowStatus, graphStart, } from './workflow-helpers.js';
-export type { WorkflowService, WorkflowServiceConfig, WorkflowRunWire, WorkflowStatus, StepStatus, WorkflowRun, StepState, WorkflowRunService, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
+export type { WorkflowService, WorkflowServiceConfig, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, StepStatus, WorkflowRun, StepState, WorkflowRunService, CoreWorkflow, PikkuWorkflow, ContextVariable, WorkflowContext, WorkflowsMeta, WorkflowRuntimeMeta, WorkflowsRuntimeMeta, WorkflowStepInput, WorkflowOrchestratorInput, WorkflowSleeperInput, } from './workflow.types.js';
 export type { WorkflowStepOptions, WorkflowWireDoRPC, WorkflowWireDoInline, WorkflowWireSleep, WorkflowWireSuspend, InputSource, OutputBinding, RpcStepMeta, SimpleCondition, Condition, BranchCase, BranchStepMeta, ParallelGroupStepMeta, FanoutStepMeta, ReturnStepMeta, InlineStepMeta, SleepStepMeta, CancelStepMeta, SetStepMeta, SwitchCaseMeta, SwitchStepMeta, FilterStepMeta, ArrayPredicateStepMeta, WorkflowStepMeta, WorkflowStepWire, PikkuWorkflowWire, } from './workflow.types.js';

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -1,5 +1,5 @@
 import type { SerializedError } from '../../types/core.types.js';
-import type { StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowStepOptions } from './workflow.types.js';
+import type { StepState, WorkflowRun, WorkflowRunWire, WorkflowStatus, WorkflowVersionStatus, WorkflowStepOptions } from './workflow.types.js';
 import type { WorkflowService } from '../../services/workflow-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 /**
@@ -197,11 +197,17 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * @returns The state object with all variables
      */
     abstract getRunState(runId: string): Promise<Record<string, unknown>>;
-    abstract upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string): Promise<void>;
+    abstract upsertWorkflowVersion(name: string, graphHash: string, graph: any, source: string, status?: WorkflowVersionStatus): Promise<void>;
+    abstract updateWorkflowVersionStatus(name: string, graphHash: string, status: WorkflowVersionStatus): Promise<void>;
     abstract getWorkflowVersion(name: string, graphHash: string): Promise<{
         graph: any;
         source: string;
     } | null>;
+    abstract getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
+        workflowName: string;
+        graphHash: string;
+        graph: any;
+    }>>;
     /**
      * Resume a paused workflow by triggering the orchestrator
      * @param runId - Run ID

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -162,8 +162,7 @@ export class PikkuWorkflowService {
         if (!workflowMeta) {
             throw new WorkflowNotFoundError(name);
         }
-        // Check if this is a graph workflow (source === 'graph')
-        if (workflowMeta.source === 'graph') {
+        if (workflowMeta.source === 'graph' || workflowMeta.source === 'ai-agent') {
             const shouldInline = options?.inline || !getSingletonServices()?.queueService;
             return runWorkflowGraph(this, name, input, rpcService, shouldInline, options?.startNode, wire);
         }

package/dist/wirings/workflow/workflow.types.d.ts

@@ -19,6 +19,10 @@ export interface WorkflowServiceConfig {
  * Workflow run status
  */
 export type WorkflowStatus = 'running' | 'suspended' | 'completed' | 'failed' | 'cancelled';
+/**
+ * Workflow version status (for AI-generated workflows)
+ */
+export type WorkflowVersionStatus = 'draft' | 'active' | 'declined';
 /**
  * Workflow step status
  */
@@ -102,6 +106,11 @@ export interface WorkflowRunService {
         graph: any;
         source: string;
     } | null>;
+    getAIGeneratedWorkflows(agentName?: string): Promise<Array<{
+        workflowName: string;
+        graphHash: string;
+        graph: any;
+    }>>;
     deleteRun(id: string): Promise<boolean>;
 }
 /**
@@ -167,7 +176,7 @@ export interface WorkflowRuntimeMeta {
     /** Pikku function name (for execution) */
     pikkuFuncId: string;
     /** Source type: 'dsl' (serializable), 'complex' (has inline steps), 'graph' */
-    source: 'dsl' | 'complex' | 'graph';
+    source: 'dsl' | 'complex' | 'graph' | 'ai-agent';
     /** Optional description */
     description?: string;
     /** Tags for organization */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "module": "dist/index.js",
@@ -30,6 +30,7 @@
     "./rpc": "./dist/wirings/rpc/index.js",
     "./mcp": "./dist/wirings/mcp/index.js",
     "./ai-agent": "./dist/wirings/ai-agent/index.js",
+    "./gateway": "./dist/wirings/gateway/index.js",
     "./cli": "./dist/wirings/cli/index.js",
     "./cli/channel": "./dist/wirings/cli/channel/index.js",
     "./node": "./dist/wirings/node/index.js",
@@ -40,8 +41,10 @@
     "./services": "./dist/services/index.js",
     "./services/local-content": "./dist/services/local-content.js",
     "./services/gopass-secrets": "./dist/services/gopass-secrets.js",
+    "./crypto-utils": "./dist/crypto-utils.js",
     "./internal": "./dist/internal.js",
-    "./schema": "./dist/schema.js"
+    "./schema": "./dist/schema.js",
+    "./testing": "./dist/testing/index.js"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
@@ -50,7 +53,7 @@
     "picoquery": "^2.5.0"
   },
   "devDependencies": {
-    "@types/node": "^24.10.12",
+    "@types/node": "^24.11.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9"
   },

package/src/crypto-utils.test.ts

@@ -1,6 +1,15 @@
 import { describe, test } from 'node:test'
 import assert from 'node:assert'
-import { encryptJSON, decryptJSON } from './crypto-utils.js'
+import {
+  encryptJSON,
+  decryptJSON,
+  generateDEK,
+  wrapDEK,
+  unwrapDEK,
+  envelopeEncrypt,
+  envelopeDecrypt,
+  envelopeRewrap,
+} from './crypto-utils.js'
 
 describe('encryptJSON / decryptJSON', () => {
   const secret = 'test-secret-key-for-encryption'
@@ -114,3 +123,92 @@ describe('encryptJSON / decryptJSON', () => {
     assert.deepStrictEqual(decrypted, original)
   })
 })
+
+describe('envelope encryption', () => {
+  const kek = 'my-key-encryption-key'
+
+  test('generateDEK produces unique keys', async () => {
+    const dek1 = await generateDEK()
+    const dek2 = await generateDEK()
+    assert.notStrictEqual(dek1, dek2)
+    assert.ok(dek1.length > 0)
+  })
+
+  test('wrapDEK / unwrapDEK round-trip', async () => {
+    const dek = await generateDEK()
+    const wrapped = await wrapDEK(kek, dek)
+    const unwrapped = await unwrapDEK(kek, wrapped)
+    assert.strictEqual(unwrapped, dek)
+  })
+
+  test('unwrapDEK fails with wrong KEK', async () => {
+    const dek = await generateDEK()
+    const wrapped = await wrapDEK(kek, dek)
+    await assert.rejects(
+      () => unwrapDEK('wrong-kek', wrapped),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('envelopeEncrypt / envelopeDecrypt round-trip', async () => {
+    const original = {
+      apiKey: 'sk-secret-123',
+      endpoint: 'https://api.example.com',
+    }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+    const decrypted = await envelopeDecrypt(kek, ciphertext, wrappedDEK)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelopeEncrypt produces unique ciphertexts and DEKs per call', async () => {
+    const value = { same: 'data' }
+    const r1 = await envelopeEncrypt(kek, value)
+    const r2 = await envelopeEncrypt(kek, value)
+    assert.notStrictEqual(r1.ciphertext, r2.ciphertext)
+    assert.notStrictEqual(r1.wrappedDEK, r2.wrappedDEK)
+  })
+
+  test('envelopeDecrypt fails with wrong KEK', async () => {
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, 'secret')
+    await assert.rejects(
+      () => envelopeDecrypt('wrong-kek', ciphertext, wrappedDEK),
+      (err: any) => err instanceof Error
+    )
+  })
+
+  test('envelopeRewrap allows decryption with new KEK', async () => {
+    const newKEK = 'my-new-kek'
+    const original = { token: 'abc-123' }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+
+    const rewrapped = await envelopeRewrap(kek, newKEK, wrappedDEK)
+
+    await assert.rejects(
+      () => envelopeDecrypt(kek, ciphertext, rewrapped),
+      (err: any) => err instanceof Error
+    )
+
+    const decrypted = await envelopeDecrypt(newKEK, ciphertext, rewrapped)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelopeRewrap does not change the ciphertext', async () => {
+    const original = { data: 'important' }
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(kek, original)
+    const rewrapped = await envelopeRewrap(kek, 'new-kek', wrappedDEK)
+
+    assert.notStrictEqual(rewrapped, wrappedDEK)
+
+    const decrypted = await envelopeDecrypt('new-kek', ciphertext, rewrapped)
+    assert.deepStrictEqual(decrypted, original)
+  })
+
+  test('envelope handles string secrets', async () => {
+    const { ciphertext, wrappedDEK } = await envelopeEncrypt(
+      kek,
+      'plain-string-secret'
+    )
+    const decrypted = await envelopeDecrypt<string>(kek, ciphertext, wrappedDEK)
+    assert.strictEqual(decrypted, 'plain-string-secret')
+  })
+})