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

package/docs/getting-started.md

@@ -114,6 +114,15 @@ try {
 }
 ```
 
+## Validate after install
+
+```bash
+npm ls node-tpm2
+node node_modules/node-tpm2/examples/smoke-test.mjs runtime
+```
+
+Smoke-test is under `node_modules/node-tpm2/examples/` after `npm install`, not `./examples/` at your project root.
+
 ## What ships in npm
 
 The published package contains the JavaScript API, type definitions, user docs, and the smoke-test example — **not** Rust sources, `tbs-probe`, or spike binaries. Those stay in the git repo for developers.

package/docs/roadmap.md

@@ -0,0 +1,220 @@
+# 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.4-beta)
+
+**Shipped**
+
+| Namespace | Methods |
+|-----------|---------|
+| Root | `Tpm.isAvailable()`, `Tpm.open()`, `Tpm.info()` |
+| `tpm.pcr` | `read`, `extend` |
+| `tpm.attest` | `provisionAk`, `quote`, `ekCertificate` |
+| `AkHandle` | `export`, `quote`, `activateCredential`, `publicKeyDer` |
+| Flat | `Tpm.pcrRead`, `Tpm.pcrExtend`, `readPublic`, `readEkCertificate`, `quote`, `provisionAk`, `activateCredential` |
+
+**Rust foundation already present (not exposed on `TpmHandle` yet):**
+
+- Command codec: `CreatePrimary`, `Create`, `Load`, `FlushContext`, `Quote`, `GetRandom`, sessions, policy digest
+- Linux key path: `keys.rs` (storage primary, AK create/load)
+- Windows PCP path: `pcp.rs` (identity AK, machine DACL, quote, activation)
+- NV: EK certificate read via fixed index
+- Credential: full activate-credential flow (Linux TBS; Windows PCP)
+
+---
+
+## 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` ✅ (this branch; decrypt deferred)
+
+**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
+- [ ] `key.decrypt` — RSA OAEP (deferred)
+- [ ] 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.
+- [ ] Acceptance: works unprivileged on swtpm and dev VM where PCRs are extendable.
+
+### Phase 4 — `tpm.nv` (1 week)
+
+**Goal:** General NV index access beyond EK cert helper.
+
+- Rust:
+  - `nv.read_public(handle)` — already partially in `nv.rs`; expose metadata (size, attributes).
+  - `nv.read(handle, offset, size)`.
+  - `nv.write(handle, offset, data, auth?)` — auth optional buffer for password/session auth.
+  - `nv.define` / `nv.undefine` — **defer** unless needed (owner-auth, high privilege).
+- Migrate `readEkCertificate` to call `nv.read` on well-known EK cert index internally.
+- JS: `tpm.nv.read`, `tpm.nv.write`; document which indices are safe on consumer hardware.
+- Acceptance: EK cert read unchanged; optional integration test against swtpm-defined NV index.
+
+### Phase 5 — `tpm.seal` / `tpm.unseal` (1–2 weeks)
+
+**Goal:** TPM-bound secrets with optional PCR policy.
+
+- Rust:
+  - `seal({ data, pcrSelection?, name? })` — create storage primary or use fixed template, `Create` sealed object, export blob.
+  - `unseal(blob)` — load + `Unseal`.
+  - PCR policy: `PolicyPCR` session when `pcrSelection` provided.
+- JS: `tpm.seal`, `tpm.unseal`; flat aliases.
+- Tests: roundtrip without PCR; roundtrip with PCR extend before unseal; negative test wrong PCR.
+- Acceptance: Linux + Windows TBS; document that PCR-bound seal requires extend permission on chosen indices.
+
+### 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. beta.4 = random + keys).
+- `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

@@ -23,6 +23,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/smoke-test.mjs

@@ -127,8 +127,8 @@ async function runProvisionMachine(args) {
   saveBlob(out, akBlob);
   console.log(`PASS  Tpm.provisionAk(machine) keyName=${keyName} SPKI=${akPublicDer.length}B`);
   console.log(`  wrote ${out}`);
-  console.log('\nNEXT (standard user):');
-  console.log(`  node examples/smoke-test.mjs quote --in ${out}`);
+  console.log('\nNEXT (standard user, from your project directory):');
+  console.log(`  node node_modules/node-tpm2/examples/smoke-test.mjs quote --in ${out}`);
 }
 
 async function runQuote(args) {
@@ -172,7 +172,9 @@ async function main() {
 
 main().catch((err) => {
   console.error('FAIL:', err.message ?? err);
+  if (err.code) console.error('  code:', err.code);
   if (err.suggestion) console.error('  suggestion:', err.suggestion);
   if (err.tpmRc != null) console.error('  tpmRc:', err.tpmRc);
+  if (err.hresult != null) console.error('  hresult:', err.hresult);
   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,19 @@ export declare type ActivateCredentialFlatOptions = ActivateCredentialOptions &
   akBlob: AkBlob;
 };
 
+/** General device key creation options. */
+export declare type KeyCreateOptions = {
+  type: 'ecc' | 'rsa';
+  sign?: boolean;
+  decrypt?: boolean;
+};
+
+/** @throws {TpmError} NOT_SUPPORTED until Phase 5 */
+export declare type SealOptions = {
+  data: Buffer;
+  pcrSelection?: number[];
+};
+
 export declare interface AkHandle {
   export(): AkBlob;
   readonly publicKeyDer: Buffer;
@@ -81,6 +97,13 @@ export declare interface AkHandle {
   activateCredential(opts: ActivateCredentialOptions): Promise<Buffer>;
 }
 
+/** @throws {TpmError} NOT_SUPPORTED until RSA decrypt is implemented */
+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 +115,26 @@ 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: {
+    /** @throws {TpmError} NOT_SUPPORTED until Phase 4 */
+    read(handle: string, offset?: number, size?: number): Promise<Buffer>;
+    /** @throws {TpmError} NOT_SUPPORTED until Phase 4 */
+    write(handle: string, data: Buffer, offset?: number): Promise<void>;
+  };
+  keys: {
+    create(opts: KeyCreateOptions): Promise<KeyHandle>;
+    load(blob: KeyBlob): Promise<KeyHandle>;
+  };
+  seal: {
+    /** @throws {TpmError} NOT_SUPPORTED until Phase 5 */
+    seal(opts: SealOptions): Promise<Buffer>;
+    /** @throws {TpmError} NOT_SUPPORTED until Phase 5 */
+    unseal(blob: Buffer): Promise<Buffer>;
   };
   attest: {
     ekCertificate(): Promise<Buffer | null>;
@@ -107,33 +150,14 @@ 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>;
 };
-
-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>;