node-tpm2 0.0.4-beta.3 → 0.0.5-beta.0

package/docs/roadmap.md

@@ -0,0 +1,216 @@
+# API roadmap
+
+Plan to complete the public `node-tpm2` API: subsystem namespaces, exportable key
+handles, and parity between Linux (TBS) and Windows (TBS for general ops, PCP for
+attestation persistence where required).
+
+This library is standalone. Consumers integrate via npm; nothing in this repo references
+or depends on downstream products.
+
+---
+
+## Current state (0.0.5-beta)
+
+**Shipped and validated on real Windows 11 hardware (Intel TPM, non-virtual):** attestation (user + machine provision, cross-user quote, SYSTEM provision), `random`, `keys` (sign + RSA decrypt), `pcr.read` / `pcr.extend` (admin on Windows), `nv` (read/write/define/undefine/readPublic), `seal` / `unseal`.
+
+| Namespace | Methods |
+|-----------|---------|
+| Root | `Tpm.isAvailable()`, `Tpm.open()`, `Tpm.info()`, `tpm.readPublic()` |
+| `tpm.random` | `bytes(n)` |
+| `tpm.pcr` | `read`, `extend` |
+| `tpm.nv` | `read`, `write`, `readPublic`, `define`, `undefine` |
+| `tpm.keys` | `create`, `load`; `KeyHandle.sign`, `export`, `decrypt` |
+| `tpm.seal` | `seal`, `unseal` |
+| `tpm.attest` | `provisionAk`, `quote`, `ekCertificate` |
+| `AkHandle` | `export`, `quote`, `activateCredential`, `publicKeyDer` |
+| Flat | Parity wrappers for all of the above (`Tpm.pcrRead`, `Tpm.nvDefine`, `Tpm.seal`, …) |
+
+**Platform split:** General ops (keys, seal, NV, PCR, random) use TBS on both OSes. Attestation persistence on Windows uses NCrypt PCP (`PCP1` / `PCP2` blobs); Linux uses TBS-wrapped ECDSA AK blobs.
+
+---
+
+## Target API
+
+```typescript
+import { Tpm, TpmError } from 'node-tpm2';
+
+await using tpm = await Tpm.open();
+
+// ── Root ──────────────────────────────────────────────────────────
+await Tpm.isAvailable();
+await tpm.info();
+
+// ── random ────────────────────────────────────────────────────────
+await tpm.random.bytes(32);
+
+// ── pcr ───────────────────────────────────────────────────────────
+await tpm.pcr.read([0, 1, 7], 'sha256');
+await tpm.pcr.extend(7, digest);              // digest: Buffer, 32 bytes for sha256 bank
+
+// ── nv ────────────────────────────────────────────────────────────
+await tpm.nv.read('0x01c00002');              // handle or well-known name
+await tpm.nv.write('0x01800001', data, opts); // opts: auth, offset — policy-dependent
+
+// ── keys ──────────────────────────────────────────────────────────
+const key = await tpm.keys.create({
+  type: 'ecc',           // 'ecc' | 'rsa'
+  sign: true,
+  decrypt: false,
+});
+const blob = key.export();
+const loaded = await tpm.keys.load(blob);
+await loaded.sign(digest);                    // Buffer in → signature Buffer out
+await loaded.decrypt(cipher);                 // when key was created with decrypt: true
+
+// ── seal ──────────────────────────────────────────────────────────
+const sealed = await tpm.seal({
+  data: secret,
+  pcrSelection: [7],
+  pcrPolicy: 'current' | digest,             // bind to current PCR state or explicit digest
+});
+const plain = await tpm.unseal(sealed);
+
+// ── attest (opinionated attestation — unchanged intent) ───────────
+const ak = await tpm.attest.provisionAk({ scope, keyName, overwrite });
+await ak.quote({ pcrSelection, qualifyingData });
+await tpm.attest.ekCertificate();
+await ak.activateCredential({ credentialBlob, secret });
+
+// ── plumbing ──────────────────────────────────────────────────────
+await tpm.readPublic('0x81010001');
+```
+
+Flat equivalents remain on `Tpm.*` for every operation (thin wrappers over the same native calls).
+
+---
+
+## Platform strategy
+
+| Concern | Linux | Windows |
+|---------|-------|---------|
+| Transport | `/dev/tpmrm0` | TBS (`Tbsip_Submit_Command`) |
+| General keys (`keys.*`) | TBS wrapped TPM2B blobs | TBS wrapped blobs (same codec as Linux) |
+| Attestation AK (`attest.provisionAk`) | TBS wrapped ECDSA AK | NCrypt PCP persisted key (`PCP1` / `PCP2` blob) |
+| Quote / activate | Load blob transiently → operate → flush | PCP open by key name + TBS for quote crypto |
+| Seal / unseal | TBS policy-bound object | TBS (same commands; no PCP required) |
+| NV | TBS NV_Read / NV_Write | TBS NV commands |
+
+**Rule:** PCP is for **attestation key persistence and fleet cross-user quote**, not for every key operation. General `keys.*` and `seal` use the shared TBS command path on both OSes so behavior and blobs stay aligned.
+
+---
+
+## Implementation phases
+
+### Phase 0 — API hygiene ✅ (this branch)
+
+**Goal:** Published types match runtime; namespace skeleton on `TpmHandle`.
+
+- [x] Remove bogus top-level exports from `index.d.ts`
+- [x] Add namespace objects on `TpmHandle`: `random`, `nv`, `keys`, `seal`, `pcr.extend`
+- [x] Add `KeyHandle` / `KeyBlob` types; unimplemented methods throw `NOT_SUPPORTED`
+- [ ] Acceptance: `npm run verify:package`
+
+### Phase 1 — `tpm.random.bytes` ✅ (this branch)
+
+**Goal:** Public `GetRandom`.
+
+- [x] Rust: `random.rs` — marshal `TPM2_GetRandom`, ≤64 bytes per call, loop for larger
+- [x] NAPI: `randomBytes`
+- [x] JS: `tpm.random.bytes(n)`, `Tpm.randomBytes(n)`
+- [ ] Tests: integration on Linux + Windows VM
+
+### Phase 2 — `tpm.keys` ✅
+
+**Goal:** General exportable signing keys via TBS wrapped blobs (both OSes).
+
+- [x] `keys.create` / `keys.load` / `key.sign` — ECC + RSA sign keys
+- [x] Unit tests: templates, Sign command golden, option validation, HW roundtrip
+- [x] `key.decrypt` — RSA OAEP
+- [ ] Windows VM sign smoke
+
+### Phase 3 — `tpm.pcr.extend` ✅ (this branch)
+
+**Goal:** Software measurement hook.
+
+- [x] Rust: `TPM2_PCR_Extend` with SHA-256 bank selection matching `pcr.read`.
+- [x] JS: `tpm.pcr.extend(index, digest)`.
+- [x] Tests: extend → read → digest changed.
+- [x] Caveats: some firmware policies lock PCRs; surface `TPM_RC` / `COMMAND_BLOCKED` cleanly.
+- [x] Acceptance: Linux unprivileged on swtpm/dev VM; **Windows Administrator** on real client hardware (PCR 23 validated).
+
+### Phase 4 — `tpm.nv` ✅ (this branch)
+
+**Goal:** General NV index access beyond EK cert helper.
+
+- [x] Rust: `nv.read_public(handle)` — size + attributes via `nv_read_public`.
+- [x] `nv.read(handle, offset, size)`.
+- [x] `nv.write(handle, offset, data, auth?)` — optional auth for password-protected indices.
+- [x] `nv.define` / `nv.undefine` — owner-auth; owner NV range only; refuses EK indices.
+- [x] Migrate `readEkCertificate` to call `nv.read` on well-known EK cert index internally.
+- [x] JS: `tpm.nv.read`, `tpm.nv.write`, `tpm.nv.readPublic`, `tpm.nv.define`, `tpm.nv.undefine`; document which indices are safe on consumer hardware.
+- [ ] Acceptance: EK cert read unchanged; optional integration test against swtpm-defined NV index (hardware: use `examples/nv-smoke.mjs` on test machine).
+
+### Phase 5 — `tpm.seal` / `tpm.unseal` ✅ (this branch)
+
+**Goal:** TPM-bound secrets with optional PCR policy.
+
+- [x] Rust: `seal({ data, pcrSelection? })` — storage primary, `Create` sealed object, export blob.
+- [x] `unseal(blob)` — load + `Unseal`.
+- [x] PCR policy: `PolicyPCR` session when `pcrSelection` provided.
+- [x] JS: `tpm.seal`, `tpm.unseal`; flat aliases.
+- [x] Tests: roundtrip without PCR; unit tests for marshalling.
+- [ ] Acceptance: Linux + Windows TBS; roundtrip with PCR extend before unseal on hardware.
+
+### Phase 6 — Hardening & 1.0 (ongoing)
+
+- Real hardware matrix (firmware TPM, Hyper-V, physical laptop).
+- Fuzz/malformed response handling on codec.
+- Stable semver on error codes (`latest` tag).
+- Performance: reuse TBS context per `TpmHandle` where safe (today: per-call context on Windows TBS path).
+
+---
+
+## Dependency order
+
+```
+Phase 0 (hygiene)
+    ↓
+Phase 1 (random) ─────────────────────────────┐
+    ↓                                         │
+Phase 2 (keys) ──→ Phase 5 (seal uses keys)   │
+    ↓                                         │
+Phase 3 (pcr.extend) ──→ Phase 5 (PCR policy) │
+    ↓                                         │
+Phase 4 (nv) ─────────────────────────────────┘
+    ↓
+Phase 6 (1.0)
+```
+
+Phases 1 and 3 can run in parallel after Phase 0. Phase 2 blocks Phase 5. Phase 4 is independent.
+
+---
+
+## Testing strategy
+
+| Layer | Tool |
+|-------|------|
+| Command golden bytes | Rust unit tests |
+| Privilege / elevation | `tbs-probe` (repo only) + `examples/smoke-test.mjs` (published) |
+| Cross-platform | Linux CI + Windows VM manual gate before each beta |
+| NV / seal edge cases | swtpm with scripted NV define in CI (Linux) |
+
+---
+
+## Out of scope (remain non-goals)
+
+- macOS TPM (no hardware).
+- Persistent handle / `EvictControl` in the public API.
+- Full TPM2 policy language exposed to JS (only fixed recipes: activate-credential, seal-with-PCR).
+- PKCS#11, OpenSSL engine, or platform keystore integration.
+
+---
+
+## Versioning
+
+- Implement phases on `dev`; beta publish after each phase or logical group (e.g. **0.0.5-beta.0** = full NV + seal + keys decrypt).
+- `1.0.0` when Phases 0–5 acceptance criteria pass on real hardware and API surface in README matches implementation.

package/docs/windows-pcp.md

@@ -7,6 +7,7 @@ On Windows, node-tpm2 uses the **Microsoft Platform Crypto Provider** for attest
 | Operation | Standard user | Elevated admin | SYSTEM |
 |-----------|---------------|----------------|--------|
 | `Tpm.isAvailable()`, PCR read, `readPublic` | Yes | Yes | Yes |
+| `tpm.pcr.extend` | No (`REQUIRES_ELEVATION`) | Yes † | Yes † |
 | `provisionAk()` user scope (`PCP1`) | Yes | Yes | Yes |
 | `quote()` | Yes | Yes | Yes |
 | `provisionAk({ scope: 'machine' })` (`PCP2`) | No | Yes | Yes (production enroll) |
@@ -14,6 +15,8 @@ On Windows, node-tpm2 uses the **Microsoft Platform Crypto Provider** for attest
 
 **Runtime apps** typically only need `quote()` with a blob/locator from enrollment. Activation is an enrollment-time proof-of-possession step.
 
+**† `pcr.extend`:** Prefer PCR indices **16–23** (not **0–7**, which are boot/Secure Boot measurements). Standard users receive **`REQUIRES_ELEVATION`** (`hresult` `0x80280400`); **Administrator** can extend (validated on real Intel laptop). Linux standard user can extend unless firmware locks the index.
+
 ## AK blob formats
 
 | Magic | Scope | Meaning |
@@ -23,6 +26,24 @@ On Windows, node-tpm2 uses the **Microsoft Platform Crypto Provider** for attest
 
 Blob layout: magic + key name + PCP creation attestation fields (`public` holds metadata; `private` is empty).
 
+## Threat model: device vs application
+
+**A quote proves an enrolled device, not a specific app or user.**
+
+On Windows, a machine-scoped attestation key (`PCP2`) is a **host-local capability**, not a secret. The exported blob is mainly a **locator**: magic, `keyName`, and scope. At quote time the library opens the persisted PCP key by that name. Any standard-user process that knows the fleet `keyName` can obtain a valid quote from the same AK — that is how cross-user runtime quoting works after one-time elevated provisioning.
+
+This is inherent to device attestation on Windows (and similar on Linux: anyone with read/write on `/dev/tpmrm0` can use a copied AK blob on the same TPM). It is **not** a library bug and should not be “fixed” by treating the blob as a password.
+
+| What a quote establishes | What it does **not** establish |
+|--------------------------|--------------------------------|
+| The TPM that was enrolled still holds the AK | Which Windows process produced the quote |
+| PCR values at quote time match the attestation | Which human user clicked “sign in” |
+| `qualifyingData` matches what the verifier sent (if you set it) | That only your product binary ran |
+
+**Your enrollment service** should bind identity at enroll time: verify `akPublicDer`, optionally verify PCP creation attestation fields in the blob, register the device once, then issue runtime challenges via `qualifyingData`. **App and user binding** are separate layers (session auth, mTLS, OS login, etc.).
+
+Use a **vendor-prefixed, stable `keyName`** for machine scope (for example `my-app-device-ak`). Do not rely on secrecy of the blob or key name; rely on TPM possession + server-side enrollment records + challenge nonces.
+
 ## Machine key provisioning
 
 ```javascript

package/examples/nv-smoke.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * NV define / read / write / undefine cycle (owner NV index).
+ *
+ * WARNING: Mutates TPM NV storage. Use only on a test machine.
+ * Requires owner authorization (often empty password on consumer TPMs).
+ *
+ * Usage:
+ *   node nv-smoke.mjs
+ *   node nv-smoke.mjs --handle 0x01800042 --size 64
+ *
+ * Install:
+ *   npm install node-tpm2@beta
+ *   node node_modules/node-tpm2/examples/nv-smoke.mjs
+ */
+
+import { Tpm } from '../index.js';
+
+function flagValue(args, name) {
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === name && args[i + 1]) return args[++i];
+    const prefix = `${name}=`;
+    if (args[i]?.startsWith(prefix)) return args[i].slice(prefix.length);
+  }
+  return undefined;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const handle = flagValue(args, '--handle') ?? '0x01800042';
+  const size = Number(flagValue(args, '--size') ?? '64');
+
+  if (!(await Tpm.isAvailable())) {
+    console.error('FAIL: no TPM');
+    process.exit(1);
+  }
+
+  await using tpm = await Tpm.open();
+  const payload = Buffer.from(`node-tpm2-nv-smoke-${Date.now()}`);
+
+  console.log(`== nv-smoke handle=${handle} size=${size} ==`);
+
+  try {
+    await tpm.nv.undefine(handle);
+    console.log('  (pre-clean undefine OK or index absent)');
+  } catch {
+    console.log('  (pre-clean undefine skipped — index may not exist)');
+  }
+
+  await tpm.nv.define({ handle, size });
+  console.log('PASS  nv.define');
+
+  const meta = await tpm.nv.readPublic(handle);
+  console.log('PASS  nv.readPublic', meta);
+
+  await tpm.nv.write(handle, payload, 0);
+  console.log('PASS  nv.write', payload.length, 'bytes');
+
+  const readBack = await tpm.nv.read(handle, 0, payload.length);
+  if (!readBack.equals(payload)) {
+    console.error('FAIL: read mismatch');
+    process.exit(1);
+  }
+  console.log('PASS  nv.read roundtrip');
+
+  await tpm.nv.undefine(handle);
+  console.log('PASS  nv.undefine');
+
+  console.log('\nnv-smoke: OK');
+}
+
+main().catch((err) => {
+  console.error('FAIL:', err.message ?? err);
+  if (err.code) console.error('  code:', err.code);
+  if (err.tpmRc != null) console.error('  tpmRc:', err.tpmRc);
+  process.exit(1);
+});

package/index.d.ts

@@ -32,6 +32,9 @@ export declare type AkBlob = {
   private: Buffer;
 };
 
+/** General key blob (same wire shape as AkBlob; distinct type for clarity). */
+export declare type KeyBlob = AkBlob;
+
 export declare type QuoteOptions = {
   akBlob: AkBlob;
   pcrSelection: number[];
@@ -74,6 +77,34 @@ export declare type ActivateCredentialFlatOptions = ActivateCredentialOptions &
   akBlob: AkBlob;
 };
 
+/** General device key creation options. */
+export declare type KeyCreateOptions = {
+  type: 'ecc' | 'rsa';
+  sign?: boolean;
+  decrypt?: boolean;
+};
+
+/** Sealed blob options. */
+export declare type SealOptions = {
+  data: Buffer;
+  pcrSelection?: number[];
+};
+
+/** Owner NV index definition (requires owner authorization). */
+export declare type NvDefineOptions = {
+  handle: string | number;
+  size: number;
+  /** Index password when attributes use AUTHREAD/AUTHWRITE. */
+  auth?: Buffer;
+  /** Owner hierarchy password (often empty on consumer TPMs). */
+  ownerAuth?: Buffer;
+};
+
+export declare type NvReadPublicResult = {
+  dataSize: number;
+  attributes: number;
+};
+
 export declare interface AkHandle {
   export(): AkBlob;
   readonly publicKeyDer: Buffer;
@@ -81,6 +112,13 @@ export declare interface AkHandle {
   activateCredential(opts: ActivateCredentialOptions): Promise<Buffer>;
 }
 
+/** @throws {TpmError} when key lacks decrypt attribute */
+export declare interface KeyHandle {
+  export(): KeyBlob;
+  sign(digest: Buffer): Promise<Buffer>;
+  decrypt(cipher: Buffer): Promise<Buffer>;
+}
+
 export declare type TpmInfo = {
   manufacturer: string;
   firmwareVersion: string;
@@ -92,6 +130,35 @@ export declare interface TpmHandle {
   info(): Promise<TpmInfo>;
   pcr: {
     read(selection: number[], bank?: 'sha256'): Promise<Record<number, string>>;
+    extend(index: number, digest: Buffer): Promise<void>;
+  };
+  random: {
+    bytes(count: number): Promise<Buffer>;
+  };
+  nv: {
+    readPublic(handle: string | number): Promise<NvReadPublicResult>;
+    read(
+      handle: string | number,
+      offset?: number,
+      size?: number,
+      auth?: Buffer,
+    ): Promise<Buffer>;
+    write(
+      handle: string | number,
+      data: Buffer,
+      offset?: number,
+      auth?: Buffer,
+    ): Promise<void>;
+    define(opts: NvDefineOptions): Promise<void>;
+    undefine(handle: string | number, ownerAuth?: Buffer): Promise<void>;
+  };
+  keys: {
+    create(opts: KeyCreateOptions): Promise<KeyHandle>;
+    load(blob: KeyBlob): Promise<KeyHandle>;
+  };
+  seal: {
+    seal(opts: SealOptions): Promise<Buffer>;
+    unseal(blob: Buffer): Promise<Buffer>;
   };
   attest: {
     ekCertificate(): Promise<Buffer | null>;
@@ -107,33 +174,32 @@ export declare const Tpm: {
   open(): Promise<TpmHandle>;
   getFixedProperties(): Promise<TpmInfo>;
   info(): Promise<TpmInfo>;
+  randomBytes(count: number): Promise<Buffer>;
   pcrRead(selection: number[], bank?: 'sha256'): Promise<Record<number, string>>;
+  pcrExtend(index: number, digest: Buffer): Promise<void>;
   readPublic(handle: string): Promise<ReadPublicResult>;
   readEkCertificate(): Promise<Buffer | null>;
   quote(opts: QuoteOptions): Promise<QuoteResult>;
   provisionAk(opts?: ProvisionAkOptions): Promise<ProvisionAkResult>;
   activateCredential(opts: ActivateCredentialFlatOptions): Promise<Buffer>;
+  createKey(opts?: KeyCreateOptions): Promise<{ publicKeyDer: Buffer; keyBlob: KeyBlob }>;
+  signKeyBlob(opts: { keyBlob: KeyBlob; digest: Buffer }): Promise<Buffer>;
+  decryptKeyBlob(opts: { keyBlob: KeyBlob; cipher: Buffer }): Promise<Buffer>;
+  nvRead(
+    handle: string | number,
+    offset?: number,
+    size?: number,
+    auth?: Buffer,
+  ): Promise<Buffer>;
+  nvWrite(
+    handle: string | number,
+    data: Buffer,
+    offset?: number,
+    auth?: Buffer,
+  ): Promise<void>;
+  nvReadPublic(handle: string | number): Promise<NvReadPublicResult>;
+  nvDefine(opts: NvDefineOptions): Promise<void>;
+  nvUndefine(handle: string | number, ownerAuth?: Buffer): Promise<void>;
+  seal(opts: SealOptions): Promise<Buffer>;
+  unseal(blob: Buffer): Promise<Buffer>;
 };
-
-export declare function pcrRead(
-  selection: number[],
-  bank?: 'sha256',
-): Promise<Record<number, string>>;
-
-export declare function readPublic(handle: string): Promise<ReadPublicResult>;
-
-export declare function readEkCertificate(): Promise<Buffer | null>;
-
-export declare function quote(opts: QuoteOptions): Promise<QuoteResult>;
-
-export declare function provisionAk(
-  opts?: ProvisionAkOptions,
-): Promise<ProvisionAkResult>;
-
-export declare function activateCredential(
-  opts: ActivateCredentialFlatOptions,
-): Promise<Buffer>;
-
-export declare function getFixedProperties(): Promise<TpmInfo>;
-
-export declare function isAvailable(): Promise<boolean>;