node-tpm2 0.0.4-beta.3 → 0.0.4-beta.4

package/README.md

@@ -1,164 +1,437 @@
 # node-tpm2
 
-**TPM 2.0 attestation for Node.js** — prebuilt native bindings, no `tpm2-tools`, no `tpm2-tss`, no Rust toolchain at install time.
+Native TPM 2.0 for Node.js. Prebuilt binaries — no `tpm2-tools`, no `tpm2-tss`, no Rust at install time.
 
-Use the TPM your OS already exposes: **TBS + Platform Crypto Provider** on Windows, **`/dev/tpmrm0`** on Linux. One small API for PCR reads, attestation key provisioning, quotes, and credential activation.
+Talks to the TPM through OS-native paths: **TBS + Platform Crypto Provider** on Windows, **`/dev/tpmrm0`** on Linux. Returns buffers and typed records, not CLI text.
 
 ```javascript
 import { Tpm } from 'node-tpm2';
 
-const tpm = await Tpm.open();
+if (!(await Tpm.isAvailable())) throw new Error('No TPM');
 
-const { akPublicDer, akBlob } = await tpm.attest.provisionAk();
-const quote = await tpm.attest.quote({
+await using tpm = await Tpm.open();
+
+const ak = await tpm.attest.provisionAk();
+const { message, signature } = await ak.quote({
+  pcrSelection: [0, 1, 7],
+  qualifyingData: Buffer.from('challenge-nonce'),
+});
+```
+
+**Pre-release** (`0.0.x-beta`). [Roadmap](./docs/roadmap.md) for remaining namespaces.
+
+---
+
+## Install
+
+```bash
+npm install node-tpm2
+```
+
+Node **20+**. One prebuilt `.node` per platform via optional dependencies.
+
+---
+
+## Examples
+
+### Check the TPM
+
+```javascript
+import { Tpm } from 'node-tpm2';
+
+if (!(await Tpm.isAvailable())) {
+  console.log('No TPM or no access');
+  process.exit(1);
+}
+
+const info = await Tpm.info();
+console.log(info.manufacturer, info.firmwareVersion, info.isVirtual ? '(virtual)' : '');
+```
+
+### Device attestation (dev / same-user)
+
+Provision a user-scoped attestation key, quote PCRs bound to a server challenge, send `message` + `signature` + `akPublicDer` to your verifier.
+
+```javascript
+import { Tpm } from 'node-tpm2';
+import { writeFileSync } from 'node:fs';
+
+const challenge = Buffer.from('server-issued-nonce-or-session-id');
+
+const { akPublicDer, akBlob } = await Tpm.provisionAk();
+writeFileSync('ak.blob.json', JSON.stringify({
+  public: akBlob.public.toString('base64'),
+  private: akBlob.private.toString('base64'),
+}));
+
+const { message, signature } = await Tpm.quote({
   akBlob,
   pcrSelection: [0, 1, 7],
-  qualifyingData: Buffer.from('your-challenge-nonce'),
+  qualifyingData: challenge,
 });
 
-// quote.message + quote.signature → send to your verifier
+// → POST { akPublicDer, message, signature, pcrSelection } to your backend
 ```
 
-## Why node-tpm2
+### Handle style (grouped API)
 
-| | node-tpm2 | Shelling out to tpm2-tools |
-|---|-----------|----------------------------|
-| Install | `npm install` + prebuilt `.node` | OS packages, PATH, version drift |
-| API | Async JavaScript, structured errors | Parse CLI output |
-| Windows fleet | Machine-scoped PCP keys, cross-user quote | PCP/NCrypt scripting pain |
-| AK persistence | Wrapped blob (`akBlob`) — no persistent TPM handles in your app | Handle bookkeeping |
+```javascript
+import { Tpm } from 'node-tpm2';
 
-**Use it when you need:**
+await using tpm = await Tpm.open();
 
-- **Device attestation** — prove boot/software state via PCR quotes bound to a challenge nonce
-- **Fleet enrollment** — provision a machine-scoped attestation key at install time (Intune, SCCM, GPO); quote at runtime as the logged-in user
-- **Remote verification** — export AK public key (SPKI DER) and quote blobs to your backend; verify with standard TPM quote rules
-- **EK-backed onboarding** — read the EK certificate, activate credentials during enrollment
+const pcrs = await tpm.pcr.read([0, 1, 7]);
+const ekCert = await tpm.attest.ekCertificate();   // Buffer | null
 
-## How it works
+const ak = await tpm.attest.provisionAk();
+const quote = await ak.quote({
+  pcrSelection: [0, 1, 7],
+  qualifyingData: Buffer.from('challenge'),
+});
 
+const saved = ak.export();   // persist { public, private } for next session
 ```
-┌─────────────────────────────────────────────────────────┐
-│  Your Node app (Tpm.open / flat helpers)                │
-└──────────────────────────┬──────────────────────────────┘
-                           │
-┌──────────────────────────▼──────────────────────────────┐
-│  node-tpm2 (napi-rs) — command build, sessions, blobs   │
-└──────────────┬─────────────────────────┬────────────────┘
-               │                         │
-     Linux     │                         │  Windows
-               ▼                         ▼
-        /dev/tpmrm0              TBS + NCrypt PCP
-        ECDSA P-256 AK           RSA-2048 persisted AK
-        TPM2B wrapped blob       PCP1 (user) / PCP2 (machine)
+
+### Windows fleet enrollment
+
+**Threat model:** A machine AK proves **this enrolled device**, not which app or user quoted. The blob is a locator (`keyName`), not a secret — see [Threat model in windows-pcp.md](./docs/windows-pcp.md#threat-model-device-vs-application).
+
+**Once** at install time (Admin or SYSTEM): create a machine-scoped key with a stable name and persist the blob.
+
+```javascript
+import { Tpm } from 'node-tpm2';
+import { writeFileSync } from 'node:fs';
+
+// Run elevated or as SYSTEM — see docs/windows-pcp.md
+const { akPublicDer, akBlob } = await Tpm.provisionAk({
+  keyName: 'my-app-device-ak',
+  scope: 'machine',
+  overwrite: true,
+});
+
+writeFileSync('C:\\ProgramData\\my-app\\ak.blob.json', JSON.stringify({
+  public: akBlob.public.toString('base64'),
+  private: akBlob.private.toString('base64'),
+}));
+// Register akPublicDer + creation data with your enrollment service
 ```
 
-- **No persistent TPM handles in your process.** You keep an `akBlob` (portable wrapped key material). Each operation loads transiently, signs, and flushes.
-- **Platform-native AK formats.** Linux uses ECDSA P-256 TPM2B blobs; Windows uses Microsoft PCP (`PCP1` user / `PCP2` machine). Verifiers should accept both.
-- **Structured errors.** Failures throw `TpmError` with stable `code`, optional `suggestion`, `tpmRc` (TPM return code), and `hresult` (Windows NCrypt).
+**Every runtime session** (standard user): load the blob and quote — no elevation.
 
-## Install
+```javascript
+import { Tpm } from 'node-tpm2';
+import { readFileSync } from 'node:fs';
 
-```bash
-npm install node-tpm2
+const raw = JSON.parse(readFileSync('C:\\ProgramData\\my-app\\ak.blob.json', 'utf8'));
+const akBlob = {
+  public: Buffer.from(raw.public, 'base64'),
+  private: Buffer.from(raw.private, 'base64'),
+};
+
+const quote = await Tpm.quote({
+  akBlob,
+  pcrSelection: [0, 1, 7],
+  qualifyingData: Buffer.from('runtime-challenge'),
+});
 ```
 
-Node **20+**. npm installs a prebuilt native binary for your OS/arch via optional platform packages.
+### Read PCRs and TPM objects
+
+```javascript
+import { Tpm } from 'node-tpm2';
+
+await using tpm = await Tpm.open();
 
-## API at a glance
+const digests = await tpm.pcr.read([0, 1, 7]);           // { 0: 'abc…', … }
+const ek = await tpm.readPublic('0x81010001');           // endorsement key
+const { publicKeyDer, name } = ek;
+```
 
-**Handle style** (grouped operations):
+### Credential activation (enrollment proof-of-possession)
 
 ```javascript
-const tpm = await Tpm.open();
+import { Tpm } from 'node-tpm2';
 
-await tpm.info();                          // manufacturer, firmware, virtual-TPM hint
-await tpm.pcr.read([0, 1, 7]);             // SHA-256 PCR digests
-await tpm.attest.ekCertificate();          // EK cert from NV, or null
+// credentialBlob + secret from your verifier's MakeCredential step
+const recovered = await Tpm.activateCredential({
+  akBlob,
+  credentialBlob,
+  secret,
+});
+// recovered → proves AK is on the TPM that owns the EK
+```
 
-const ak = await tpm.attest.provisionAk();   // returns AkHandle
-await ak.quote({ pcrSelection: [7], qualifyingData: nonce });
-await ak.export();                           // persist akBlob
-await ak.activateCredential({ credentialBlob, secret });
+### Errors
 
-await using tpm = await Tpm.open();        // Symbol.asyncDispose when done
+```javascript
+import { Tpm, TpmError } from 'node-tpm2';
+
+try {
+  await Tpm.provisionAk({ scope: 'machine', keyName: 'fleet-ak' });
+} catch (err) {
+  if (err instanceof TpmError && err.code === 'REQUIRES_ELEVATION') {
+    // Windows: run enrollment elevated or as SYSTEM, not at runtime
+  }
+}
+```
+
+More detail: [getting-started.md](./docs/getting-started.md) · [api-reference.md](./docs/api-reference.md) · [windows-pcp.md](./docs/windows-pcp.md) · [Error reference](#error-reference)
+
+---
+
+## Privilege matrix
+
+**Legend:** ✓ standard user (with normal TPM access) · ✗ needs elevation · — not applicable · \* policy/firmware may block
+
+| API | Linux standard user | Windows standard user | Windows Admin / SYSTEM |
+|-----|:-------------------:|:---------------------:|:----------------------:|
+| **Root** | | | |
+| `Tpm.isAvailable()` | ✓ | ✓ | ✓ |
+| `Tpm.open()` | ✓ | ✓ | ✓ |
+| `tpm.info()` | ✓ | ✓ | ✓ |
+| `tpm.readPublic(handle)` | ✓ | ✓ | ✓ |
+| **random** | | | |
+| `tpm.random.bytes(n)` | ✓ | ✓ | ✓ |
+| **pcr** | | | |
+| `tpm.pcr.read(...)` | ✓ | ✓ | ✓ |
+| `tpm.pcr.extend(i, digest)` | ✓ * | ✓ * | ✓ |
+| **nv** | | | |
+| `tpm.nv.read(...)` | ✓ *planned* | ✓ *planned* | ✓ |
+| `tpm.nv.write(...)` | ✓ *planned* | ✓ *planned* | ✓ |
+| `tpm.attest.ekCertificate()` | ✓ | ✓ | ✓ |
+| **keys** | | | |
+| `tpm.keys.create(...)` | ✓ | ✓ | ✓ |
+| `tpm.keys.load(blob)` | ✓ | ✓ | ✓ |
+| `key.sign(digest)` | ✓ | ✓ | ✓ |
+| `key.decrypt(cipher)` | — *planned* | — *planned* | — *planned* |
+| **seal** | | | |
+| `tpm.seal(...)` | ✓ *planned* | ✓ *planned* | ✓ |
+| `tpm.unseal(blob)` | ✓ *planned* | ✓ *planned* | ✓ |
+| **attest** | | | |
+| `tpm.attest.provisionAk()` user | ✓ | ✓ | ✓ |
+| `tpm.attest.provisionAk({ scope: 'machine' })` | — | ✗ | ✓ |
+| `ak.quote(...)` / `Tpm.quote(...)` | ✓ | ✓ | ✓ |
+| `ak.activateCredential(...)` | ✓ | ✗ | ✓ |
+
+**Linux standard user** requires read/write on `/dev/tpmrm0` (commonly the `tss` group). That is a one-time deploy permission, not root for every call.
+
+**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.
+
+---
+
+## API reference (shipped)
+
+Import: `import { Tpm, TpmError } from 'node-tpm2'`
+
+All flat methods also exist on `Tpm.*` (e.g. `Tpm.pcrRead` ≡ `tpm.pcr.read`).
+
+### Availability
+
+```javascript
+await Tpm.isAvailable();              // boolean, never throws
+await Tpm.info();                     // { manufacturer, firmwareVersion, isVirtual, spec }
+```
+
+### Handle
+
+```javascript
+await using tpm = await Tpm.open();
+await tpm.readPublic('0x81000001');   // → { publicKeyDer, name }
+```
+
+### PCR
+
+```javascript
+await tpm.pcr.read([0, 1, 7], 'sha256');   // → { 0: 'hex…', 1: 'hex…', … }
+await tpm.pcr.extend(7, digest);           // digest: 32-byte Buffer (SHA-256 bank)
+await Tpm.pcrExtend(7, digest);            // flat
+```
+
+### Random
+
+```javascript
+await tpm.random.bytes(32);   // Buffer from TPM2_GetRandom
+await Tpm.randomBytes(32);    // flat
+```
+
+### Keys (device-bound signing)
+
+```javascript
+const key = await tpm.keys.create({ type: 'ecc', sign: true });
+const digest = crypto.createHash('sha256').update('payload').digest();
+const signature = await key.sign(digest);
+const saved = key.export();
+
+const reloaded = await tpm.keys.load(saved);
+await reloaded.sign(digest);
 ```
 
-**Flat style** (same operations, functional entry points):
+Flat: `Tpm.createKey()`, `Tpm.signKeyBlob({ keyBlob, digest })`. RSA `decrypt` is not yet implemented.
+
+### Attestation
+
+```javascript
+const ak = await tpm.attest.provisionAk({
+  keyName: 'my-app-device-ak',    // Windows: required for machine scope
+  scope: 'machine',               // Windows: 'user' | 'machine'
+  overwrite: true,
+});
+
+const akBlob = ak.export();         // { public, private }
+await ak.quote({ pcrSelection: [0, 1, 7], qualifyingData: Buffer.from('nonce') });
+await tpm.attest.ekCertificate();   // Buffer | null
+await ak.activateCredential({ credentialBlob, secret });
+```
+
+### Flat equivalents
 
 ```javascript
-await Tpm.isAvailable();
-await Tpm.provisionAk({ keyName: 'my-app-ak' });
-await Tpm.quote({ akBlob, pcrSelection: [0], qualifyingData: nonce });
 await Tpm.pcrRead([0, 1, 7]);
+await Tpm.readPublic('0x81010001');
 await Tpm.readEkCertificate();
+await Tpm.provisionAk({ scope: 'user' });
+await Tpm.quote({ akBlob, pcrSelection: [7], qualifyingData: nonce });
 await Tpm.activateCredential({ akBlob, credentialBlob, secret });
 ```
 
-Errors:
+### Types
+
+```typescript
+type AkBlob = { public: Buffer; private: Buffer };
+
+type ProvisionAkOptions = {
+  keyName?: string;
+  scope?: 'user' | 'machine';
+  overwrite?: boolean;
+};
+
+type QuoteOptions = {
+  akBlob: AkBlob;
+  pcrSelection: number[];
+  qualifyingData: Buffer;
+  bank?: 'sha256';
+};
+```
+
+---
+
+## Error reference
+
+Failures throw `TpmError` (subclass of `Error`). Inspect **`code`** for programmatic handling; use **`message`** for logs; **`tpmRc`** / **`hresult`** carry raw platform codes when present.
 
 ```javascript
+import { Tpm, TpmError } from 'node-tpm2';
+
 try {
   await Tpm.provisionAk({ scope: 'machine', keyName: 'fleet-ak' });
 } catch (err) {
-  if (err.code === 'REQUIRES_ELEVATION') {
-    // Windows: machine keys need Admin/SYSTEM at provision time only
+  if (err instanceof TpmError) {
+    err.code;        // stable string — branch on this
+    err.message;     // human detail (includes context + hex codes)
+    err.suggestion;  // optional remediation
+    err.tpmRc;       // TPM 2.0 response code (number), when applicable
+    err.hresult;     // Windows NCrypt / Win32 HRESULT (number), when applicable
   }
 }
 ```
 
-Full reference: [docs/getting-started.md](./docs/getting-started.md) · Windows fleet: [docs/windows-pcp.md](./docs/windows-pcp.md)
+**Wire format** (native → JS): `__tpm2__code|message|suggestion|tpmRc|hresult` — empty trailing fields mean undefined.
 
-## Privileges (honest summary)
+**Stability:** error **codes** are semver-stable after `latest`. New codes may be added in minors; renames require a major.
 
-There is **no separate TPM daemon to install**, but the OS still controls access:
+### Stable error codes
 
-| | Linux | Windows |
-|---|-------|---------|
-| **Typical runtime** (quote, PCR read) | User in `tss` group (or equivalent access to `/dev/tpmrm0`) | Standard user — no elevation |
-| **User-scoped AK** (`provisionAk()`) | Same as runtime | Standard user |
-| **Machine-scoped AK** (`scope: 'machine'`) | N/A | **Admin or SYSTEM at enrollment** — then standard users quote with the saved blob |
-| **Credential activation** | TPM policy dependent | Elevated / SYSTEM |
+| Code | When | `tpmRc` | `hresult` | Typical `suggestion` |
+|------|------|:-------:|:---------:|----------------------|
+| `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) |
+| `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 |
+| `ALREADY_EXISTS` | NCrypt key name already exists | — | ✓ | Use `overwrite: true` |
+| `MARSHALLING_ERROR` | Codec bug, malformed TPM command, or unclassified NCrypt failure | sometimes | sometimes | Report bug or check firmware |
+| `TRANSPORT_ERROR` | TBS / `/dev/tpmrm0` I/O failure | — | — | Retry; check driver / device node |
+| `AUTH_FAILED` | TPM auth-class response (policy / password / hierarchy) | ✓ | — | Check object auth or policy |
+| `TPM_RC` | Other TPM non-success response | ✓ | — | See `tpmRc` nibble / TPM spec |
 
-**Fleet pattern:** installer runs once elevated (or as SYSTEM) → saves `akBlob` → app quotes unprivileged forever after. See [docs/windows-pcp.md](./docs/windows-pcp.md).
+### TPM response code → `TpmError.code`
 
-## Validate your install
+When the TPM returns a non-zero response code, the library classifies it:
 
-```bash
-npm ls node-tpm2
-node node_modules/node-tpm2/examples/smoke-test.mjs runtime
-```
+| TPM RC class | Condition | Maps to | Example `tpmRc` |
+|--------------|-----------|---------|-----------------|
+| 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` |
+| Other | everything else | `TPM_RC` | vendor-specific |
 
-Windows fleet smoke (elevated provision, then standard-user quote):
+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.
 
-```bash
-node node_modules/node-tpm2/examples/smoke-test.mjs provision-machine --key-name my-app-device-ak --out ak.blob.json
-node node_modules/node-tpm2/examples/smoke-test.mjs quote --in ak.blob.json
-```
+### Windows NCrypt HRESULT → `TpmError.code`
+
+PCP / NCrypt failures on Windows map through `classify_ncrypt` (`src/tbs/ncrypt.rs`):
+
+| HRESULT | Name | Typical code | Notes |
+|---------|------|--------------|-------|
+| `0x80090011` | `NTE_NOT_FOUND` | `KEY_NOT_FOUND` | Missing persisted key |
+| `0x80090016` | `NTE_BAD_KEYSET` | `KEY_NOT_FOUND` | Key set not found |
+| `0x8009000B` | `NTE_EXISTS` | `ALREADY_EXISTS` | Key name collision |
+| `0x80090027` | `NTE_INVALID_PARAMETER` | `INVALID_ARGUMENT` | Bad NCrypt parameter |
+| `0x80090030` | `NTE_DEVICE_NOT_READY` | `REQUIRES_ELEVATION` | Often privilege / readiness |
+| `0x80090010` | `NTE_PERM` | `REQUIRES_ELEVATION` | Permission |
+| `0x80090029` | `NTE_BAD_FLAGS` | `REQUIRES_ELEVATION` | Bad flags |
+| `0x8009000F` | `NTE_INTERNAL_ERROR` | `REQUIRES_ELEVATION` | Machine provision from standard user (observed) |
+| `0x80280084` | PCP activation / `TPM_RC_VALUE` | `REQUIRES_ELEVATION` | Standard user activation; elevated → `MARSHALLING_ERROR` |
+| `0x5` / `0x80070005` | Access denied | `REQUIRES_ELEVATION` or `ACCESS_DENIED` | Machine provision → elevation |
+| (other) | — | `MARSHALLING_ERROR` | Unmapped NCrypt failure |
 
-Use paths under `node_modules/node-tpm2/` after `npm install` (not `examples/` at the project root).
+**Transport** errors from `/dev/tpmrm0` or TBS that mention permission denied are promoted to `ACCESS_DENIED`; other I/O errors stay `TRANSPORT_ERROR`.
 
-## Platform support
+---
+
+## API reference (planned)
+
+Subsystem namespaces not yet on `TpmHandle`. See [docs/roadmap.md](./docs/roadmap.md) for phases and acceptance criteria.
+
+| Namespace | Methods |
+|-----------|---------|
+| `tpm.random` | `bytes(n)` ✅ |
+| `tpm.keys` | `create`, `load`, `KeyHandle.sign` ✅ · `decrypt` planned |
+| `tpm.pcr` | `extend(index, digest)` |
+| `tpm.seal` | `seal`, `unseal` |
+
+---
+
+## Platforms
 
 | Platform | Status | Attestation key |
 |----------|--------|-----------------|
-| Linux (glibc/musl, x64/arm64) | Supported | ECDSA P-256 TPM2B |
-| Windows (x64/arm64) | Supported | RSA-2048 PCP |
-| macOS | Not supported (`isAvailable()` → false) | — |
+| Linux x64/arm64 gnu/musl | Supported | ECDSA P-256 TPM2B |
+| Windows x64/arm64 | Supported | RSA-2048 PCP |
+| macOS | Unavailable | `isAvailable()` → `false` |
+
+---
 
-## Development
+## Contributing
 
 ```bash
 git clone https://github.com/stacks0x/tpm2.git && cd tpm2
 npm install && npm run build
+cargo test --lib
+npm run verify:package
 node examples/smoke-test.mjs runtime
 ```
 
-Rust probe for low-level validation (repo only, **not** published to npm):
+Docs: [getting-started.md](./docs/getting-started.md) · [windows-pcp.md](./docs/windows-pcp.md) · [roadmap.md](./docs/roadmap.md)
 
-```powershell
-cargo run --no-default-features --features probe-bin --bin tbs-probe -- all
-```
+Low-level Rust validation: `cargo run --no-default-features --features probe-bin --bin tbs-probe --` (repo only, not published to npm).
+
+---
 
 ## License
 

package/api.js

@@ -66,6 +66,38 @@ export class TpmError extends Error {
   }
 }
 
+function notSupported(feature) {
+  return async () => {
+    throw new TpmError('NOT_SUPPORTED', `${feature} is not implemented yet.`);
+  };
+}
+
+function createKeyHandle(publicKeyDer, keyBlob) {
+  return {
+    export() {
+      return {
+        public: Buffer.from(keyBlob.public),
+        private: Buffer.from(keyBlob.private),
+      };
+    },
+
+    get publicKeyDer() {
+      return Buffer.from(publicKeyDer);
+    },
+
+    sign: wrapNative(async (digest) => {
+      requireNative('signKeyBlob');
+      const sig = await native.signKeyBlob({
+        keyBlob,
+        digest,
+      });
+      return Buffer.from(sig);
+    }),
+
+    decrypt: notSupported('key.decrypt'),
+  };
+}
+
 function createAkHandle(akPublicDer, akBlob) {
   return {
     /** Wrapped TPM2B_PUBLIC + TPM2B_PRIVATE for persistence (no persistent TPM handle). */
@@ -114,6 +146,49 @@ function createTpmHandle() {
         requireNative('pcrRead');
         return native.pcrRead(selection, bank);
       }),
+
+      /** Extend a PCR digest in the SHA-256 bank. */
+      extend: wrapNative(async (index, digest) => {
+        requireNative('pcrExtend');
+        await native.pcrExtend(index, digest);
+      }),
+    },
+
+    random: {
+      /** Read `count` bytes from the TPM RNG (GetRandom). */
+      bytes: wrapNative(async (count) => {
+        requireNative('randomBytes');
+        const buf = await native.randomBytes(count);
+        return Buffer.from(buf);
+      }),
+    },
+
+    nv: {
+      read: notSupported('tpm.nv.read'),
+      write: notSupported('tpm.nv.write'),
+    },
+
+    keys: {
+      create: wrapNative(async (opts) => {
+        requireNative('createKey');
+        const result = await native.createKey({
+          keyType: opts?.type,
+          sign: opts?.sign,
+          decrypt: opts?.decrypt,
+        });
+        return createKeyHandle(result.publicKeyDer, result.keyBlob);
+      }),
+
+      load: wrapNative(async (blob) => {
+        requireNative('keyBlobPublicDer');
+        const publicKeyDer = await native.keyBlobPublicDer(blob);
+        return createKeyHandle(publicKeyDer, blob);
+      }),
+    },
+
+    seal: {
+      seal: notSupported('tpm.seal'),
+      unseal: notSupported('tpm.unseal'),
     },
 
     attest: {
@@ -202,12 +277,25 @@ export const Tpm = {
     return this.getFixedProperties();
   },
 
+  /** Flat: TPM RNG bytes (GetRandom). Prefer `tpm.random.bytes` on an open handle. */
+  randomBytes: wrapNative(async (count) => {
+    requireNative('randomBytes');
+    const buf = await native.randomBytes(count);
+    return Buffer.from(buf);
+  }),
+
   /** Flat native binding: PCR read. Prefer `tpm.pcr.read` on an open handle. */
   pcrRead: wrapNative(async (selection, bank) => {
     requireNative('pcrRead');
     return native.pcrRead(selection, bank);
   }),
 
+  /** Flat native binding: PCR extend. Prefer `tpm.pcr.extend` on an open handle. */
+  pcrExtend: wrapNative(async (index, digest) => {
+    requireNative('pcrExtend');
+    await native.pcrExtend(index, digest);
+  }),
+
   /** Flat native binding: ReadPublic. */
   readPublic: wrapNative(async (handle) => {
     requireNative('readPublic');
@@ -245,4 +333,23 @@ export const Tpm = {
     requireNative('activateCredential');
     return native.activateCredential(opts);
   }),
+
+  createKey: wrapNative(async (opts) => {
+    requireNative('createKey');
+    const result = await native.createKey({
+      keyType: opts?.type,
+      sign: opts?.sign,
+      decrypt: opts?.decrypt,
+    });
+    return {
+      publicKeyDer: result.publicKeyDer,
+      keyBlob: result.keyBlob,
+    };
+  }),
+
+  signKeyBlob: wrapNative(async (opts) => {
+    requireNative('signKeyBlob');
+    const sig = await native.signKeyBlob(opts);
+    return Buffer.from(sig);
+  }),
 };