neozip-blockchain 1.0.5 → 1.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 Blockchain functionality for NeoZip: **NeoZip Token Service timestamping** (stamp, upgrade, mint, verify), NFT minting, verification, and wallet management. Part of the [neozipkit monorepo](../../README.md).
 
-> **Stable 1.0:** This package **1.0.5** (first non-beta was **1.0.2**). Format profile: [NEOZIP_APPNOTE.md](../neozipkit/NEOZIP_APPNOTE.md). See [WHATS_NEW.md](WHATS_NEW.md).
+> **Stable 1.5:** This package **1.5.0** (identity-based encryption; pairs with `neozipkit@1.5.0`). Format profile: [NEOZIP_APPNOTE.md](../neozipkit/NEOZIP_APPNOTE.md). See [WHATS_NEW.md](WHATS_NEW.md).
 
 See [WHATS_NEW.md](WHATS_NEW.md) for release notes.
 
@@ -16,6 +16,7 @@ This package provides the client-side API and utilities that work with the sibli
 - **Wallet Management**: Browser and Node.js wallet integrations
 - **Multi-Network Support**: Base Mainnet, Base Sepolia, and more
 - **Examples**: Runnable scripts for stamp, upgrade, mint, verify, and token-create flows (see [`examples/README.md`](examples/README.md), `examples/`, and `package.json` `example:*` scripts)
+- **Identity encryption**: Encrypt `.nzip` archives for ENS / address / Lit PKP recipients (`neozip-blockchain/encryption` + `neozip-blockchain/identity`). See [docs/ENCRYPTION.md](docs/ENCRYPTION.md).
 
 ## Installation
 

package/WHATS_NEW.md

@@ -2,6 +2,32 @@
 
 Release notes for people who install and use **`neozip-blockchain`** from npm (alongside [`neozipkit`](https://www.npmjs.com/package/neozipkit)).
 
+## 1.5.0 (2026-10-25)
+
+Released with sibling **`neozipkit@1.5.0`** (Zip64, Extra Field `0x014F`, browser/buffer zstd, `forceZip64`).
+
+### Identity-based (recipient) encryption
+
+Moved from the former private `@neowareinc/neozipkit-pro` package into this library:
+
+- **`neozip-blockchain/encryption`** — ECIES key wrapping (secp256k1 / X25519 + AES-256-GCM), `META-INF/ACCESS.NZIP`, `encryptForRecipients` / `decryptAsRecipient`
+- **`neozip-blockchain/identity`** — ENS / address / Lit PKP resolvers for recipient public keys
+
+Inner ZIP entry encryption still uses **neozipkit** NeoEncrypt (`neo-aes256`) by default. See [docs/ENCRYPTION.md](docs/ENCRYPTION.md).
+
+HKDF domain-separation strings are unchanged (`neozipkit-pro/ecies/v1`, …) so existing recipient-encrypted archives remain decryptable.
+
+```bash
+npm install neozipkit@^1.5.0 neozip-blockchain@^1.5.0
+```
+
+```typescript
+import { encryptForRecipients } from 'neozip-blockchain/encryption';
+import { ENSResolver } from 'neozip-blockchain/identity';
+```
+
+---
+
 ## 1.0.5 (2026-08-14)
 
 ### Token Service network profiles (Base Sepolia + Base Mainnet)

package/dist/encryption/AccessMetadata.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Serialize and parse META-INF/ACCESS.NZIP — the JSON envelope that stores
+ * ECIES-wrapped AES passwords and recipient identity information.
+ */
+import { type ResolvedIdentity } from '../identity/types';
+import type { AccessControlMetadata, WrappedKeyResult } from './types';
+/** Well-known path inside a .nzip archive for recipient access control. */
+export declare const ACCESS_NZIP_PATH = "META-INF/ACCESS.NZIP";
+/**
+ * Build an AccessControlMetadata object from resolved identities and their
+ * individually wrapped keys.
+ */
+export declare function buildAccessMetadata(recipients: Array<{
+    resolved: ResolvedIdentity;
+    wrapped: WrappedKeyResult;
+}>, scheme?: AccessControlMetadata['scheme'], innerZipEncryption?: 'neo-aes256' | 'aes256'): AccessControlMetadata;
+/** Serialize metadata to a UTF-8 buffer suitable for writing as a ZIP entry. */
+export declare function serializeAccessMetadata(metadata: AccessControlMetadata): Buffer;
+/**
+ * Parse a raw buffer (extracted from META-INF/ACCESS.NZIP) back into typed metadata.
+ * Throws on malformed JSON or missing required fields.
+ */
+export declare function parseAccessMetadata(raw: Buffer | string): AccessControlMetadata;
+//# sourceMappingURL=AccessMetadata.d.ts.map

package/dist/encryption/AccessMetadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccessMetadata.d.ts","sourceRoot":"","sources":["../../src/encryption/AccessMetadata.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,KAAK,EACV,qBAAqB,EAErB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAEjB,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,KAAK,CAAC;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,CAAC,EAC5E,MAAM,GAAE,qBAAqB,CAAC,QAAQ,CAAgB,EACtD,kBAAkB,GAAE,YAAY,GAAG,QAAuB,GACzD,qBAAqB,CAgCvB;AAED,gFAAgF;AAChF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,qBAAqB,GAC9B,MAAM,CAER;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,qBAAqB,CAsB/E"}

package/dist/encryption/AccessMetadata.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Serialize and parse META-INF/ACCESS.NZIP — the JSON envelope that stores
+ * ECIES-wrapped AES passwords and recipient identity information.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ACCESS_NZIP_PATH = void 0;
+exports.buildAccessMetadata = buildAccessMetadata;
+exports.serializeAccessMetadata = serializeAccessMetadata;
+exports.parseAccessMetadata = parseAccessMetadata;
+const version_1 = require("../version");
+const types_1 = require("../identity/types");
+/** Well-known path inside a .nzip archive for recipient access control. */
+exports.ACCESS_NZIP_PATH = 'META-INF/ACCESS.NZIP';
+/**
+ * Build an AccessControlMetadata object from resolved identities and their
+ * individually wrapped keys.
+ */
+function buildAccessMetadata(recipients, scheme = 'ens-hybrid', innerZipEncryption = 'neo-aes256') {
+    const encryptionInner = innerZipEncryption === 'aes256'
+        ? {
+            method: 'aes-256-winzip',
+            note: 'AES key derived via PBKDF2 from wrapped password (neozipkit AE-1)',
+        }
+        : {
+            method: 'neo-aes256',
+            note: 'NeoEncrypt (NEO extra 0x024E); AES-256 via PBKDF2 from wrapped password (neozipkit)',
+        };
+    const wrappedRecipients = recipients.map(({ resolved, wrapped }) => ({
+        identity: resolved.identity,
+        identityType: resolved.identityType,
+        resolvedAddress: resolved.address,
+        publicKeyHex: resolved.publicKeyHex,
+        wrappedKey: wrapped.ciphertext,
+        ephemeralPublicKey: wrapped.ephemeralPublicKey,
+        keyAlgorithm: wrapped.keyAlgorithm,
+    }));
+    return {
+        version: '1.0',
+        scheme,
+        recipients: wrappedRecipients,
+        encryption: encryptionInner,
+        created: new Date().toISOString(),
+        proVersion: version_1.VERSION,
+    };
+}
+/** Serialize metadata to a UTF-8 buffer suitable for writing as a ZIP entry. */
+function serializeAccessMetadata(metadata) {
+    return Buffer.from(JSON.stringify(metadata, null, 2), 'utf8');
+}
+/**
+ * Parse a raw buffer (extracted from META-INF/ACCESS.NZIP) back into typed metadata.
+ * Throws on malformed JSON or missing required fields.
+ */
+function parseAccessMetadata(raw) {
+    const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+    const parsed = JSON.parse(text);
+    if (!parsed.version || !parsed.scheme || !Array.isArray(parsed.recipients)) {
+        throw new Error('Invalid ACCESS.NZIP: missing version, scheme, or recipients');
+    }
+    for (const r of parsed.recipients) {
+        if (!r.identityType || !(0, types_1.isIdentityType)(r.identityType)) {
+            throw new Error(`Invalid ACCESS.NZIP recipient "${r.identity ?? '?'}": unknown or missing identityType`);
+        }
+        if (!r.wrappedKey || !r.ephemeralPublicKey || !r.keyAlgorithm) {
+            throw new Error(`Invalid ACCESS.NZIP recipient "${r.identity}": missing wrappedKey, ephemeralPublicKey, or keyAlgorithm`);
+        }
+    }
+    return parsed;
+}
+//# sourceMappingURL=AccessMetadata.js.map

package/dist/encryption/AccessMetadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AccessMetadata.js","sourceRoot":"","sources":["../../src/encryption/AccessMetadata.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAiBH,kDAoCC;AAGD,0DAIC;AAMD,kDAsBC;AAtFD,wCAAqC;AACrC,6CAA0E;AAO1E,2EAA2E;AAC9D,QAAA,gBAAgB,GAAG,sBAAsB,CAAC;AAEvD;;;GAGG;AACH,SAAgB,mBAAmB,CACjC,UAA4E,EAC5E,SAA0C,YAAY,EACtD,qBAA8C,YAAY;IAE1D,MAAM,eAAe,GACnB,kBAAkB,KAAK,QAAQ;QAC7B,CAAC,CAAC;YACE,MAAM,EAAE,gBAAyB;YACjC,IAAI,EAAE,mEAAmE;SAC1E;QACH,CAAC,CAAC;YACE,MAAM,EAAE,YAAqB;YAC7B,IAAI,EAAE,qFAAqF;SAC5F,CAAC;IAER,MAAM,iBAAiB,GAAuB,UAAU,CAAC,GAAG,CAC1D,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;QAC1B,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,eAAe,EAAE,QAAQ,CAAC,OAAO;QACjC,YAAY,EAAE,QAAQ,CAAC,YAAY;QACnC,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;QAC9C,YAAY,EAAE,OAAO,CAAC,YAAY;KACnC,CAAC,CACH,CAAC;IAEF,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM;QACN,UAAU,EAAE,iBAAiB;QAC7B,UAAU,EAAE,eAAe;QAC3B,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACjC,UAAU,EAAE,iBAAO;KACpB,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,SAAgB,uBAAuB,CACrC,QAA+B;IAE/B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,SAAgB,mBAAmB,CAAC,GAAoB;IACtD,MAAM,IAAI,GAAG,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAA0B,CAAC;IAEzD,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACjF,CAAC;IAED,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,IAAA,sBAAc,EAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC;YACvD,MAAM,IAAI,KAAK,CACb,kCAAkC,CAAC,CAAC,QAAQ,IAAI,GAAG,oCAAoC,CACxF,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,kBAAkB,IAAI,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC;YAC9D,MAAM,IAAI,KAAK,CACb,kCAAkC,CAAC,CAAC,QAAQ,4DAA4D,CACzG,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/encryption/KeyWrapper.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ECIES key wrapping using secp256k1.
+ *
+ * Encrypt:
+ *   1. Generate ephemeral secp256k1 key pair
+ *   2. ECDH(ephemeral private, recipient public) → shared secret
+ *   3. HKDF-SHA256(shared secret) → 32-byte wrapping key
+ *   4. AES-256-GCM encrypt plaintext with wrapping key
+ *
+ * Decrypt:
+ *   1. ECDH(recipient private, ephemeral public) → same shared secret
+ *   2. HKDF-SHA256(shared secret) → same wrapping key
+ *   3. AES-256-GCM decrypt ciphertext
+ */
+import type { WrappedKeyResult } from './types';
+export declare const KEY_ALGORITHM_SECP256K1 = "ecies-secp256k1-aes256gcm";
+/** @deprecated Use KEY_ALGORITHM_SECP256K1 */
+export declare const KEY_ALGORITHM = "ecies-secp256k1-aes256gcm";
+/**
+ * Wrap (encrypt) plaintext so only the holder of `recipientPubKeyHex` can unwrap it.
+ *
+ * @param recipientPubKeyHex Uncompressed secp256k1 public key ("04…", 130 hex chars).
+ * @param plaintext          The secret to protect (typically a hex-encoded AES password).
+ */
+export declare function wrapKey(recipientPubKeyHex: string, plaintext: Buffer): WrappedKeyResult;
+/**
+ * Unwrap (decrypt) ciphertext using the recipient's private key.
+ *
+ * @param recipientPrivKeyHex  Recipient's secp256k1 private key (hex, 64 chars).
+ * @param ciphertextB64        Base64 string produced by `wrapKey`.
+ * @param ephemeralPubKeyHex   Ephemeral public key from `wrapKey` result.
+ * @returns The original plaintext buffer.
+ */
+export declare function unwrapKey(recipientPrivKeyHex: string, ciphertextB64: string, ephemeralPubKeyHex: string): Buffer;
+/**
+ * Derive the public key (uncompressed, hex) from a private key. Useful for
+ * matching a recipient entry in ACCESS.NZIP without knowing the identity string.
+ */
+export declare function publicKeyFromPrivate(privKeyHex: string): string;
+//# sourceMappingURL=KeyWrapper.d.ts.map

package/dist/encryption/KeyWrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyWrapper.d.ts","sourceRoot":"","sources":["../../src/encryption/KeyWrapper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AACnE,8CAA8C;AAC9C,eAAO,MAAM,aAAa,8BAA0B,CAAC;AAYrD;;;;;GAKG;AACH,wBAAgB,OAAO,CACrB,kBAAkB,EAAE,MAAM,EAC1B,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAsBlB;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACvB,mBAAmB,EAAE,MAAM,EAC3B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAgBR;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAI/D"}

package/dist/encryption/KeyWrapper.js

@@ -0,0 +1,129 @@
+"use strict";
+/**
+ * ECIES key wrapping using secp256k1.
+ *
+ * Encrypt:
+ *   1. Generate ephemeral secp256k1 key pair
+ *   2. ECDH(ephemeral private, recipient public) → shared secret
+ *   3. HKDF-SHA256(shared secret) → 32-byte wrapping key
+ *   4. AES-256-GCM encrypt plaintext with wrapping key
+ *
+ * Decrypt:
+ *   1. ECDH(recipient private, ephemeral public) → same shared secret
+ *   2. HKDF-SHA256(shared secret) → same wrapping key
+ *   3. AES-256-GCM decrypt ciphertext
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY_ALGORITHM = exports.KEY_ALGORITHM_SECP256K1 = void 0;
+exports.wrapKey = wrapKey;
+exports.unwrapKey = unwrapKey;
+exports.publicKeyFromPrivate = publicKeyFromPrivate;
+const crypto = __importStar(require("crypto"));
+const secp256k1_1 = require("@noble/curves/secp256k1");
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
+exports.KEY_ALGORITHM_SECP256K1 = 'ecies-secp256k1-aes256gcm';
+/** @deprecated Use KEY_ALGORITHM_SECP256K1 */
+exports.KEY_ALGORITHM = exports.KEY_ALGORITHM_SECP256K1;
+const AES_KEY_BYTES = 32;
+const GCM_IV_BYTES = 12;
+const GCM_AUTH_TAG_BYTES = 16;
+const HKDF_INFO = Buffer.from('neozipkit-pro/ecies/v1', 'utf8');
+function deriveWrappingKey(sharedSecret) {
+    const ikm = sharedSecret.slice(1); // drop the 0x04 prefix byte
+    const derived = (0, hkdf_1.hkdf)(sha256_1.sha256, ikm, undefined, HKDF_INFO, AES_KEY_BYTES);
+    return Buffer.from(derived);
+}
+/**
+ * Wrap (encrypt) plaintext so only the holder of `recipientPubKeyHex` can unwrap it.
+ *
+ * @param recipientPubKeyHex Uncompressed secp256k1 public key ("04…", 130 hex chars).
+ * @param plaintext          The secret to protect (typically a hex-encoded AES password).
+ */
+function wrapKey(recipientPubKeyHex, plaintext) {
+    const recipientPub = hexToBytes(recipientPubKeyHex);
+    const ephPriv = secp256k1_1.secp256k1.utils.randomPrivateKey();
+    const ephPub = secp256k1_1.secp256k1.getPublicKey(ephPriv, false); // uncompressed
+    const shared = secp256k1_1.secp256k1.getSharedSecret(ephPriv, recipientPub, false);
+    const wrappingKey = deriveWrappingKey(shared);
+    const iv = crypto.randomBytes(GCM_IV_BYTES);
+    const cipher = crypto.createCipheriv('aes-256-gcm', wrappingKey, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // ciphertext layout: iv (12) || authTag (16) || encrypted data
+    const ciphertextBuf = Buffer.concat([iv, tag, encrypted]);
+    return {
+        ciphertext: ciphertextBuf.toString('base64'),
+        ephemeralPublicKey: Buffer.from(ephPub).toString('hex'),
+        keyAlgorithm: exports.KEY_ALGORITHM,
+    };
+}
+/**
+ * Unwrap (decrypt) ciphertext using the recipient's private key.
+ *
+ * @param recipientPrivKeyHex  Recipient's secp256k1 private key (hex, 64 chars).
+ * @param ciphertextB64        Base64 string produced by `wrapKey`.
+ * @param ephemeralPubKeyHex   Ephemeral public key from `wrapKey` result.
+ * @returns The original plaintext buffer.
+ */
+function unwrapKey(recipientPrivKeyHex, ciphertextB64, ephemeralPubKeyHex) {
+    const recipientPriv = hexToBytes(recipientPrivKeyHex);
+    const ephPub = hexToBytes(ephemeralPubKeyHex);
+    const shared = secp256k1_1.secp256k1.getSharedSecret(recipientPriv, ephPub, false);
+    const wrappingKey = deriveWrappingKey(shared);
+    const ciphertextBuf = Buffer.from(ciphertextB64, 'base64');
+    const iv = ciphertextBuf.subarray(0, GCM_IV_BYTES);
+    const tag = ciphertextBuf.subarray(GCM_IV_BYTES, GCM_IV_BYTES + GCM_AUTH_TAG_BYTES);
+    const encrypted = ciphertextBuf.subarray(GCM_IV_BYTES + GCM_AUTH_TAG_BYTES);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', wrappingKey, iv);
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+    return decrypted;
+}
+/**
+ * Derive the public key (uncompressed, hex) from a private key. Useful for
+ * matching a recipient entry in ACCESS.NZIP without knowing the identity string.
+ */
+function publicKeyFromPrivate(privKeyHex) {
+    const priv = hexToBytes(privKeyHex);
+    const pub = secp256k1_1.secp256k1.getPublicKey(priv, false);
+    return Buffer.from(pub).toString('hex');
+}
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    return Uint8Array.from(Buffer.from(clean, 'hex'));
+}
+//# sourceMappingURL=KeyWrapper.js.map

package/dist/encryption/KeyWrapper.js.map

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

package/dist/encryption/KeyWrapperX25519.d.ts

@@ -0,0 +1,43 @@
+/**
+ * ECIES key wrapping using X25519 (Curve25519 Diffie-Hellman).
+ *
+ * X25519 is purpose-built for key agreement / secure messaging and is used by
+ * Signal, WireGuard, TLS 1.3, and libsodium. The ZipStamp server provisions
+ * X25519 key pairs for each user, so no additional key infrastructure is needed.
+ *
+ * Encrypt:
+ *   1. Generate ephemeral X25519 key pair
+ *   2. X25519(ephemeral private, recipient public) → 32-byte shared secret
+ *   3. HKDF-SHA256(shared secret) → 32-byte wrapping key
+ *   4. AES-256-GCM encrypt plaintext with wrapping key
+ *
+ * Decrypt:
+ *   1. X25519(recipient private, ephemeral public) → same shared secret
+ *   2. HKDF-SHA256(shared secret) → same wrapping key
+ *   3. AES-256-GCM decrypt ciphertext
+ */
+import type { WrappedKeyResult } from './types';
+export declare const KEY_ALGORITHM_X25519 = "ecies-x25519-aes256gcm";
+/**
+ * Wrap (encrypt) plaintext so only the holder of `recipientPubKeyHex` can unwrap it.
+ *
+ * @param recipientPubKeyHex  Raw X25519 public key, 64 hex chars (32 bytes).
+ *                            Obtained from ZipStamp GET /crypto/public → x25519PublicKey.
+ * @param plaintext           The secret to protect (typically a hex-encoded AES password).
+ */
+export declare function wrapKeyX25519(recipientPubKeyHex: string, plaintext: Buffer): WrappedKeyResult;
+/**
+ * Unwrap (decrypt) ciphertext using the recipient's X25519 private key.
+ *
+ * @param recipientPrivKeyHex  Recipient's X25519 private key (hex, 64 chars / 32 bytes).
+ * @param ciphertextB64        Base64 string produced by `wrapKeyX25519`.
+ * @param ephemeralPubKeyHex   Ephemeral public key from `wrapKeyX25519` result (64 hex chars).
+ * @returns The original plaintext buffer.
+ */
+export declare function unwrapKeyX25519(recipientPrivKeyHex: string, ciphertextB64: string, ephemeralPubKeyHex: string): Buffer;
+/**
+ * Derive the X25519 public key (hex, 64 chars) from a private key.
+ * Useful for matching a recipient entry in ACCESS.NZIP.
+ */
+export declare function publicKeyFromPrivateX25519(privKeyHex: string): string;
+//# sourceMappingURL=KeyWrapperX25519.d.ts.map

package/dist/encryption/KeyWrapperX25519.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyWrapperX25519.d.ts","sourceRoot":"","sources":["../../src/encryption/KeyWrapperX25519.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,eAAO,MAAM,oBAAoB,2BAA2B,CAAC;AAW7D;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,kBAAkB,EAAE,MAAM,EAC1B,SAAS,EAAE,MAAM,GAChB,gBAAgB,CAyBlB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,mBAAmB,EAAE,MAAM,EAC3B,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAsBR;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAKrE"}

package/dist/encryption/KeyWrapperX25519.js

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * ECIES key wrapping using X25519 (Curve25519 Diffie-Hellman).
+ *
+ * X25519 is purpose-built for key agreement / secure messaging and is used by
+ * Signal, WireGuard, TLS 1.3, and libsodium. The ZipStamp server provisions
+ * X25519 key pairs for each user, so no additional key infrastructure is needed.
+ *
+ * Encrypt:
+ *   1. Generate ephemeral X25519 key pair
+ *   2. X25519(ephemeral private, recipient public) → 32-byte shared secret
+ *   3. HKDF-SHA256(shared secret) → 32-byte wrapping key
+ *   4. AES-256-GCM encrypt plaintext with wrapping key
+ *
+ * Decrypt:
+ *   1. X25519(recipient private, ephemeral public) → same shared secret
+ *   2. HKDF-SHA256(shared secret) → same wrapping key
+ *   3. AES-256-GCM decrypt ciphertext
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY_ALGORITHM_X25519 = void 0;
+exports.wrapKeyX25519 = wrapKeyX25519;
+exports.unwrapKeyX25519 = unwrapKeyX25519;
+exports.publicKeyFromPrivateX25519 = publicKeyFromPrivateX25519;
+const crypto = __importStar(require("crypto"));
+const ed25519_1 = require("@noble/curves/ed25519");
+const hkdf_1 = require("@noble/hashes/hkdf");
+const sha256_1 = require("@noble/hashes/sha256");
+exports.KEY_ALGORITHM_X25519 = 'ecies-x25519-aes256gcm';
+const AES_KEY_BYTES = 32;
+const GCM_IV_BYTES = 12;
+const GCM_AUTH_TAG_BYTES = 16;
+const HKDF_INFO = Buffer.from('neozipkit-pro/ecies-x25519/v1', 'utf8');
+function deriveWrappingKey(sharedSecret) {
+    const derived = (0, hkdf_1.hkdf)(sha256_1.sha256, sharedSecret, undefined, HKDF_INFO, AES_KEY_BYTES);
+    return Buffer.from(derived);
+}
+/**
+ * Wrap (encrypt) plaintext so only the holder of `recipientPubKeyHex` can unwrap it.
+ *
+ * @param recipientPubKeyHex  Raw X25519 public key, 64 hex chars (32 bytes).
+ *                            Obtained from ZipStamp GET /crypto/public → x25519PublicKey.
+ * @param plaintext           The secret to protect (typically a hex-encoded AES password).
+ */
+function wrapKeyX25519(recipientPubKeyHex, plaintext) {
+    const clean = recipientPubKeyHex.startsWith('0x')
+        ? recipientPubKeyHex.slice(2)
+        : recipientPubKeyHex;
+    const recipientPub = Uint8Array.from(Buffer.from(clean, 'hex'));
+    const ephPriv = ed25519_1.x25519.utils.randomPrivateKey();
+    const ephPub = ed25519_1.x25519.getPublicKey(ephPriv);
+    const shared = ed25519_1.x25519.getSharedSecret(ephPriv, recipientPub);
+    const wrappingKey = deriveWrappingKey(shared);
+    const iv = crypto.randomBytes(GCM_IV_BYTES);
+    const cipher = crypto.createCipheriv('aes-256-gcm', wrappingKey, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    // ciphertext layout: iv (12) || authTag (16) || encrypted data
+    const ciphertextBuf = Buffer.concat([iv, tag, encrypted]);
+    return {
+        ciphertext: ciphertextBuf.toString('base64'),
+        ephemeralPublicKey: Buffer.from(ephPub).toString('hex'),
+        keyAlgorithm: exports.KEY_ALGORITHM_X25519,
+    };
+}
+/**
+ * Unwrap (decrypt) ciphertext using the recipient's X25519 private key.
+ *
+ * @param recipientPrivKeyHex  Recipient's X25519 private key (hex, 64 chars / 32 bytes).
+ * @param ciphertextB64        Base64 string produced by `wrapKeyX25519`.
+ * @param ephemeralPubKeyHex   Ephemeral public key from `wrapKeyX25519` result (64 hex chars).
+ * @returns The original plaintext buffer.
+ */
+function unwrapKeyX25519(recipientPrivKeyHex, ciphertextB64, ephemeralPubKeyHex) {
+    const cleanPriv = recipientPrivKeyHex.startsWith('0x')
+        ? recipientPrivKeyHex.slice(2)
+        : recipientPrivKeyHex;
+    const cleanEph = ephemeralPubKeyHex.startsWith('0x')
+        ? ephemeralPubKeyHex.slice(2)
+        : ephemeralPubKeyHex;
+    const recipientPriv = Uint8Array.from(Buffer.from(cleanPriv, 'hex'));
+    const ephPub = Uint8Array.from(Buffer.from(cleanEph, 'hex'));
+    const shared = ed25519_1.x25519.getSharedSecret(recipientPriv, ephPub);
+    const wrappingKey = deriveWrappingKey(shared);
+    const ciphertextBuf = Buffer.from(ciphertextB64, 'base64');
+    const iv = ciphertextBuf.subarray(0, GCM_IV_BYTES);
+    const tag = ciphertextBuf.subarray(GCM_IV_BYTES, GCM_IV_BYTES + GCM_AUTH_TAG_BYTES);
+    const encrypted = ciphertextBuf.subarray(GCM_IV_BYTES + GCM_AUTH_TAG_BYTES);
+    const decipher = crypto.createDecipheriv('aes-256-gcm', wrappingKey, iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+}
+/**
+ * Derive the X25519 public key (hex, 64 chars) from a private key.
+ * Useful for matching a recipient entry in ACCESS.NZIP.
+ */
+function publicKeyFromPrivateX25519(privKeyHex) {
+    const clean = privKeyHex.startsWith('0x') ? privKeyHex.slice(2) : privKeyHex;
+    const priv = Uint8Array.from(Buffer.from(clean, 'hex'));
+    const pub = ed25519_1.x25519.getPublicKey(priv);
+    return Buffer.from(pub).toString('hex');
+}
+//# sourceMappingURL=KeyWrapperX25519.js.map

package/dist/encryption/KeyWrapperX25519.js.map

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

package/dist/encryption/RecipientEncryption.d.ts

@@ -0,0 +1,60 @@
+/**
+ * High-level orchestrator for identity-based (recipient) encryption.
+ *
+ * Encrypt workflow:
+ *   1. Generate a random AES password (32 random bytes → hex)
+ *   2. Create a NeoEncrypt (neo-aes256) encrypted .nzip via neozipkit by default
+ *   3. For each recipient: ECIES-wrap the password with their public key
+ *   4. Append META-INF/ACCESS.NZIP (STORED, unencrypted) with the wrapped keys
+ *
+ * Decrypt workflow:
+ *   1. Load the .nzip and extract META-INF/ACCESS.NZIP
+ *   2. Match the recipient by public key derived from the private key
+ *   3. ECIES-unwrap → recover the AES password
+ *   4. Set the password on the zipkit instance for normal extraction
+ */
+import type { ResolvedIdentity } from '../identity/types';
+import type { RecipientEncryptionFileInput, RecipientEncryptionOptions } from './types';
+interface ZipkitNodeLike {
+    initializeZipFile(outputPath: string): Promise<any>;
+    prepareEntryFromFile(filePath: string, entryName?: string): Promise<any>;
+    writeZipEntry(writer: any, entry: any, filePath: string, options?: any): Promise<void>;
+    writeCentralDirectory(writer: any, entries: any[], options?: any): Promise<number>;
+    writeEndOfCentralDirectory(writer: any, count: number, size: number, offset: number): Promise<void>;
+    finalizeZipFile(writer: any): Promise<void>;
+    getDirectory(): any[];
+    loadZipFile(filePath: string): Promise<any[]>;
+    getZipEntry(filename: string): any | null;
+    extractToBuffer(entry: any, options?: any): Promise<Buffer>;
+    /** neozipkit ZipkitNode: close read handle opened by loadZipFile */
+    closeFile?: () => Promise<void>;
+}
+/**
+ * Create an encrypted .nzip file that can only be opened by the listed
+ * recipients (via their secp256k1 public keys). Entry data uses **NeoEncrypt**
+ * (`neo-aes256`, NEO extra `0x024E` in neozipkit) by default; set
+ * `zipEncryptionMethod: 'aes256'` in options if you need WinZip AES.
+ *
+ * @param zipkit       A fresh ZipkitNode instance (will be mutated).
+ * @param files        Paths only (`string[]`) or `{ path, entryName? }[]` — forwarded to neozipkit
+ *                     `prepareEntryFromFile` / `writeZipEntry` (compress then encrypt).
+ * @param outputPath   Where to write the .nzip.
+ * @param recipients   Pre-resolved identities with public keys.
+ * @param options      Compression and inner ZIP encryption options forwarded to neozipkit.
+ */
+export declare function encryptForRecipients(zipkit: ZipkitNodeLike, files: string[] | RecipientEncryptionFileInput[], outputPath: string, recipients: ResolvedIdentity[], options?: RecipientEncryptionOptions): Promise<void>;
+/**
+ * Recover the AES password from a recipient-encrypted .nzip and configure the
+ * zipkit instance for extraction.
+ *
+ * After this call succeeds, use the returned zipkit normally:
+ *   `const buf = await zipkit.extractToBuffer(entry);`
+ *
+ * @param zipkit            A ZipkitNode instance.
+ * @param archivePath       Path to the .nzip file.
+ * @param recipientPrivKey  Recipient's secp256k1 private key (hex).
+ * @returns The same zipkit instance, now configured with the recovered password.
+ */
+export declare function decryptAsRecipient(zipkit: ZipkitNodeLike, archivePath: string, recipientPrivKey: string): Promise<ZipkitNodeLike>;
+export {};
+//# sourceMappingURL=RecipientEncryption.d.ts.map

package/dist/encryption/RecipientEncryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecipientEncryption.d.ts","sourceRoot":"","sources":["../../src/encryption/RecipientEncryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAmBH,OAAO,KAAK,EAAE,gBAAgB,EAAkC,MAAM,mBAAmB,CAAC;AAC1F,OAAO,KAAK,EAAE,4BAA4B,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AAwCxF,UAAU,cAAc;IACtB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACpD,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACzE,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvF,qBAAqB,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACnF,0BAA0B,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpG,eAAe,CAAC,MAAM,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,YAAY,IAAI,GAAG,EAAE,CAAC;IACtB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IAC9C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC;IAC1C,eAAe,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5D,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACjC;AAQD;;;;;;;;;;;;GAYG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,MAAM,EAAE,GAAG,4BAA4B,EAAE,EAChD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,gBAAgB,EAAE,EAC9B,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,IAAI,CAAC,CAkFf;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,cAAc,CAAC,CA6DzB"}