@serfab/cadre-core 0.0.2

package/dist/hibernation-manager.d.ts

@@ -0,0 +1,68 @@
+import type { StrandInstance, HibernationConfig } from './types.js';
+/**
+ * Callbacks for hibernation state changes
+ */
+export interface HibernationCallbacks {
+    onIdle: (strandId: string) => Promise<void>;
+    onHibernate: (strandId: string) => Promise<void>;
+    onWake: (strandId: string) => Promise<void>;
+}
+/**
+ * Manages strand hibernation state transitions based on activity.
+ *
+ * State machine:
+ *   active → idle (after idleTimeout with no activity)
+ *   idle → hibernating (after hibernateTimeout with no activity)
+ *   idle → active (on activity)
+ *   hibernating → active (on wake signal or check-in with pending activity)
+ */
+export declare class HibernationManager {
+    private readonly config;
+    private readonly callbacks;
+    private readonly timers;
+    private readonly checkInTimers;
+    private running;
+    constructor(config: HibernationConfig, callbacks: HibernationCallbacks);
+    /**
+     * Get effective timeouts for a latency hint
+     */
+    private getTimeouts;
+    /**
+     * Start managing hibernation for all strands
+     */
+    start(): void;
+    /**
+     * Stop managing hibernation
+     */
+    stop(): void;
+    /**
+     * Register a strand for hibernation management
+     */
+    trackStrand(instance: StrandInstance): void;
+    /**
+     * Untrack a strand from hibernation management
+     */
+    untrackStrand(strandId: string): void;
+    /**
+     * Record activity on a strand - resets idle timer
+     */
+    recordActivity(instance: StrandInstance): void;
+    /**
+     * Force wake a hibernating strand
+     */
+    wakeStrand(strandId: string): Promise<void>;
+    private scheduleIdleTransition;
+    private handleIdleTimeout;
+    private scheduleHibernateTransition;
+    private handleHibernateTimeout;
+    private scheduleCheckIn;
+    private clearTimer;
+    private clearTimers;
+    /**
+     * Get the current status of hibernation tracking
+     */
+    getStatus(): {
+        enabled: boolean;
+        trackedStrands: number;
+    };
+}

package/dist/hibernation-manager.js

@@ -0,0 +1,212 @@
+import debug from 'debug';
+import { HIBERNATION_TIMEOUTS } from './types.js';
+const log = debug('sereus:cadre:hibernation');
+/**
+ * Manages strand hibernation state transitions based on activity.
+ *
+ * State machine:
+ *   active → idle (after idleTimeout with no activity)
+ *   idle → hibernating (after hibernateTimeout with no activity)
+ *   idle → active (on activity)
+ *   hibernating → active (on wake signal or check-in with pending activity)
+ */
+export class HibernationManager {
+    constructor(config, callbacks) {
+        this.timers = new Map();
+        this.checkInTimers = new Map();
+        this.running = false;
+        this.config = config;
+        this.callbacks = callbacks;
+        log('HibernationManager created, enabled=%s', config.enabled);
+    }
+    /**
+     * Get effective timeouts for a latency hint
+     */
+    getTimeouts(hint) {
+        const defaults = HIBERNATION_TIMEOUTS[hint];
+        const custom = this.config.customTimeouts?.[hint];
+        if (!custom)
+            return defaults;
+        return {
+            idleTimeout: custom.idleTimeout ?? defaults.idleTimeout,
+            hibernateTimeout: custom.hibernateTimeout ?? defaults.hibernateTimeout,
+            checkInInterval: custom.checkInInterval ?? defaults.checkInInterval
+        };
+    }
+    /**
+     * Start managing hibernation for all strands
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        log('HibernationManager started');
+    }
+    /**
+     * Stop managing hibernation
+     */
+    stop() {
+        if (!this.running)
+            return;
+        this.running = false;
+        // Clear all timers
+        for (const timer of this.timers.values()) {
+            clearTimeout(timer);
+        }
+        this.timers.clear();
+        for (const timer of this.checkInTimers.values()) {
+            clearInterval(timer);
+        }
+        this.checkInTimers.clear();
+        log('HibernationManager stopped');
+    }
+    /**
+     * Register a strand for hibernation management
+     */
+    trackStrand(instance) {
+        if (!this.config.enabled || !this.running)
+            return;
+        const { strandId, latencyHint } = instance;
+        const timeouts = this.getTimeouts(latencyHint);
+        // Don't track strands that never hibernate
+        if (timeouts.idleTimeout === Infinity) {
+            log('Strand %s has realtime latency hint - no hibernation', strandId);
+            return;
+        }
+        log('Tracking strand %s for hibernation (hint=%s)', strandId, latencyHint);
+        this.scheduleIdleTransition(instance);
+    }
+    /**
+     * Untrack a strand from hibernation management
+     */
+    untrackStrand(strandId) {
+        this.clearTimers(strandId);
+        log('Untracked strand %s from hibernation', strandId);
+    }
+    /**
+     * Record activity on a strand - resets idle timer
+     */
+    recordActivity(instance) {
+        if (!this.config.enabled || !this.running)
+            return;
+        const { strandId, status, latencyHint } = instance;
+        instance.lastActivity = new Date();
+        // If idle or hibernating, wake up
+        if (status === 'idle' || status === 'hibernating') {
+            log('Activity on %s strand %s - waking', status, strandId);
+            this.clearTimers(strandId);
+            void this.callbacks.onWake(strandId);
+        }
+        // Reschedule idle transition if active
+        if (status === 'active') {
+            const timeouts = this.getTimeouts(latencyHint);
+            if (timeouts.idleTimeout !== Infinity) {
+                this.scheduleIdleTransition(instance);
+            }
+        }
+    }
+    /**
+     * Force wake a hibernating strand
+     */
+    async wakeStrand(strandId) {
+        this.clearTimers(strandId);
+        await this.callbacks.onWake(strandId);
+    }
+    scheduleIdleTransition(instance) {
+        const { strandId, latencyHint } = instance;
+        const timeouts = this.getTimeouts(latencyHint);
+        // Clear existing timer
+        this.clearTimer(strandId);
+        // Schedule idle transition
+        const timer = setTimeout(() => {
+            this.handleIdleTimeout(instance);
+        }, timeouts.idleTimeout);
+        this.timers.set(strandId, timer);
+    }
+    handleIdleTimeout(instance) {
+        const { strandId, latencyHint } = instance;
+        if (!this.running)
+            return;
+        log('Idle timeout for strand %s', strandId);
+        // Transition to idle
+        void this.callbacks.onIdle(strandId).then(() => {
+            // Schedule hibernate transition
+            const timeouts = this.getTimeouts(latencyHint);
+            if (timeouts.hibernateTimeout !== Infinity) {
+                this.scheduleHibernateTransition(instance);
+            }
+        });
+    }
+    scheduleHibernateTransition(instance) {
+        const { strandId, latencyHint } = instance;
+        const timeouts = this.getTimeouts(latencyHint);
+        // Clear existing timer
+        this.clearTimer(strandId);
+        // Schedule hibernate transition
+        const timer = setTimeout(() => {
+            this.handleHibernateTimeout(instance);
+        }, timeouts.hibernateTimeout);
+        this.timers.set(strandId, timer);
+    }
+    handleHibernateTimeout(instance) {
+        const { strandId, latencyHint } = instance;
+        if (!this.running)
+            return;
+        log('Hibernate timeout for strand %s', strandId);
+        // Transition to hibernating
+        void this.callbacks.onHibernate(strandId).then(() => {
+            // Schedule periodic check-ins
+            const timeouts = this.getTimeouts(latencyHint);
+            if (timeouts.checkInInterval !== Infinity) {
+                this.scheduleCheckIn(instance);
+            }
+        });
+    }
+    scheduleCheckIn(instance) {
+        const { strandId, latencyHint } = instance;
+        const timeouts = this.getTimeouts(latencyHint);
+        // Clear existing check-in timer
+        const existing = this.checkInTimers.get(strandId);
+        if (existing) {
+            clearInterval(existing);
+        }
+        // Schedule periodic check-ins
+        const timer = setInterval(() => {
+            if (!this.running) {
+                clearInterval(timer);
+                return;
+            }
+            log('Check-in for hibernating strand %s', strandId);
+            instance.nextCheckIn = new Date(Date.now() + timeouts.checkInInterval);
+            // In a real implementation, this would query the cohort for pending activity
+            // For now, we just update the nextCheckIn timestamp
+        }, timeouts.checkInInterval);
+        this.checkInTimers.set(strandId, timer);
+        instance.nextCheckIn = new Date(Date.now() + timeouts.checkInInterval);
+    }
+    clearTimer(strandId) {
+        const timer = this.timers.get(strandId);
+        if (timer) {
+            clearTimeout(timer);
+            this.timers.delete(strandId);
+        }
+    }
+    clearTimers(strandId) {
+        this.clearTimer(strandId);
+        const checkInTimer = this.checkInTimers.get(strandId);
+        if (checkInTimer) {
+            clearInterval(checkInTimer);
+            this.checkInTimers.delete(strandId);
+        }
+    }
+    /**
+     * Get the current status of hibernation tracking
+     */
+    getStatus() {
+        return {
+            enabled: this.config.enabled && this.running,
+            trackedStrands: this.timers.size + this.checkInTimers.size
+        };
+    }
+}
+//# sourceMappingURL=hibernation-manager.js.map

package/dist/hibernation-manager.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from './types.js';
+export { CadreNode } from './cadre-node.js';
+export { ControlDatabase, type ControlDatabaseConfig } from './control-database.js';
+export { StrandDatabase, type StrandDatabaseConfig } from './strand-database.js';
+export { StrandWatcher, type StrandWatcherCallbacks, type StrandQueryable, type SAppIdLookup, type StrandRowWithApp } from './strand-watcher.js';
+export { StrandInstanceManager, type StartStrandConfig, getStrandStoragePath } from './strand-instance-manager.js';
+export { HibernationManager, type HibernationCallbacks } from './hibernation-manager.js';
+export { ArachnodeStub, createArachnodeStub, type RingConfig } from './arachnode-stub.js';
+export { EnrollmentService, type MemberVerifier, type MemberRegistry } from './enrollment.js';
+export { StrandSolicitationService, type DisclosureValidator, type FormationUsageRecorder, type StrandProvisioner, type FormationSigner, type StrandSolicitationServiceOptions } from './strand-solicitation.js';
+export { SeedBootstrapService, SEED_PROTOCOL, type SeedBootstrapConfig, type SeedEventCallbacks } from './seed-bootstrap.js';
+export { StrandFormationManager, createStrandFormationManager, type StrandFormationManagerConfig, type StrandFormationManagerOptions } from './strand-formation-manager.js';

package/dist/index.js

@@ -0,0 +1,24 @@
+// Core types
+export * from './types.js';
+// Main CadreNode class
+export { CadreNode } from './cadre-node.js';
+// Control database
+export { ControlDatabase } from './control-database.js';
+// Strand database
+export { StrandDatabase } from './strand-database.js';
+// Strand management
+export { StrandWatcher } from './strand-watcher.js';
+export { StrandInstanceManager, getStrandStoragePath } from './strand-instance-manager.js';
+// Hibernation
+export { HibernationManager } from './hibernation-manager.js';
+// Arachnode (stub)
+export { ArachnodeStub, createArachnodeStub } from './arachnode-stub.js';
+// Enrollment
+export { EnrollmentService } from './enrollment.js';
+// Strand Solicitation
+export { StrandSolicitationService } from './strand-solicitation.js';
+// Seed Bootstrap
+export { SeedBootstrapService, SEED_PROTOCOL } from './seed-bootstrap.js';
+// Strand Formation (strand-proto integration)
+export { StrandFormationManager, createStrandFormationManager } from './strand-formation-manager.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,aAAa;AACb,cAAc,YAAY,CAAC;AAE3B,uBAAuB;AACvB,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,mBAAmB;AACnB,OAAO,EAAE,eAAe,EAA8B,MAAM,uBAAuB,CAAC;AAEpF,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAA6B,MAAM,sBAAsB,CAAC;AAEjF,oBAAoB;AACpB,OAAO,EACL,aAAa,EAKd,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,qBAAqB,EAErB,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AAEtC,cAAc;AACd,OAAO,EACL,kBAAkB,EAEnB,MAAM,0BAA0B,CAAC;AAElC,mBAAmB;AACnB,OAAO,EACL,aAAa,EACb,mBAAmB,EAEpB,MAAM,qBAAqB,CAAC;AAE7B,aAAa;AACb,OAAO,EACL,iBAAiB,EAGlB,MAAM,iBAAiB,CAAC;AAEzB,sBAAsB;AACtB,OAAO,EACL,yBAAyB,EAM1B,MAAM,0BAA0B,CAAC;AAElC,iBAAiB;AACjB,OAAO,EACL,oBAAoB,EACpB,aAAa,EAGd,MAAM,qBAAqB,CAAC;AAE7B,8CAA8C;AAC9C,OAAO,EACL,sBAAsB,EACtB,4BAA4B,EAG7B,MAAM,+BAA+B,CAAC"}

package/dist/seed-bootstrap.d.ts

@@ -0,0 +1,164 @@
+import type { Libp2p } from '@libp2p/interface';
+import type { ControlNetworkSeed, SeedAckMessage, AuthorizePeerOptions, ApplySeedResult, AddDroneOptions, AddPhoneOptions, DroneInitResult, InviteResult, CadreInvite } from './types.js';
+import type { ControlDatabase } from './control-database.js';
+/** Protocol ID for seed delivery */
+export declare const SEED_PROTOCOL = "/sereus/seed/1.0.0";
+/**
+ * Configuration for the SeedBootstrapService
+ */
+export interface SeedBootstrapConfig {
+    /** Party ID for this cadre */
+    partyId: string;
+    /** Authority private key for signing seeds and peer authorizations (base64url) */
+    authorityPrivateKey?: string;
+    /** Authority public key (base64url) - derived from private key if not provided */
+    authorityPublicKey?: string;
+}
+/**
+ * Event callbacks for seed-related events
+ */
+export interface SeedEventCallbacks {
+    /** Called when a seed is received via the protocol */
+    onSeedReceived?: (partyId: string, peerId: string) => void;
+    /** Called when a seed is successfully applied */
+    onSeedApplied?: (partyId: string, peersAdded: number) => void;
+    /** Called when seed application fails */
+    onSeedError?: (partyId: string, error: string) => void;
+}
+/**
+ * SeedBootstrapService handles control network seed generation and delivery.
+ *
+ * Seeds solve the cold-start problem: new nodes need control data to validate
+ * connections, but can't get data without connecting first. Seeds pre-populate
+ * the new node's cache with peer information and optionally transactions.
+ */
+export declare class SeedBootstrapService {
+    private readonly config;
+    private libp2pNode;
+    private controlDatabase;
+    private readonly authorityPublicKey;
+    private eventCallbacks;
+    constructor(config: SeedBootstrapConfig);
+    /**
+     * Set event callbacks for seed-related events.
+     * Used by CadreNode to emit events.
+     */
+    setEventCallbacks(callbacks: SeedEventCallbacks): void;
+    /**
+     * Initialize the service with libp2p node and control database
+     */
+    initialize(libp2pNode: Libp2p, controlDatabase: ControlDatabase): void;
+    /**
+     * Authorize a new peer to join the cadre.
+     * Signs the peer ID with the authority key and inserts into CadrePeer table.
+     */
+    authorizePeer(options: AuthorizePeerOptions): Promise<void>;
+    /**
+     * Create a seed from the current control network state.
+     * The seed contains peer information and is signed by an authority.
+     */
+    createSeed(): Promise<ControlNetworkSeed>;
+    /**
+     * Apply a seed to populate the peer cache and enable connections.
+     * Validates the seed signature before applying.
+     */
+    applySeed(seed: ControlNetworkSeed): Promise<ApplySeedResult>;
+    /**
+     * Encode a seed for out-of-band delivery (e.g., QR code, copy/paste).
+     */
+    encodeSeed(seed: ControlNetworkSeed): string;
+    /**
+     * Decode a seed from base64url encoding.
+     */
+    decodeSeed(encoded: string): ControlNetworkSeed;
+    /**
+     * Deliver a seed directly to a peer via the /sereus/seed/1.0.0 protocol.
+     */
+    deliverSeed(targetMultiaddr: string, seed: ControlNetworkSeed): Promise<SeedAckMessage>;
+    /**
+     * Get this node's circuit relay address for inclusion in seeds.
+     * Returns null if no relay address is available.
+     */
+    getRelayAddress(): Promise<string | null>;
+    /**
+     * Validate a seed's signature.
+     */
+    validateSeedSignature(seed: ControlNetworkSeed): boolean;
+    /**
+     * Query peers from the control database.
+     */
+    private queryPeers;
+    /**
+     * Register the seed protocol handler.
+     */
+    private registerProtocolHandler;
+    /**
+     * Shutdown the service.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Add a drone to the cadre (phone/server adds provider-hosted node).
+     *
+     * Use this when you've spawned a drone via provider API and received its
+     * peer ID and multiaddrs. This method:
+     * 1. Authorizes the drone peer
+     * 2. Creates a seed including all current peers
+     * 3. Returns the seed for sending to provider API
+     *
+     * @param options - Drone peer info from provider API
+     * @returns Seed and encoded seed for drone initialization
+     */
+    addDrone(options: AddDroneOptions): Promise<DroneInitResult>;
+    /**
+     * Create an invite for a phone to join the cadre.
+     *
+     * Use this when a server (public IP) wants to invite a phone (NAT'd).
+     * The invite is shared out-of-band (QR code, link, etc.) and contains
+     * the server's address so the phone can dial in.
+     *
+     * @param token - Optional invite token for validation
+     * @param expiresIn - Optional expiration time in milliseconds
+     * @returns Invite and encoded invite for sharing
+     */
+    createInvite(token?: string, expiresIn?: number): Promise<InviteResult>;
+    /**
+     * Accept a phone connection using an invite.
+     *
+     * Use this when a phone dials in with an invite token. This method:
+     * 1. Validates the token if provided
+     * 2. Authorizes the phone peer
+     *
+     * After this, the phone can sync the control database normally.
+     *
+     * @param options - Phone peer info and invite token
+     * @param issuedInvite - The original invite for validation
+     */
+    acceptPhone(options: AddPhoneOptions, issuedInvite?: CadreInvite): Promise<void>;
+    /**
+     * Add a phone to the cadre with relay support.
+     *
+     * Use this when both nodes are NAT'd (phone-to-phone). This method:
+     * 1. Authorizes the new phone peer
+     * 2. Creates a seed with relay addresses for dialing
+     *
+     * @param phonePeerId - Peer ID of the new phone
+     * @returns Seed with relay addresses for out-of-band delivery
+     */
+    addPhoneWithRelay(phonePeerId: string): Promise<DroneInitResult>;
+    /**
+     * Encode an invite for out-of-band delivery.
+     */
+    encodeInvite(invite: CadreInvite): string;
+    /**
+     * Decode an invite from base64url encoding.
+     */
+    decodeInvite(encoded: string): CadreInvite;
+    /**
+     * Dial an authority from an invite.
+     * Use this on a phone after receiving an invite to connect to the authority.
+     *
+     * @param invite - The invite received out-of-band
+     * @returns Connection to the authority
+     */
+    dialInvite(invite: CadreInvite): Promise<void>;
+}