@occ-core/stub 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @occ/stub public API
+ */
+export { StubHost } from "./stub-host.js";
+export type { StubHostOptions, PersistentStubHostOptions } from "./stub-host.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+/**
+ * @occ/stub public API
+ */
+export { StubHost } from "./stub-host.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/stub-host.d.ts

@@ -0,0 +1,119 @@
+/**
+ * @occ/stub — StubHost
+ *
+ * An in-process implementation of HostCapabilities for development and
+ * testing.  All TEE-specific operations are performed in software using
+ * Node.js built-ins and @noble/ed25519.
+ *
+ * SECURITY WARNING: This implementation provides NO security guarantees.
+ * Keys are held in process memory (or a plaintext JSON file for persistence),
+ * the counter is software-only, and there is no hardware-backed attestation.
+ *
+ * DO NOT use StubHost in production or in any security-sensitive context.
+ * Its sole purpose is to allow developers to run, test, and explore
+ * occ-core locally without a real TEE.
+ */
+import type { HostCapabilities } from "@occ/core";
+export interface StubHostOptions {
+    /**
+     * Ed25519 private key (32 bytes).
+     * If omitted, a fresh random key is generated.
+     * Providing a fixed key is useful for deterministic tests.
+     */
+    privateKey?: Uint8Array;
+    /**
+     * Measurement string returned by getMeasurement().
+     * Defaults to a fixed placeholder string.
+     */
+    measurement?: string;
+    /**
+     * Initial counter value. Defaults to 0.
+     */
+    initialCounter?: bigint;
+    /**
+     * If true, secureTime() is available and returns Date.now().
+     * Defaults to true.
+     */
+    enableTime?: boolean;
+    /**
+     * If true, nextCounter() is available.
+     * Defaults to true.
+     */
+    enableCounter?: boolean;
+}
+export interface PersistentStubHostOptions {
+    /**
+     * Path to a JSON file where identity and counter state is persisted.
+     * If the file does not exist, it is created with a fresh keypair and
+     * counter starting at 0.  If it exists, the stored key and counter
+     * are loaded and resumed.
+     */
+    statePath: string;
+    /**
+     * Measurement string returned by getMeasurement().
+     * Defaults to "stub:measurement:not-a-real-tee".
+     */
+    measurement?: string;
+    /**
+     * If true, secureTime() is available and returns Date.now().
+     * Defaults to true.
+     */
+    enableTime?: boolean;
+    /**
+     * If true, nextCounter() is available and persists across restarts.
+     * Defaults to true.
+     */
+    enableCounter?: boolean;
+}
+/**
+ * StubHost wraps a HostCapabilities object built from in-process crypto.
+ *
+ * Optional capabilities are conditionally attached to the plain object
+ * returned by `.host` — this avoids TypeScript exactOptionalPropertyTypes
+ * conflicts that arise when implementing optional interface methods as class
+ * fields that could be undefined.
+ */
+export declare class StubHost {
+    #private;
+    private constructor();
+    /**
+     * Record the hash of the last produced proof into persistent state.
+     * Call this after each successful commit when using persistent mode to
+     * enable automatic proof chaining across restarts.
+     */
+    setLastProofHash(hashB64: string): void;
+    /**
+     * Read the last proof hash from persistent state (for chaining).
+     * Returns undefined if no proof has been committed yet.
+     */
+    getLastProofHash(): string | undefined;
+    /**
+     * Create a StubHost with ephemeral (in-memory) state.
+     * Counter resets to 0 on every process restart.
+     * Async because key derivation is async in @noble/ed25519.
+     */
+    static create(opts?: StubHostOptions): Promise<StubHost>;
+    /**
+     * Create a StubHost that persists identity and counter to a JSON file.
+     *
+     * On first call: generates a fresh keypair and writes it to `statePath`.
+     * On subsequent calls: loads the existing keypair and counter and resumes.
+     *
+     * This lets a local demo service maintain a stable identity and
+     * monotonically increasing counter across restarts.
+     *
+     * The state file is plaintext JSON — not for production use.
+     */
+    static createPersistent(opts: PersistentStubHostOptions): Promise<StubHost>;
+    /**
+     * Return the HostCapabilities object to pass to Constructor.initialize().
+     */
+    get host(): HostCapabilities;
+    /** Return the raw private key bytes (test use only). */
+    get privateKeyBytes(): Uint8Array;
+    /** Return the raw public key bytes. */
+    get publicKeyBytes(): Uint8Array;
+    /** Return the current counter value without advancing it. */
+    get currentCounter(): bigint;
+}
+//# sourceMappingURL=stub-host.d.ts.map

package/dist/stub-host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-host.d.ts","sourceRoot":"","sources":["../src/stub-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAMlD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IAExB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAMD,MAAM,WAAW,yBAAyB;IACxC;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAmBD;;;;;;;GAOG;AACH,qBAAa,QAAQ;;IAQnB,OAAO;IAoDP;;;;OAIG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAevC;;;OAGG;IACH,gBAAgB,IAAI,MAAM,GAAG,SAAS;IActC;;;;OAIG;WACU,MAAM,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAkBlE;;;;;;;;;;OAUG;WACU,gBAAgB,CAAC,IAAI,EAAE,yBAAyB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAmDjF;;OAEG;IACH,IAAI,IAAI,IAAI,gBAAgB,CAE3B;IAED,wDAAwD;IACxD,IAAI,eAAe,IAAI,UAAU,CAEhC;IAED,uCAAuC;IACvC,IAAI,cAAc,IAAI,UAAU,CAE/B;IAED,6DAA6D;IAC7D,IAAI,cAAc,IAAI,MAAM,CAE3B;CACF"}

package/dist/stub-host.js

@@ -0,0 +1,212 @@
+/**
+ * @occ/stub — StubHost
+ *
+ * An in-process implementation of HostCapabilities for development and
+ * testing.  All TEE-specific operations are performed in software using
+ * Node.js built-ins and @noble/ed25519.
+ *
+ * SECURITY WARNING: This implementation provides NO security guarantees.
+ * Keys are held in process memory (or a plaintext JSON file for persistence),
+ * the counter is software-only, and there is no hardware-backed attestation.
+ *
+ * DO NOT use StubHost in production or in any security-sensitive context.
+ * Its sole purpose is to allow developers to run, test, and explore
+ * occ-core locally without a real TEE.
+ */
+import { getPublicKeyAsync, signAsync, utils } from "@noble/ed25519";
+import { randomBytes } from "crypto";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+// ---------------------------------------------------------------------------
+// StubHost
+// ---------------------------------------------------------------------------
+/**
+ * StubHost wraps a HostCapabilities object built from in-process crypto.
+ *
+ * Optional capabilities are conditionally attached to the plain object
+ * returned by `.host` — this avoids TypeScript exactOptionalPropertyTypes
+ * conflicts that arise when implementing optional interface methods as class
+ * fields that could be undefined.
+ */
+export class StubHost {
+    #host;
+    #privateKey;
+    #publicKey;
+    #measurement;
+    #counter;
+    #statePath;
+    constructor(privateKey, publicKey, opts, statePath) {
+        this.#privateKey = privateKey;
+        this.#publicKey = publicKey;
+        this.#measurement = opts.measurement;
+        this.#counter = opts.initialCounter;
+        this.#statePath = statePath;
+        // Build the base host with required capabilities
+        const base = {
+            enforcementTier: "stub",
+            getMeasurement: async () => this.#measurement,
+            getFreshNonce: async () => new Uint8Array(randomBytes(32)),
+            sign: async (data) => signAsync(data, this.#privateKey),
+            getPublicKey: async () => this.#publicKey,
+        };
+        // Conditionally attach optional capabilities
+        if (opts.enableCounter) {
+            base.nextCounter = async () => {
+                this.#counter += 1n;
+                if (this.#statePath !== undefined) {
+                    this.#persistState();
+                }
+                return String(this.#counter);
+            };
+        }
+        if (opts.enableTime) {
+            base.secureTime = async () => Date.now();
+        }
+        this.#host = base;
+    }
+    // ---------------------------------------------------------------------------
+    // Persistence helpers
+    // ---------------------------------------------------------------------------
+    #persistState() {
+        if (this.#statePath === undefined)
+            return;
+        const state = {
+            privateKeyB64: Buffer.from(this.#privateKey).toString("base64"),
+            counter: String(this.#counter),
+        };
+        writeFileSync(this.#statePath, JSON.stringify(state, null, 2), "utf8");
+    }
+    /**
+     * Record the hash of the last produced proof into persistent state.
+     * Call this after each successful commit when using persistent mode to
+     * enable automatic proof chaining across restarts.
+     */
+    setLastProofHash(hashB64) {
+        if (this.#statePath === undefined)
+            return;
+        let existing;
+        try {
+            existing = JSON.parse(readFileSync(this.#statePath, "utf8"));
+        }
+        catch {
+            existing = {
+                privateKeyB64: Buffer.from(this.#privateKey).toString("base64"),
+                counter: String(this.#counter),
+            };
+        }
+        existing.lastProofHashB64 = hashB64;
+        writeFileSync(this.#statePath, JSON.stringify(existing, null, 2), "utf8");
+    }
+    /**
+     * Read the last proof hash from persistent state (for chaining).
+     * Returns undefined if no proof has been committed yet.
+     */
+    getLastProofHash() {
+        if (this.#statePath === undefined)
+            return undefined;
+        try {
+            const raw = JSON.parse(readFileSync(this.#statePath, "utf8"));
+            return raw.lastProofHashB64;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Factory methods
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a StubHost with ephemeral (in-memory) state.
+     * Counter resets to 0 on every process restart.
+     * Async because key derivation is async in @noble/ed25519.
+     */
+    static async create(opts = {}) {
+        const privateKey = opts.privateKey ?? utils.randomPrivateKey();
+        if (privateKey.length !== 32) {
+            throw new RangeError("StubHost: privateKey must be 32 bytes");
+        }
+        const publicKey = await getPublicKeyAsync(privateKey);
+        const resolved = {
+            privateKey,
+            measurement: opts.measurement ?? "stub:measurement:not-a-real-tee",
+            initialCounter: opts.initialCounter ?? 0n,
+            enableTime: opts.enableTime ?? true,
+            enableCounter: opts.enableCounter ?? true,
+        };
+        return new StubHost(privateKey, publicKey, resolved);
+    }
+    /**
+     * Create a StubHost that persists identity and counter to a JSON file.
+     *
+     * On first call: generates a fresh keypair and writes it to `statePath`.
+     * On subsequent calls: loads the existing keypair and counter and resumes.
+     *
+     * This lets a local demo service maintain a stable identity and
+     * monotonically increasing counter across restarts.
+     *
+     * The state file is plaintext JSON — not for production use.
+     */
+    static async createPersistent(opts) {
+        const { statePath, measurement, enableTime, enableCounter } = opts;
+        let privateKey;
+        let initialCounter;
+        // Try to load existing state
+        let existingState;
+        try {
+            existingState = JSON.parse(readFileSync(statePath, "utf8"));
+        }
+        catch {
+            // File doesn't exist or is corrupt — start fresh
+        }
+        if (existingState !== undefined) {
+            privateKey = new Uint8Array(Buffer.from(existingState.privateKeyB64, "base64"));
+            initialCounter = BigInt(existingState.counter);
+        }
+        else {
+            // First run — generate a fresh key
+            privateKey = utils.randomPrivateKey();
+            initialCounter = 0n;
+            // Ensure the directory exists
+            mkdirSync(dirname(statePath), { recursive: true });
+            const initialState = {
+                privateKeyB64: Buffer.from(privateKey).toString("base64"),
+                counter: String(initialCounter),
+            };
+            writeFileSync(statePath, JSON.stringify(initialState, null, 2), "utf8");
+        }
+        if (privateKey.length !== 32) {
+            throw new RangeError("StubHost.createPersistent: loaded key is not 32 bytes");
+        }
+        const publicKey = await getPublicKeyAsync(privateKey);
+        const resolved = {
+            privateKey,
+            measurement: measurement ?? "stub:measurement:not-a-real-tee",
+            initialCounter,
+            enableTime: enableTime ?? true,
+            enableCounter: enableCounter ?? true,
+        };
+        return new StubHost(privateKey, publicKey, resolved, statePath);
+    }
+    // ---------------------------------------------------------------------------
+    // Accessors
+    // ---------------------------------------------------------------------------
+    /**
+     * Return the HostCapabilities object to pass to Constructor.initialize().
+     */
+    get host() {
+        return this.#host;
+    }
+    /** Return the raw private key bytes (test use only). */
+    get privateKeyBytes() {
+        return this.#privateKey;
+    }
+    /** Return the raw public key bytes. */
+    get publicKeyBytes() {
+        return this.#publicKey;
+    }
+    /** Return the current counter value without advancing it. */
+    get currentCounter() {
+        return this.#counter;
+    }
+}
+//# sourceMappingURL=stub-host.js.map

package/dist/stub-host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub-host.js","sourceRoot":"","sources":["../src/stub-host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAoF/B,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E;;;;;;;GAOG;AACH,MAAM,OAAO,QAAQ;IACV,KAAK,CAAmB;IACxB,WAAW,CAAa;IACxB,UAAU,CAAa;IACvB,YAAY,CAAS;IAC9B,QAAQ,CAAS;IACR,UAAU,CAAqB;IAExC,YACE,UAAsB,EACtB,SAAqB,EACrB,IAA+B,EAC/B,SAAkB;QAElB,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC;QAC9B,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAC5B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC;QACrC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,cAAc,CAAC;QACpC,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;QAE5B,iDAAiD;QACjD,MAAM,IAAI,GAAqB;YAC7B,eAAe,EAAE,MAAM;YACvB,cAAc,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,YAAY;YAC7C,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;YAC1D,IAAI,EAAE,KAAK,EAAE,IAAgB,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC;YACnE,YAAY,EAAE,KAAK,IAAI,EAAE,CAAC,IAAI,CAAC,UAAU;SAC1C,CAAC;QAEF,6CAA6C;QAC7C,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACvB,IAAI,CAAC,WAAW,GAAG,KAAK,IAAqB,EAAE;gBAC7C,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;gBACpB,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;oBAClC,IAAI,CAAC,aAAa,EAAE,CAAC;gBACvB,CAAC;gBACD,OAAO,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC/B,CAAC,CAAC;QACJ,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,IAAI,CAAC,UAAU,GAAG,KAAK,IAAqB,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC;QAC5D,CAAC;QAED,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;IAED,8EAA8E;IAC9E,sBAAsB;IACtB,8EAA8E;IAE9E,aAAa;QACX,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO;QAC1C,MAAM,KAAK,GAAmB;YAC5B,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAC/D,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;SAC/B,CAAC;QACF,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IACzE,CAAC;IAED;;;;OAIG;IACH,gBAAgB,CAAC,OAAe;QAC9B,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO;QAC1C,IAAI,QAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAmB,CAAC;QACjF,CAAC;QAAC,MAAM,CAAC;YACP,QAAQ,GAAG;gBACT,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBAC/D,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC;aAC/B,CAAC;QACJ,CAAC;QACD,QAAQ,CAAC,gBAAgB,GAAG,OAAO,CAAC;QACpC,aAAa,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAC5E,CAAC;IAED;;;OAGG;IACH,gBAAgB;QACd,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAmB,CAAC;YAChF,OAAO,GAAG,CAAC,gBAAgB,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;;OAIG;IACH,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,OAAwB,EAAE;QAC5C,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QAC/D,IAAI,UAAU,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,UAAU,CAAC,uCAAuC,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAEtD,MAAM,QAAQ,GAA8B;YAC1C,UAAU;YACV,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,iCAAiC;YAClE,cAAc,EAAE,IAAI,CAAC,cAAc,IAAI,EAAE;YACzC,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI;YACnC,aAAa,EAAE,IAAI,CAAC,aAAa,IAAI,IAAI;SAC1C,CAAC;QAEF,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;OAUG;IACH,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAAC,IAA+B;QAC3D,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,GAAG,IAAI,CAAC;QAEnE,IAAI,UAAsB,CAAC;QAC3B,IAAI,cAAsB,CAAC;QAE3B,6BAA6B;QAC7B,IAAI,aAAyC,CAAC;QAC9C,IAAI,CAAC;YACH,aAAa,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAmB,CAAC;QAChF,CAAC;QAAC,MAAM,CAAC;YACP,iDAAiD;QACnD,CAAC;QAED,IAAI,aAAa,KAAK,SAAS,EAAE,CAAC;YAChC,UAAU,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC,CAAC;YAChF,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,mCAAmC;YACnC,UAAU,GAAG,KAAK,CAAC,gBAAgB,EAAE,CAAC;YACtC,cAAc,GAAG,EAAE,CAAC;YACpB,8BAA8B;YAC9B,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,YAAY,GAAmB;gBACnC,aAAa,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;gBACzD,OAAO,EAAE,MAAM,CAAC,cAAc,CAAC;aAChC,CAAC;YACF,aAAa,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;QAC1E,CAAC;QAED,IAAI,UAAU,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;YAC7B,MAAM,IAAI,UAAU,CAAC,uDAAuD,CAAC,CAAC;QAChF,CAAC;QAED,MAAM,SAAS,GAAG,MAAM,iBAAiB,CAAC,UAAU,CAAC,CAAC;QAEtD,MAAM,QAAQ,GAA8B;YAC1C,UAAU;YACV,WAAW,EAAE,WAAW,IAAI,iCAAiC;YAC7D,cAAc;YACd,UAAU,EAAE,UAAU,IAAI,IAAI;YAC9B,aAAa,EAAE,aAAa,IAAI,IAAI;SACrC,CAAC;QAEF,OAAO,IAAI,QAAQ,CAAC,UAAU,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC;IAClE,CAAC;IAED,8EAA8E;IAC9E,YAAY;IACZ,8EAA8E;IAE9E;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,wDAAwD;IACxD,IAAI,eAAe;QACjB,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,uCAAuC;IACvC,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED,6DAA6D;IAC7D,IAAI,cAAc;QAChB,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;CACF"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@occ-core/stub",
+  "version": "0.1.0",
+  "description": "In-process HostCapabilities stub for occ-core — development and testing only",
+  "keywords": [
+    "occ",
+    "origin-controlled-computing",
+    "tee",
+    "stub",
+    "dev",
+    "ed25519",
+    "tamper-evident"
+  ],
+  "author": "Mike Argento",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mikeargento/occ-core.git",
+    "directory": "packages/occ-core-stub"
+  },
+  "homepage": "https://github.com/mikeargento/occ-core#readme",
+  "bugs": {
+    "url": "https://github.com/mikeargento/occ-core/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/__tests__",
+    "src",
+    "!src/__tests__"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test dist/__tests__/*.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.1.0",
+    "@occ-core/core": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+/**
+ * @occ/stub public API
+ */
+export { StubHost } from "./stub-host.js";
+export type { StubHostOptions, PersistentStubHostOptions } from "./stub-host.js";

package/src/stub-host.ts

@@ -0,0 +1,320 @@
+/**
+ * @occ/stub — StubHost
+ *
+ * An in-process implementation of HostCapabilities for development and
+ * testing.  All TEE-specific operations are performed in software using
+ * Node.js built-ins and @noble/ed25519.
+ *
+ * SECURITY WARNING: This implementation provides NO security guarantees.
+ * Keys are held in process memory (or a plaintext JSON file for persistence),
+ * the counter is software-only, and there is no hardware-backed attestation.
+ *
+ * DO NOT use StubHost in production or in any security-sensitive context.
+ * Its sole purpose is to allow developers to run, test, and explore
+ * occ-core locally without a real TEE.
+ */
+
+import { getPublicKeyAsync, signAsync, utils } from "@noble/ed25519";
+import { randomBytes } from "crypto";
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { dirname } from "path";
+import type { HostCapabilities } from "@occ/core";
+
+// ---------------------------------------------------------------------------
+// StubHost options
+// ---------------------------------------------------------------------------
+
+export interface StubHostOptions {
+  /**
+   * Ed25519 private key (32 bytes).
+   * If omitted, a fresh random key is generated.
+   * Providing a fixed key is useful for deterministic tests.
+   */
+  privateKey?: Uint8Array;
+
+  /**
+   * Measurement string returned by getMeasurement().
+   * Defaults to a fixed placeholder string.
+   */
+  measurement?: string;
+
+  /**
+   * Initial counter value. Defaults to 0.
+   */
+  initialCounter?: bigint;
+
+  /**
+   * If true, secureTime() is available and returns Date.now().
+   * Defaults to true.
+   */
+  enableTime?: boolean;
+
+  /**
+   * If true, nextCounter() is available.
+   * Defaults to true.
+   */
+  enableCounter?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Persistent StubHost options
+// ---------------------------------------------------------------------------
+
+export interface PersistentStubHostOptions {
+  /**
+   * Path to a JSON file where identity and counter state is persisted.
+   * If the file does not exist, it is created with a fresh keypair and
+   * counter starting at 0.  If it exists, the stored key and counter
+   * are loaded and resumed.
+   */
+  statePath: string;
+
+  /**
+   * Measurement string returned by getMeasurement().
+   * Defaults to "stub:measurement:not-a-real-tee".
+   */
+  measurement?: string;
+
+  /**
+   * If true, secureTime() is available and returns Date.now().
+   * Defaults to true.
+   */
+  enableTime?: boolean;
+
+  /**
+   * If true, nextCounter() is available and persists across restarts.
+   * Defaults to true.
+   */
+  enableCounter?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Persisted state shape (written as JSON)
+// ---------------------------------------------------------------------------
+
+interface PersistedState {
+  /** Base64-encoded Ed25519 private key (32 bytes). */
+  privateKeyB64: string;
+  /** Current counter value as a decimal string (survives BigInt round-trip). */
+  counter: string;
+  /** Base64 of the last proof's canonical hash — populated by the service layer. */
+  lastProofHashB64?: string;
+}
+
+// ---------------------------------------------------------------------------
+// StubHost
+// ---------------------------------------------------------------------------
+
+/**
+ * StubHost wraps a HostCapabilities object built from in-process crypto.
+ *
+ * Optional capabilities are conditionally attached to the plain object
+ * returned by `.host` — this avoids TypeScript exactOptionalPropertyTypes
+ * conflicts that arise when implementing optional interface methods as class
+ * fields that could be undefined.
+ */
+export class StubHost {
+  readonly #host: HostCapabilities;
+  readonly #privateKey: Uint8Array;
+  readonly #publicKey: Uint8Array;
+  readonly #measurement: string;
+  #counter: bigint;
+  readonly #statePath: string | undefined;
+
+  private constructor(
+    privateKey: Uint8Array,
+    publicKey: Uint8Array,
+    opts: Required<StubHostOptions>,
+    statePath?: string
+  ) {
+    this.#privateKey = privateKey;
+    this.#publicKey = publicKey;
+    this.#measurement = opts.measurement;
+    this.#counter = opts.initialCounter;
+    this.#statePath = statePath;
+
+    // Build the base host with required capabilities
+    const base: HostCapabilities = {
+      enforcementTier: "stub",
+      getMeasurement: async () => this.#measurement,
+      getFreshNonce: async () => new Uint8Array(randomBytes(32)),
+      sign: async (data: Uint8Array) => signAsync(data, this.#privateKey),
+      getPublicKey: async () => this.#publicKey,
+    };
+
+    // Conditionally attach optional capabilities
+    if (opts.enableCounter) {
+      base.nextCounter = async (): Promise<string> => {
+        this.#counter += 1n;
+        if (this.#statePath !== undefined) {
+          this.#persistState();
+        }
+        return String(this.#counter);
+      };
+    }
+
+    if (opts.enableTime) {
+      base.secureTime = async (): Promise<number> => Date.now();
+    }
+
+    this.#host = base;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Persistence helpers
+  // ---------------------------------------------------------------------------
+
+  #persistState(): void {
+    if (this.#statePath === undefined) return;
+    const state: PersistedState = {
+      privateKeyB64: Buffer.from(this.#privateKey).toString("base64"),
+      counter: String(this.#counter),
+    };
+    writeFileSync(this.#statePath, JSON.stringify(state, null, 2), "utf8");
+  }
+
+  /**
+   * Record the hash of the last produced proof into persistent state.
+   * Call this after each successful commit when using persistent mode to
+   * enable automatic proof chaining across restarts.
+   */
+  setLastProofHash(hashB64: string): void {
+    if (this.#statePath === undefined) return;
+    let existing: PersistedState;
+    try {
+      existing = JSON.parse(readFileSync(this.#statePath, "utf8")) as PersistedState;
+    } catch {
+      existing = {
+        privateKeyB64: Buffer.from(this.#privateKey).toString("base64"),
+        counter: String(this.#counter),
+      };
+    }
+    existing.lastProofHashB64 = hashB64;
+    writeFileSync(this.#statePath, JSON.stringify(existing, null, 2), "utf8");
+  }
+
+  /**
+   * Read the last proof hash from persistent state (for chaining).
+   * Returns undefined if no proof has been committed yet.
+   */
+  getLastProofHash(): string | undefined {
+    if (this.#statePath === undefined) return undefined;
+    try {
+      const raw = JSON.parse(readFileSync(this.#statePath, "utf8")) as PersistedState;
+      return raw.lastProofHashB64;
+    } catch {
+      return undefined;
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Factory methods
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Create a StubHost with ephemeral (in-memory) state.
+   * Counter resets to 0 on every process restart.
+   * Async because key derivation is async in @noble/ed25519.
+   */
+  static async create(opts: StubHostOptions = {}): Promise<StubHost> {
+    const privateKey = opts.privateKey ?? utils.randomPrivateKey();
+    if (privateKey.length !== 32) {
+      throw new RangeError("StubHost: privateKey must be 32 bytes");
+    }
+    const publicKey = await getPublicKeyAsync(privateKey);
+
+    const resolved: Required<StubHostOptions> = {
+      privateKey,
+      measurement: opts.measurement ?? "stub:measurement:not-a-real-tee",
+      initialCounter: opts.initialCounter ?? 0n,
+      enableTime: opts.enableTime ?? true,
+      enableCounter: opts.enableCounter ?? true,
+    };
+
+    return new StubHost(privateKey, publicKey, resolved);
+  }
+
+  /**
+   * Create a StubHost that persists identity and counter to a JSON file.
+   *
+   * On first call: generates a fresh keypair and writes it to `statePath`.
+   * On subsequent calls: loads the existing keypair and counter and resumes.
+   *
+   * This lets a local demo service maintain a stable identity and
+   * monotonically increasing counter across restarts.
+   *
+   * The state file is plaintext JSON — not for production use.
+   */
+  static async createPersistent(opts: PersistentStubHostOptions): Promise<StubHost> {
+    const { statePath, measurement, enableTime, enableCounter } = opts;
+
+    let privateKey: Uint8Array;
+    let initialCounter: bigint;
+
+    // Try to load existing state
+    let existingState: PersistedState | undefined;
+    try {
+      existingState = JSON.parse(readFileSync(statePath, "utf8")) as PersistedState;
+    } catch {
+      // File doesn't exist or is corrupt — start fresh
+    }
+
+    if (existingState !== undefined) {
+      privateKey = new Uint8Array(Buffer.from(existingState.privateKeyB64, "base64"));
+      initialCounter = BigInt(existingState.counter);
+    } else {
+      // First run — generate a fresh key
+      privateKey = utils.randomPrivateKey();
+      initialCounter = 0n;
+      // Ensure the directory exists
+      mkdirSync(dirname(statePath), { recursive: true });
+      const initialState: PersistedState = {
+        privateKeyB64: Buffer.from(privateKey).toString("base64"),
+        counter: String(initialCounter),
+      };
+      writeFileSync(statePath, JSON.stringify(initialState, null, 2), "utf8");
+    }
+
+    if (privateKey.length !== 32) {
+      throw new RangeError("StubHost.createPersistent: loaded key is not 32 bytes");
+    }
+
+    const publicKey = await getPublicKeyAsync(privateKey);
+
+    const resolved: Required<StubHostOptions> = {
+      privateKey,
+      measurement: measurement ?? "stub:measurement:not-a-real-tee",
+      initialCounter,
+      enableTime: enableTime ?? true,
+      enableCounter: enableCounter ?? true,
+    };
+
+    return new StubHost(privateKey, publicKey, resolved, statePath);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Accessors
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Return the HostCapabilities object to pass to Constructor.initialize().
+   */
+  get host(): HostCapabilities {
+    return this.#host;
+  }
+
+  /** Return the raw private key bytes (test use only). */
+  get privateKeyBytes(): Uint8Array {
+    return this.#privateKey;
+  }
+
+  /** Return the raw public key bytes. */
+  get publicKeyBytes(): Uint8Array {
+    return this.#publicKey;
+  }
+
+  /** Return the current counter value without advancing it. */
+  get currentCounter(): bigint {
+    return this.#counter;
+  }
+}