@aster-rpc/aster 0.1.2

package/dist/trust/bootstrap.js

@@ -0,0 +1,311 @@
+/**
+ * Producer mesh bootstrap -- founding node + join.
+ *
+ * Spec reference: Aster-trust-spec.md S2.1, S2.5.  Plan: ASTER_PLAN.md S14.5.
+ *
+ * Two startup modes:
+ *
+ * startFoundingNode()
+ *     The first producer in a new mesh. Generates a random 32-byte salt, derives
+ *     the gossip topic, initializes MeshState, and returns it for the caller.
+ *
+ * joinMesh()
+ *     A subsequent producer. Builds an AdmissionRequest from its credential.
+ *     The caller dials the bootstrap peer and sends the request, then calls
+ *     applyAdmissionResponse() with the result.
+ *
+ * handleAdmissionRpc()
+ *     Server-side handler: parses a request, runs offline admission checks,
+ *     and returns an AdmissionResponse.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { MeshState, saveMeshState } from './mesh.js';
+import { deriveGossipTopic } from './gossip.js';
+import { hexToBytes, bytesToHex } from './credentials.js';
+import { checkOffline } from './admission.js';
+// ── Internal helpers ────────────────────────────────────────────────────────
+const DEFAULT_STATE_DIR = join(homedir(), '.aster');
+function stateDir(config) {
+    return config?.stateDir ?? process.env.ASTER_MESH_STATE_DIR ?? DEFAULT_STATE_DIR;
+}
+function statePath(name, config) {
+    return join(stateDir(config), name);
+}
+function ensureStateDir(config) {
+    const dir = stateDir(config);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * Load an EnrollmentCredential from a JSON file.
+ * Path resolved from argument -> ASTER_ENROLLMENT env var.
+ */
+function loadEnrollmentCredential(path) {
+    const envPath = path ?? process.env.ASTER_ENROLLMENT;
+    if (!envPath) {
+        throw new Error('Set ASTER_ENROLLMENT to the path of your enrollment credential JSON file');
+    }
+    const raw = readFileSync(envPath, 'utf-8');
+    const d = JSON.parse(raw);
+    return {
+        endpointId: d.endpoint_id,
+        rootPubkey: d.root_pubkey, // already hex
+        expiresAt: Number(d.expires_at),
+        attributes: d.attributes ?? {},
+        signature: d.signature ?? '',
+    };
+}
+/**
+ * Load or generate 32-byte mesh salt.
+ * Persists to stateDir/mesh_salt for crash recovery.
+ */
+function loadOrGenerateSalt(config) {
+    const saltPath = statePath('mesh_salt', config);
+    ensureStateDir(config);
+    if (existsSync(saltPath)) {
+        const buf = readFileSync(saltPath);
+        if (buf.length !== 32) {
+            throw new Error(`mesh_salt at ${saltPath} is ${buf.length} bytes; expected 32`);
+        }
+        return new Uint8Array(buf);
+    }
+    const salt = randomBytes(32);
+    writeFileSync(saltPath, salt);
+    return new Uint8Array(salt);
+}
+/**
+ * Persist a MeshState to stateDir/mesh_state.json (atomic rename).
+ */
+function persistMeshState(state, config) {
+    const path = statePath('mesh_state.json', config);
+    saveMeshState(state, path);
+}
+// ── Founding node ───────────────────────────────────────────────────────────
+/**
+ * Start the founding node of a new producer mesh.
+ *
+ * Steps (S2.1):
+ * 1. Load credential from JSON file.
+ * 2. Verify credential offline.
+ * 3. Generate or load 32-byte salt.
+ * 4. Derive gossip topic.
+ * 5. Create MeshState with self as only accepted producer.
+ * 6. Persist state.
+ *
+ * @returns The initialized MeshState.
+ */
+export async function startFoundingNode(enrollmentPath, config) {
+    // 1. Load credential
+    const cred = loadEnrollmentCredential(enrollmentPath);
+    // 2. Verify offline
+    const result = await checkOffline(cred, cred.endpointId);
+    if (!result.admitted) {
+        throw new Error(`Founding node credential invalid: ${result.reason}`);
+    }
+    // 3. Salt
+    const salt = loadOrGenerateSalt(config);
+    // 4. Topic derivation
+    await deriveGossipTopic(hexToBytes(cred.rootPubkey), salt); // validates topic derivation
+    // 5. MeshState -- self is the only accepted producer
+    const state = new MeshState();
+    state.addPeer(cred.endpointId);
+    // 6. Persist
+    persistMeshState(state, config);
+    return state;
+}
+// ── Join mesh ───────────────────────────────────────────────────────────────
+/**
+ * Build an AdmissionRequest from a credential for joining an existing mesh.
+ *
+ * The caller should send this request to the bootstrap peer over
+ * the aster.producer_admission ALPN, then call applyAdmissionResponse()
+ * with the result.
+ */
+export function joinMesh(credential, iidToken) {
+    const credJson = JSON.stringify({
+        endpoint_id: credential.endpointId,
+        root_pubkey: credential.rootPubkey,
+        expires_at: credential.expiresAt,
+        attributes: credential.attributes,
+        signature: credential.signature,
+    });
+    return {
+        credentialJson: credJson,
+        iidToken,
+    };
+}
+// ── Apply admission response ────────────────────────────────────────────────
+/**
+ * Finalize MeshState after receiving a successful AdmissionResponse.
+ *
+ * @param response        The AdmissionResponse from the bootstrap peer.
+ * @param ownEndpointId   This node's endpoint ID.
+ * @param rootPubkey      The root public key (raw bytes) for topic derivation.
+ * @returns Initialized MeshState ready for gossip subscription.
+ * @throws If response.accepted is false.
+ */
+export async function applyAdmissionResponse(response, ownEndpointId, rootPubkey) {
+    if (!response.accepted) {
+        throw new Error(`Admission refused: ${response.reason ?? '(no reason provided)'}`);
+    }
+    const salt = hexToBytes(response.salt);
+    await deriveGossipTopic(rootPubkey, salt); // validates topic derivation
+    const state = new MeshState();
+    // Add all accepted producers + self
+    for (const peerId of response.acceptedProducers) {
+        state.addPeer(peerId);
+    }
+    state.addPeer(ownEndpointId);
+    return state;
+}
+// ── Server-side admission RPC ───────────────────────────────────────────────
+/**
+ * Server-side handler for aster.producer_admission ALPN.
+ *
+ * Parses an AdmissionRequest, runs offline admission checks, and returns
+ * an AdmissionResponse. On success, the peer is added to ownState.
+ *
+ * @param requestJson     JSON-serialized credential (the credentialJson field
+ *                        from AdmissionRequest, or a raw credential JSON).
+ * @param ownState        The founding/accepting node's MeshState.
+ * @param ownRootPubkey   Hex-encoded root public key this mesh trusts.
+ * @param config          Optional BootstrapConfig.
+ * @returns AdmissionResponse (accepted or rejected with reason).
+ */
+export async function handleAdmissionRpc(requestJson, ownState, ownRootPubkey, config) {
+    let cred;
+    try {
+        const d = JSON.parse(requestJson);
+        cred = {
+            endpointId: d.endpoint_id,
+            rootPubkey: d.root_pubkey,
+            expiresAt: Number(d.expires_at),
+            attributes: d.attributes ?? {},
+            signature: d.signature ?? '',
+        };
+    }
+    catch {
+        return {
+            accepted: false,
+            salt: '',
+            acceptedProducers: [],
+            reason: 'malformed request',
+        };
+    }
+    // Verify the credential's root_pubkey matches the mesh's trusted key
+    if (cred.rootPubkey !== ownRootPubkey) {
+        return {
+            accepted: false,
+            salt: '',
+            acceptedProducers: [],
+            reason: 'untrusted root key',
+        };
+    }
+    // Run offline admission checks (signature, expiry, endpoint_id match)
+    const result = await checkOffline(cred, cred.endpointId);
+    if (!result.admitted) {
+        return {
+            accepted: false,
+            salt: '',
+            acceptedProducers: [],
+            reason: result.reason ?? 'admission check failed',
+        };
+    }
+    // Accept: add peer to mesh state
+    ownState.addPeer(cred.endpointId);
+    persistMeshState(ownState, config);
+    // Load salt from state dir for response
+    let saltHex = '';
+    try {
+        const saltPath = statePath('mesh_salt', config);
+        if (existsSync(saltPath)) {
+            saltHex = bytesToHex(new Uint8Array(readFileSync(saltPath)));
+        }
+    }
+    catch {
+        // Salt unavailable -- ephemeral mesh
+    }
+    return {
+        accepted: true,
+        salt: saltHex,
+        acceptedProducers: ownState.allPeers(),
+        reason: '', // never leak reason on wire
+    };
+}
+// ── Per-connection handler ──────────────────────────────────────────────────
+/**
+ * Handle one producer admission connection: read request, write response.
+ *
+ * @param conn            An IrohConnection-like object with acceptBi() and remoteId().
+ * @param ownRootPubkey   Hex-encoded root public key.
+ * @param ownState        This node's MeshState; mutated on accept.
+ * @param config          Optional BootstrapConfig.
+ * @returns The AdmissionResponse that was sent.
+ */
+export async function handleProducerAdmissionConnection(conn, ownRootPubkey, ownState, config) {
+    const peerId = conn.remoteId();
+    try {
+        const [send, recv] = await conn.acceptBi();
+        const raw = await recv.readToEnd(64 * 1024);
+        if (raw.length === 0) {
+            const resp = {
+                accepted: false,
+                salt: '',
+                acceptedProducers: [],
+                reason: 'empty request',
+            };
+            return resp;
+        }
+        // Parse the AdmissionRequest wrapper and extract credential_json
+        let credJson;
+        try {
+            const wrapper = JSON.parse(new TextDecoder().decode(raw));
+            credJson = wrapper.credential_json ?? '';
+        }
+        catch {
+            // Back-compat: accept raw credential JSON as well
+            credJson = new TextDecoder().decode(raw);
+        }
+        const response = await handleAdmissionRpc(credJson, ownState, ownRootPubkey, config);
+        // Write response (strip reason -- oracle protection)
+        const wirePayload = {
+            accepted: response.accepted,
+            salt: response.salt,
+            accepted_producers: response.acceptedProducers,
+            reason: '', // oracle protection -- never leak on wire
+        };
+        await send.writeAll(new TextEncoder().encode(JSON.stringify(wirePayload)));
+        await send.finish();
+        return response;
+    }
+    catch (exc) {
+        return {
+            accepted: false,
+            salt: '',
+            acceptedProducers: [],
+            reason: `connection error from ${peerId}: ${exc}`,
+        };
+    }
+}
+// ── Ephemeral state ─────────────────────────────────────────────────────────
+/**
+ * Build an in-memory MeshState for a standalone producer.
+ *
+ * Useful for demos, tests, and single-node setups. Generates a fresh random
+ * salt and an empty accepted-producer set with no persistence.
+ */
+export async function makeEphemeralMeshState(rootPubkey) {
+    const salt = randomBytes(32);
+    const state = new MeshState();
+    // Derive topic if rootPubkey provided (for gossip subscription)
+    if (rootPubkey != null) {
+        const topicId = await deriveGossipTopic(rootPubkey, new Uint8Array(salt));
+        state.topicId = bytesToHex(topicId);
+    }
+    return state;
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/trust/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/trust/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/trust/clock.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Clock drift detection for mesh peers.
+ *
+ * Spec reference: Aster-trust-spec.md
+ *
+ * Detects excessive clock skew between mesh peers by comparing
+ * timestamps in gossip heartbeats. Peers with drift beyond
+ * the configured tolerance are isolated.
+ */
+/** Clock drift configuration. */
+export interface ClockDriftConfig {
+    /** Maximum allowed drift in milliseconds (default: 30 seconds). */
+    toleranceMs: number;
+    /** Grace period after mesh join before drift checks kick in (default: 60 seconds). */
+    gracePeriodMs: number;
+    /** Minimum number of peers required for mesh median computation (default: 3). */
+    minPeers: number;
+}
+/** Default clock drift config. */
+export declare const DEFAULT_CLOCK_DRIFT_CONFIG: ClockDriftConfig;
+/**
+ * Check if a peer's timestamp indicates excessive clock drift.
+ *
+ * @param peerTimestampMs - Epoch ms from the peer's heartbeat
+ * @param localTimestampMs - Local epoch ms (default: Date.now())
+ * @returns The drift in milliseconds (positive = peer is ahead, negative = behind)
+ */
+export declare function computeDrift(peerTimestampMs: number, localTimestampMs?: number): number;
+/**
+ * Check whether a peer should be isolated due to clock drift.
+ *
+ * @param driftMs - The computed drift (from computeDrift)
+ * @param meshJoinedAtMs - When we joined the mesh
+ * @param config - Drift configuration
+ * @returns true if the peer should be isolated
+ */
+export declare function shouldIsolate(driftMs: number, meshJoinedAtMs: number, config?: ClockDriftConfig): boolean;
+/**
+ * Clock drift tracker for multiple peers.
+ *
+ * Records per-peer clock offsets and tracks which peers have been
+ * isolated due to excessive drift.
+ */
+export declare class ClockDriftTracker {
+    private offsets;
+    private isolated;
+    private meshJoinedAtMs;
+    private config;
+    constructor(meshJoinedAtMs?: number, config?: Partial<ClockDriftConfig>);
+    /**
+     * Update a peer's clock offset from a heartbeat.
+     *
+     * @returns true if the peer was newly isolated
+     */
+    update(peerEndpointId: string, peerTimestampMs: number): boolean;
+    /**
+     * Track a peer's clock offset from a received timestamp.
+     * Alias for update() — tracks the offset and returns true if peer was newly isolated.
+     */
+    trackOffset(peerEndpointId: string, peerTimestampMs: number): boolean;
+    /** Check if a peer is currently isolated. */
+    isIsolated(peerEndpointId: string): boolean;
+    /** Get drift for a peer in ms. */
+    getDrift(peerEndpointId: string): number | undefined;
+    /** All isolated peers. */
+    isolatedPeers(): string[];
+    /** Return a copy of the current peer offset map. */
+    peerOffsets(): Map<string, number>;
+    /**
+     * Compute the mesh median offset from all tracked peers.
+     *
+     * Returns undefined if fewer than minPeers peers are tracked
+     * (not enough data for meaningful drift detection).
+     *
+     * Uses median_high (higher-middle for even counts) for determinism.
+     */
+    meshMedianOffset(): number | undefined;
+    /**
+     * Check if this node's own clock appears to be the outlier.
+     *
+     * @param selfOffsetEstimate - now_ms - msg.epoch_ms computed when this node
+     *   sends a message (i.e. ~0 if the clock is correct).
+     * @returns true if self is the outlier. Returns false during grace period or
+     *   when there are too few peers.
+     */
+    selfInDrift(selfOffsetEstimate: number): boolean;
+    /**
+     * Remove a peer from the offset tracking table and isolation set.
+     * Called on Depart or lease expiry.
+     */
+    removePeer(endpointId: string): void;
+}
+//# sourceMappingURL=clock.d.ts.map

package/dist/trust/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../../src/trust/clock.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,iCAAiC;AACjC,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,sFAAsF;IACtF,aAAa,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,kCAAkC;AAClC,eAAO,MAAM,0BAA0B,EAAE,gBAIxC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,eAAe,EAAE,MAAM,EACvB,gBAAgB,SAAa,GAC5B,MAAM,CAER;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM,EACtB,MAAM,GAAE,gBAA6C,GACpD,OAAO,CAMT;AAiBD;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,MAAM,CAAmB;gBAErB,cAAc,SAAa,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAK3E;;;;OAIG;IACH,MAAM,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO;IAiBhE;;;OAGG;IACH,WAAW,CAAC,cAAc,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO;IAIrE,6CAA6C;IAC7C,UAAU,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAI3C,kCAAkC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIpD,0BAA0B;IAC1B,aAAa,IAAI,MAAM,EAAE;IAIzB,oDAAoD;IACpD,WAAW,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIlC;;;;;;;OAOG;IACH,gBAAgB,IAAI,MAAM,GAAG,SAAS;IAQtC;;;;;;;OAOG;IACH,WAAW,CAAC,kBAAkB,EAAE,MAAM,GAAG,OAAO;IAUhD;;;OAGG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;CAIrC"}

package/dist/trust/clock.js

@@ -0,0 +1,154 @@
+/**
+ * Clock drift detection for mesh peers.
+ *
+ * Spec reference: Aster-trust-spec.md
+ *
+ * Detects excessive clock skew between mesh peers by comparing
+ * timestamps in gossip heartbeats. Peers with drift beyond
+ * the configured tolerance are isolated.
+ */
+/** Default clock drift config. */
+export const DEFAULT_CLOCK_DRIFT_CONFIG = {
+    toleranceMs: 30_000,
+    gracePeriodMs: 60_000,
+    minPeers: 3,
+};
+/**
+ * Check if a peer's timestamp indicates excessive clock drift.
+ *
+ * @param peerTimestampMs - Epoch ms from the peer's heartbeat
+ * @param localTimestampMs - Local epoch ms (default: Date.now())
+ * @returns The drift in milliseconds (positive = peer is ahead, negative = behind)
+ */
+export function computeDrift(peerTimestampMs, localTimestampMs = Date.now()) {
+    return peerTimestampMs - localTimestampMs;
+}
+/**
+ * Check whether a peer should be isolated due to clock drift.
+ *
+ * @param driftMs - The computed drift (from computeDrift)
+ * @param meshJoinedAtMs - When we joined the mesh
+ * @param config - Drift configuration
+ * @returns true if the peer should be isolated
+ */
+export function shouldIsolate(driftMs, meshJoinedAtMs, config = DEFAULT_CLOCK_DRIFT_CONFIG) {
+    // Don't isolate during grace period
+    const elapsed = Date.now() - meshJoinedAtMs;
+    if (elapsed < config.gracePeriodMs)
+        return false;
+    return Math.abs(driftMs) > config.toleranceMs;
+}
+/**
+ * Compute the high median of an array of numbers.
+ *
+ * For odd-length arrays, returns the middle element.
+ * For even-length arrays, returns the higher of the two middle elements
+ * (matches Python's statistics.median_high for determinism).
+ *
+ * @param values - Array of numbers (must not be empty).
+ */
+function medianHigh(values) {
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted[mid];
+}
+/**
+ * Clock drift tracker for multiple peers.
+ *
+ * Records per-peer clock offsets and tracks which peers have been
+ * isolated due to excessive drift.
+ */
+export class ClockDriftTracker {
+    offsets = new Map(); // peer -> latest drift ms
+    isolated = new Set();
+    meshJoinedAtMs;
+    config;
+    constructor(meshJoinedAtMs = Date.now(), config) {
+        this.meshJoinedAtMs = meshJoinedAtMs;
+        this.config = { ...DEFAULT_CLOCK_DRIFT_CONFIG, ...config };
+    }
+    /**
+     * Update a peer's clock offset from a heartbeat.
+     *
+     * @returns true if the peer was newly isolated
+     */
+    update(peerEndpointId, peerTimestampMs) {
+        const drift = computeDrift(peerTimestampMs);
+        this.offsets.set(peerEndpointId, drift);
+        if (shouldIsolate(drift, this.meshJoinedAtMs, this.config)) {
+            if (!this.isolated.has(peerEndpointId)) {
+                this.isolated.add(peerEndpointId);
+                return true;
+            }
+        }
+        else {
+            // Peer recovered — remove from isolation
+            this.isolated.delete(peerEndpointId);
+        }
+        return false;
+    }
+    /**
+     * Track a peer's clock offset from a received timestamp.
+     * Alias for update() — tracks the offset and returns true if peer was newly isolated.
+     */
+    trackOffset(peerEndpointId, peerTimestampMs) {
+        return this.update(peerEndpointId, peerTimestampMs);
+    }
+    /** Check if a peer is currently isolated. */
+    isIsolated(peerEndpointId) {
+        return this.isolated.has(peerEndpointId);
+    }
+    /** Get drift for a peer in ms. */
+    getDrift(peerEndpointId) {
+        return this.offsets.get(peerEndpointId);
+    }
+    /** All isolated peers. */
+    isolatedPeers() {
+        return [...this.isolated];
+    }
+    /** Return a copy of the current peer offset map. */
+    peerOffsets() {
+        return new Map(this.offsets);
+    }
+    /**
+     * Compute the mesh median offset from all tracked peers.
+     *
+     * Returns undefined if fewer than minPeers peers are tracked
+     * (not enough data for meaningful drift detection).
+     *
+     * Uses median_high (higher-middle for even counts) for determinism.
+     */
+    meshMedianOffset() {
+        const values = [...this.offsets.values()];
+        if (values.length < this.config.minPeers) {
+            return undefined;
+        }
+        return medianHigh(values);
+    }
+    /**
+     * Check if this node's own clock appears to be the outlier.
+     *
+     * @param selfOffsetEstimate - now_ms - msg.epoch_ms computed when this node
+     *   sends a message (i.e. ~0 if the clock is correct).
+     * @returns true if self is the outlier. Returns false during grace period or
+     *   when there are too few peers.
+     */
+    selfInDrift(selfOffsetEstimate) {
+        const elapsed = Date.now() - this.meshJoinedAtMs;
+        if (elapsed < this.config.gracePeriodMs)
+            return false;
+        const median = this.meshMedianOffset();
+        if (median === undefined)
+            return false;
+        return Math.abs(selfOffsetEstimate - median) > this.config.toleranceMs;
+    }
+    /**
+     * Remove a peer from the offset tracking table and isolation set.
+     * Called on Depart or lease expiry.
+     */
+    removePeer(endpointId) {
+        this.offsets.delete(endpointId);
+        this.isolated.delete(endpointId);
+    }
+}
+//# sourceMappingURL=clock.js.map

package/dist/trust/clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.js","sourceRoot":"","sources":["../../src/trust/clock.ts"],"names":[],"mappings":"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"}