@serfab/cadre-core 0.0.2

package/src/strand-instance-manager.ts

@@ -0,0 +1,281 @@
+import debug from 'debug';
+import type { Libp2p } from '@libp2p/interface';
+import { createLibp2pNode, type IRawStorage } from '@optimystic/db-p2p';
+import type { IRepo } from '@optimystic/db-core';
+import { StrandDatabase } from './strand-database.js';
+import type {
+  StrandInstance,
+  StrandRow,
+  StorageConfig,
+  NetworkConfig,
+  LatencyHint,
+  NodeProfile,
+  SAppConfig,
+  SAppInfo,
+  RawStorageProvider
+} from './types.js';
+
+/**
+ * Extended Libp2p node with coordinatedRepo attached by createLibp2pNode.
+ * The db-p2p createLibp2pNode function attaches these properties after node creation.
+ */
+interface Libp2pNodeWithRepo extends Libp2p {
+  coordinatedRepo: IRepo;
+}
+
+const log = debug('sereus:cadre:strand-manager');
+
+/**
+ * Configuration for starting a strand instance
+ */
+export interface StartStrandConfig {
+  strandRow: StrandRow;
+  /** sApp configuration provided by the hosting application */
+  sAppConfig: SAppConfig;
+  storage?: StorageConfig;
+  network?: NetworkConfig;
+  profile: NodeProfile;
+  defaultLatencyHint: LatencyHint;
+}
+
+/**
+ * Get the isolated storage path for a specific strand.
+ *
+ * @deprecated This function uses Node.js path module which is not available in React Native.
+ * Use a storage provider factory function instead, which receives the strandId and can
+ * create strand-specific storage paths using platform-appropriate methods.
+ *
+ * @example
+ * // Instead of using getStrandStoragePath, use a storage provider factory:
+ * const storage = {
+ *   provider: (strandId: string) => new FileRawStorage(`./data/strands/${strandId}`)
+ * };
+ */
+export function getStrandStoragePath(basePath: string, strandId: string): string {
+  // Check if we're in a Node.js environment
+  if (typeof process === 'undefined' || !process.versions?.node) {
+    throw new Error(
+      'getStrandStoragePath is not available in React Native. ' +
+      'Use a storage provider factory function instead.'
+    );
+  }
+
+  // Dynamically require path only in Node.js
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const path = require('path');
+
+  // Sanitize strandId for filesystem safety (UUIDs should be safe, but just in case)
+  const safeId = strandId.replace(/[^a-zA-Z0-9-]/g, '_');
+  return path.join(basePath, 'strands', safeId);
+}
+
+/**
+ * Resolve a storage provider for a specific strand.
+ * If the provider is a factory function, call it with the strandId.
+ *
+ * @param provider - Storage provider (instance or factory)
+ * @param strandId - The strand ID to create storage for
+ * @returns The resolved IRawStorage instance, or undefined if no provider
+ */
+function resolveStrandStorage(
+  provider: RawStorageProvider | undefined,
+  strandId: string
+): IRawStorage | undefined {
+  if (!provider) {
+    return undefined;
+  }
+  return typeof provider === 'function' ? provider(strandId) : provider;
+}
+
+/**
+ * Manages individual strand instances - creates and destroys isolated libp2p nodes
+ * for each strand the cadre participates in.
+ */
+export class StrandInstanceManager {
+  private instances: Map<string, StrandInstance> = new Map();
+  private stopping = false;
+
+  constructor() {
+    log('StrandInstanceManager created');
+  }
+
+  /**
+   * Get all current strand instances
+   */
+  getInstances(): Map<string, StrandInstance> {
+    return new Map(this.instances);
+  }
+
+  /**
+   * Get a specific strand instance
+   */
+  getInstance(strandId: string): StrandInstance | undefined {
+    return this.instances.get(strandId);
+  }
+
+  /**
+   * Check if a strand is currently running
+   */
+  hasStrand(strandId: string): boolean {
+    return this.instances.has(strandId);
+  }
+
+  /**
+   * Start a new strand instance
+   */
+  async startStrand(config: StartStrandConfig): Promise<StrandInstance> {
+    const { strandRow, sAppConfig } = config;
+    const strandId = strandRow.Id;
+
+    if (this.stopping) {
+      throw new Error('StrandInstanceManager is stopping');
+    }
+
+    if (this.instances.has(strandId)) {
+      log('Strand %s already running', strandId);
+      return this.instances.get(strandId)!;
+    }
+
+    log('Starting strand instance: %s (sApp: %s v%s)', strandId, sAppConfig.id, sAppConfig.version);
+
+    // Convert SAppConfig to SAppInfo for the instance
+    const sAppInfo: SAppInfo = {
+      id: sAppConfig.id,
+      version: sAppConfig.version,
+      schema: sAppConfig.schema,
+      signature: sAppConfig.signature
+    };
+
+    // Determine latency hint: sApp config > default
+    const latencyHint = sAppConfig.latencyHint ?? config.defaultLatencyHint;
+
+    const instance: StrandInstance = {
+      strandId,
+      status: 'starting',
+      sAppInfo,
+      memberPrivateKey: strandRow.MemberPrivateKey ?? undefined,
+      connectedPeers: 0,
+      lastActivity: new Date(),
+      latencyHint
+    };
+
+    this.instances.set(strandId, instance);
+
+    try {
+      // Resolve storage for this strand
+      // If a factory function is provided, it will be called with the strandId
+      // to create strand-specific storage (e.g., strand-isolated directories)
+      const strandStorage = resolveStrandStorage(config.storage?.provider, strandId);
+      if (strandStorage) {
+        log('Strand %s using provided storage provider', strandId);
+      }
+
+      // Create isolated libp2p node for this strand
+      // Note: protocolPrefix would be used by libp2p services, but createLibp2pNode
+      // may not support it yet - tracked for future implementation
+      const _protocolPrefix = `/sereus/strand/${strandId}`;
+
+      // Determine relay mode: if explicitly set in config, use that;
+      // otherwise default to true for storage profile nodes
+      const enableRelay = config.network?.enableRelay ?? (config.profile === 'storage');
+
+      const node = await createLibp2pNode({
+        port: 0, // Random port
+        bootstrapNodes: [], // Will be populated from strand cohort
+        networkName: `strand-${strandId}`,
+        storage: strandStorage,
+        fretProfile: config.profile === 'storage' ? 'core' : 'edge',
+        relay: enableRelay,
+        clusterSize: 3,
+        clusterPolicy: {
+          allowDownsize: true,
+          sizeTolerance: 0.5
+        },
+        arachnode: {
+          enableRingZulu: true
+          // Storage ring participation stub - will be added when arachnode is built
+          // storageRing: config.profile === 'storage' ? { ring: 0 } : undefined
+        },
+        ...(config.network?.transports && { transports: config.network.transports }),
+        ...(config.network?.listenAddrs && { listenAddrs: config.network.listenAddrs })
+      }) as Libp2pNodeWithRepo;
+
+      instance.libp2pNode = node;
+
+      // Create and initialize the StrandDatabase
+      const strandDb = new StrandDatabase({
+        strandId,
+        sAppConfig,
+        libp2pNode: node,
+        coordinatedRepo: node.coordinatedRepo
+      });
+      await strandDb.initialize();
+      instance.database = strandDb;
+
+      instance.status = 'active';
+      instance.lastActivity = new Date();
+
+      log('Strand %s started successfully with sApp %s', strandId, sAppConfig.id);
+      return instance;
+
+    } catch (error) {
+      instance.status = 'error';
+      instance.error = error instanceof Error ? error.message : String(error);
+      log('Failed to start strand %s: %s', strandId, instance.error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop a strand instance
+   */
+  async stopStrand(strandId: string): Promise<void> {
+    const instance = this.instances.get(strandId);
+    if (!instance) {
+      log('Strand %s not found', strandId);
+      return;
+    }
+
+    log('Stopping strand instance: %s', strandId);
+    instance.status = 'stopping';
+
+    try {
+      // Close the database before stopping libp2p
+      if (instance.database) {
+        await instance.database.close();
+        instance.database = undefined;
+      }
+      if (instance.libp2pNode) {
+        await instance.libp2pNode.stop();
+        instance.libp2pNode = undefined;
+      }
+      instance.status = 'stopped';
+      this.instances.delete(strandId);
+      log('Strand %s stopped successfully', strandId);
+    } catch (error) {
+      instance.status = 'error';
+      instance.error = error instanceof Error ? error.message : String(error);
+      log('Error stopping strand %s: %s', strandId, instance.error);
+      throw error;
+    }
+  }
+
+  /**
+   * Stop all strand instances
+   */
+  async stopAll(): Promise<void> {
+    this.stopping = true;
+    log('Stopping all strand instances (%d)', this.instances.size);
+    
+    const stopPromises = Array.from(this.instances.keys()).map(id => 
+      this.stopStrand(id).catch(err => {
+        log('Error stopping strand %s during shutdown: %s', id, err);
+      })
+    );
+    
+    await Promise.all(stopPromises);
+    this.stopping = false;
+    log('All strand instances stopped');
+  }
+}
+

package/src/strand-solicitation.ts

@@ -0,0 +1,318 @@
+import debug from 'debug';
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { generateKeyPair, privateKeyToProtobuf } from '@libp2p/crypto/keys';
+import { peerIdFromPrivateKey } from '@libp2p/peer-id';
+import type { Libp2p } from '@libp2p/interface';
+import type {
+  OpenInvitation,
+  FormStrandResult,
+  ValidateFormationResult,
+  StrandFormationDisclosure
+} from './types.js';
+import {
+  StrandFormationManager,
+  type StrandFormationManagerConfig
+} from './strand-formation-manager.js';
+
+const log = debug('sereus:cadre:solicitation');
+
+/**
+ * Interface for validating formation disclosures
+ */
+export interface DisclosureValidator {
+  /**
+   * Validate the disclosure provided by an initiator
+   * @param token The invitation token
+   * @param disclosure The disclosure object from the initiator
+   * @returns Whether the disclosure is acceptable
+   */
+  validateDisclosure(token: string, disclosure: StrandFormationDisclosure): Promise<boolean>;
+}
+
+/**
+ * Interface for recording formation usage
+ */
+export interface FormationUsageRecorder {
+  /**
+   * Record that a formation invite was used
+   */
+  recordUsage(token: string, initiatorKey: string, strandId: string): Promise<void>;
+
+  /**
+   * Check if a token has already been used (for single-use invites)
+   */
+  isTokenUsed(token: string): Promise<boolean>;
+
+  /**
+   * Check if a token is valid and not expired
+   */
+  isTokenValid(token: string): Promise<{ valid: boolean; invitation?: OpenInvitation }>;
+}
+
+/**
+ * Interface for strand provisioning during formation
+ */
+export interface StrandProvisioner {
+  /**
+   * Provision a new strand after formation is validated
+   */
+  provisionStrand(
+    sAppId: string,
+    initiatorKey: string,
+    responderKey: string
+  ): Promise<{ strandId: string }>;
+}
+
+/**
+ * Interface for signing formation approvals
+ */
+export interface FormationSigner {
+  /**
+   * Sign a formation approval
+   */
+  signFormation(token: string, disclosure: StrandFormationDisclosure): Promise<{
+    validationKey: string;
+    validationSignature: string;
+  }>;
+}
+
+export interface StrandSolicitationServiceOptions {
+  disclosureValidator?: DisclosureValidator;
+  formationUsageRecorder?: FormationUsageRecorder;
+  strandProvisioner?: StrandProvisioner;
+  formationSigner?: FormationSigner;
+  /** Party ID for this node (used in protocol messages) */
+  partyId?: string;
+  /** Cadre peer addresses for this node */
+  cadrePeerAddrs?: string[];
+  /** Configuration for the formation manager */
+  formationConfig?: StrandFormationManagerConfig;
+}
+
+/**
+ * Strand Solicitation API for forming strands via open invitations.
+ *
+ * This service handles the high-level API defined in api.md:
+ * - formStrand(invitation, disclosure, node) - called by initiator
+ * - validateStrandFormation(token, disclosure) - called by responder
+ *
+ * When a libp2p node is provided, the underlying protocol is handled by
+ * strand-proto's SessionManager via StrandFormationManager.
+ */
+export class StrandSolicitationService {
+  private readonly disclosureValidator?: DisclosureValidator;
+  private readonly formationUsageRecorder?: FormationUsageRecorder;
+  private readonly strandProvisioner?: StrandProvisioner;
+  private readonly formationSigner?: FormationSigner;
+  private readonly partyId: string;
+  private readonly cadrePeerAddrs: string[];
+  private formationManager?: StrandFormationManager;
+  private readonly formationConfig?: StrandFormationManagerConfig;
+
+  constructor(options?: StrandSolicitationServiceOptions) {
+    this.disclosureValidator = options?.disclosureValidator;
+    this.formationUsageRecorder = options?.formationUsageRecorder;
+    this.strandProvisioner = options?.strandProvisioner;
+    this.formationSigner = options?.formationSigner;
+    this.partyId = options?.partyId ?? `party-${Date.now()}`;
+    this.cadrePeerAddrs = options?.cadrePeerAddrs ?? [];
+    this.formationConfig = options?.formationConfig;
+    log('StrandSolicitationService created for party: %s', this.partyId);
+  }
+
+  /**
+   * Get or create the StrandFormationManager.
+   * Lazily initialized to allow configuration after construction.
+   */
+  private getFormationManager(): StrandFormationManager {
+    if (!this.formationManager) {
+      this.formationManager = new StrandFormationManager({
+        disclosureValidator: this.disclosureValidator,
+        formationUsageRecorder: this.formationUsageRecorder,
+        strandProvisioner: this.strandProvisioner,
+        partyId: this.partyId,
+        cadrePeerAddrs: this.cadrePeerAddrs,
+        config: this.formationConfig
+      });
+    }
+    return this.formationManager;
+  }
+
+  /**
+   * Register as a responder on a libp2p node.
+   * This enables the node to handle incoming strand formation requests.
+   */
+  registerResponder(node: Libp2p): void {
+    this.getFormationManager().registerResponder(node);
+    log('Registered as responder');
+  }
+
+  /**
+   * Unregister as a responder from a libp2p node.
+   */
+  unregisterResponder(node: Libp2p): void {
+    this.getFormationManager().unregisterResponder(node);
+    log('Unregistered as responder');
+  }
+
+  /**
+   * Form a strand with a responder via an open invitation.
+   *
+   * Called by the initiator (the party who received an out-of-band invitation).
+   * This generates a member key, contacts the responder's cadre, and negotiates
+   * strand formation.
+   *
+   * @param invitation The open invitation (or just token for legacy API)
+   * @param disclosure Identity/context information to share with the responder
+   * @param node Optional libp2p node for real protocol handling
+   * @returns The member key and strand info if successful
+   */
+  async formStrand(
+    invitation: OpenInvitation | string,
+    disclosure: StrandFormationDisclosure,
+    node?: Libp2p
+  ): Promise<FormStrandResult> {
+    // Handle legacy API where just token was passed
+    const token = typeof invitation === 'string' ? invitation : invitation.token;
+    log('Forming strand with token: %s', token);
+
+    // Generate a new keypair for this strand membership
+    const privateKey = await generateKeyPair('Ed25519');
+    const peerId = peerIdFromPrivateKey(privateKey);
+    const privateKeyBytes = privateKeyToProtobuf(privateKey);
+
+    const memberKey = peerId.toString();
+    const invitePrivateKey = uint8ArrayToString(privateKeyBytes, 'base64');
+
+    log('Generated member key: %s', memberKey);
+
+    // If we have a full invitation and a node, use the real protocol
+    if (typeof invitation !== 'string' && node) {
+      log('Using strand-proto for real protocol handling');
+      const result = await this.getFormationManager().formStrand(
+        invitation,
+        { ...disclosure, partyId: memberKey },
+        node
+      );
+      return {
+        memberKey,
+        invitePrivateKey,
+        strandId: result.strandId
+      };
+    }
+
+    // Fallback: placeholder strandId (for testing without network)
+    log('No node provided, using placeholder strandId');
+    const strandId = `strand-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+    return {
+      memberKey,
+      invitePrivateKey,
+      strandId
+    };
+  }
+
+  /**
+   * Validate a strand formation request.
+   *
+   * Called by the responder (the party who created the open invitation) when
+   * an initiator contacts them to form a strand. Validates the disclosure
+   * and returns a signed approval.
+   *
+   * @param token The invitation token being used
+   * @param disclosure The disclosure from the initiator
+   * @returns Validation key and signature if approved
+   * @throws If validation fails or token is invalid
+   */
+  async validateStrandFormation(
+    token: string,
+    disclosure: StrandFormationDisclosure
+  ): Promise<ValidateFormationResult> {
+    log('Validating strand formation for token: %s', token);
+
+    // Check token validity
+    if (this.formationUsageRecorder) {
+      const tokenCheck = await this.formationUsageRecorder.isTokenValid(token);
+      if (!tokenCheck.valid) {
+        log('Token invalid or expired: %s', token);
+        throw new Error('Invalid or expired token');
+      }
+
+      // Check if already used (for single-use tokens)
+      const isUsed = await this.formationUsageRecorder.isTokenUsed(token);
+      if (isUsed) {
+        log('Token already used: %s', token);
+        throw new Error('Token has already been used');
+      }
+    }
+
+    // Validate the disclosure
+    if (this.disclosureValidator) {
+      const isValid = await this.disclosureValidator.validateDisclosure(token, disclosure);
+      if (!isValid) {
+        log('Disclosure validation failed for token: %s', token);
+        throw new Error('Disclosure validation failed');
+      }
+    }
+
+    // Sign the formation approval
+    if (!this.formationSigner) {
+      throw new Error('FormationSigner not configured');
+    }
+
+    const { validationKey, validationSignature } = await this.formationSigner.signFormation(
+      token,
+      disclosure
+    );
+
+    log('Formation validated, key: %s', validationKey);
+
+    return {
+      validationKey,
+      validationSignature
+    };
+  }
+
+  /**
+   * Create an open invitation for others to form strands with this party.
+   *
+   * @param sAppId The sApp to use for formed strands
+   * @param expirationMs How long the invitation is valid (ms from now)
+   * @param bootstrap Bootstrap addresses for contacting this party's cadre
+   * @returns The open invitation to share out-of-band
+   */
+  async createOpenInvitation(
+    sAppId: string,
+    expirationMs: number,
+    bootstrap: string[]
+  ): Promise<OpenInvitation> {
+    // Generate a unique token
+    const token = `invite-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    const expiration = new Date(Date.now() + expirationMs);
+
+    log('Created open invitation: %s (expires %s)', token, expiration.toISOString());
+
+    return {
+      token,
+      sAppId,
+      expiration,
+      bootstrap
+    };
+  }
+
+  /**
+   * Record that a formation was completed successfully.
+   * Called after strand provisioning to track usage.
+   */
+  async recordFormationComplete(
+    token: string,
+    initiatorKey: string,
+    strandId: string
+  ): Promise<void> {
+    if (this.formationUsageRecorder) {
+      await this.formationUsageRecorder.recordUsage(token, initiatorKey, strandId);
+      log('Recorded formation usage: token=%s strand=%s', token, strandId);
+    }
+  }
+}
+