@molecule/api-encryption-aes 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,18 @@
+/**
+ * Browser guard — `@molecule/api-encryption-aes` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-encryption-aes is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * AES-256-GCM encryption provider for molecule.dev.
+ *
+ * Uses Node.js built-in `crypto` for AES-256-GCM authenticated encryption,
+ * SHA-256 hashing, and timing-safe verification. Supports key rotation with
+ * versioned ciphertext format.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-encryption'
+ * import { provider } from '@molecule/api-encryption-aes'
+ *
+ * // Wire the provider at startup (reads ENCRYPTION_KEY from env)
+ * setProvider(provider)
+ *
+ * // Or create with explicit config
+ * import { createProvider } from '@molecule/api-encryption-aes'
+ * const customProvider = createProvider({ key: 'your-64-char-hex-key' })
+ * setProvider(customProvider)
+ * ```
+ *
+ * @remarks
+ * - **`rotateKey()` is transition-safe — it never orphans data.** Keys live in
+ *   a version-keyed keyring: `encrypt()` tags each ciphertext with the current
+ *   `v{n}`, `decrypt()` reads that tag and selects the matching key, and
+ *   `rotateKey(oldKey, newKey)` ADDS `newKey` at the next version while RETAINING
+ *   the prior key(s). So ciphertext written before a rotation still decrypts
+ *   afterward (the core contract's "previously encrypted data can still be
+ *   decrypted during a transition period"). Once you have re-encrypted the old
+ *   ciphertext under the new key, retire the old keys explicitly with
+ *   `pruneKeyVersions()` — rotation alone deliberately keeps them.
+ * - A ciphertext whose `v{n}` version is not in the keyring (unknown/pruned key)
+ *   fails cleanly with a descriptive error — never a silent wrong decrypt.
+ * - Rotation state is per-process and in-memory: the lazy `provider` singleton
+ *   starts a fresh keyring at version 1 from `ENCRYPTION_KEY` on each process,
+ *   so a rotation done in a prior process is not restored. For rotation that
+ *   survives restarts, build with `createProvider({ key, priorKeys })`, seeding
+ *   the historical `{ version, key }` entries from your secret store.
+ * - `hash()`/`verify()` are plain unsalted SHA-256 — integrity checks only.
+ *   NEVER use them for passwords; use `@molecule/api-password` with a bond
+ *   like `@molecule/api-password-bcrypt`.
+ * - `encrypt(plaintext, context)`: the optional `context` is GCM AAD — the
+ *   SAME context string must be supplied to `decrypt()` or authentication
+ *   fails.
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,50 @@
+/**
+ * AES-256-GCM encryption provider for molecule.dev.
+ *
+ * Uses Node.js built-in `crypto` for AES-256-GCM authenticated encryption,
+ * SHA-256 hashing, and timing-safe verification. Supports key rotation with
+ * versioned ciphertext format.
+ *
+ * @module
+ * @example
+ * ```typescript
+ * import { setProvider } from '@molecule/api-encryption'
+ * import { provider } from '@molecule/api-encryption-aes'
+ *
+ * // Wire the provider at startup (reads ENCRYPTION_KEY from env)
+ * setProvider(provider)
+ *
+ * // Or create with explicit config
+ * import { createProvider } from '@molecule/api-encryption-aes'
+ * const customProvider = createProvider({ key: 'your-64-char-hex-key' })
+ * setProvider(customProvider)
+ * ```
+ *
+ * @remarks
+ * - **`rotateKey()` is transition-safe — it never orphans data.** Keys live in
+ *   a version-keyed keyring: `encrypt()` tags each ciphertext with the current
+ *   `v{n}`, `decrypt()` reads that tag and selects the matching key, and
+ *   `rotateKey(oldKey, newKey)` ADDS `newKey` at the next version while RETAINING
+ *   the prior key(s). So ciphertext written before a rotation still decrypts
+ *   afterward (the core contract's "previously encrypted data can still be
+ *   decrypted during a transition period"). Once you have re-encrypted the old
+ *   ciphertext under the new key, retire the old keys explicitly with
+ *   `pruneKeyVersions()` — rotation alone deliberately keeps them.
+ * - A ciphertext whose `v{n}` version is not in the keyring (unknown/pruned key)
+ *   fails cleanly with a descriptive error — never a silent wrong decrypt.
+ * - Rotation state is per-process and in-memory: the lazy `provider` singleton
+ *   starts a fresh keyring at version 1 from `ENCRYPTION_KEY` on each process,
+ *   so a rotation done in a prior process is not restored. For rotation that
+ *   survives restarts, build with `createProvider({ key, priorKeys })`, seeding
+ *   the historical `{ version, key }` entries from your secret store.
+ * - `hash()`/`verify()` are plain unsalted SHA-256 — integrity checks only.
+ *   NEVER use them for passwords; use `@molecule/api-password` with a bond
+ *   like `@molecule/api-password-bcrypt`.
+ * - `encrypt(plaintext, context)`: the optional `context` is GCM AAD — the
+ *   SAME context string must be supplied to `decrypt()` or authentication
+ *   fails.
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './types.js';

package/dist/provider.d.ts

@@ -0,0 +1,46 @@
+/**
+ * AES-256-GCM implementation of `EncryptionProvider`.
+ *
+ * Uses Node.js built-in `crypto` module for all operations:
+ * - **encrypt/decrypt**: AES-256-GCM with random IV and authentication tag
+ * - **hash**: SHA-256
+ * - **verify**: Timing-safe comparison of SHA-256 hashes
+ * - **rotateKey**: Adds the new key to a versioned keyring (retaining prior
+ *   keys) so ciphertext encrypted before the rotation still decrypts
+ *
+ * Ciphertext format: `v{keyVersion}:{iv}:{authTag}:{ciphertext}` (all
+ * hex-encoded). `decrypt()` reads the `v{n}` tag and selects the matching key
+ * from the keyring — so a rotation never orphans existing data.
+ *
+ * @module
+ */
+import './secrets.js';
+import type { AesConfig, AesEncryptionProvider } from './types.js';
+/**
+ * Creates an AES-256-GCM encryption provider.
+ *
+ * Rotation is transition-safe: keys are held in a version-keyed keyring.
+ * `encrypt()` tags each ciphertext with the current key version, `decrypt()`
+ * selects the key named by that tag, and `rotateKey()` ADDS the new key while
+ * keeping prior keys — so ciphertext from before a rotation still decrypts.
+ * Retire old keys explicitly (once their data is re-encrypted) via
+ * `pruneKeyVersions()`.
+ *
+ * @param config - Provider configuration including the hex-encoded 256-bit key.
+ * @returns An `AesEncryptionProvider` using AES-256-GCM.
+ */
+export declare const createProvider: (config: AesConfig) => AesEncryptionProvider;
+/**
+ * Default AES-256-GCM encryption provider instance.
+ *
+ * Lazily initializes on first property access using the `ENCRYPTION_KEY`
+ * environment variable (hex-encoded 256-bit key). This singleton starts a
+ * fresh keyring at version 1 on each process, so a rotation performed in a
+ * prior process is NOT restored here — for rotation that survives restarts,
+ * construct with `createProvider({ key, priorKeys })` seeding the historical
+ * keys from your secret store.
+ *
+ * @throws {Error} If `ENCRYPTION_KEY` environment variable is not set.
+ */
+export declare const provider: AesEncryptionProvider;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAaH,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AA0ClE;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,SAAS,KAAG,qBAoHlD,CAAA;AAKD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,EAAE,qBA0BrB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,196 @@
+/**
+ * AES-256-GCM implementation of `EncryptionProvider`.
+ *
+ * Uses Node.js built-in `crypto` module for all operations:
+ * - **encrypt/decrypt**: AES-256-GCM with random IV and authentication tag
+ * - **hash**: SHA-256
+ * - **verify**: Timing-safe comparison of SHA-256 hashes
+ * - **rotateKey**: Adds the new key to a versioned keyring (retaining prior
+ *   keys) so ciphertext encrypted before the rotation still decrypts
+ *
+ * Ciphertext format: `v{keyVersion}:{iv}:{authTag}:{ciphertext}` (all
+ * hex-encoded). `decrypt()` reads the `v{n}` tag and selects the matching key
+ * from the keyring — so a rotation never orphans existing data.
+ *
+ * @module
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual, } from 'node:crypto';
+// Side-effect import: registers this bond's secret definitions so the
+// runtime registry is populated even when provider.js is imported directly
+// (not through the package barrel).
+import './secrets.js';
+/** AES-256-GCM algorithm identifier. */
+const ALGORITHM = 'aes-256-gcm';
+/** IV length in bytes (96-bit / 12 bytes recommended for GCM). */
+const IV_LENGTH = 12;
+/** Authentication tag length in bytes. */
+const AUTH_TAG_LENGTH = 16;
+/** Parses the `v{n}` key-version prefix of a ciphertext tag. */
+const parseKeyVersion = (tag) => {
+    const match = /^v(\d+)$/.exec(tag);
+    return match ? Number(match[1]) : null;
+};
+/** A 256-bit key is exactly 64 hex characters. */
+const HEX_256_BIT = /^[0-9a-fA-F]{64}$/;
+/**
+ * Decode a hex-encoded 256-bit key, refusing anything that isn't exactly 64 hex
+ * chars. `Buffer.from(x, 'hex')` SILENTLY truncates at the first non-hex byte
+ * and silently drops an odd trailing nibble, so a typo'd or short key would
+ * otherwise yield a wrong-length buffer that either 500s on every encrypt or —
+ * worse — encrypts under a key nobody can reproduce. Fail loud at construction.
+ *
+ * @param key - The hex-encoded key to validate and decode.
+ * @param label - Human context for the error (e.g. `'ENCRYPTION_KEY'`).
+ * @returns The 32-byte key buffer.
+ * @throws {Error} When the key is not exactly 64 hex characters.
+ */
+const decodeKey = (key, label) => {
+    if (!HEX_256_BIT.test(key)) {
+        throw new Error(`Invalid AES ${label}: expected exactly 64 hex characters (a 256-bit key); ` +
+            `got ${key.length} character(s). Generate one with \`openssl rand -hex 32\`.`);
+    }
+    return Buffer.from(key, 'hex');
+};
+/**
+ * Creates an AES-256-GCM encryption provider.
+ *
+ * Rotation is transition-safe: keys are held in a version-keyed keyring.
+ * `encrypt()` tags each ciphertext with the current key version, `decrypt()`
+ * selects the key named by that tag, and `rotateKey()` ADDS the new key while
+ * keeping prior keys — so ciphertext from before a rotation still decrypts.
+ * Retire old keys explicitly (once their data is re-encrypted) via
+ * `pruneKeyVersions()`.
+ *
+ * @param config - Provider configuration including the hex-encoded 256-bit key.
+ * @returns An `AesEncryptionProvider` using AES-256-GCM.
+ */
+export const createProvider = (config) => {
+    let currentVersion = config.keyVersion ?? 1;
+    let currentKey = decodeKey(config.key, 'key');
+    // Version -> key buffer. Rotation adds a new version and retains prior keys,
+    // so ciphertext tagged with an older `v{n}` still decrypts. Seed historical
+    // keys first, then set the current one so it wins on any version collision.
+    const keyring = new Map();
+    for (const prior of config.priorKeys ?? []) {
+        keyring.set(prior.version, decodeKey(prior.key, `priorKeys[v${prior.version}]`));
+    }
+    keyring.set(currentVersion, currentKey);
+    return {
+        async encrypt(plaintext, context) {
+            const iv = randomBytes(IV_LENGTH);
+            const cipher = createCipheriv(ALGORITHM, currentKey, iv, { authTagLength: AUTH_TAG_LENGTH });
+            if (context) {
+                cipher.setAAD(Buffer.from(context, 'utf-8'));
+            }
+            const encrypted = Buffer.concat([cipher.update(plaintext, 'utf-8'), cipher.final()]);
+            const authTag = cipher.getAuthTag();
+            return `v${currentVersion}:${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted.toString('hex')}`;
+        },
+        async decrypt(ciphertext, context) {
+            const parts = ciphertext.split(':');
+            if (parts.length !== 4) {
+                throw new Error('Invalid ciphertext format');
+            }
+            const version = parseKeyVersion(parts[0]);
+            if (version === null) {
+                throw new Error('Invalid ciphertext format: missing or malformed key version prefix');
+            }
+            // Select the key that ENCRYPTED this ciphertext by its version tag — not
+            // the current key — so pre-rotation ciphertext decrypts with its own key.
+            const key = keyring.get(version);
+            if (!key) {
+                throw new Error(`No encryption key available for key version ${version}; ` +
+                    `seed it via priorKeys or do not prune it before re-encrypting its ciphertext`);
+            }
+            const iv = Buffer.from(parts[1], 'hex');
+            const authTag = Buffer.from(parts[2], 'hex');
+            const encrypted = Buffer.from(parts[3], 'hex');
+            const decipher = createDecipheriv(ALGORITHM, key, iv, {
+                authTagLength: AUTH_TAG_LENGTH,
+            });
+            decipher.setAuthTag(authTag);
+            if (context) {
+                decipher.setAAD(Buffer.from(context, 'utf-8'));
+            }
+            const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+            return decrypted.toString('utf-8');
+        },
+        async hash(data) {
+            return createHash('sha256').update(data, 'utf-8').digest('hex');
+        },
+        async verify(data, hashed) {
+            const computed = createHash('sha256').update(data, 'utf-8').digest('hex');
+            if (computed.length !== hashed.length) {
+                return false;
+            }
+            return timingSafeEqual(Buffer.from(computed, 'utf-8'), Buffer.from(hashed, 'utf-8'));
+        },
+        async rotateKey(oldKey, newKey) {
+            // Validate the NEW key before anything else: a malformed newKey must not
+            // become currentKey (it would encrypt future data under a wrong-length /
+            // truncated key). oldKey is only compared, so a bad one just fails to match.
+            const newBuffer = decodeKey(newKey, 'newKey');
+            const oldBuffer = Buffer.from(oldKey, 'hex');
+            if (oldBuffer.length !== currentKey.length || !timingSafeEqual(oldBuffer, currentKey)) {
+                throw new Error('Old key does not match the current encryption key');
+            }
+            // Add the new key at the next version and make it current. The prior key
+            // stays in the keyring so ciphertext tagged with the old version still
+            // decrypts — rotation NEVER orphans existing data. Retire old keys
+            // explicitly with pruneKeyVersions() once their data is re-encrypted.
+            currentVersion += 1;
+            currentKey = newBuffer;
+            keyring.set(currentVersion, currentKey);
+        },
+        pruneKeyVersions(keep) {
+            const retained = new Set([currentVersion, ...(keep ?? [])]);
+            const pruned = [];
+            for (const version of keyring.keys()) {
+                if (!retained.has(version)) {
+                    pruned.push(version);
+                }
+            }
+            for (const version of pruned) {
+                keyring.delete(version);
+            }
+            return pruned;
+        },
+    };
+};
+/** Lazily-initialized default provider instance. */
+let _provider = null;
+/**
+ * Default AES-256-GCM encryption provider instance.
+ *
+ * Lazily initializes on first property access using the `ENCRYPTION_KEY`
+ * environment variable (hex-encoded 256-bit key). This singleton starts a
+ * fresh keyring at version 1 on each process, so a rotation performed in a
+ * prior process is NOT restored here — for rotation that survives restarts,
+ * construct with `createProvider({ key, priorKeys })` seeding the historical
+ * keys from your secret store.
+ *
+ * @throws {Error} If `ENCRYPTION_KEY` environment variable is not set.
+ */
+export const provider = new Proxy({}, {
+    get(_, prop, receiver) {
+        if (!_provider) {
+            const key = process.env['ENCRYPTION_KEY'];
+            if (!key) {
+                throw new Error('ENCRYPTION_KEY environment variable is required for AES encryption provider');
+            }
+            _provider = createProvider({ key });
+        }
+        return Reflect.get(_provider, prop, receiver);
+    },
+    // set trap: methods run with `this` bound to the proxy — without it, instance-state writes land on the dummy target and are lost (see api-push-notifications-web-push)
+    set(_, prop, value) {
+        if (!_provider) {
+            const key = process.env['ENCRYPTION_KEY'];
+            if (!key) {
+                throw new Error('ENCRYPTION_KEY environment variable is required for AES encryption provider');
+            }
+            _provider = createProvider({ key });
+        }
+        return Reflect.set(_provider, prop, value);
+    },
+});

package/dist/secrets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * AES encryption secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import type { SecretDefinition } from '@molecule/api-secrets';
+/** Secret definitions required by the AES encryption bond. */
+export declare const encryptionAesSecretDefinitions: SecretDefinition[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,EAAE,gBAAgB,EAO5D,CAAA"}

package/dist/secrets.js

@@ -0,0 +1,22 @@
+/**
+ * AES encryption secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions required by the AES encryption bond. */
+export const encryptionAesSecretDefinitions = [
+    {
+        key: 'ENCRYPTION_KEY',
+        description: 'AES-256 encryption key — 64-character hex (256-bit) key for AES-GCM encryption. Auto-generated at scaffold — no manual setup needed.',
+        required: true,
+    },
+];
+registerSecrets(encryptionAesSecretDefinitions);

package/dist/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * AES-256-GCM encryption provider configuration.
+ *
+ * @module
+ */
+import type { EncryptionProvider } from '@molecule/api-encryption';
+/**
+ * A historical (pre-rotation) key, retained so ciphertext encrypted under it
+ * remains decryptable.
+ *
+ * Ciphertext is tagged with the `v{version}` of the key that produced it; the
+ * provider selects the matching key from its keyring at decrypt time. Seed the
+ * keyring with the app's prior keys (from a secret store) so rotations survive
+ * a process restart — see {@link AesConfig.priorKeys}.
+ */
+export interface PriorKey {
+    /** The key version tag this key decrypts (matches the `v{n}` ciphertext prefix). */
+    version: number;
+    /** The 256-bit key, hex-encoded (64 hex characters). */
+    key: string;
+}
+/**
+ * Configuration options for the AES-256-GCM encryption provider.
+ */
+export interface AesConfig {
+    /** The current 256-bit encryption key, hex-encoded (64 hex characters). */
+    key: string;
+    /**
+     * Version of the current `key`. Ciphertext produced by `encrypt()` is tagged
+     * with this version; `decrypt()` selects the key to use from the `v{n}` tag,
+     * so it must be stable for a given key. `rotateKey()` advances it.
+     *
+     * @default 1
+     */
+    keyVersion?: number;
+    /**
+     * Prior keys to seed the keyring with, so ciphertext encrypted before a
+     * rotation still decrypts after this provider is (re)constructed — e.g. on a
+     * process restart, when the in-memory rotation state would otherwise be lost.
+     * Each entry maps a historical `v{n}` version to its key. The current `key`
+     * (at {@link AesConfig.keyVersion}) always wins over any prior entry sharing
+     * its version.
+     *
+     * @default []
+     */
+    priorKeys?: PriorKey[];
+}
+/**
+ * AES-256-GCM encryption provider.
+ *
+ * Fully satisfies the core `EncryptionProvider` contract, so it bonds anywhere
+ * an `EncryptionProvider` is expected. It additionally exposes
+ * {@link AesEncryptionProvider.pruneKeyVersions} to explicitly retire old keys
+ * once their ciphertext has been re-encrypted — rotation alone never drops a
+ * key, so it can never orphan data.
+ */
+export interface AesEncryptionProvider extends EncryptionProvider {
+    /**
+     * Retires key versions from the in-memory keyring. Call this only AFTER every
+     * ciphertext encrypted under those versions has been re-encrypted under the
+     * current key — a pruned version can no longer decrypt its ciphertext.
+     *
+     * The current key version is ALWAYS retained (it cannot be pruned). By
+     * default every non-current version is removed; pass `keep` to retain
+     * specific older versions during a staged migration.
+     *
+     * @param keep - Old versions to retain in addition to the current one.
+     * @returns The versions that were removed.
+     */
+    pruneKeyVersions(keep?: number[]): number[];
+}
+//# 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;;;;GAIG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAElE;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACvB,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAA;IAEf,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAA;IAEX;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;CACvB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D;;;;;;;;;;;OAWG;IACH,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAA;CAC5C"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * AES-256-GCM encryption provider configuration.
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@molecule/api-encryption-aes",
+  "version": "1.0.0",
+  "description": "AES-256-GCM encryption provider for molecule.dev — authenticated encryption, SHA-256 hashing, and key rotation",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "molecule",
+    "encryption",
+    "aes",
+    "aes-256-gcm",
+    "field-level-encryption",
+    "key-rotation"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@molecule/api-encryption": "^1.0.0",
+    "@molecule/api-secrets": "^1.0.0"
+  },
+  "devDependencies": {
+    "@molecule/api-encryption": "1.0.0",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/encryption/aes"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/encryption/aes",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}