@agentshouse/envelope 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,32 @@
+# @agentshouse/envelope
+
+The AES-256-GCM purpose-bound envelope agents.house seals recoverable secrets
+with. Every value gets a fresh data key and nonce, an authentication tag, and an
+authenticated context that binds it to its immutable owning object and one
+purpose the caller supplies. Key management stays behind a port the caller
+implements, so the package names no purpose and no key-management provider.
+
+## Use
+
+```js
+const { open, seal } = require('@agentshouse/envelope');
+
+const envelope = await seal(keys, 'provider-token', objectId, plaintext);
+const token = await open(keys, 'provider-token', objectId, envelope, (plaintext) =>
+  plaintext.toString('utf8'),
+);
+```
+
+`keys` implements `Keys`: `wrap(dataKey, authenticatedData)` and
+`unwrap(wrappedDataKey, authenticatedData)`. The authenticated context is the
+canonical JSON `{"object":…,"purpose":…,"version":1}` and is passed to both.
+`objectId` is a UUID.
+
+The `Envelope` is five components the caller stores as they are: `version`,
+`wrappedDataKey`, `nonce`, `tag` and `ciphertext`. `open` refuses a malformed or
+forged envelope, and one opened under another object or purpose, with
+`IntegrityError`. `valid(envelope)` is the check of the stored form `open`
+makes before it asks the port, so a caller can refuse a malformed record when it
+reads one. An error the port throws passes through unchanged, so the caller maps
+its own refusals and unavailability. The plaintext exists only inside the
+callback and is wiped when it returns.

package/index.d.ts

@@ -0,0 +1,17 @@
+export interface Keys {
+    wrap(dataKey: Uint8Array, authenticatedData: Uint8Array): Promise<Uint8Array>;
+    unwrap(wrappedDataKey: Uint8Array, authenticatedData: Uint8Array): Promise<Uint8Array>;
+}
+export interface Envelope {
+    readonly version: number;
+    readonly wrappedDataKey: Buffer;
+    readonly nonce: Buffer;
+    readonly tag: Buffer;
+    readonly ciphertext: Buffer;
+}
+export declare class IntegrityError extends Error {
+    constructor();
+}
+export declare function valid(envelope: Envelope): boolean;
+export declare function seal(keys: Keys, purpose: string, objectId: string, plaintext: Uint8Array): Promise<Envelope>;
+export declare function open<T>(keys: Keys, purpose: string, objectId: string, envelope: Envelope, work: (plaintext: Buffer) => Promise<T> | T): Promise<T>;

package/index.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IntegrityError = void 0;
+exports.valid = valid;
+exports.seal = seal;
+exports.open = open;
+const node_crypto_1 = require("node:crypto");
+const VERSION = 1;
+const DATA_KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+const TAG_BYTES = 16;
+const OBJECT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+class IntegrityError extends Error {
+    constructor() {
+        super('envelope_integrity');
+        this.name = 'IntegrityError';
+    }
+}
+exports.IntegrityError = IntegrityError;
+function authenticatedContext(purpose, objectId) {
+    if (!OBJECT_ID.test(objectId))
+        throw new IntegrityError();
+    return Buffer.from(JSON.stringify({ object: objectId, purpose, version: VERSION }), 'utf8');
+}
+function length(component) {
+    return component instanceof Uint8Array ? component.length : -1;
+}
+function valid(envelope) {
+    return (envelope.version === VERSION &&
+        length(envelope.wrappedDataKey) > 0 &&
+        length(envelope.nonce) === NONCE_BYTES &&
+        length(envelope.tag) === TAG_BYTES &&
+        length(envelope.ciphertext) > 0);
+}
+async function seal(keys, purpose, objectId, plaintext) {
+    if (plaintext.length < 1)
+        throw new IntegrityError();
+    const aad = authenticatedContext(purpose, objectId);
+    const dataKey = (0, node_crypto_1.randomBytes)(DATA_KEY_BYTES);
+    try {
+        const nonce = (0, node_crypto_1.randomBytes)(NONCE_BYTES);
+        const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', dataKey, nonce);
+        cipher.setAAD(aad);
+        const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+        const tag = cipher.getAuthTag();
+        const wrappedDataKey = Buffer.from(await keys.wrap(dataKey, aad));
+        return { version: VERSION, wrappedDataKey, nonce, tag, ciphertext };
+    }
+    finally {
+        dataKey.fill(0);
+    }
+}
+async function open(keys, purpose, objectId, envelope, work) {
+    if (!valid(envelope))
+        throw new IntegrityError();
+    const aad = authenticatedContext(purpose, objectId);
+    const dataKey = Buffer.from(await keys.unwrap(envelope.wrappedDataKey, aad));
+    let opened;
+    try {
+        try {
+            const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', dataKey, envelope.nonce);
+            decipher.setAAD(aad);
+            decipher.setAuthTag(envelope.tag);
+            opened = Buffer.concat([decipher.update(envelope.ciphertext), decipher.final()]);
+        }
+        catch {
+            throw new IntegrityError();
+        }
+        return await work(opened);
+    }
+    finally {
+        dataKey.fill(0);
+        opened?.fill(0);
+    }
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@agentshouse/envelope",
+  "version": "0.1.0-alpha.1",
+  "description": "AES-256-GCM purpose-bound envelope over a key-management port: a fresh data key and nonce per value, bound to its owning object and one caller purpose.",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "*.js",
+    "*.d.ts",
+    "README.md"
+  ]
+}