@totemsdk/omnia-host 0.9.0 → 0.11.0

package/dist/pairing.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * RFC-062 — local node/extension pairing MVP.
+ *
+ * A loopback HTTP service issues one-time pairing codes, verifies the extension
+ * origin, binds a device key and returns a scoped bearer token plus the node
+ * identity/fingerprint and advertised capabilities (chain RPC, P2P hub, lease).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPairingService = createPairingService;
+exports.createPairingHttpServer = createPairingHttpServer;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_http_1 = __importDefault(require("node:http"));
+const node_path_1 = __importDefault(require("node:path"));
+function sha256(value) {
+    return node_crypto_1.default.createHash('sha256').update(value).digest('hex');
+}
+function loadStore(storePath) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(storePath, 'utf8'));
+        if (parsed.identity?.publicKey && parsed.identity?.privateKey) {
+            return { identity: parsed.identity, clients: parsed.clients ?? {} };
+        }
+    }
+    catch {
+        // Create a new identity below.
+    }
+    const pair = node_crypto_1.default.generateKeyPairSync('ed25519');
+    const identity = {
+        publicKey: pair.publicKey.export({ type: 'spki', format: 'der' }).toString('base64'),
+        privateKey: pair.privateKey.export({ type: 'pkcs8', format: 'der' }).toString('base64'),
+        createdAt: Date.now(),
+    };
+    const store = { identity, clients: {} };
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(storePath), { recursive: true });
+    node_fs_1.default.writeFileSync(storePath, JSON.stringify(store, null, 2), { mode: 0o600 });
+    return store;
+}
+function createPairingService(options) {
+    const now = options.now ?? (() => Date.now());
+    const ttlMs = options.ttlMs ?? 5 * 60_000;
+    const endpoint = options.endpoint ?? 'http://127.0.0.1:7789';
+    const network = options.network ?? 'minima';
+    const scopes = options.scopes ?? ['chain.read', 'chain.submit', 'p2p.pubsub'];
+    const capabilities = options.capabilities ?? {};
+    const store = loadStore(options.storePath);
+    const sessions = new Map();
+    const publicKeyBytes = Buffer.from(store.identity.publicKey, 'base64');
+    const fingerprint = sha256(publicKeyBytes);
+    const nodeId = fingerprint.slice(0, 16);
+    const persist = () => {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(options.storePath), { recursive: true });
+        node_fs_1.default.writeFileSync(options.storePath, JSON.stringify(store, null, 2), { mode: 0o600 });
+    };
+    const allowsOrigin = (origin) => {
+        if (!origin)
+            return true;
+        if (!options.allowedOrigins || options.allowedOrigins.length === 0)
+            return true;
+        return options.allowedOrigins.includes(origin);
+    };
+    const baseInfo = () => ({
+        nodeId,
+        fingerprint,
+        network,
+        scopes,
+        capabilities,
+    });
+    return {
+        nodeId,
+        fingerprint,
+        network,
+        scopes,
+        capabilities,
+        createInvitation() {
+            const code = node_crypto_1.default.randomBytes(18).toString('base64url');
+            const hash = sha256(code);
+            const expiresAt = now() + ttlMs;
+            sessions.set(hash, { hash, expiresAt, attempts: 0 });
+            // Opportunistic cleanup; expired sessions cannot be completed.
+            for (const [key, session] of sessions) {
+                if (session.expiresAt <= now())
+                    sessions.delete(key);
+            }
+            return { endpoint, code, ...baseInfo(), expiresAt };
+        },
+        info(code) {
+            const session = sessions.get(sha256(code));
+            if (!session || session.expiresAt <= now())
+                throw new Error('Invalid or expired pairing code');
+            return { ...baseInfo(), expiresAt: session.expiresAt };
+        },
+        complete({ code, devicePublicKey, origin, scopes: requested }) {
+            const hash = sha256(code);
+            const session = sessions.get(hash);
+            if (!session || session.expiresAt <= now())
+                throw new Error('Invalid or expired pairing code');
+            if (!allowsOrigin(origin))
+                throw new Error('Origin not allowed for pairing');
+            const granted = requested ?? scopes;
+            if (granted.some((scope) => !scopes.includes(scope)))
+                throw new Error('Requested scope is not offered');
+            const token = node_crypto_1.default.randomBytes(32).toString('base64url');
+            const clientId = `pair-${node_crypto_1.default.randomBytes(8).toString('hex')}`;
+            store.clients[clientId] = {
+                clientId,
+                origin,
+                devicePublicKey,
+                scopes: granted,
+                tokenHash: sha256(token),
+                createdAt: now(),
+                lastUsedAt: now(),
+            };
+            persist();
+            sessions.delete(hash);
+            return {
+                token,
+                clientId,
+                node: { nodeId, fingerprint, network },
+                capabilities,
+            };
+        },
+        identity() {
+            return {
+                nodeId,
+                fingerprint,
+                publicKey: store.identity.publicKey,
+                network,
+                capabilities,
+            };
+        },
+        listClients() {
+            return Object.values(store.clients);
+        },
+        revoke(clientId) {
+            const client = store.clients[clientId];
+            if (!client)
+                return false;
+            client.revokedAt = now();
+            persist();
+            return true;
+        },
+        allowsOrigin,
+    };
+}
+function createPairingHttpServer(service, options) {
+    const maxBodyBytes = options.maxBodyBytes ?? 16 * 1024;
+    const server = node_http_1.default.createServer(async (req, res) => {
+        const origin = typeof req.headers.origin === 'string' ? req.headers.origin : undefined;
+        const cors = () => {
+            if (origin && service.allowsOrigin(origin)) {
+                res.setHeader('access-control-allow-origin', origin);
+                res.setHeader('vary', 'Origin');
+            }
+            res.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
+            res.setHeader('access-control-allow-headers', 'content-type');
+        };
+        cors();
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204).end();
+            return;
+        }
+        const send = (status, body) => {
+            const payload = JSON.stringify(body);
+            res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) });
+            res.end(payload);
+        };
+        const url = new URL(req.url ?? '/', 'http://localhost');
+        try {
+            if (req.method === 'GET' && url.pathname === '/healthz')
+                return send(200, { ok: true });
+            if (req.method === 'GET' && url.pathname === '/node/v1/identity')
+                return send(200, service.identity());
+            if (req.method === 'GET' && url.pathname === '/pair/v1/info') {
+                const code = url.searchParams.get('code');
+                if (!code)
+                    return send(400, { error: 'code is required' });
+                if (origin && !service.allowsOrigin(origin))
+                    return send(403, { error: 'Origin not allowed' });
+                return send(200, service.info(code));
+            }
+            if (req.method === 'POST' && url.pathname === '/pair/v1/complete') {
+                const body = await readBody(req, maxBodyBytes);
+                const parsed = JSON.parse(body);
+                if (!parsed.code || !parsed.devicePublicKey)
+                    return send(400, { error: 'code and devicePublicKey are required' });
+                return send(200, service.complete({
+                    code: parsed.code,
+                    devicePublicKey: parsed.devicePublicKey,
+                    origin: parsed.origin ?? origin ?? '',
+                    scopes: parsed.scopes,
+                }));
+            }
+            send(404, { error: 'Not found' });
+        }
+        catch (error) {
+            send(400, { error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+    let address;
+    return {
+        get address() { return address; },
+        listen: () => new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(options.port, options.host ?? '127.0.0.1', () => {
+                server.off('error', reject);
+                address = server.address();
+                resolve({ host: address.address, port: address.port });
+            });
+        }),
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => error ? reject(error) : resolve());
+        }),
+    };
+}
+async function readBody(req, limit) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > limit)
+            throw new Error('Request body too large');
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}

package/dist/reply-cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Idempotent request/reply support for peer proposals.
+ *
+ * A requester resends a proposal when the transport reconnects (the proposal or
+ * its reply may have been lost). The responder must then:
+ *   - never sign/allocate a second time for the same logical request, and
+ *   - return the exact same reply so the requester sees a consistent result.
+ *
+ * Keyed by `(type, kind, channelId, nonce)`; concurrent duplicates await the
+ * in-flight execution instead of starting a second one.
+ */
+export declare class ReplyCache {
+    private readonly _maxEntries;
+    private readonly _ttlMs;
+    private readonly _replies;
+    private readonly _inFlight;
+    constructor(_maxEntries?: number, _ttlMs?: number);
+    key(type: string, channelId: string, nonce: number | undefined, kind?: string): string;
+    run<T>(key: string, fn: () => Promise<T | null>): Promise<T | null>;
+    private _evict;
+}

package/dist/reply-cache.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplyCache = void 0;
+/**
+ * Idempotent request/reply support for peer proposals.
+ *
+ * A requester resends a proposal when the transport reconnects (the proposal or
+ * its reply may have been lost). The responder must then:
+ *   - never sign/allocate a second time for the same logical request, and
+ *   - return the exact same reply so the requester sees a consistent result.
+ *
+ * Keyed by `(type, kind, channelId, nonce)`; concurrent duplicates await the
+ * in-flight execution instead of starting a second one.
+ */
+class ReplyCache {
+    _maxEntries;
+    _ttlMs;
+    _replies = new Map();
+    _inFlight = new Map();
+    constructor(_maxEntries = 512, _ttlMs = 10 * 60_000) {
+        this._maxEntries = _maxEntries;
+        this._ttlMs = _ttlMs;
+    }
+    key(type, channelId, nonce, kind) {
+        return [type, kind ?? '', channelId, nonce ?? ''].join(':');
+    }
+    async run(key, fn) {
+        const cached = this._replies.get(key);
+        if (cached) {
+            if (Date.now() - cached.at < this._ttlMs)
+                return cached.reply;
+            this._replies.delete(key);
+        }
+        const inFlight = this._inFlight.get(key);
+        if (inFlight)
+            return inFlight;
+        const promise = (async () => {
+            try {
+                const reply = await fn();
+                if (reply !== null) {
+                    this._replies.set(key, { reply, at: Date.now() });
+                    this._evict();
+                }
+                return reply;
+            }
+            finally {
+                this._inFlight.delete(key);
+            }
+        })();
+        this._inFlight.set(key, promise);
+        return promise;
+    }
+    _evict() {
+        while (this._replies.size > this._maxEntries) {
+            const oldest = this._replies.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this._replies.delete(oldest);
+        }
+    }
+}
+exports.ReplyCache = ReplyCache;

package/dist/signer-port.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Local signer port (RFC-058 P1).
+ *
+ * Adapts the host's unified TreeKey signer + WOTS lease to the SDK `SignerPort`
+ * contract. A hosted deployment supplies its own `SignerPort` (KMS/HSM/MPC +
+ * policy) instead; the host code is agnostic.
+ */
+import { type CustodyMode, type SignDomain, type SignRequest, type SignerPort } from '@totemsdk/omnia';
+import type { HostSigning } from './signing.js';
+export declare function createLocalSignerPort(signing: HostSigning): SignerPort;
+/** Hosted/KMS policy checks applied before delegating to the underlying port. */
+export interface SignerPolicy {
+    allowedDomains?: SignDomain[];
+    allowedModes?: CustodyMode[];
+    /** Reject requests whose declared amount exceeds this value (base units). */
+    maxAmount?: bigint;
+    /** Require a disclosure hash/version on the custody context. */
+    requireDisclosure?: boolean;
+    /** Additional operator approval hook (KMS/HSM/MPC or quorum). */
+    authorize?: (request: SignRequest) => void | Promise<void>;
+}
+/**
+ * Wrap a signer port with policy checks. The underlying port may be a local
+ * signer, KMS/HSM/MPC adapter, or hosted policy engine; this wrapper only
+ * enforces the deployment policy and disclosure requirements.
+ */
+export declare function createPolicySignerPort(base: SignerPort, policy?: SignerPolicy): SignerPort;

package/dist/signer-port.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Local signer port (RFC-058 P1).
+ *
+ * Adapts the host's unified TreeKey signer + WOTS lease to the SDK `SignerPort`
+ * contract. A hosted deployment supplies its own `SignerPort` (KMS/HSM/MPC +
+ * policy) instead; the host code is agnostic.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLocalSignerPort = createLocalSignerPort;
+exports.createPolicySignerPort = createPolicySignerPort;
+const core_1 = require("@totemsdk/core");
+const omnia_1 = require("@totemsdk/omnia");
+function createLocalSignerPort(signing) {
+    return {
+        publicKeyDigest: signing.publicKeyDigest,
+        async sign(request) {
+            (0, omnia_1.assertSignRequest)(request);
+            if (!request.signers.includes(signing.publicKeyDigest)) {
+                throw new Error(`local signer ${signing.publicKeyDigest} is not a required signer for ${request.requestId}`);
+            }
+            const payload = (0, omnia_1.signRequestPayload)(request);
+            if (request.signingIndices) {
+                // Caller owns the lease (channel/factory tx signing); sign the exact leaf.
+                return signing.signer.sign(payload, request.signingIndices);
+            }
+            const reservation = await signing.leaseProvider.reserveKeyUse({
+                treeId: 'omnia-sign-request',
+                purpose: `sign-request:${request.domain}`,
+                payloadHash: (0, core_1.bytesToHex)(payload),
+            });
+            try {
+                const signature = await signing.signer.sign(payload, reservation.indices);
+                await signing.leaseProvider.commitKeyUse(reservation.reservationId, `sign-request:${request.domain}`);
+                return signature;
+            }
+            catch (err) {
+                await signing.leaseProvider
+                    .burnReservation(reservation.reservationId, 'sign-request-failed')
+                    .catch(() => { });
+                throw err;
+            }
+        },
+    };
+}
+/**
+ * Wrap a signer port with policy checks. The underlying port may be a local
+ * signer, KMS/HSM/MPC adapter, or hosted policy engine; this wrapper only
+ * enforces the deployment policy and disclosure requirements.
+ */
+function createPolicySignerPort(base, policy = {}) {
+    return {
+        publicKeyDigest: base.publicKeyDigest,
+        async sign(request) {
+            (0, omnia_1.assertSignRequest)(request);
+            if (!request.signers.includes(base.publicKeyDigest)) {
+                throw new Error(`signer ${base.publicKeyDigest} is not a required signer for ${request.requestId}`);
+            }
+            if (policy.allowedDomains && !policy.allowedDomains.includes(request.domain)) {
+                throw new Error(`domain ${request.domain} is not allowed by policy`);
+            }
+            if (policy.allowedModes && !policy.allowedModes.includes(request.custody.mode)) {
+                throw new Error(`custody mode ${request.custody.mode} is not allowed by policy`);
+            }
+            if (policy.requireDisclosure && (!request.custody.disclosureHash || !request.custody.disclosureVersion)) {
+                throw new Error('policy requires a disclosure hash and version');
+            }
+            const amount = request.context.amount;
+            if (policy.maxAmount !== undefined && amount !== undefined) {
+                const parsed = BigInt(amount);
+                if (parsed > policy.maxAmount) {
+                    throw new Error(`request amount ${parsed} exceeds policy limit ${policy.maxAmount}`);
+                }
+            }
+            await policy.authorize?.(request);
+            return base.sign(request);
+        },
+    };
+}

package/dist/signing.d.ts

@@ -24,6 +24,17 @@ import type { OmniaHostConfig } from './config.js';
 export interface HostSigning {
     signer: ChannelSigner;
     leaseProvider: WotsLeaseProvider;
+    /**
+     * Stable ed25519 keypair used as the native Hyperswarm transport identity.
+     * Derived deterministically from the host seed. The transport is classical
+     * (noise); its public key is bound to the PQ identity by the signed manifest.
+     */
+    transportKeyPair: {
+        publicKey: Uint8Array;
+        secretKey: Uint8Array;
+    };
+    /** `0x`-prefixed hex transport public key (published in the signed manifest). */
+    transportPubkey: string;
     /** Minima address for the unified child TreeKey (identity + channels). */
     address: string;
     /** Channel participant key: the unified child TreeKey root pubkey (RFC-037). */

package/dist/signing.js

@@ -79,6 +79,29 @@ function encryptSeedForKeyfile(seed, passphrase) {
         authTag: cipher.getAuthTag().toString('hex'),
     };
 }
+/**
+ * Derive the stable ed25519 transport keypair from the host seed.
+ *
+ * The transport is Hyperswarm's classical noise channel; this key is *not* the
+ * quantum-resistant identity. It is published in the identity-signed manifest
+ * so peers can bind it to the host's PQ identity.
+ */
+function deriveTransportKeyPair(baseSeed) {
+    const seed = (0, node_crypto_1.createHash)('sha256')
+        .update(Buffer.concat([Buffer.from(baseSeed), Buffer.from('omnia-transport-v1')]))
+        .digest();
+    // Ed25519 PKCS#8 DER prefix + 32-byte seed
+    const pkcs8 = Buffer.concat([
+        Buffer.from('302e020100300506032b657004220420', 'hex'),
+        seed,
+    ]);
+    const privateKey = (0, node_crypto_1.createPrivateKey)({ key: pkcs8, format: 'der', type: 'pkcs8' });
+    const spki = (0, node_crypto_1.createPublicKey)(privateKey).export({ format: 'der', type: 'spki' });
+    const publicKey = spki.subarray(spki.length - 32);
+    // sodium/ed25519 64-byte secret key = seed || publicKey
+    const secretKey = Buffer.concat([seed, publicKey]);
+    return { publicKey: new Uint8Array(publicKey), secretKey: new Uint8Array(secretKey) };
+}
 function resolveBaseSeed(config) {
     if (config.seed) {
         const trimmed = config.seed.trim();
@@ -194,11 +217,15 @@ function createHostSigning(config) {
             return (0, core_1.serializeTreeSignature)(treeKey.sign(payload));
         },
     };
+    const transportKeyPair = deriveTransportKeyPair(baseSeed);
+    const transportPubkey = `0x${(0, core_1.bytesToHex)(transportKeyPair.publicKey)}`;
     return {
         signer,
         leaseProvider,
         address,
         publicKeyDigest,
+        transportKeyPair,
+        transportPubkey,
         baseSeed,
         treeKey,
         addressIndex,

package/dist/stores/operations.d.ts

@@ -9,10 +9,11 @@ export interface OperationRecord {
     result?: unknown;
     error?: string;
 }
-/** Durable operation journal with atomic status transitions. */
+/** Durable operation journal with atomic status transitions, via storage SDK. */
 export declare class OperationStore {
-    private readonly db;
+    private readonly kv;
     constructor(dbPath: string);
+    private migrateLegacy;
     get(operationId: string): OperationRecord | undefined;
     create(operationId: string, request?: unknown, now?: number): OperationRecord;
     verifyRequest(operationId: string, request: unknown): boolean;