@siglo/crypto 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Jerico de guzman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# @siglo/crypto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Zero-dependency cryptographic step package for Siglo workflows: timing-safe webhook verification, AEAD envelope field encryption, and context redaction.
+
+---
+
+## Features
+
+- **Timing-Attack Safe**: Guarantees constant-time buffer comparison via `node:crypto.timingSafeEqual` with strict length guards.
+- **Replay Attack Defense**: Automatic header timestamp parsing and configurable tolerance windows (`toleranceSeconds: 300`).
+- **Zero Serialization Skew**: Enforces verification strictly over raw `Buffer` or unparsed payload strings before JSON parsing.
+- **Pluggable Webhook Strategies**: Built-in presets for Stripe, GitHub, Shopify, Slack, Svix / Standard Webhooks, and generic HMAC, plus support for custom protocols and asymmetric Ed25519/RSA keys.
+- **Envelope Encryption**: Field-level AES-256-GCM encryption with fresh 96-bit (12-byte) IVs per invocation for securing sensitive context across durable checkpoints.
+- **Context Redaction & Masking**: Declarative PII masking (`maskFieldsStep`) with presets for SSNs, credit cards, emails, and custom patterns.
+- **Zero External Dependencies**: Built entirely on Node.js standard libraries (`node:crypto`).
+
+---
+
+## Installation
+
+```bash
+npm install @siglo/crypto
+```
+
+---
+
+## Usage Examples
+
+### 1. Webhook Signature Verification
+
+```typescript
+import { flow } from '@siglo/core';
+import { verifyWebhookStep } from '@siglo/crypto';
+
+interface WebhookContext {
+  rawBody: string;
+  headers: Record<string, string>;
+}
+
+export const processWebhook = flow(
+  verifyWebhookStep('verifyStripe', {
+    provider: 'stripe',
+    secret: process.env.STRIPE_WEBHOOK_SECRET!,
+    payload: (ctx: WebhookContext) => ctx.rawBody,
+    signature: (ctx: WebhookContext) => ctx.headers['stripe-signature'],
+    toleranceSeconds: 300,
+  })
+);
+```
+
+### 2. Envelope Field Encryption across Durable Checkpoints
+
+```typescript
+import { flow, waitForEvent, Step } from '@siglo/core';
+import { encryptFieldsStep, decryptFieldsStep } from '@siglo/crypto';
+
+interface UserContext {
+  userId: string;
+  ssn: string;
+  creditCard: string;
+}
+
+export const sensitiveWorkflow = flow(
+  // Encrypt sensitive fields before saving durable checkpoint
+  encryptFieldsStep('securePii', {
+    fields: ['ssn', 'creditCard'],
+    secretKey: process.env.MASTER_KEY!,
+  }),
+
+  // State in checkpoint storage (PostgreSQL/Redis) is encrypted at rest!
+  waitForEvent('USER_VERIFIED', { timeout: '24h' }),
+
+  // Decrypt fields back into plaintext upon workflow resumption
+  decryptFieldsStep('unprotectPii', {
+    fields: ['ssn', 'creditCard'],
+    secretKey: process.env.MASTER_KEY!,
+  })
+);
+```
+
+### 3. Context Redaction / Masking
+
+```typescript
+import { flow } from '@siglo/core';
+import { maskFieldsStep, maskPatterns } from '@siglo/crypto';
+
+export const sanitizeWorkflow = flow(
+  maskFieldsStep('maskSensitiveData', {
+    fields: ['creditCard', 'ssn'],
+    maskPattern: maskPatterns.last4,
+  })
+);
+```
+
+### 4. Custom Asymmetric Webhook Protocol (Ed25519)
+
+```typescript
+import { verifyWebhookStep, WebhookProtocol } from '@siglo/crypto';
+import crypto from 'node:crypto';
+
+export const customEd25519Protocol: WebhookProtocol = {
+  name: 'custom-ed25519',
+  verify({ secret, rawPayload, headers, signatureHeader, toleranceSeconds = 300 }) {
+    const timestamp = Number(headers['x-timestamp']);
+    const now = Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > toleranceSeconds) {
+      return false;
+    }
+
+    const toSign = Buffer.from(`${timestamp}.${rawPayload}`);
+    const signature = Buffer.from(signatureHeader, 'base64');
+    return crypto.verify(null, toSign, secret, signature);
+  }
+};
+```
+
+---
+
+## License
+
+MIT © Jerico de Guzman

package/dist/cipher/aes-gcm.d.ts

@@ -0,0 +1,43 @@
+import { EncryptedEnvelope } from '../types';
+/**
+ * Type guard for EncryptedEnvelope.
+ */
+export declare function isEncryptedEnvelope(val: unknown): val is EncryptedEnvelope;
+/**
+ * Resolves a 256-bit (32-byte) key buffer from a string or Buffer.
+ * Supports raw 32-byte Buffers, 64-char hex strings, 32-char UTF-8 strings,
+ * or derives a 32-byte key via SHA-256 for arbitrary passphrases.
+ */
+export declare function resolveKey(key: string | Buffer): Buffer;
+/**
+ * Derives a context-bound 256-bit subkey from a master key using RFC 5869 HKDF.
+ * Isolates cryptographic keyspaces per tenant, workflow run, or checkpoint.
+ */
+export declare function deriveSubkey(masterKey: string | Buffer, contextInfo: string | Buffer, salt?: string | Buffer): Buffer;
+/** NIST SP 800-38D recommended maximum threshold for 96-bit random IVs (2^24) */
+export declare const NIST_RECOMMENDED_INVOCATION_CEILING = 16777216;
+export declare function getKeyInvocationCount(key: string | Buffer): number;
+export declare function resetKeyInvocationCounters(): void;
+export interface EncryptOptions {
+    kid?: string;
+    aad?: string | Buffer;
+    deriveKeyContext?: string | Buffer;
+    v?: number;
+}
+export interface DecryptOptions {
+    aad?: string | Buffer;
+    deriveKeyContext?: string | Buffer;
+}
+/**
+ * Encrypts arbitrary data using AES-256-GCM envelope encryption.
+ * Generates a cryptographically secure 96-bit (12-byte) IV for each invocation.
+ * Supports AAD (Additional Authenticated Data) and context-derived subkeys.
+ */
+export declare function encryptAESGCM(data: unknown, key: string | Buffer, options?: EncryptOptions): EncryptedEnvelope;
+/**
+ * Decrypts an AES-256-GCM envelope and verifies authentication tag integrity.
+ * Supports AAD verification and context-derived subkey reconstruction.
+ * Throws if the auth tag, ciphertext, or AAD was tampered with.
+ */
+export declare function decryptAESGCM(envelope: EncryptedEnvelope, key: string | Buffer, options?: DecryptOptions): any;
+//# sourceMappingURL=aes-gcm.d.ts.map

package/dist/cipher/aes-gcm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes-gcm.d.ts","sourceRoot":"","sources":["../../src/cipher/aes-gcm.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,iBAAiB,CAS1E;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAoBvD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GACrB,MAAM,CAOR;AAKD,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,WAAW,CAAC;AAE5D,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAGlE;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD;AAgBD,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,OAAO,CAAC,EAAE,cAAc,GACvB,iBAAiB,CAqCnB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,iBAAiB,EAC3B,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,OAAO,CAAC,EAAE,cAAc,GACvB,GAAG,CAkCL"}

package/dist/cipher/aes-gcm.js

@@ -0,0 +1,152 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NIST_RECOMMENDED_INVOCATION_CEILING = void 0;
+exports.isEncryptedEnvelope = isEncryptedEnvelope;
+exports.resolveKey = resolveKey;
+exports.deriveSubkey = deriveSubkey;
+exports.getKeyInvocationCount = getKeyInvocationCount;
+exports.resetKeyInvocationCounters = resetKeyInvocationCounters;
+exports.encryptAESGCM = encryptAESGCM;
+exports.decryptAESGCM = decryptAESGCM;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/**
+ * Type guard for EncryptedEnvelope.
+ */
+function isEncryptedEnvelope(val) {
+    return (typeof val === 'object' &&
+        val !== null &&
+        val.__sigloCipher === 'aes-256-gcm' &&
+        typeof val.iv === 'string' &&
+        typeof val.tag === 'string' &&
+        typeof val.data === 'string');
+}
+/**
+ * Resolves a 256-bit (32-byte) key buffer from a string or Buffer.
+ * Supports raw 32-byte Buffers, 64-char hex strings, 32-char UTF-8 strings,
+ * or derives a 32-byte key via SHA-256 for arbitrary passphrases.
+ */
+function resolveKey(key) {
+    if (Buffer.isBuffer(key)) {
+        if (key.length === 32) {
+            return key;
+        }
+        return node_crypto_1.default.createHash('sha256').update(key).digest();
+    }
+    if (typeof key === 'string') {
+        if (key.length === 64 && /^[0-9a-fA-F]{64}$/.test(key)) {
+            return Buffer.from(key, 'hex');
+        }
+        const utf8Buf = Buffer.from(key, 'utf8');
+        if (utf8Buf.length === 32) {
+            return utf8Buf;
+        }
+        return node_crypto_1.default.createHash('sha256').update(key).digest();
+    }
+    throw new TypeError('Secret key must be a string or Buffer');
+}
+/**
+ * Derives a context-bound 256-bit subkey from a master key using RFC 5869 HKDF.
+ * Isolates cryptographic keyspaces per tenant, workflow run, or checkpoint.
+ */
+function deriveSubkey(masterKey, contextInfo, salt) {
+    const resolvedMaster = resolveKey(masterKey);
+    const resolvedSalt = salt
+        ? (Buffer.isBuffer(salt) ? salt : Buffer.from(salt))
+        : Buffer.alloc(32, 0);
+    const info = Buffer.isBuffer(contextInfo) ? contextInfo : Buffer.from(contextInfo);
+    return Buffer.from(node_crypto_1.default.hkdfSync('sha256', resolvedMaster, resolvedSalt, info, 32));
+}
+/** Key invocation tracking per key hash to warn/guard against NIST SP 800-38D limits */
+const keyUsageCounts = new Map();
+/** NIST SP 800-38D recommended maximum threshold for 96-bit random IVs (2^24) */
+exports.NIST_RECOMMENDED_INVOCATION_CEILING = 16777216;
+function getKeyInvocationCount(key) {
+    const hash = node_crypto_1.default.createHash('sha256').update(resolveKey(key)).digest('hex');
+    return keyUsageCounts.get(hash) ?? 0;
+}
+function resetKeyInvocationCounters() {
+    keyUsageCounts.clear();
+}
+function recordKeyUsage(key) {
+    const hash = node_crypto_1.default.createHash('sha256').update(key).digest('hex');
+    const current = (keyUsageCounts.get(hash) ?? 0) + 1;
+    keyUsageCounts.set(hash, current);
+    if (current === exports.NIST_RECOMMENDED_INVOCATION_CEILING) {
+        if (typeof process !== 'undefined' && process.emitWarning) {
+            process.emitWarning(`AES-GCM key usage for key fingerprint '${hash.slice(0, 8)}' reached ${exports.NIST_RECOMMENDED_INVOCATION_CEILING} invocations. Key rotation recommended per NIST SP 800-38D.`, 'SecurityWarning');
+        }
+    }
+}
+/**
+ * Encrypts arbitrary data using AES-256-GCM envelope encryption.
+ * Generates a cryptographically secure 96-bit (12-byte) IV for each invocation.
+ * Supports AAD (Additional Authenticated Data) and context-derived subkeys.
+ */
+function encryptAESGCM(data, key, options) {
+    let resolvedKey = resolveKey(key);
+    if (options?.deriveKeyContext) {
+        resolvedKey = deriveSubkey(resolvedKey, options.deriveKeyContext);
+    }
+    recordKeyUsage(resolvedKey);
+    const iv = node_crypto_1.default.randomBytes(12);
+    const plaintext = JSON.stringify(data);
+    const cipher = node_crypto_1.default.createCipheriv('aes-256-gcm', resolvedKey, iv);
+    if (options?.aad) {
+        const aadBuf = Buffer.isBuffer(options.aad) ? options.aad : Buffer.from(options.aad);
+        cipher.setAAD(aadBuf);
+    }
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    const envelope = {
+        __sigloCipher: 'aes-256-gcm',
+        v: options?.v ?? 1,
+        iv: iv.toString('hex'),
+        tag: tag.toString('hex'),
+        data: ciphertext.toString('hex')
+    };
+    if (options?.kid) {
+        envelope.kid = options.kid;
+    }
+    return envelope;
+}
+/**
+ * Decrypts an AES-256-GCM envelope and verifies authentication tag integrity.
+ * Supports AAD verification and context-derived subkey reconstruction.
+ * Throws if the auth tag, ciphertext, or AAD was tampered with.
+ */
+function decryptAESGCM(envelope, key, options) {
+    if (!isEncryptedEnvelope(envelope)) {
+        throw new TypeError('Invalid encrypted envelope structure');
+    }
+    let resolvedKey = resolveKey(key);
+    if (options?.deriveKeyContext) {
+        resolvedKey = deriveSubkey(resolvedKey, options.deriveKeyContext);
+    }
+    const iv = Buffer.from(envelope.iv, 'hex');
+    const tag = Buffer.from(envelope.tag, 'hex');
+    const ciphertext = Buffer.from(envelope.data, 'hex');
+    const decipher = node_crypto_1.default.createDecipheriv('aes-256-gcm', resolvedKey, iv);
+    if (options?.aad) {
+        const aadBuf = Buffer.isBuffer(options.aad) ? options.aad : Buffer.from(options.aad);
+        decipher.setAAD(aadBuf);
+    }
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([
+        decipher.update(ciphertext),
+        decipher.final()
+    ]);
+    const plaintextStr = decrypted.toString('utf8');
+    try {
+        return JSON.parse(plaintextStr);
+    }
+    catch {
+        return plaintextStr;
+    }
+}
+//# sourceMappingURL=aes-gcm.js.map

package/dist/cipher/aes-gcm.js.map

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

package/dist/cipher/decrypt-step.d.ts

@@ -0,0 +1,13 @@
+import { Step, ExecutionOptions } from '@siglo/core';
+import { FieldCipherOptions } from '../types';
+export declare class DecryptFieldsStep<TInput = any, TName extends string = string> extends Step<TInput, TInput, TName> {
+    constructor(name: TName, options: FieldCipherOptions<TInput>);
+    execute(param?: TInput, options?: ExecutionOptions): Promise<TInput>;
+    run(param?: TInput, options?: ExecutionOptions): Promise<TInput>;
+}
+/**
+ * Creates a step that decrypts encrypted context envelopes in-place back to their plaintext values.
+ * Supports dot-notation paths, KeyRing rotation, AAD verification, and lazy checkpoint re-key flags.
+ */
+export declare function decryptFieldsStep<const TName extends string, TInput>(name: TName, options: FieldCipherOptions<TInput>): DecryptFieldsStep<TInput, TName>;
+//# sourceMappingURL=decrypt-step.d.ts.map

package/dist/cipher/decrypt-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decrypt-step.d.ts","sourceRoot":"","sources":["../../src/cipher/decrypt-step.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAW,MAAM,UAAU,CAAC;AAkBvD,qBAAa,iBAAiB,CAAC,MAAM,GAAG,GAAG,EAAE,KAAK,SAAS,MAAM,GAAG,MAAM,CACxE,SAAQ,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;gBAEvB,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC;IAgGnD,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpE,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CAG1E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,EAClE,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAClC,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,CAElC"}

package/dist/cipher/decrypt-step.js

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DecryptFieldsStep = void 0;
+exports.decryptFieldsStep = decryptFieldsStep;
+const core_1 = require("@siglo/core");
+const aes_gcm_1 = require("./aes-gcm");
+const key_ring_1 = require("./key-ring");
+const paths_1 = require("../redaction/paths");
+function sanitizeStepInput(param) {
+    if (!param || typeof param !== 'object' || Array.isArray(param)) {
+        return param;
+    }
+    const clean = {};
+    for (const [key, val] of Object.entries(param)) {
+        if (key !== '$steps' && key !== '$history' && key !== '$stackId') {
+            clean[key] = val;
+        }
+    }
+    return clean;
+}
+class DecryptFieldsStep extends core_1.Step {
+    constructor(name, options) {
+        const action = async (ctx) => {
+            // 1. Resolve key or KeyRing
+            let keyOrRing;
+            if (options.keyRing) {
+                keyOrRing = options.keyRing;
+            }
+            else if (typeof options.secretKey === 'function') {
+                keyOrRing = await options.secretKey(ctx);
+            }
+            else {
+                keyOrRing = options.secretKey;
+            }
+            if (!keyOrRing) {
+                throw new core_1.ValidationException([{ field: 'secretKey', message: 'Secret key or KeyRing is required for decryption' }], { stepName: name, phase: 'action', retryable: false });
+            }
+            // 2. Resolve optional AAD and deriveKeyContext
+            const resolvedAad = typeof options.aad === 'function' ? options.aad(ctx) : options.aad;
+            const resolvedDeriveCtx = typeof options.deriveKeyContext === 'function'
+                ? options.deriveKeyContext(ctx)
+                : options.deriveKeyContext;
+            let hasRekeyNeeded = false;
+            // 3. Decrypt fields using structural sharing
+            const result = (0, paths_1.transformFields)(ctx, options.fields, (val, concretePath) => {
+                if (!(0, aes_gcm_1.isEncryptedEnvelope)(val)) {
+                    return val;
+                }
+                const fieldName = concretePath.join('.');
+                // Resolve key for this specific envelope
+                let keyToUse;
+                let activeKid;
+                if ((0, key_ring_1.isKeyRing)(keyOrRing)) {
+                    const active = keyOrRing.getActiveKey();
+                    activeKid = active instanceof Promise ? undefined : active.kid;
+                    if (val.kid) {
+                        keyToUse = keyOrRing.getKey(val.kid);
+                        if (!keyToUse) {
+                            throw new core_1.ValidationException([{ field: fieldName, message: `Failed to decrypt field '${fieldName}': key ID '${val.kid}' not found in KeyRing` }], { stepName: name, phase: 'action', retryable: false });
+                        }
+                        if (activeKid && val.kid !== activeKid) {
+                            hasRekeyNeeded = true;
+                            if (options.onNeedsRekey) {
+                                options.onNeedsRekey(ctx, fieldName, val.kid, activeKid);
+                            }
+                        }
+                    }
+                    else {
+                        // Legacy envelope without kid: try active key
+                        const activeRes = active instanceof Promise ? undefined : active;
+                        keyToUse = activeRes?.key;
+                    }
+                }
+                else {
+                    keyToUse = keyOrRing;
+                }
+                if (!keyToUse) {
+                    throw new core_1.ValidationException([{ field: fieldName, message: `Failed to resolve decryption key for field '${fieldName}'` }], { stepName: name, phase: 'action', retryable: false });
+                }
+                try {
+                    return (0, aes_gcm_1.decryptAESGCM)(val, keyToUse, {
+                        aad: resolvedAad,
+                        deriveKeyContext: resolvedDeriveCtx
+                    });
+                }
+                catch (err) {
+                    throw new core_1.ValidationException([{ field: fieldName, message: `Failed to decrypt field '${fieldName}': authentication tag verification failed` }], { stepName: name, phase: 'action', retryable: false, cause: err });
+                }
+            });
+            if (hasRekeyNeeded && !options.onNeedsRekey && typeof result === 'object' && result !== null) {
+                result.$needsRekey = true;
+            }
+            return result;
+        };
+        super(name, action);
+    }
+    execute(param, options) {
+        const cleanParam = param ? sanitizeStepInput(param) : param;
+        return super.execute(cleanParam, { pojo: true, ...options });
+    }
+    run(param, options) {
+        return this.execute(param, options);
+    }
+}
+exports.DecryptFieldsStep = DecryptFieldsStep;
+/**
+ * Creates a step that decrypts encrypted context envelopes in-place back to their plaintext values.
+ * Supports dot-notation paths, KeyRing rotation, AAD verification, and lazy checkpoint re-key flags.
+ */
+function decryptFieldsStep(name, options) {
+    return new DecryptFieldsStep(name, options);
+}
+//# sourceMappingURL=decrypt-step.js.map

package/dist/cipher/decrypt-step.js.map

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

package/dist/cipher/encrypt-step.d.ts

@@ -0,0 +1,13 @@
+import { Step, ExecutionOptions } from '@siglo/core';
+import { FieldCipherOptions } from '../types';
+export declare class EncryptFieldsStep<TInput = any, TName extends string = string> extends Step<TInput, TInput, TName> {
+    constructor(name: TName, options: FieldCipherOptions<TInput>);
+    execute(param?: TInput, options?: ExecutionOptions): Promise<TInput>;
+    run(param?: TInput, options?: ExecutionOptions): Promise<TInput>;
+}
+/**
+ * Creates a step that encrypts specified context fields in-place using AES-256-GCM envelope encryption.
+ * Supports dot-notation paths, wildcards, KeyRing rotation, AAD, and HKDF key derivation.
+ */
+export declare function encryptFieldsStep<const TName extends string, TInput>(name: TName, options: FieldCipherOptions<TInput>): EncryptFieldsStep<TInput, TName>;
+//# sourceMappingURL=encrypt-step.d.ts.map

package/dist/cipher/encrypt-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encrypt-step.d.ts","sourceRoot":"","sources":["../../src/cipher/encrypt-step.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAuB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAW,MAAM,UAAU,CAAC;AAkBvD,qBAAa,iBAAiB,CAAC,MAAM,GAAG,GAAG,EAAE,KAAK,SAAS,MAAM,GAAG,MAAM,CACxE,SAAQ,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC;gBAEvB,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC;IAsDnD,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpE,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;CAG1E;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,MAAM,EAClE,IAAI,EAAE,KAAK,EACX,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,GAClC,iBAAiB,CAAC,MAAM,EAAE,KAAK,CAAC,CAElC"}

package/dist/cipher/encrypt-step.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EncryptFieldsStep = void 0;
+exports.encryptFieldsStep = encryptFieldsStep;
+const core_1 = require("@siglo/core");
+const aes_gcm_1 = require("./aes-gcm");
+const key_ring_1 = require("./key-ring");
+const paths_1 = require("../redaction/paths");
+function sanitizeStepInput(param) {
+    if (!param || typeof param !== 'object' || Array.isArray(param)) {
+        return param;
+    }
+    const clean = {};
+    for (const [key, val] of Object.entries(param)) {
+        if (key !== '$steps' && key !== '$history' && key !== '$stackId') {
+            clean[key] = val;
+        }
+    }
+    return clean;
+}
+class EncryptFieldsStep extends core_1.Step {
+    constructor(name, options) {
+        const action = async (ctx) => {
+            // 1. Resolve key or KeyRing
+            let keyOrRing;
+            if (options.keyRing) {
+                keyOrRing = options.keyRing;
+            }
+            else if (typeof options.secretKey === 'function') {
+                keyOrRing = await options.secretKey(ctx);
+            }
+            else {
+                keyOrRing = options.secretKey;
+            }
+            if (!keyOrRing) {
+                throw new core_1.ValidationException([{ field: 'secretKey', message: 'Secret key or KeyRing is required for encryption' }], { stepName: name, phase: 'action', retryable: false });
+            }
+            let activeKey;
+            let activeKid;
+            if ((0, key_ring_1.isKeyRing)(keyOrRing)) {
+                const active = await keyOrRing.getActiveKey();
+                activeKey = active.key;
+                activeKid = active.kid;
+            }
+            else {
+                activeKey = keyOrRing;
+            }
+            // 2. Resolve optional AAD and deriveKeyContext
+            const resolvedAad = typeof options.aad === 'function' ? options.aad(ctx) : options.aad;
+            const resolvedDeriveCtx = typeof options.deriveKeyContext === 'function'
+                ? options.deriveKeyContext(ctx)
+                : options.deriveKeyContext;
+            // 3. Encrypt target fields using structural sharing
+            const result = (0, paths_1.transformFields)(ctx, options.fields, (val) => {
+                if (val !== undefined && val !== null && !(0, aes_gcm_1.isEncryptedEnvelope)(val)) {
+                    return (0, aes_gcm_1.encryptAESGCM)(val, activeKey, {
+                        kid: activeKid,
+                        aad: resolvedAad,
+                        deriveKeyContext: resolvedDeriveCtx
+                    });
+                }
+                return val;
+            });
+            return result;
+        };
+        super(name, action);
+    }
+    execute(param, options) {
+        const cleanParam = param ? sanitizeStepInput(param) : param;
+        return super.execute(cleanParam, { pojo: true, ...options });
+    }
+    run(param, options) {
+        return this.execute(param, options);
+    }
+}
+exports.EncryptFieldsStep = EncryptFieldsStep;
+/**
+ * Creates a step that encrypts specified context fields in-place using AES-256-GCM envelope encryption.
+ * Supports dot-notation paths, wildcards, KeyRing rotation, AAD, and HKDF key derivation.
+ */
+function encryptFieldsStep(name, options) {
+    return new EncryptFieldsStep(name, options);
+}
+//# sourceMappingURL=encrypt-step.js.map

package/dist/cipher/encrypt-step.js.map

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

package/dist/cipher/key-ring.d.ts

@@ -0,0 +1,24 @@
+import { KeyRing, KeyRingKey } from '../types';
+/**
+ * Type guard to check if an object satisfies the KeyRing interface.
+ */
+export declare function isKeyRing(val: unknown): val is KeyRing;
+/**
+ * In-memory multi-key provider supporting active key generation and historical key retrieval.
+ */
+export declare class StaticKeyRing implements KeyRing {
+    private activeKeyId;
+    private keys;
+    constructor(activeKeyId: string, keys: Record<string, string | Buffer> | Map<string, string | Buffer>);
+    getActiveKey(): KeyRingKey;
+    getKey(kid: string): string | Buffer | null;
+    /**
+     * Adds or rotates a key in the ring.
+     */
+    addKey(kid: string, key: string | Buffer, makeActive?: boolean): void;
+    /**
+     * Sets the active key ID for subsequent encryption operations.
+     */
+    setActiveKey(kid: string): void;
+}
+//# sourceMappingURL=key-ring.d.ts.map

package/dist/cipher/key-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-ring.d.ts","sourceRoot":"","sources":["../../src/cipher/key-ring.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE/C;;GAEG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,OAAO,CAOtD;AAED;;GAEG;AACH,qBAAa,aAAc,YAAW,OAAO;IAC3C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,IAAI,CAA2C;gBAGrD,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAetE,YAAY,IAAI,UAAU;IAW1B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI;IAI3C;;OAEG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,UAAU,GAAE,OAAe,GAAG,IAAI;IAO5E;;OAEG;IACH,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAMhC"}