node-tpm2 0.0.4-beta.4 → 0.0.5-beta.1

package/README.md

@@ -18,7 +18,7 @@ const { message, signature } = await ak.quote({
 });
 ```
 
-**Pre-release** (`0.0.x-beta`). [Roadmap](./docs/roadmap.md) for remaining namespaces.
+**Pre-release** (`0.0.x-beta`). Full public API implemented; validated on real Windows 11 + Intel TPM. [API reference](./docs/api-reference.md) · [Roadmap](./docs/roadmap.md).
 
 ---
 
@@ -194,19 +194,21 @@ More detail: [getting-started.md](./docs/getting-started.md) · [api-reference.m
 | `tpm.random.bytes(n)` | ✓ | ✓ | ✓ |
 | **pcr** | | | |
 | `tpm.pcr.read(...)` | ✓ | ✓ | ✓ |
-| `tpm.pcr.extend(i, digest)` | ✓ * | ✓ * | ✓ |
+| `tpm.pcr.extend(i, digest)` | ✓ † | ✗ → `REQUIRES_ELEVATION` | ✓ † |
 | **nv** | | | |
-| `tpm.nv.read(...)` | ✓ *planned* | ✓ *planned* | ✓ |
-| `tpm.nv.write(...)` | ✓ *planned* | ✓ *planned* | ✓ |
+| `tpm.nv.read(...)` | ✓ ‡ | ✓ ‡ | ✓ |
+| `tpm.nv.write(...)` | ✓ ‡ | ✓ ‡ | ✓ |
+| `tpm.nv.define(...)` | ✓ § | ✓ § | ✓ § |
+| `tpm.nv.undefine(...)` | ✓ § | ✓ § | ✓ § |
 | `tpm.attest.ekCertificate()` | ✓ | ✓ | ✓ |
 | **keys** | | | |
 | `tpm.keys.create(...)` | ✓ | ✓ | ✓ |
 | `tpm.keys.load(blob)` | ✓ | ✓ | ✓ |
 | `key.sign(digest)` | ✓ | ✓ | ✓ |
-| `key.decrypt(cipher)` | — *planned* | — *planned* | — *planned* |
+| `key.decrypt(cipher)` | ✓ | ✓ | ✓ |
 | **seal** | | | |
-| `tpm.seal(...)` | ✓ *planned* | ✓ *planned* | ✓ |
-| `tpm.unseal(blob)` | ✓ *planned* | ✓ *planned* | ✓ |
+| `tpm.seal.seal(...)` | ✓ | ✓ | ✓ |
+| `tpm.unseal(blob)` | ✓ | ✓ | ✓ |
 | **attest** | | | |
 | `tpm.attest.provisionAk()` user | ✓ | ✓ | ✓ |
 | `tpm.attest.provisionAk({ scope: 'machine' })` | — | ✗ | ✓ |
@@ -217,7 +219,15 @@ More detail: [getting-started.md](./docs/getting-started.md) · [api-reference.m
 
 **Windows fleet pattern:** provision machine AK elevated or as SYSTEM once → persist `akBlob` → standard users quote forever after. See [docs/windows-pcp.md](./docs/windows-pcp.md).
 
-**Planned rows** are design targets from the [roadmap](./docs/roadmap.md); unprivileged use matches the Phase 0 spike (`GetRandom`, `CreatePrimary` succeeded on Windows 11 without admin). Firmware or group policy can still deny specific PCR/NV operations — those surface as `TPM_RC` or `COMMAND_BLOCKED`, not silent failure.
+**Hardware validation (beta):** Windows 11 Intel TPM — attestation suite, `random`, `keys`, `pcr.read` / `pcr.extend` (elevated), `nv.read`. Linux: CI + swtpm. Firmware or group policy can still deny specific PCR/NV operations — those surface as `TPM_RC` or `REQUIRES_ELEVATION`, not silent failure.
+
+**‡ `nv.read/write`:** Success depends on index attributes and auth. EK cert indices (`0x01c00002`, `0x01c0000A`) are read-only.
+
+**§ `nv.define/undefine`:** Owner NV range only (`0x01800000`–`0x01BFFFFF`). Requires owner authorization (often empty password). **Consumes NV space** until undefined — use only on test machines or with a chosen index. Windows standard user → **`REQUIRES_ELEVATION`** (same TBS block as `pcr.extend`); run Admin PowerShell.
+
+**Note:** On Windows, raw TBS may reject `nv.readPublic` for owner-range indices (`TPM_RC` ~`0xA6`) even when define/read/write succeed. Factory indices (`0x01c00002` EK cert) work. After `nv.define`, use the known size for read/write; `examples/nv-smoke.mjs` handles this.
+
+**† `pcr.extend`:** Linux standard user (prefer indices **16–23** for experiments; avoid **0–7** boot/Secure Boot PCRs). **Windows standard user → `REQUIRES_ELEVATION`** (`TPM_E_COMMAND_BLOCKED` from TBS). Windows Administrator can extend on real hardware (validated). Standard-user failure is not `COMMAND_BLOCKED` — re-run elevated.
 
 ---
 
@@ -268,7 +278,31 @@ const reloaded = await tpm.keys.load(saved);
 await reloaded.sign(digest);
 ```
 
-Flat: `Tpm.createKey()`, `Tpm.signKeyBlob({ keyBlob, digest })`. RSA `decrypt` is not yet implemented.
+const rsaKey = await tpm.keys.create({ type: 'rsa', sign: true, decrypt: true });
+const plain = await rsaKey.decrypt(ciphertext);
+
+Flat: `Tpm.createKey()`, `Tpm.signKeyBlob({ keyBlob, digest })`, `Tpm.decryptKeyBlob({ keyBlob, cipher })`.
+
+### NV
+
+```javascript
+await tpm.nv.read('0x01c00002');              // EK cert index (read-only on most hardware)
+await tpm.nv.readPublic('0x01800042');        // metadata before read/write
+await tpm.nv.define({ handle: '0x01800042', size: 64 });  // owner NV — test machines only
+await tpm.nv.write('0x01800042', data, 0);
+await tpm.nv.undefine('0x01800042');
+```
+
+Flat: `Tpm.nvRead`, `Tpm.nvWrite`, `Tpm.nvReadPublic`, `Tpm.nvDefine`, `Tpm.nvUndefine`. See `examples/nv-smoke.mjs`.
+
+### Seal
+
+```javascript
+const sealed = await tpm.seal.seal({ data: secret, pcrSelection: [23] });
+const plain = await tpm.seal.unseal(sealed);
+```
+
+Flat: `Tpm.seal`, `Tpm.unseal`.
 
 ### Attestation
 
@@ -347,8 +381,8 @@ try {
 |------|------|:-------:|:---------:|----------------------|
 | `TPM_UNAVAILABLE` | No TPM, no native binary, macOS, or backend not built | — | — | Install platform package / check TPM |
 | `ACCESS_DENIED` | OS denied device or key access | — | sometimes | Linux: `tss` group; container: pass device |
-| `REQUIRES_ELEVATION` | Windows operation needs Admin/SYSTEM | — | ✓ | Re-run enrollment elevated or as SYSTEM |
-| `COMMAND_BLOCKED` | Windows TBS driver blocked the command ordinal | ✓ | — | Use NCrypt PCP path (e.g. activation) |
+| `REQUIRES_ELEVATION` | Windows operation needs Admin/SYSTEM | — | ✓ | Re-run elevated; **`pcr.extend`** and **`nv.define`/`nv.undefine`** from standard user |
+| `COMMAND_BLOCKED` | Windows TBS blocked raw ordinal (e.g. ActivateCredential) | ✓ | — | Use NCrypt PCP — elevation does not help |
 | `NOT_SUPPORTED` | Feature or PCP capability missing on this platform | — | sometimes | — |
 | `INVALID_ARGUMENT` | Bad JS/Rust option (e.g. empty machine `keyName`) | — | sometimes | Fix caller input |
 | `KEY_NOT_FOUND` | NCrypt key / blob locator not found | — | ✓ | Check persisted blob / key name |
@@ -367,7 +401,9 @@ When the TPM returns a non-zero response code, the library classifies it:
 | Success | `rc === 0` | (no error) | `0` |
 | Auth | `(rc & 0x0300) === 0x0300` | `AUTH_FAILED` | `0x38E` (`TPM_RC_AUTH_FAIL`) |
 | Format | `(rc & 0xFF00) === 0x0100` or FMT1 bit set | `MARSHALLING_ERROR` | `0x125` (`TPM_RC_ASYMMETRIC`) |
-| Windows TBS blocked | `rc === 0x80280400` | `COMMAND_BLOCKED` | `0x80280400` |
+| Windows TBS blocked | `rc === 0x80280400` | `COMMAND_BLOCKED` * | `0x80280400` |
+
+\* **`PCR_Extend`:** mapped to **`REQUIRES_ELEVATION`** (same `hresult` `0x80280400`) — Administrator can extend on Windows client; standard user should re-run elevated.
 | Other | everything else | `TPM_RC` | vendor-specific |
 
 Auth-class and format-class detection follows TPM 2.0 response-code layout (see `src/tbs/rc.rs`). **`tpmRc` on the error is the full 32-bit value** from the TPM response header — use it for logs and TPM spec lookup.
@@ -394,16 +430,17 @@ PCP / NCrypt failures on Windows map through `classify_ncrypt` (`src/tbs/ncrypt.
 
 ---
 
-## API reference (planned)
+## API reference
 
-Subsystem namespaces not yet on `TpmHandle`. See [docs/roadmap.md](./docs/roadmap.md) for phases and acceptance criteria.
+Subsystem namespaces on `TpmHandle`. See [docs/api-reference.md](./docs/api-reference.md) for full detail.
 
 | Namespace | Methods |
 |-----------|---------|
 | `tpm.random` | `bytes(n)` ✅ |
-| `tpm.keys` | `create`, `load`, `KeyHandle.sign` ✅ · `decrypt` planned |
-| `tpm.pcr` | `extend(index, digest)` |
-| `tpm.seal` | `seal`, `unseal` |
+| `tpm.keys` | `create`, `load`, `KeyHandle.sign`, `KeyHandle.decrypt` ✅ |
+| `tpm.pcr` | `read`, `extend` ✅ |
+| `tpm.nv` | `read`, `write`, `readPublic`, `define`, `undefine` ✅ |
+| `tpm.seal` | `seal`, `unseal` ✅ |
 
 ---
 

package/api.js

@@ -66,10 +66,11 @@ export class TpmError extends Error {
   }
 }
 
-function notSupported(feature) {
-  return async () => {
-    throw new TpmError('NOT_SUPPORTED', `${feature} is not implemented yet.`);
-  };
+function parseTpmHandle(handle) {
+  if (typeof handle === 'number') {
+    return `0x${handle.toString(16).padStart(8, '0')}`;
+  }
+  return handle;
 }
 
 function createKeyHandle(publicKeyDer, keyBlob) {
@@ -94,7 +95,14 @@ function createKeyHandle(publicKeyDer, keyBlob) {
       return Buffer.from(sig);
     }),
 
-    decrypt: notSupported('key.decrypt'),
+    decrypt: wrapNative(async (cipher) => {
+      requireNative('decryptKeyBlob');
+      const plain = await native.decryptKeyBlob({
+        keyBlob,
+        cipher,
+      });
+      return Buffer.from(plain);
+    }),
   };
 }
 
@@ -164,8 +172,49 @@ function createTpmHandle() {
     },
 
     nv: {
-      read: notSupported('tpm.nv.read'),
-      write: notSupported('tpm.nv.write'),
+      readPublic: wrapNative(async (handle) => {
+        requireNative('nvReadPublic');
+        return native.nvReadPublic(parseTpmHandle(handle));
+      }),
+
+      read: wrapNative(async (handle, offset, size, auth) => {
+        requireNative('nvRead');
+        const buf = await native.nvRead(
+          parseTpmHandle(handle),
+          offset ?? undefined,
+          size ?? undefined,
+          auth ?? undefined,
+        );
+        return Buffer.from(buf);
+      }),
+
+      write: wrapNative(async (handle, data, offset, auth) => {
+        requireNative('nvWrite');
+        await native.nvWrite({
+          handle: parseTpmHandle(handle),
+          data,
+          offset: offset ?? undefined,
+          auth: auth ?? undefined,
+        });
+      }),
+
+      define: wrapNative(async (opts) => {
+        requireNative('nvDefine');
+        await native.nvDefine({
+          handle: parseTpmHandle(opts.handle),
+          size: opts.size,
+          auth: opts.auth ?? undefined,
+          ownerAuth: opts.ownerAuth ?? undefined,
+        });
+      }),
+
+      undefine: wrapNative(async (handle, ownerAuth) => {
+        requireNative('nvUndefine');
+        await native.nvUndefine({
+          handle: parseTpmHandle(handle),
+          ownerAuth: ownerAuth ?? undefined,
+        });
+      }),
     },
 
     keys: {
@@ -187,8 +236,20 @@ function createTpmHandle() {
     },
 
     seal: {
-      seal: notSupported('tpm.seal'),
-      unseal: notSupported('tpm.unseal'),
+      seal: wrapNative(async (opts) => {
+        requireNative('seal');
+        const buf = await native.seal({
+          data: opts.data,
+          pcrSelection: opts.pcrSelection,
+        });
+        return Buffer.from(buf);
+      }),
+
+      unseal: wrapNative(async (blob) => {
+        requireNative('unseal');
+        const plain = await native.unseal(blob);
+        return Buffer.from(plain);
+      }),
     },
 
     attest: {
@@ -352,4 +413,69 @@ export const Tpm = {
     const sig = await native.signKeyBlob(opts);
     return Buffer.from(sig);
   }),
+
+  decryptKeyBlob: wrapNative(async (opts) => {
+    requireNative('decryptKeyBlob');
+    const plain = await native.decryptKeyBlob(opts);
+    return Buffer.from(plain);
+  }),
+
+  nvRead: wrapNative(async (handle, offset, size, auth) => {
+    requireNative('nvRead');
+    const buf = await native.nvRead(
+      parseTpmHandle(handle),
+      offset ?? undefined,
+      size ?? undefined,
+      auth ?? undefined,
+    );
+    return Buffer.from(buf);
+  }),
+
+  nvWrite: wrapNative(async (handle, data, offset, auth) => {
+    requireNative('nvWrite');
+    await native.nvWrite({
+      handle: parseTpmHandle(handle),
+      data,
+      offset: offset ?? undefined,
+      auth: auth ?? undefined,
+    });
+  }),
+
+  nvReadPublic: wrapNative(async (handle) => {
+    requireNative('nvReadPublic');
+    return native.nvReadPublic(parseTpmHandle(handle));
+  }),
+
+  nvDefine: wrapNative(async (opts) => {
+    requireNative('nvDefine');
+    await native.nvDefine({
+      handle: parseTpmHandle(opts.handle),
+      size: opts.size,
+      auth: opts.auth ?? undefined,
+      ownerAuth: opts.ownerAuth ?? undefined,
+    });
+  }),
+
+  nvUndefine: wrapNative(async (handle, ownerAuth) => {
+    requireNative('nvUndefine');
+    await native.nvUndefine({
+      handle: parseTpmHandle(handle),
+      ownerAuth: ownerAuth ?? undefined,
+    });
+  }),
+
+  seal: wrapNative(async (opts) => {
+    requireNative('seal');
+    const buf = await native.seal({
+      data: opts.data,
+      pcrSelection: opts.pcrSelection,
+    });
+    return Buffer.from(buf);
+  }),
+
+  unseal: wrapNative(async (blob) => {
+    requireNative('unseal');
+    const plain = await native.unseal(blob);
+    return Buffer.from(plain);
+  }),
 };

package/docs/api-reference.md

@@ -27,7 +27,7 @@ import { Tpm, TpmError } from 'node-tpm2';
 11. [Error model (`TpmError`)](#error-model-tpmerror)
 12. [Platform differences](#platform-differences)
 13. [Privilege matrix](#privilege-matrix)
-14. [Planned / not yet implemented](#planned--not-yet-implemented)
+14. [Deferred / not in public API](#deferred--not-in-public-api)
 15. [Symbol index](#symbol-index)
 
 ---
@@ -66,7 +66,7 @@ flowchart TB
 
 **Design rules:**
 
-- **General keys, PCR, random, ReadPublic, seal (planned)** use the shared TBS command path on both Linux and Windows so blobs and behavior stay aligned.
+- **General keys, PCR, random, ReadPublic, NV, seal** use the shared TBS command path on both Linux and Windows so blobs and behavior stay aligned.
 - **Attestation key persistence on Windows** uses NCrypt Platform Crypto Provider (PCP) because raw TBS cannot persist cross-user identity keys reliably.
 - **Transient TPM handles** are created and flushed inside each native call. You do not manage TPM handle slots in JavaScript.
 
@@ -378,7 +378,11 @@ Returned by `Tpm.open()`. All sub-namespaces are plain objects with async method
 
 **Under the hood:** Sends `TPM2_PCR_Extend` with `authHandle = TPM_RH_NULL`, one SHA-256 digest in `TPML_DIGEST_VALUES`. The TPM updates the bank as `SHA256(old_pcr || digest)`.
 
-**Caveats:** Firmware or platform policy may lock specific PCRs; failures surface as `TPM_RC` or `COMMAND_BLOCKED`.
+**Caveats:**
+
+- **Linux:** Firmware may lock specific indices (often **0–7**). Prefer **16–23** for application measurements.
+- **Windows standard user:** TBS returns `TPM_E_COMMAND_BLOCKED` → library maps to **`REQUIRES_ELEVATION`** (re-run Admin PowerShell). Not `COMMAND_BLOCKED`.
+- **Windows Administrator:** Can extend on real client hardware (validated). Does not affect quotes that only select other PCRs (e.g. `[0,1,7]`).
 
 **Flat equivalent:** [`Tpm.pcrExtend(index, digest)`](#tpm-pcrextendindex-digest-promisevoid).
 
@@ -390,15 +394,81 @@ Returned by `Tpm.open()`. All sub-namespaces are plain objects with async method
 
 ---
 
-### `tpm.nv.read(handle, offset?, size?)`
+### `tpm.nv.read(handle, offset?, size?, auth?)`
+
+**Implemented.**
+
+```typescript
+// handle: hex string ('0x01c00002') or number
+await tpm.nv.read('0x01c00002');
+await tpm.nv.read('0x01c00002', 0, 512);
+await tpm.nv.read('0x01800001', 0, undefined, authBuffer);
+```
+
+**Under the hood:** `NV_ReadPublic` → size/attribute check → `NV_Read` with owner or index auth (based on `TPMA_NV_PPREAD` / `TPMA_NV_AUTHREAD`). Optional `auth` supplies the index password for `AUTHREAD` indices.
+
+**Safe indices on consumer hardware:**
+
+| Index | Typical use | Writable |
+|-------|-------------|----------|
+| `0x01c00002`, `0x01c0000A` | EK certificate (RSA / ECC) | **Read-only** (firmware) |
+| `0x01c0000B` | EK template | Read-only |
+| User-defined (`0x01800001`+) | Application data | **`nv.define` then read/write** |
+
+Prefer read-only access to well-known TCG indices. Writes fail with `TPM_RC` / `AUTH_FAILED` when the index is not writable or auth is wrong.
+
+**Flat equivalent:** [`Tpm.nvRead(handle, offset?, size?, auth?)`](#tpm-nvread).
+
+---
+
+### `tpm.nv.readPublic(handle): Promise<{ dataSize, attributes }>`
 
-**NOT_SUPPORTED** — throws `NOT_SUPPORTED`. Planned Phase 4. EK certificate today uses internal NV read only via `ekCertificate()`.
+**Implemented.** Returns NV index metadata from `NV_ReadPublic` without reading data.
+
+**Windows caveat:** Raw TBS often rejects this command for **owner-range** indices (`0x01800000`–`0x01BFFFFF`) with `MARSHALLING_ERROR` / `TPM_RC` ~`0xA6`, even when the index exists. Factory indices (e.g. EK cert `0x01c00002`) work. After [`tpm.nv.define`](#tpmnvdefineopts-promisevoid), use the known `size` for read/write — the library falls back to owner auth automatically.
+
+**Flat equivalent:** [`Tpm.nvReadPublic(handle)`](#tpm-nvreadpublic).
+
+---
+
+### `tpm.nv.define(opts): Promise<void>`
+
+**Implemented.** Creates an owner NV index (`TPM2_NV_DefineSpace`).
+
+```typescript
+type NvDefineOptions = {
+  handle: string | number;  // 0x01800000..0x01BFFFFF
+  size: number;             // 1..65535 bytes
+  auth?: Buffer;            // index password (if using AUTH* attributes)
+  ownerAuth?: Buffer;       // owner hierarchy password (often empty)
+};
+```
+
+**Default attributes:** `OWNERREAD | OWNERWRITE | NO_DA` — read/write via owner auth on `TPM_RH_OWNER`.
+
+**Destructive / privileged:** Consumes TPM NV space until [`tpm.nv.undefine`](#tpmnvundefinehandle-ownerauth). Refuses EK cert indices. **Not for production laptops without intent.** Windows standard user → **`REQUIRES_ELEVATION`** (re-run Admin PowerShell).
+
+**Flat equivalent:** [`Tpm.nvDefine(opts)`](#tpm-nvdefine).
 
 ---
 
-### `tpm.nv.write(handle, data, offset?)`
+### `tpm.nv.undefine(handle, ownerAuth?): Promise<void>`
+
+**Implemented.** Deletes an owner NV index (`TPM2_NV_UndefineSpace`).
 
-**NOT_SUPPORTED** — throws `NOT_SUPPORTED`. Planned Phase 4.
+**Flat equivalent:** [`Tpm.nvUndefine(handle, ownerAuth?)`](#tpm-nvundefine).
+
+---
+
+### `tpm.nv.write(handle, data, offset?, auth?)`
+
+**Implemented.**
+
+**Under the hood:** `NV_ReadPublic` bounds check → `NV_Write` with owner or index auth (`TPMA_NV_PPWRITE` / `TPMA_NV_AUTHWRITE`).
+
+**Caveats:** Most factory NV indices are read-only. User-defined indices must be created with [`tpm.nv.define`](#tpmnvdefineopts-promisevoid) first.
+
+**Flat equivalent:** [`Tpm.nvWrite(handle, data, offset?, auth?)`](#tpm-nvwrite).
 
 ---
 
@@ -410,7 +480,7 @@ Returned by `Tpm.open()`. All sub-namespaces are plain objects with async method
 type KeyCreateOptions = {
   type: 'ecc' | 'rsa';
   sign?: boolean;    // default true
-  decrypt?: boolean; // default false; RSA only when implemented
+  decrypt?: boolean; // default false; RSA only
 };
 ```
 
@@ -448,7 +518,32 @@ At least one of `sign` or `decrypt` must be true. `decrypt: true` with `type: 'e
 
 ### `tpm.seal.seal(opts)` / `tpm.seal.unseal(blob)`
 
-**NOT_SUPPORTED** — throws `NOT_SUPPORTED`. Planned Phase 5.
+**Implemented.**
+
+```typescript
+type SealOptions = {
+  data: Buffer;
+  pcrSelection?: number[]; // SHA-256 bank; binds to current PCR values at seal time
+};
+
+const sealed = await tpm.seal.seal({ data: secret });
+const plain = await tpm.seal.unseal(sealed);
+
+// PCR-bound: unseal fails if PCR state changes
+const bound = await tpm.seal.seal({ data: secret, pcrSelection: [7] });
+```
+
+**Under the hood:**
+
+1. `CreatePrimary` — transient storage primary.
+2. Optional `PolicyPCR` session when `pcrSelection` is set; policy digest embedded in sealed object.
+3. `Create` — keyedhash sealed object (`fixedTPM | fixedParent | userWithAuth | noDA`).
+4. Export `SEAL` wire blob (public + private + PCR metadata).
+5. `unseal`: load + `Unseal` (with matching `PolicyPCR` when bound).
+
+**Caveats:** PCR-bound seal requires the chosen PCRs to match at unseal time. `tpm.pcr.extend` on Windows needs elevation for many indices.
+
+**Flat equivalents:** [`Tpm.seal(opts)`](#tpm-sealopts), [`Tpm.unseal(blob)`](#tpm-unsealblob).
 
 ---
 
@@ -460,7 +555,7 @@ At least one of `sign` or `decrypt` must be true. `decrypt: true` with `type: 'e
 
 **Use for:** Chain-of-trust to manufacturer EK cert in attestation verification.
 
-**Not for:** General NV index access ([planned](#tpm-nv)).
+**Not for:** Attestation quotes (use `attest.provisionAk`). For general NV access use [`tpm.nv.read`](#tpmnvreadhandle-offset-size-auth).
 
 ---
 
@@ -559,7 +654,13 @@ Returned by `tpm.keys.create()` and `tpm.keys.load()`.
 
 ### `key.decrypt(cipher)`
 
-**NOT_SUPPORTED** — throws `NOT_SUPPORTED`. RSA OAEP decrypt planned for keys created with `decrypt: true`.
+**Implemented.** RSA OAEP (SHA-256) via `TPM2_RSA_Decrypt`. Key must have been created with `decrypt: true` (RSA only).
+
+**Under the hood:** Regenerate storage primary → `Load` → `RSA_Decrypt` with explicit OAEP scheme → flush.
+
+**Use for:** Decrypting ciphertext produced for the TPM RSA key's public half.
+
+**Not for:** ECC keys or sign-only RSA keys (`INVALID_ARGUMENT`).
 
 ---
 
@@ -727,7 +828,7 @@ Native Rust errors serialize as `__tpm2__code|message|suggestion|tpmRc|hresult`
 | `ACCESS_DENIED` | OS denied device access (Linux permissions, container) |
 | `REQUIRES_ELEVATION` | Windows Admin/SYSTEM required (machine AK, activation) |
 | `COMMAND_BLOCKED` | Windows TBS driver blocked command ordinal |
-| `NOT_SUPPORTED` | Unimplemented JS stub or PCP/TBS capability gap |
+| `NOT_SUPPORTED` | PCP/TBS capability gap on this platform | — | sometimes | — |
 | `INVALID_ARGUMENT` | Bad options (wrong digest size, invalid key type, empty `keyName`) |
 | `KEY_NOT_FOUND` | NCrypt persisted key missing |
 | `ALREADY_EXISTS` | NCrypt key name collision (`overwrite: false`) |
@@ -762,32 +863,32 @@ TPM response codes map by class: auth → `AUTH_FAILED`, format → `MARSHALLING
 | API | Linux user | Windows user | Windows Admin/SYSTEM |
 |-----|:----------:|:------------:|:--------------------:|
 | `Tpm.isAvailable()`, `open()`, `info()` | ✓ | ✓ | ✓ |
-| `tpm.random.bytes`, `tpm.pcr.read`, `tpm.pcr.extend` | ✓ | ✓ | ✓ |
-| `tpm.keys.create/load`, `key.sign` | ✓ | ✓ | ✓ |
+| `tpm.random.bytes`, `tpm.pcr.read` | ✓ | ✓ | ✓ |
+| `tpm.pcr.extend` | ✓ † | ✗ → `REQUIRES_ELEVATION` | ✓ † |
+| `tpm.nv.read` / `tpm.nv.write` | ✓ ‡ | ✓ ‡ | ✓ |
+| `tpm.nv.define` / `tpm.nv.undefine` | ✓ § | ✓ § | ✓ § |
+| `tpm.keys.create/load`, `key.sign`, `key.decrypt` | ✓ | ✓ | ✓ |
+| `tpm.seal.seal` / `tpm.seal.unseal` | ✓ | ✓ | ✓ |
 | `tpm.attest.provisionAk()` user scope | ✓ | ✓ | ✓ |
 | `tpm.attest.provisionAk({ scope: 'machine' })` | — | ✗ | ✓ |
 | `ak.quote` / `Tpm.quote` | ✓ | ✓ | ✓ |
 | `ak.activateCredential` | ✓ | ✗ | ✓ |
-| `tpm.pcr.extend` | ✓* | ✓* | ✓ |
-| `tpm.nv.*` (planned) | ✓* | ✓* | ✓ |
 
-\* Planned; firmware/policy may still deny.
+† **`pcr.extend`:** Linux user OK (avoid boot PCRs 0–7). Windows user blocked → **`REQUIRES_ELEVATION`**; Admin/SYSTEM OK. See [windows-pcp.md](./windows-pcp.md).
 
-Linux requires read/write on `/dev/tpmrm0`. Windows fleet pattern: provision machine AK once elevated → standard users quote forever.
+‡ **`nv.read/write`:** Index permissions vary; EK cert indices are read-only. Writes to undefined indices fail at the TPM.
 
----
+§ **`nv.define/undefine`:** Owner authorization required; owner NV range only. Destructive on NV space. Windows standard user → **`REQUIRES_ELEVATION`**.
 
-## Planned / not yet implemented
+Linux requires read/write on `/dev/tpmrm0`. Windows fleet pattern: provision machine AK once elevated → standard users quote forever.
 
-These methods exist on `TpmHandle` but **throw `TpmError` with code `NOT_SUPPORTED`** at call time:
+---
 
-| Method | Phase | Notes |
-|--------|-------|-------|
-| `tpm.nv.read/write` | 4 | General NV; EK cert uses internal path today |
-| `tpm.seal.seal` / `tpm.seal.unseal` | 5 | PCR-bound sealed storage |
-| `key.decrypt(cipher)` | 2+ | RSA OAEP for decrypt keys |
+## Deferred / not in public API
 
-Roadmap detail: [roadmap.md](./roadmap.md).
+| Feature | Notes |
+|---------|-------|
+| *(none — all planned namespaces are implemented)* | See [roadmap](./roadmap.md) for hardening / polish |
 
 ---
 
@@ -800,12 +901,16 @@ Roadmap detail: [roadmap.md](./roadmap.md).
 | Random | `tpm.random.bytes(n)` | `Tpm.randomBytes(n)` | `Buffer` |
 | PCR read | `tpm.pcr.read(sel, bank?)` | `Tpm.pcrRead(sel, bank?)` | `Record<number, string>` |
 | PCR extend | `tpm.pcr.extend(i, d)` | `Tpm.pcrExtend(i, d)` | `void` |
-| NV | `tpm.nv.read/write` | — | **NOT_SUPPORTED** |
+| NV read | `tpm.nv.read(h, off?, sz?, auth?)` | `Tpm.nvRead(...)` | `Buffer` |
+| NV write | `tpm.nv.write(h, data, off?, auth?)` | `Tpm.nvWrite(...)` | `void` |
+| NV readPublic | `tpm.nv.readPublic(h)` | `Tpm.nvReadPublic(h)` | `{ dataSize, attributes }` |
+| NV define | `tpm.nv.define(opts)` | `Tpm.nvDefine(opts)` | `void` |
+| NV undefine | `tpm.nv.undefine(h, ownerAuth?)` | `Tpm.nvUndefine(...)` | `void` |
 | Create key | `tpm.keys.create(opts)` | `Tpm.createKey(opts)` | `KeyHandle` / `{ publicKeyDer, keyBlob }` |
 | Load key | `tpm.keys.load(blob)` | — | `KeyHandle` |
 | Sign | `key.sign(digest)` | `Tpm.signKeyBlob({ keyBlob, digest })` | `Buffer` |
-| Decrypt | `key.decrypt(cipher)` | — | **NOT_SUPPORTED** |
-| Seal | `tpm.seal.seal/unseal` | — | **NOT_SUPPORTED** |
+| Decrypt | `key.decrypt(cipher)` | `Tpm.decryptKeyBlob({ keyBlob, cipher })` | `Buffer` |
+| Seal | `tpm.seal.seal/unseal` | `Tpm.seal` / `Tpm.unseal` | `Buffer` |
 | EK cert | `tpm.attest.ekCertificate()` | `Tpm.readEkCertificate()` | `Buffer \| null` |
 | Provision AK | `tpm.attest.provisionAk(opts)` | `Tpm.provisionAk(opts)` | `AkHandle` / `{ akPublicDer, akBlob }` |
 | Quote | `ak.quote(opts)` / `tpm.attest.quote(opts)` | `Tpm.quote({ akBlob, ... })` | `QuoteResult` |
@@ -886,17 +991,28 @@ All public exports from `'node-tpm2'`:
 | `Tpm.activateCredential` | function | Implemented |
 | `Tpm.createKey` | function | Implemented |
 | `Tpm.signKeyBlob` | function | Implemented |
+| `Tpm.decryptKeyBlob` | function | Implemented |
+| `Tpm.nvRead` | function | Implemented |
+| `Tpm.nvWrite` | function | Implemented |
+| `Tpm.nvReadPublic` | function | Implemented |
+| `Tpm.nvDefine` | function | Implemented |
+| `Tpm.nvUndefine` | function | Implemented |
+| `Tpm.seal` | function | Implemented |
+| `Tpm.unseal` | function | Implemented |
 | `TpmHandle.info` | method | Implemented |
 | `TpmHandle.readPublic` | method | Implemented |
 | `TpmHandle.pcr.read` | method | Implemented |
 | `TpmHandle.pcr.extend` | method | Implemented |
 | `TpmHandle.random.bytes` | method | Implemented |
-| `TpmHandle.nv.read` | method | **NOT_SUPPORTED** |
-| `TpmHandle.nv.write` | method | **NOT_SUPPORTED** |
+| `TpmHandle.nv.read` | method | Implemented |
+| `TpmHandle.nv.write` | method | Implemented |
+| `TpmHandle.nv.readPublic` | method | Implemented |
+| `TpmHandle.nv.define` | method | Implemented |
+| `TpmHandle.nv.undefine` | method | Implemented |
 | `TpmHandle.keys.create` | method | Implemented |
 | `TpmHandle.keys.load` | method | Implemented |
-| `TpmHandle.seal.seal` | method | **NOT_SUPPORTED** |
-| `TpmHandle.seal.unseal` | method | **NOT_SUPPORTED** |
+| `TpmHandle.seal.seal` | method | Implemented |
+| `TpmHandle.seal.unseal` | method | Implemented |
 | `TpmHandle.attest.ekCertificate` | method | Implemented |
 | `TpmHandle.attest.provisionAk` | method | Implemented |
 | `TpmHandle.attest.quote` | method | Implemented |
@@ -904,7 +1020,7 @@ All public exports from `'node-tpm2'`:
 | `KeyHandle.export` | method | Implemented |
 | `KeyHandle.publicKeyDer` | getter | Implemented |
 | `KeyHandle.sign` | method | Implemented |
-| `KeyHandle.decrypt` | method | **NOT_SUPPORTED** |
+| `KeyHandle.decrypt` | method | Implemented |
 | `AkHandle.export` | method | Implemented |
 | `AkHandle.publicKeyDer` | getter | Implemented |
 | `AkHandle.quote` | method | Implemented |