@serfab/cadre-core 0.0.2

package/dist/types.d.ts

@@ -0,0 +1,484 @@
+import type { Libp2p, PeerId } from '@libp2p/interface';
+import type { IRawStorage, Libp2pTransports } from '@optimystic/db-p2p';
+import type { StrandDatabase } from './strand-database.js';
+/**
+ * Node profile determines storage participation
+ */
+export type NodeProfile = 'transaction' | 'storage';
+/**
+ * Strand filter configuration - determines which strands this node participates in
+ */
+export type StrandFilter = {
+    mode: 'all';
+} | {
+    mode: 'sAppId';
+    sAppId: string;
+} | {
+    mode: 'strandId';
+    strandId: string;
+} | {
+    mode: 'none';
+};
+/**
+ * Latency hint for strand hibernation behavior
+ */
+export type LatencyHint = 'realtime' | 'interactive' | 'background' | 'archive';
+/**
+ * Hibernation timeout configuration per latency hint (in milliseconds)
+ */
+export interface HibernationTimeouts {
+    /** Time before transitioning from active to idle */
+    idleTimeout: number;
+    /** Time before transitioning from idle to hibernating */
+    hibernateTimeout: number;
+    /** Interval for check-ins while hibernating */
+    checkInInterval: number;
+}
+/**
+ * Default hibernation timeouts per latency hint
+ */
+export declare const HIBERNATION_TIMEOUTS: Record<LatencyHint, HibernationTimeouts>;
+/**
+ * Storage provider type - either an IRawStorage instance or a factory function.
+ * Factory functions are useful for creating strand-specific storage instances.
+ */
+export type RawStorageProvider = IRawStorage | ((strandId: string) => IRawStorage);
+/**
+ * Storage configuration for storage profile nodes
+ */
+export interface StorageConfig {
+    /**
+     * Storage provider - either an IRawStorage instance or a factory function.
+     *
+     * For Node.js environments, use FileRawStorage from @optimystic/db-p2p-storage-fs:
+     * ```typescript
+     * import { FileRawStorage } from '@optimystic/db-p2p-storage-fs';
+     * storage: { provider: (strandId) => new FileRawStorage(`./data/${strandId}`) }
+     * ```
+     *
+     * For React Native, use the appropriate storage from @optimystic/db-p2p-storage-rn:
+     * ```typescript
+     * import { RNRawStorage } from '@optimystic/db-p2p-storage-rn';
+     * storage: { provider: (strandId) => new RNRawStorage(strandId) }
+     * ```
+     *
+     * For in-memory storage (testing):
+     * ```typescript
+     * import { MemoryRawStorage } from '@optimystic/db-p2p';
+     * storage: { provider: () => new MemoryRawStorage() }
+     * ```
+     */
+    provider: RawStorageProvider;
+    quotaBytes?: number;
+}
+/**
+ * Network configuration for libp2p
+ */
+export interface NetworkConfig {
+    listenAddrs?: string[];
+    announceAddrs?: string[];
+    relayAddrs?: string[];
+    /**
+     * Enable circuit relay server - allows this node to relay connections for other peers.
+     * When undefined, defaults to true for storage profile nodes (they typically have
+     * better connectivity and uptime), false for transaction profile nodes.
+     */
+    enableRelay?: boolean;
+    /**
+     * Custom libp2p transports. When omitted, the default transports from
+     * `@optimystic/db-p2p` are used (TCP + circuit relay for Node.js).
+     *
+     * React Native apps must supply WebSocket-based transports because TCP
+     * is not available in the RN runtime:
+     * ```typescript
+     * import { webSockets } from '@libp2p/websockets';
+     * import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+     *
+     * network: {
+     *   transports: [webSockets(), circuitRelayTransport()],
+     *   listenAddrs: []  // RN nodes typically cannot listen
+     * }
+     * ```
+     */
+    transports?: Libp2pTransports;
+}
+/**
+ * Hibernation configuration
+ */
+export interface HibernationConfig {
+    enabled: boolean;
+    defaultLatencyHint?: LatencyHint;
+    /** Custom timeouts per latency hint (overrides defaults) */
+    customTimeouts?: Partial<Record<LatencyHint, Partial<HibernationTimeouts>>>;
+}
+/**
+ * Control network configuration
+ */
+export interface ControlNetworkConfig {
+    partyId: string;
+    bootstrapNodes: string[];
+    /** Optional path to the control schema file (defaults to bundled schema) */
+    schemaPath?: string;
+}
+/**
+ * Main configuration for a CadreNode
+ */
+export interface CadreNodeConfig {
+    /** If provided, use this keypair for the node identity */
+    privateKey?: Uint8Array;
+    /** Control network connection settings */
+    controlNetwork: ControlNetworkConfig;
+    /** Node profile: transaction-only or storage */
+    profile: NodeProfile;
+    /** Which strands to participate in */
+    strandFilter?: StrandFilter;
+    /** Storage configuration (only for storage profile) */
+    storage?: StorageConfig;
+    /** Network configuration */
+    network?: NetworkConfig;
+    /** Hibernation configuration */
+    hibernation?: HibernationConfig;
+    /** Polling interval for strand watcher in ms (default: 5000) */
+    strandWatchInterval?: number;
+}
+/**
+ * Status of a strand instance
+ */
+export type StrandStatus = 'starting' | 'active' | 'idle' | 'hibernating' | 'stopping' | 'stopped' | 'error';
+/**
+ * App information from strand header
+ */
+export interface SAppInfo {
+    id: string;
+    version: string;
+    schema: string;
+    signature: string;
+}
+/**
+ * Strand instance state
+ */
+export interface StrandInstance {
+    strandId: string;
+    status: StrandStatus;
+    sAppInfo?: SAppInfo;
+    /** The libp2p node for this strand (only when active/idle) */
+    libp2pNode?: Libp2p;
+    /** The Quereus database for this strand (only when active/idle) */
+    database?: StrandDatabase;
+    /** Membership info for closed strands */
+    memberKey?: string;
+    memberPrivateKey?: string;
+    /** Activity tracking */
+    connectedPeers: number;
+    lastActivity: Date;
+    nextCheckIn?: Date;
+    /** Latency hint from app or override */
+    latencyHint: LatencyHint;
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * Strand row from control network - basic membership info
+ */
+export interface StrandRow {
+    Id: string;
+    MemberPrivateKey: string | null;
+    Type: 'o' | 'c';
+}
+/**
+ * sApp configuration provided by the hosting application when creating a strand.
+ * This is what the app developer provides - NOT loaded from the network.
+ */
+export interface SAppConfig {
+    /** Public key of the sApp author */
+    id: string;
+    /** Version of the sApp */
+    version: string;
+    /** The declarative schema DDL */
+    schema: string;
+    /** Author's signature over the schema for verification */
+    signature: string;
+    /** Latency hint for hibernation behavior (optional, defaults to config) */
+    latencyHint?: LatencyHint;
+}
+/**
+ * Full strand configuration when adding a strand via the API
+ */
+export interface StrandConfig {
+    /** Strand row from control network */
+    strandRow: StrandRow;
+    /** sApp configuration provided by the hosting application */
+    sAppConfig: SAppConfig;
+}
+/**
+ * Result of creating a new cadre peer
+ */
+export interface CreatePeerResult {
+    peerId: PeerId;
+    privateKey: Uint8Array;
+}
+/**
+ * Registration data for joining a strand as a member.
+ * Sent from invited member to any cadre member to accept invitation.
+ */
+export interface MemberRegistration {
+    /** The strand being joined */
+    strandId: string;
+    /** The member's public key for this strand */
+    key: string;
+    /** Peer IDs of the member's cadre nodes that will participate */
+    peerIds: string[];
+}
+/**
+ * Result of member registration
+ */
+export interface MemberRegistrationResult {
+    success: boolean;
+    reason?: string;
+}
+/**
+ * Open invitation for strand formation.
+ * Shared out-of-band to allow strangers to form strands.
+ */
+export interface OpenInvitation {
+    /** Unique token identifying this invitation */
+    token: string;
+    /** The sApp that will be used for the strand */
+    sAppId: string;
+    /** When this invitation expires */
+    expiration: Date;
+    /** Bootstrap addresses to contact the inviter's cadre */
+    bootstrap: string[];
+}
+/**
+ * Result of forming a strand via open invitation
+ */
+export interface FormStrandResult {
+    /** The member key assigned to the initiator for this strand */
+    memberKey: string;
+    /** Private key for the invitation (for signing future messages) */
+    invitePrivateKey: string;
+    /** The strand that was created */
+    strandId: string;
+}
+/**
+ * Result of validating a strand formation request
+ */
+export interface ValidateFormationResult {
+    /** Public key for validating this formation */
+    validationKey: string;
+    /** Signature over the formation approval */
+    validationSignature: string;
+}
+/**
+ * Disclosure object provided during strand formation.
+ * Contains identity and context information from the initiator.
+ */
+export interface StrandFormationDisclosure {
+    /** Initiator's party identifier */
+    partyId?: string;
+    /** Additional identity bundle (app-specific) */
+    identityBundle?: unknown;
+    /** Human-readable purpose/reason for forming the strand */
+    purpose?: string;
+    /** Additional app-specific metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Arachnode ring participation stub - will be implemented when arachnode is built
+ */
+export interface ArachnodeConfig {
+    /** Enable Ring Zulu (transaction ring) - all nodes participate */
+    enableRingZulu: boolean;
+    /** Storage ring participation (storage profile only) */
+    storageRing?: {
+        /** Which ring to participate in based on capacity */
+        ring: number;
+        /** Partition within the ring */
+        partition?: number;
+    };
+}
+/**
+ * Events emitted by CadreNode
+ */
+export interface CadreNodeEvents {
+    'strand:started': {
+        strandId: string;
+    };
+    'strand:stopped': {
+        strandId: string;
+    };
+    'strand:error': {
+        strandId: string;
+        error: Error;
+    };
+    'strand:idle': {
+        strandId: string;
+    };
+    'strand:hibernating': {
+        strandId: string;
+    };
+    'strand:waking': {
+        strandId: string;
+    };
+    'control:connected': void;
+    'control:disconnected': void;
+    /** Emitted when a seed is received via the seed protocol */
+    'seed:received': {
+        partyId: string;
+        peerId: string;
+    };
+    /** Emitted when a seed is successfully applied */
+    'seed:applied': {
+        partyId: string;
+        peersAdded: number;
+    };
+    /** Emitted when seed application fails */
+    'seed:error': {
+        partyId: string;
+        error: string;
+    };
+}
+/**
+ * A peer entry in a control network seed.
+ * Contains connection information for a cadre peer.
+ */
+export interface SeedPeer {
+    /** Peer ID (libp2p identity) */
+    peerId: string;
+    /** Multiaddrs for connecting to this peer */
+    multiaddrs: string[];
+    /** Whether this peer holds an authority key */
+    isAuthority: boolean;
+}
+/**
+ * Control network seed for bootstrapping new nodes.
+ * Pre-populates a new node's cache to solve the cold-start problem:
+ * new nodes need control data to validate connections, but can't get
+ * data without connecting first.
+ */
+export interface ControlNetworkSeed {
+    /** Party ID this seed belongs to */
+    partyId: string;
+    /** Known peers in the cadre */
+    peers: SeedPeer[];
+    /** Optional signed transactions to pre-populate the cache */
+    transactions?: SignedTransaction[];
+    /** Signature over the seed by an authority key */
+    signature: string;
+    /** The authority key that signed this seed */
+    signerKey: string;
+}
+/**
+ * A signed transaction for inclusion in seeds.
+ * Allows pre-populating the control network cache.
+ */
+export interface SignedTransaction {
+    /** Transaction ID */
+    id: string;
+    /** Serialized transaction data */
+    data: string;
+    /** Signature over the transaction */
+    signature: string;
+}
+/**
+ * Message sent from instigator to new node during seed delivery.
+ * Delivered via /sereus/seed/1.0.0 libp2p protocol.
+ */
+export interface SeedMessage {
+    /** Party ID for the cadre */
+    partyId: string;
+    /** Known peers in the cadre */
+    peers: SeedPeer[];
+    /** Optional transactions to pre-populate cache */
+    transactions?: SignedTransaction[];
+    /** Signature by an authority key */
+    signature: string;
+    /** The authority key that signed this message */
+    signerKey: string;
+}
+/**
+ * Acknowledgment message from new node to instigator.
+ */
+export interface SeedAckMessage {
+    /** Whether the seed was accepted */
+    accepted: boolean;
+    /** Reason for rejection (if not accepted) */
+    reason?: string;
+}
+/**
+ * Options for authorizing a new peer in the cadre.
+ */
+export interface AuthorizePeerOptions {
+    /** Peer ID to authorize */
+    peerId: string;
+    /** Optional multiaddrs for the peer */
+    multiaddrs?: string[];
+}
+/**
+ * Result of applying a seed to a node.
+ */
+export interface ApplySeedResult {
+    /** Whether the seed was successfully applied */
+    success: boolean;
+    /** Number of peers added to the peer store */
+    peersAdded: number;
+    /** Error message if not successful */
+    error?: string;
+}
+/**
+ * Node network topology type for seed helper scenarios.
+ */
+export type NodeTopology = 'public' | 'nat';
+/**
+ * Invite code for phone-to-server enrollment.
+ * Used when a server invites a phone to join the cadre.
+ */
+export interface CadreInvite {
+    /** Party ID of the cadre */
+    partyId: string;
+    /** Multiaddrs to dial the authority */
+    authorityAddrs: string[];
+    /** Optional invite token for validation */
+    token?: string;
+    /** Timestamp when invite was created */
+    createdAt: number;
+    /** Optional expiration timestamp */
+    expiresAt?: number;
+}
+/**
+ * Options for adding a drone via provider API.
+ */
+export interface AddDroneOptions {
+    /** Peer ID of the new drone (returned from provider) */
+    dronePeerId: string;
+    /** Multiaddrs of the drone (returned from provider) */
+    droneMultiaddrs: string[];
+}
+/**
+ * Options for adding a phone via invite flow.
+ */
+export interface AddPhoneOptions {
+    /** Peer ID of the phone (sent by phone when it connects) */
+    phonePeerId: string;
+    /** Invite token for validation (must match issued invite) */
+    token?: string;
+}
+/**
+ * Result of preparing a seed for drone initialization.
+ */
+export interface DroneInitResult {
+    /** The seed to send to the provider API */
+    seed: ControlNetworkSeed;
+    /** Base64url encoded seed for transport */
+    encodedSeed: string;
+}
+/**
+ * Result of creating an invite for a phone.
+ */
+export interface InviteResult {
+    /** The invite to share out-of-band */
+    invite: CadreInvite;
+    /** Base64url encoded invite for QR/link */
+    encodedInvite: string;
+}

package/dist/types.js

@@ -0,0 +1,26 @@
+/**
+ * Default hibernation timeouts per latency hint
+ */
+export const HIBERNATION_TIMEOUTS = {
+    realtime: {
+        idleTimeout: Infinity, // Never idle
+        hibernateTimeout: Infinity, // Never hibernate
+        checkInInterval: Infinity // N/A
+    },
+    interactive: {
+        idleTimeout: 5 * 60 * 1000, // 5 minutes
+        hibernateTimeout: 15 * 60 * 1000, // 15 minutes after idle
+        checkInInterval: 30 * 1000 // 30 seconds
+    },
+    background: {
+        idleTimeout: 1 * 60 * 1000, // 1 minute
+        hibernateTimeout: 5 * 60 * 1000, // 5 minutes after idle
+        checkInInterval: 5 * 60 * 1000 // 5 minutes
+    },
+    archive: {
+        idleTimeout: 10 * 1000, // 10 seconds
+        hibernateTimeout: 30 * 1000, // 30 seconds after idle
+        checkInInterval: 60 * 60 * 1000 // 1 hour
+    }
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAmCA;;GAEG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAA6C;IAC5E,QAAQ,EAAE;QACR,WAAW,EAAE,QAAQ,EAAS,aAAa;QAC3C,gBAAgB,EAAE,QAAQ,EAAI,kBAAkB;QAChD,eAAe,EAAE,QAAQ,CAAK,MAAM;KACrC;IACD,WAAW,EAAE;QACX,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,YAAY;QAC1C,gBAAgB,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,EAAE,wBAAwB;QAC1D,eAAe,EAAE,EAAE,GAAG,IAAI,CAAI,aAAa;KAC5C;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAI,WAAW;QACzC,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAG,uBAAuB;QACzD,eAAe,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,CAAI,YAAY;KAC/C;IACD,OAAO,EAAE;QACP,WAAW,EAAE,EAAE,GAAG,IAAI,EAAQ,aAAa;QAC3C,gBAAgB,EAAE,EAAE,GAAG,IAAI,EAAG,wBAAwB;QACtD,eAAe,EAAE,EAAE,GAAG,EAAE,GAAG,IAAI,CAAG,SAAS;KAC5C;CACF,CAAC"}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@serfab/cadre-core",
+  "version": "0.0.2",
+  "type": "module",
+  "description": "Core library for Sereus cadre nodes - manages control networks and strand participation",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gotchoices/sereus.git",
+    "directory": "packages/cadre-core"
+  },
+  "author": "Got Choices Foundation",
+  "license": "MIT",
+  "keywords": [
+    "sereus",
+    "cadre",
+    "core",
+    "distributed",
+    "p2p",
+    "libp2p"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "dev:test": "vitest"
+  },
+  "devDependencies": {
+    "@chainsafe/libp2p-noise": "^17.0.0",
+    "@chainsafe/libp2p-yamux": "^8.0.1",
+    "@libp2p/peer-id-factory": "^4.2.4",
+    "@libp2p/tcp": "^11.0.10",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^25.0.10",
+    "aegir": "^45.2.1",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "dependencies": {
+    "@libp2p/crypto": "^5.1.13",
+    "@libp2p/interface": "^3.1.0",
+    "@libp2p/peer-id": "^6.0.4",
+    "@optimystic/db-core": "^0.5.2",
+    "@optimystic/db-p2p": "^0.2.3",
+    "@optimystic/quereus-plugin-crypto": "^0.4.3",
+    "@optimystic/quereus-plugin-optimystic": "^0.4.2",
+    "@quereus/quereus": "^0.17.0",
+    "@serfab/strand-proto": "^0.1.0",
+    "debug": "^4.4.3",
+    "libp2p": "^3.1.3",
+    "uint8arrays": "^5.1.0"
+  }
+}