kxco-pq-vault 0.1.0

package/LICENSE

@@ -0,0 +1,182 @@
+                                 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 made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "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 transformations
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as 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. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      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
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combined work (in which such
+      Contribution(s) with the Work. If You institute patent litigation
+      against any entity (including a cross-claim or counterclaim in a
+      lawsuit) alleging that the Work or any Contribution embodied within
+      the Work constitutes direct or contributory patent infringement,
+      then any patent licenses granted to You under this License for that
+      Work shall terminate as of the date such litigation is filed.
+
+   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, You must include a readable copy of the
+          attribution notices contained within such NOTICE file, in
+          at least one of the following places: within a NOTICE text
+          file distributed as part of the Derivative Works; within
+          the Source form or documentation, if provided along with the
+          Derivative Works; or, within a display generated by the
+          Derivative Works, if and wherever such third-party notices
+          normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License.
+          You may add Your own attribution notices within Derivative
+          Works that You distribute, alongside or in addition to the
+          NOTICE text from the Work, provided that such additional
+          attribution notices cannot be construed as modifying the License.
+
+      You may add Your own license statement for Your modifications and
+      may provide additional grant of rights to use, reproduce, modify,
+      prepare Derivative Works of, publicly display, publicly perform,
+      sublicense, and distribute those modifications and that Work.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or reproducing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or all other
+      commercial damages or losses), even if such Contributor has been
+      advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may offer only
+      conditions that are Your own responsibility and not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend, and
+      hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 KXCO
+
+   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/README.md

@@ -0,0 +1,149 @@
+# kxco-pq-vault
+
+Post-quantum file encryption CLI and library. Uses **ML-KEM-768** (NIST FIPS 203) for key encapsulation and **AES-256-GCM** for symmetric encryption.
+
+A direct answer to "harvest now, decrypt later" attacks: files encrypted today cannot be broken even by a future quantum computer.
+
+```
+npm install -g kxco-pq-vault
+```
+
+---
+
+## Quick start
+
+```sh
+# 1. Generate a keypair
+kxco-vault keygen --out alice.kxco
+
+# 2. Share your recipient string with senders
+kxco-vault recipient alice.kxco
+# → kxco1qvp93xj...  (paste this to anyone who needs to encrypt to you)
+
+# 3. Encrypt a file
+kxco-vault encrypt secret.txt --recipient kxco1qvp93xj... --out secret.txt.kxco
+
+# 4. Decrypt it
+kxco-vault decrypt secret.txt.kxco --identity alice.kxco --out secret.txt
+```
+
+---
+
+## Commands
+
+### `keygen`
+
+```
+kxco-vault keygen --out <keypair.kxco>
+kxco-vault keygen --out <keypair.kxco> --master <hex> --label <string>
+```
+
+Generates an ML-KEM-768 keypair. The identity file contains both public and secret key material — keep it private.
+
+With `--master` + `--label`, derivation is deterministic (same inputs always produce the same keypair). Different labels under the same master produce different keypairs.
+
+### `recipient`
+
+```
+kxco-vault recipient <keypair.kxco>
+```
+
+Prints the `kxco1...` bech32m recipient string from an identity file. Share this string with anyone who needs to encrypt files to you.
+
+### `encrypt`
+
+```
+kxco-vault encrypt <file> --recipient <kxco1...|@keyfile> [--recipient ...] [--out <file.kxco>]
+```
+
+Encrypts a file for one or more recipients. Each recipient can independently decrypt using their identity file.
+
+`--recipient` accepts either a `kxco1...` bech32m string or `@/path/to/keypair.kxco`.
+
+Multiple `--recipient` flags produce a multi-recipient envelope. All recipients decrypt the same plaintext.
+
+### `decrypt`
+
+```
+kxco-vault decrypt <file.kxco> --identity <keypair.kxco> [--out <file>]
+```
+
+Decrypts an envelope using your identity file. Fails cleanly if your identity is not a recipient in the envelope, or if the envelope has been tampered with.
+
+### `inspect`
+
+```
+kxco-vault inspect <file.kxco>
+```
+
+Prints the envelope header without decrypting: algorithm, recipient count, recipient key IDs, nonce, created timestamp, and ciphertext size.
+
+---
+
+## Envelope format
+
+`.kxco` files have a plain-text header (readable with `cat`/`less`) followed by raw binary ciphertext:
+
+```
+KXCO-VAULT/1.0
+algorithm: ml-kem-768+aes-256-gcm
+recipients: 1
+recipient[0].kid: <16 hex chars — first 8 bytes of SHA-256(pubkey)>
+recipient[0].encapsulated_key: <hex — 1088-byte ML-KEM-768 ciphertext>
+recipient[0].wrapped_dek: <hex — 48 bytes: AES-256-GCM(ss, nonce=0, ad=kid).encrypt(dek)>
+nonce: <hex — 12-byte GCM nonce>
+created: 2026-05-23T00:00:00Z
+--- BEGIN CIPHERTEXT ---
+<binary — AES-256-GCM ciphertext + 16-byte auth tag>
+```
+
+The entire header (everything before `--- BEGIN CIPHERTEXT ---`) is used as **additional authenticated data** in the GCM call. Tampering with any header field — including the nonce, recipient entries, or algorithm line — causes decryption to fail with an authentication error.
+
+---
+
+## Crypto design
+
+- **ML-KEM-768** (FIPS 203 final) — Security Category 3, ~AES-192 equivalent. Pure post-quantum; no classical fallback by design.
+- **AES-256-GCM** — AEAD symmetric encryption of the file payload.
+- **DEK wrapping** — A random 32-byte data encryption key (DEK) is generated per file. Each recipient's ML-KEM shared secret is used directly as a per-recipient AES-256-GCM key to wrap the DEK.
+- **Header integrity** — The full canonical header is the GCM additional data, binding header + ciphertext together.
+
+---
+
+## Identity file format
+
+```
+KXCO-VAULT-IDENTITY/1.0
+algorithm: ml-kem-768
+created: 2026-05-23T00:00:00Z
+public: kxco1<bech32m of 1184-byte ML-KEM-768 public key>
+secret: <hex of 2400-byte ML-KEM-768 secret key>
+```
+
+The identity file is the only secret. The `public:` field can be shared freely. There is no passphrase protection in v1 (v0.2.0).
+
+---
+
+## Library usage
+
+```js
+import {
+  encodePublicKey, decodePublicKey,
+  serializeHeader, parseEnvelope,
+  computeKid, generateDek, generateNonce,
+  wrapDek, unwrapDek, encryptPayload, decryptPayload,
+  KxcoVaultError,
+} from 'kxco-pq-vault'
+```
+
+---
+
+## Why not hybrid X25519+ML-KEM?
+
+This is a deliberate v1 choice. ML-KEM-768 is FIPS 203 final. Files encrypted here cannot be broken by a quantum computer. A hybrid adds implementation complexity without meaningful security gain over a finalized PQC standard. Hybrid support (defense-in-depth for non-PQ-capable recipients) is planned for v0.2.0.
+
+---
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE).

package/bin/kxco-vault.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js'
+
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (err) => {
+    process.stderr.write(`kxco-vault: ${err.message || err}\n`)
+    process.exit(1)
+  },
+)

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "kxco-pq-vault",
+  "version": "0.1.0",
+  "description": "Post-quantum file encryption CLI and library — ML-KEM-768 + AES-256-GCM",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "kxco-vault": "./bin/kxco-vault.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "dependencies": {
+    "@scure/base": "^1.2.4",
+    "kxco-post-quantum": "^1.1.2"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "lint": "node --input-type=module --eval \"import('./src/cli.js')\" && echo lint ok"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "keywords": [
+    "post-quantum",
+    "encryption",
+    "ml-kem",
+    "kyber",
+    "cli",
+    "kxco",
+    "pqc",
+    "aes-gcm"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JackKXCO/kxco-pq-vault"
+  },
+  "author": "KXCO <dev@kxco.ai>"
+}

package/src/bech32.js

@@ -0,0 +1,28 @@
+import { bech32m } from '@scure/base'
+import { KxcoVaultError } from './errors.js'
+
+const HRP = 'kxco'
+const PUBKEY_BYTES = 1184 // ML-KEM-768 public key
+const LIMIT = false      // disable default 90-char cap
+
+export function encodePublicKey(pubkeyBytes) {
+  const words = bech32m.toWords(pubkeyBytes)
+  return bech32m.encode(HRP, words, LIMIT)
+}
+
+export function decodePublicKey(str) {
+  let decoded
+  try {
+    decoded = bech32m.decode(str, LIMIT)
+  } catch (e) {
+    throw new KxcoVaultError(`invalid recipient string: ${e.message}`)
+  }
+  if (decoded.prefix !== HRP) {
+    throw new KxcoVaultError(`invalid recipient prefix: expected "${HRP}", got "${decoded.prefix}"`)
+  }
+  const bytes = Buffer.from(bech32m.fromWords(decoded.words))
+  if (bytes.length !== PUBKEY_BYTES) {
+    throw new KxcoVaultError(`invalid recipient: expected ${PUBKEY_BYTES} bytes, got ${bytes.length}`)
+  }
+  return bytes
+}

package/src/cli.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname } from 'node:path'
+
+const USAGE = `
+kxco-vault — post-quantum file encryption (ML-KEM-768 + AES-256-GCM)
+
+commands:
+  keygen     generate an ML-KEM-768 identity keypair
+  encrypt    encrypt a file for one or more recipients
+  decrypt    decrypt a file with your identity
+  recipient  extract the public recipient string from an identity file
+  inspect    show envelope header info
+
+run 'kxco-vault <command> --help' for command-specific usage
+`.trim()
+
+export async function run(argv) {
+  const [cmd, ...args] = argv
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(USAGE + '\n')
+    return 0
+  }
+
+  if (cmd === '--version' || cmd === '-v') {
+    const pkg = JSON.parse(
+      readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'),
+    )
+    process.stdout.write(`${pkg.name} ${pkg.version}\n`)
+    return 0
+  }
+
+  switch (cmd) {
+    case 'keygen': {
+      const { keygen } = await import('./commands/keygen.js')
+      return keygen(args)
+    }
+    case 'encrypt': {
+      const { encrypt } = await import('./commands/encrypt.js')
+      return encrypt(args)
+    }
+    case 'decrypt': {
+      const { decrypt } = await import('./commands/decrypt.js')
+      return decrypt(args)
+    }
+    case 'recipient': {
+      const { recipient } = await import('./commands/recipient.js')
+      return recipient(args)
+    }
+    case 'inspect': {
+      const { inspect } = await import('./commands/inspect.js')
+      return inspect(args)
+    }
+    default:
+      process.stderr.write(`kxco-vault: unknown command "${cmd}"\n${USAGE}\n`)
+      return 2
+  }
+}

package/src/commands/decrypt.js

@@ -0,0 +1,75 @@
+import { writeFileSync } from 'node:fs'
+import { mlKem } from 'kxco-post-quantum'
+import { parseEnvelope } from '../envelope.js'
+import { computeKid, unwrapDek, decryptPayload } from '../crypto.js'
+import { readFileBytes, readIdentity } from '../util.js'
+import { KxcoVaultError } from '../errors.js'
+
+function parseArgs(args) {
+  let inputFile = null
+  let identityPath = null
+  let outPath = null
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]
+    if (arg === '--identity') {
+      if (!args[i + 1]) throw new KxcoVaultError('--identity requires a value')
+      identityPath = args[i + 1]
+      i += 2
+    } else if (arg.startsWith('--identity=')) {
+      identityPath = arg.slice('--identity='.length)
+      i++
+    } else if (arg === '--out') {
+      if (!args[i + 1]) throw new KxcoVaultError('--out requires a value')
+      outPath = args[i + 1]
+      i += 2
+    } else if (arg.startsWith('--out=')) {
+      outPath = arg.slice('--out='.length)
+      i++
+    } else if (!arg.startsWith('--')) {
+      inputFile = arg
+      i++
+    } else {
+      throw new KxcoVaultError(`unknown flag: ${arg}`)
+    }
+  }
+  return { inputFile, identityPath, outPath }
+}
+
+export async function decrypt(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(
+      `usage: kxco-vault decrypt <file.kxco> --identity <keypair.kxco> [--out <file>]\n`,
+    )
+    return 0
+  }
+
+  const { inputFile, identityPath, outPath } = parseArgs(args)
+
+  if (!inputFile) throw new KxcoVaultError('decrypt: input file required')
+  if (!identityPath) throw new KxcoVaultError('decrypt: --identity is required')
+
+  const { publicKey, secretKey } = readIdentity(identityPath)
+  const myKid = computeKid(publicKey)
+
+  const buf = readFileBytes(inputFile)
+  const { header, canonicalHeader, ciphertext } = parseEnvelope(buf)
+
+  const recipientBlock = header.recipients.find(r => r.kid === myKid)
+  if (!recipientBlock) throw new KxcoVaultError('recipient kid not in envelope')
+
+  const mlKemCt = Buffer.from(recipientBlock.encapsulatedKey, 'hex')
+  const ss = Buffer.from(mlKem.decapsulate(mlKemCt, secretKey))
+  const wrappedDek = Buffer.from(recipientBlock.wrappedDek, 'hex')
+  const dek = unwrapDek(ss, myKid, wrappedDek)
+
+  const nonce = Buffer.from(header.nonce, 'hex')
+  const plaintext = decryptPayload(dek, nonce, canonicalHeader, ciphertext)
+
+  const defaultOut = inputFile.endsWith('.kxco') ? inputFile.slice(0, -5) : `${inputFile}.dec`
+  const outFile = outPath || defaultOut
+
+  writeFileSync(outFile, plaintext)
+  process.stdout.write(`decrypted: ${outFile}\n`)
+  return 0
+}

package/src/commands/encrypt.js

@@ -0,0 +1,88 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { mlKem } from 'kxco-post-quantum'
+import { serializeHeader } from '../envelope.js'
+import { generateDek, generateNonce, computeKid, wrapDek, encryptPayload } from '../crypto.js'
+import { resolveRecipient } from '../util.js'
+import { KxcoVaultError } from '../errors.js'
+
+const SEPARATOR = Buffer.from('--- BEGIN CIPHERTEXT ---\n', 'utf-8')
+
+function parseArgs(args) {
+  const recipients = []
+  let inputFile = null
+  let outPath = null
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]
+    if (arg === '--recipient') {
+      if (!args[i + 1]) throw new KxcoVaultError('--recipient requires a value')
+      recipients.push(args[i + 1])
+      i += 2
+    } else if (arg.startsWith('--recipient=')) {
+      recipients.push(arg.slice('--recipient='.length))
+      i++
+    } else if (arg === '--out') {
+      if (!args[i + 1]) throw new KxcoVaultError('--out requires a value')
+      outPath = args[i + 1]
+      i += 2
+    } else if (arg.startsWith('--out=')) {
+      outPath = arg.slice('--out='.length)
+      i++
+    } else if (!arg.startsWith('--')) {
+      inputFile = arg
+      i++
+    } else {
+      throw new KxcoVaultError(`unknown flag: ${arg}`)
+    }
+  }
+  return { inputFile, recipients, outPath }
+}
+
+export async function encrypt(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(
+      `usage: kxco-vault encrypt <file> --recipient <kxco1...|@keyfile> [--recipient ...] [--out <file.kxco>]\n`,
+    )
+    return 0
+  }
+
+  const { inputFile, recipients: recipientStrs, outPath } = parseArgs(args)
+
+  if (!inputFile) throw new KxcoVaultError('encrypt: input file required')
+  if (recipientStrs.length === 0) throw new KxcoVaultError('encrypt: at least one --recipient required')
+
+  const outFile = outPath || `${inputFile}.kxco`
+
+  let plaintext
+  try {
+    plaintext = readFileSync(inputFile)
+  } catch (e) {
+    throw new KxcoVaultError(`cannot read "${inputFile}": ${e.message}`)
+  }
+
+  const dek = generateDek()
+  const nonce = generateNonce()
+  const created = new Date().toISOString().replace(/\.\d+Z$/, 'Z')
+
+  const recipientBlocks = recipientStrs.map((str) => {
+    const pubkeyBytes = resolveRecipient(str)
+    const kid = computeKid(pubkeyBytes)
+    const { ciphertext: mlKemCt, sharedSecret: ss } = mlKem.encapsulate(pubkeyBytes)
+    const wrappedDek = wrapDek(Buffer.from(ss), kid, dek)
+    return {
+      kid,
+      encapsulatedKey: Buffer.from(mlKemCt).toString('hex'),
+      wrappedDek: wrappedDek.toString('hex'),
+    }
+  })
+
+  const headerText = serializeHeader({ recipients: recipientBlocks, nonce: nonce.toString('hex'), created })
+  const canonicalHeader = Buffer.from(headerText, 'utf-8')
+  const payload = encryptPayload(dek, nonce, canonicalHeader, plaintext)
+
+  writeFileSync(outFile, Buffer.concat([canonicalHeader, SEPARATOR, payload]))
+
+  process.stdout.write(`encrypted: ${outFile}\n`)
+  process.stdout.write(`recipients: ${recipientBlocks.length}\n`)
+  return 0
+}

package/src/commands/inspect.js

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs'
+import { parseHeaderText } from '../envelope.js'
+import { KxcoVaultError } from '../errors.js'
+
+const SEPARATOR = '--- BEGIN CIPHERTEXT ---\n'
+
+export async function inspect(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(`usage: kxco-vault inspect <file.kxco>\n`)
+    return 0
+  }
+
+  const inputFile = args.find(a => !a.startsWith('--'))
+  if (!inputFile) throw new KxcoVaultError('inspect: input file required')
+
+  let buf
+  try {
+    buf = readFileSync(inputFile)
+  } catch (e) {
+    throw new KxcoVaultError(`cannot read "${inputFile}": ${e.message}`)
+  }
+
+  const text = buf.toString('utf-8')
+  const sepIdx = text.indexOf(SEPARATOR)
+  if (sepIdx === -1) throw new KxcoVaultError('invalid envelope: missing ciphertext separator')
+
+  const headerText = text.slice(0, sepIdx)
+  const ciphertextBytes = buf.length - sepIdx - Buffer.byteLength(SEPARATOR)
+
+  const header = parseHeaderText(headerText)
+
+  process.stdout.write(`version:    KXCO-VAULT/1.0\n`)
+  process.stdout.write(`algorithm:  ${header.algorithm}\n`)
+  process.stdout.write(`recipients: ${header.recipients.length}\n`)
+  for (let i = 0; i < header.recipients.length; i++) {
+    process.stdout.write(`  [${i}] kid: ${header.recipients[i].kid}\n`)
+  }
+  process.stdout.write(`nonce:      ${header.nonce}\n`)
+  process.stdout.write(`created:    ${header.created}\n`)
+  process.stdout.write(`ciphertext: ${ciphertextBytes} bytes\n`)
+  return 0
+}

package/src/commands/keygen.js

@@ -0,0 +1,80 @@
+import { randomBytes } from 'node:crypto'
+import { writeFileSync } from 'node:fs'
+import { mlKem, deriveSeed } from 'kxco-post-quantum'
+import { encodePublicKey } from '../bech32.js'
+import { KxcoVaultError } from '../errors.js'
+
+const FLAGS = new Set(['out', 'master', 'label'])
+
+function parseFlags(args) {
+  const flags = {}
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]
+    if (!arg.startsWith('--')) throw new KxcoVaultError(`unexpected argument: ${arg}`)
+    let key, val
+    if (arg.includes('=')) {
+      const eq = arg.indexOf('=')
+      key = arg.slice(2, eq)
+      val = arg.slice(eq + 1)
+      i++
+    } else {
+      key = arg.slice(2)
+      if (i + 1 >= args.length || args[i + 1].startsWith('--')) {
+        throw new KxcoVaultError(`--${key} requires a value`)
+      }
+      val = args[i + 1]
+      i += 2
+    }
+    if (!FLAGS.has(key)) throw new KxcoVaultError(`unknown flag --${key}`)
+    flags[key] = val
+  }
+  return flags
+}
+
+export async function keygen(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(`usage: kxco-vault keygen --out <keypair.kxco> [--master <hex> --label <string>]\n`)
+    return 0
+  }
+
+  const flags = parseFlags(args)
+  if (!flags.out) throw new KxcoVaultError('keygen: --out is required')
+
+  let publicKey, secretKey
+
+  if (flags.master) {
+    // Deterministic derivation
+    if (!flags.label) throw new KxcoVaultError('keygen: --label is required with --master')
+    if (!/^[0-9a-fA-F]+$/.test(flags.master) || flags.master.length < 32) {
+      throw new KxcoVaultError('keygen: --master must be at least 16 hex bytes')
+    }
+    const masterBytes = Buffer.from(flags.master, 'hex')
+    const result = mlKem.keypairFromMaster(masterBytes, flags.label)
+    publicKey = result.publicKey
+    secretKey = result.secretKey
+  } else {
+    // Random keygen: generate 32-byte random master, derive 64-byte seed
+    const randomMaster = randomBytes(32)
+    const result = mlKem.keypairFromMaster(randomMaster, 'kxco-vault/keygen/v1')
+    publicKey = result.publicKey
+    secretKey = result.secretKey
+  }
+
+  const created = new Date().toISOString().replace(/\.\d+Z$/, 'Z')
+  const recipient = encodePublicKey(Buffer.from(publicKey))
+
+  const identity = [
+    'KXCO-VAULT-IDENTITY/1.0',
+    'algorithm: ml-kem-768',
+    `created: ${created}`,
+    `public: ${recipient}`,
+    `secret: ${Buffer.from(secretKey).toString('hex')}`,
+    '',
+  ].join('\n')
+
+  writeFileSync(flags.out, identity, 'utf-8')
+  process.stdout.write(`identity: ${flags.out}\n`)
+  process.stdout.write(`recipient: ${recipient}\n`)
+  return 0
+}

package/src/commands/recipient.js

@@ -0,0 +1,28 @@
+import { readFileText } from '../util.js'
+import { decodePublicKey, encodePublicKey } from '../bech32.js'
+import { KxcoVaultError } from '../errors.js'
+
+export async function recipient(args) {
+  if (args.includes('--help') || args.includes('-h')) {
+    process.stdout.write(`usage: kxco-vault recipient <keypair.kxco>\n`)
+    return 0
+  }
+
+  const keyfile = args.find(a => !a.startsWith('--'))
+  if (!keyfile) throw new KxcoVaultError('recipient: identity file argument required')
+
+  const content = readFileText(keyfile)
+  if (!content.startsWith('KXCO-VAULT-IDENTITY/')) {
+    throw new KxcoVaultError(`not a kxco-vault identity file: ${keyfile}`)
+  }
+
+  const match = content.match(/^public:\s*(kxco1\S+)/m)
+  if (!match) throw new KxcoVaultError(`identity file missing public key: ${keyfile}`)
+
+  // Validate bech32m round-trip
+  const pubkeyBytes = decodePublicKey(match[1])
+  const recipient = encodePublicKey(pubkeyBytes)
+
+  process.stdout.write(`${recipient}\n`)
+  return 0
+}

package/src/crypto.js

@@ -0,0 +1,56 @@
+import { randomBytes, createHash, createCipheriv, createDecipheriv } from 'node:crypto'
+import { KxcoVaultError } from './errors.js'
+
+export function generateDek() { return randomBytes(32) }
+export function generateNonce() { return randomBytes(12) }
+
+// kid = first 8 bytes of SHA-256(pubkey), as 16-char lowercase hex
+export function computeKid(pubkeyBytes) {
+  return createHash('sha256').update(pubkeyBytes).digest().slice(0, 8).toString('hex')
+}
+
+// Wrap DEK with the ML-KEM shared secret (32 bytes = AES-256 key).
+// nonce = 12 zero bytes (ss is fresh per encapsulation, reuse-safe).
+// ad = raw kid bytes (8 bytes) for domain separation.
+// Output: 48 bytes (32-byte ciphertext + 16-byte GCM auth tag).
+export function wrapDek(ss, kid, dek) {
+  const cipher = createCipheriv('aes-256-gcm', ss, Buffer.alloc(12))
+  cipher.setAAD(Buffer.from(kid, 'hex'))
+  const ct = Buffer.concat([cipher.update(dek), cipher.final()])
+  return Buffer.concat([ct, cipher.getAuthTag()])
+}
+
+// Unwrap DEK. Throws KxcoVaultError if auth fails.
+export function unwrapDek(ss, kid, wrappedDek) {
+  if (wrappedDek.length !== 48) throw new KxcoVaultError('authentication failed: invalid wrapped_dek length')
+  const decipher = createDecipheriv('aes-256-gcm', ss, Buffer.alloc(12))
+  decipher.setAAD(Buffer.from(kid, 'hex'))
+  decipher.setAuthTag(wrappedDek.slice(32))
+  try {
+    return Buffer.concat([decipher.update(wrappedDek.slice(0, 32)), decipher.final()])
+  } catch {
+    throw new KxcoVaultError('authentication failed')
+  }
+}
+
+// Encrypt plaintext. Returns ciphertext||tag (payload.length = plaintext.length + 16).
+// ad = canonicalHeader bytes.
+export function encryptPayload(dek, nonce, ad, plaintext) {
+  const cipher = createCipheriv('aes-256-gcm', dek, nonce)
+  cipher.setAAD(ad)
+  const ct = Buffer.concat([cipher.update(plaintext), cipher.final()])
+  return Buffer.concat([ct, cipher.getAuthTag()])
+}
+
+// Decrypt payload (ciphertext||tag). Throws KxcoVaultError if auth fails.
+export function decryptPayload(dek, nonce, ad, payload) {
+  if (payload.length < 16) throw new KxcoVaultError('authentication failed: ciphertext too short')
+  const decipher = createDecipheriv('aes-256-gcm', dek, nonce)
+  decipher.setAAD(ad)
+  decipher.setAuthTag(payload.slice(-16))
+  try {
+    return Buffer.concat([decipher.update(payload.slice(0, -16)), decipher.final()])
+  } catch {
+    throw new KxcoVaultError('authentication failed')
+  }
+}

package/src/envelope.js

@@ -0,0 +1,73 @@
+import { KxcoVaultError } from './errors.js'
+
+const SEPARATOR = '--- BEGIN CIPHERTEXT ---\n'
+const VERSION = 'KXCO-VAULT/1.0'
+const ALGORITHM = 'ml-kem-768+aes-256-gcm'
+
+// Serialize a header object to a UTF-8 string (no separator line).
+// recipients: [{ kid, encapsulatedKey, wrappedDek }]   (all hex strings)
+// nonce: hex string (24 chars = 12 bytes)
+// created: ISO 8601 string
+export function serializeHeader({ recipients, nonce, created }) {
+  const lines = [
+    VERSION,
+    `algorithm: ${ALGORITHM}`,
+    `recipients: ${recipients.length}`,
+  ]
+  for (let i = 0; i < recipients.length; i++) {
+    const r = recipients[i]
+    lines.push(`recipient[${i}].kid: ${r.kid}`)
+    lines.push(`recipient[${i}].encapsulated_key: ${r.encapsulatedKey}`)
+    lines.push(`recipient[${i}].wrapped_dek: ${r.wrappedDek}`)
+  }
+  lines.push(`nonce: ${nonce}`)
+  lines.push(`created: ${created}`)
+  return lines.join('\n') + '\n'
+}
+
+// Parse a full envelope Buffer into { header, canonicalHeader, ciphertext }.
+// canonicalHeader is the raw bytes used as GCM AAD.
+export function parseEnvelope(buf) {
+  const sepBytes = Buffer.from(SEPARATOR, 'utf-8')
+  const sepIdx = buf.indexOf(sepBytes)
+  if (sepIdx === -1) throw new KxcoVaultError('invalid envelope: missing ciphertext separator')
+
+  const canonicalHeader = buf.slice(0, sepIdx)
+  const ciphertext = buf.slice(sepIdx + sepBytes.length)
+
+  const header = parseHeaderText(canonicalHeader.toString('utf-8'))
+  return { header, canonicalHeader, ciphertext }
+}
+
+// Parse just the text portion of a header (for inspect).
+export function parseHeaderText(text) {
+  const lines = text.split('\n').map(l => l.trim()).filter(l => l.length > 0)
+  if (lines[0] !== VERSION) throw new KxcoVaultError(`unsupported vault version: ${lines[0]}`)
+
+  const get = (key) => {
+    const line = lines.find(l => l.startsWith(`${key}: `))
+    if (!line) throw new KxcoVaultError(`missing header field: ${key}`)
+    return line.slice(key.length + 2)
+  }
+
+  const algorithm = get('algorithm')
+  if (algorithm !== ALGORITHM) throw new KxcoVaultError(`unsupported algorithm: ${algorithm}`)
+
+  const nRecipients = parseInt(get('recipients'), 10)
+  if (!Number.isFinite(nRecipients) || nRecipients < 1) {
+    throw new KxcoVaultError(`invalid recipients count: ${get('recipients')}`)
+  }
+
+  const recipients = []
+  for (let i = 0; i < nRecipients; i++) {
+    const kid = get(`recipient[${i}].kid`)
+    const encapsulatedKey = get(`recipient[${i}].encapsulated_key`)
+    const wrappedDek = get(`recipient[${i}].wrapped_dek`)
+    recipients.push({ kid, encapsulatedKey, wrappedDek })
+  }
+
+  const nonce = get('nonce')
+  const created = get('created')
+
+  return { algorithm, recipients, nonce, created }
+}

package/src/errors.js

@@ -0,0 +1,6 @@
+export class KxcoVaultError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = 'KxcoVaultError'
+  }
+}

package/src/index.js

@@ -0,0 +1,14 @@
+// Library entry point — re-exports all public primitives.
+export { encodePublicKey, decodePublicKey } from './bech32.js'
+export { serializeHeader, parseEnvelope, parseHeaderText } from './envelope.js'
+export {
+  generateDek,
+  generateNonce,
+  computeKid,
+  wrapDek,
+  unwrapDek,
+  encryptPayload,
+  decryptPayload,
+} from './crypto.js'
+export { resolveRecipient, readIdentity } from './util.js'
+export { KxcoVaultError } from './errors.js'

package/src/util.js

@@ -0,0 +1,47 @@
+import { readFileSync } from 'node:fs'
+import { decodePublicKey } from './bech32.js'
+import { KxcoVaultError } from './errors.js'
+
+export function readFileBytes(path) {
+  try {
+    return readFileSync(path)
+  } catch (e) {
+    throw new KxcoVaultError(`cannot read file "${path}": ${e.message}`)
+  }
+}
+
+export function readFileText(path) {
+  return readFileBytes(path).toString('utf-8')
+}
+
+// Resolve a --recipient value to raw pubkey bytes.
+// Accepts: "kxco1..." bech32m string, or "@/path/to/file"
+export function resolveRecipient(str) {
+  if (str.startsWith('@')) {
+    const content = readFileText(str.slice(1)).trim()
+    if (content.startsWith('KXCO-VAULT-IDENTITY/')) {
+      const match = content.match(/^public:\s*(kxco1\S+)/m)
+      if (!match) throw new KxcoVaultError('identity file missing public key')
+      return decodePublicKey(match[1])
+    }
+    return decodePublicKey(content)
+  }
+  return decodePublicKey(str)
+}
+
+// Parse an identity file (keypair.kxco) and return { publicKey, secretKey }
+export function readIdentity(path) {
+  const content = readFileText(path)
+  if (!content.startsWith('KXCO-VAULT-IDENTITY/')) {
+    throw new KxcoVaultError(`not a kxco-vault identity file: ${path}`)
+  }
+  const pubMatch = content.match(/^public:\s*(kxco1\S+)/m)
+  const secMatch = content.match(/^secret:\s*([0-9a-fA-F]+)/m)
+  if (!pubMatch || !secMatch) throw new KxcoVaultError(`malformed identity file: ${path}`)
+  const publicKey = decodePublicKey(pubMatch[1])
+  const secretKey = Buffer.from(secMatch[1], 'hex')
+  if (secretKey.length !== 2400) {
+    throw new KxcoVaultError(`invalid secret key length in ${path}: expected 2400 bytes, got ${secretKey.length}`)
+  }
+  return { publicKey, secretKey }
+}