@serfab/cadre-core 0.0.2

package/src/control-database.ts

@@ -0,0 +1,376 @@
+import debug from 'debug';
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { Database, registerPlugin } from '@quereus/quereus';
+import cryptoPlugin from '@optimystic/quereus-plugin-crypto/plugin';
+import optimysticPlugin from '@optimystic/quereus-plugin-optimystic/plugin';
+import { digest, randomBytes } from '@optimystic/quereus-plugin-crypto';
+import type { Libp2p } from '@libp2p/interface';
+import type { IRepo } from '@optimystic/db-core';
+import type { StrandRow } from './types.js';
+
+const log = debug('sereus:cadre:control-db');
+
+/**
+ * Embedded control schema for cross-platform compatibility.
+ * This schema is embedded directly in the code to work in React Native and other
+ * environments where file system access is not available.
+ */
+const CONTROL_SCHEMA = `-- This manages a Sereus party's cadre, or set of nodes, and their participation in strands (networks)
+declare schema CadreControl {
+    -- A key that can authorize various control changes
+    table AuthorityKey (
+        Key text primary key,
+        constraint Authorized check (
+            -- Bootstrap: first authority key needs no existing authorization
+            (select count(1) from AuthorityKey) <= 1
+
+                -- Old authority can authorize by signature and transaction stamp id (not repeatable)
+                or (old.Key is not null and old.Key = context.AuthorityKey and verify(digest(context.StampId, 'sha256', 'utf8'), context.Signature, old.Key, 'ed25519'))
+
+                -- or other authorities can authorize by signature and transaction stamp id (not repeatable)
+                or exists (select 1 from AuthorityKey A where A.Key = context.AuthorityKey and verify(digest(context.StampId, 'sha256', 'utf8'), context.Signature, A.Key, 'ed25519'))
+        )
+    ) with context (AuthorityKey text null, Signature text null, StampId text);
+
+    -- A key that can validate a strand formation disclosure
+    table ValidationKey (
+        Key text primary key,
+        constraint Authorized check (
+            -- Authorities can authorize by signature and transaction stamp id (not repeatable)
+            exists (select 1 from AuthorityKey A where A.Key = context.AuthorityKey and verify(digest(context.StampId, 'sha256', 'utf8'), context.Signature, A.Key, 'ed25519'))
+        )
+    ) with context (AuthorityKey text, StampId text, Signature text);
+
+    -- A network of members sharing an sApp database, each contributing peer nodes (their cadre) to the overall cohort
+    -- Cadre peers should participate in each of these strands
+    table Strand (
+        Id text primary key,    -- UUID
+        MemberPrivateKey text null unique,   -- Our private key as a member of this strand
+        Type text, -- Types: 'o' = Open, 'c' = Closed -- Open can still control writes in the sApp, but only Closed controls reads
+        constraint Authorized check (
+            -- Authorized by authority signature and transaction stamp id (not repeatable)
+            exists (select 1 from AuthorityKey A where A.Key = context.AuthorityKey and verify(digest(context.StampId, 'sha256', 'utf8'), context.Signature, A.Key, 'ed25519'))
+
+                -- or authorized by a cadre peer who has received a valid formation invitation
+                or exists (select 1 from FormationUsage FU where FU.StrandId = new.Id)
+        ),
+        -- TODO: constraint to ensure member private key only if closed
+    ) with context (AuthorityKey text, StampId text, Signature text);
+
+    -- A peer (node) that is part of the cadre
+    table CadrePeer (
+        PeerId text primary key,
+        Multiaddr text,
+        constraint AuthorizedInsert check on insert, delete (
+            -- Authorized by an authority key
+            -- Use utf8 input encoding since peer IDs are base58btc strings, not base64url
+            exists (select 1 from AuthorityKey A where A.Key = context.AuthorityKey and verify(digest(coalesce(new.PeerId, old.PeerId), 'sha256', 'utf8'), context.Signature, A.Key, 'ed25519'))
+        ),
+        constraint AuthorizedUpdate check on update (
+            -- Peer can change its own multiaddr (using utf8 encoding for both values)
+            verify(digest(new.PeerId, 'sha256', 'utf8') || digest(new.Multiaddr, 'sha256', 'utf8'), context.Signature, new.PeerId, 'ed25519')
+                -- or authorized by an authority key
+                or exists (select 1 from AuthorityKey A where A.Key = context.AuthorityKey and verify(digest(new.PeerId, 'sha256', 'utf8'), context.Signature, A.Key, 'ed25519'))
+        )
+    ) with context (AuthorityKey text null, Signature text);
+
+    -- An open invitation to form a strand with this party
+    table FormationInvite (
+        Token text primary key, -- Just a random string
+        sAppId text, -- The app for the strand that will be formed
+        ExpiresAt datetime null,
+        TotalUses int null check (TotalUses >= 0),
+        ValidationUrl text null,   -- Web hook - send disclosure, IP address...
+        constraint AuthorizedAddOrRemove check on insert, delete (
+            -- Authorized by an authority key to add or remove this invite
+            exists (select 1 from AuthorityKey A where A.Key = context.AuthorityKey and verify(digest(context.StampId), context.Signature, A.Key))
+        )
+    ) with context (AuthorityKey text, StampId text, Signature text);
+
+    table FormationUsage (
+        Token text,
+        UseNumber int,
+        Disclosure text,
+        StrandId text,
+        primary key (Token, UseNumber),
+        constraint InsertOnly check on update, delete (false),
+        constraint Monotonic check (
+            new.UseNumber = coalesce((select max(UseNumber) from FormationUsage U where U.Token = new.Token), 0) + 1
+        ),
+        constraint Authorized check on insert (
+            -- Satisfies an invitation
+            exists (
+                select 1 from FormationInvite FI
+                    where FI.Token = new.Token
+                        and (FI.TotalUses is null or FI.TotalUses >= new.UseNumber)
+                        and (FI.ExpiresAt is null or FI.ExpiresAt > context.Now)
+                        and (FI.ValidationUrl is null or verify(digest(new.Token, new.Disclosure), context.ValidationSignature, context.ValidationKey))
+            )
+        ),
+        constraint StrandExists check (exists (select 1 from Strand S where S.Id = new.StrandId)),
+    ) with context (PeerId text, PeerSignature text, Now datetime, ValidationKey text null, ValidationSignature text null);
+}
+
+apply schema CadreControl;`;
+
+/**
+ * Generate a unique stamp ID for transaction authorization.
+ * Format: 32 bytes base64url encoded
+ * - First 16 bytes: SHA-256 hash of peer ID (for distributed uniqueness)
+ * - Last 16 bytes: Random bytes (for collision resistance)
+ */
+function generateStampId(peerId: string): string {
+  // Hash the peer ID and get first 16 bytes (128 bits)
+  const peerIdHash = digest(peerId, 'sha256', 'utf8', 'bytes') as Uint8Array;
+  const peerIdHashPart = peerIdHash.slice(0, 16);
+
+  // Generate 16 random bytes
+  const randomPart = randomBytes(128, 'bytes') as Uint8Array;
+
+  // Combine peer ID hash and random bytes
+  const combined = new Uint8Array(32);
+  combined.set(peerIdHashPart, 0);
+  combined.set(randomPart, 16);
+
+  // Convert to base64url
+  return uint8ArrayToString(combined, 'base64url');
+}
+
+/**
+ * Minimal interface for the CollectionFactory returned by the optimystic plugin.
+ * We only need the methods we actually use.
+ */
+interface CollectionFactory {
+  registerLibp2pNode(networkName: string, node: Libp2p, coordinatedRepo: IRepo): void;
+  shutdown(): Promise<void>;
+}
+
+/** Result of registering the optimystic plugin */
+interface OptimysticPluginResult {
+  collectionFactory: CollectionFactory;
+  vtables: Array<{ name: string; module: unknown; auxData: unknown }>;
+  functions: Array<{ schema: unknown }>;
+  [key: string]: unknown;
+}
+
+export interface ControlDatabaseConfig {
+  /** Party ID for the control network */
+  partyId: string;
+  /**
+   * Optional path to the control schema file.
+   * If not provided, uses the embedded schema for cross-platform compatibility.
+   * Only use this if you need to override the default schema (e.g., for testing).
+   */
+  schemaPath?: string;
+  /** Libp2p node for the control network (injected) */
+  libp2pNode: Libp2p;
+  /** Coordinated repo from the libp2p node */
+  coordinatedRepo: IRepo;
+}
+
+/**
+ * ControlDatabase manages the CadreControl schema using Quereus with Optimystic backend.
+ * It provides typed query methods for accessing control network data.
+ */
+export class ControlDatabase {
+  private db: Database | null = null;
+  private collectionFactory: CollectionFactory | null = null;
+  private readonly config: ControlDatabaseConfig;
+  private initialized = false;
+
+  constructor(config: ControlDatabaseConfig) {
+    this.config = config;
+  }
+
+  /**
+   * Initialize the database - load schema and register plugins
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      log('ControlDatabase already initialized');
+      return;
+    }
+
+    log('Initializing ControlDatabase for party: %s', this.config.partyId);
+
+    // Create database instance
+    this.db = new Database();
+
+    // Register crypto plugin (provides digest, sign, verify functions)
+    await registerPlugin(this.db, cryptoPlugin);
+    log('Registered crypto plugin');
+
+    // Register optimystic plugin with network transactor as default
+    const networkName = `control-${this.config.partyId}`;
+    const pluginResult = optimysticPlugin(this.db, {
+      default_transactor: 'network',
+      default_key_network: 'libp2p',
+      default_network_name: networkName,
+      enable_cache: true,
+    }) as OptimysticPluginResult;
+
+    // Register vtables and functions manually since we need access to collectionFactory
+    for (const vtable of pluginResult.vtables as Array<{ name: string; module: unknown; auxData: unknown }>) {
+      this.db.registerModule(vtable.name, vtable.module as any, vtable.auxData);
+    }
+    for (const func of pluginResult.functions as Array<{ schema: unknown }>) {
+      this.db.registerFunction(func.schema as any);
+    }
+
+    this.collectionFactory = pluginResult.collectionFactory;
+
+    // Inject the libp2p node into the collection factory
+    this.collectionFactory.registerLibp2pNode(
+      networkName,
+      this.config.libp2pNode,
+      this.config.coordinatedRepo
+    );
+    log('Registered libp2p node with collection factory');
+
+    // Load and execute the schema
+    await this.loadSchema();
+
+    this.initialized = true;
+    log('ControlDatabase initialized successfully');
+  }
+
+  private async loadSchema(): Promise<void> {
+    let schemaContent: string;
+
+    if (this.config.schemaPath) {
+      // Load from file if explicitly provided (for testing or custom schemas)
+      // This only works in Node.js environments
+      log('Loading schema from file: %s', this.config.schemaPath);
+
+      // Check if we're in a Node.js environment
+      if (typeof process !== 'undefined' && process.versions?.node) {
+        try {
+          // Use require to conditionally load fs only in Node.js
+          // This won't be bundled by React Native's Metro bundler
+          const fs = require('fs/promises');
+          schemaContent = await fs.readFile(this.config.schemaPath, 'utf-8');
+        } catch (error) {
+          throw new Error(
+            `Failed to load schema from ${this.config.schemaPath}: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+      } else {
+        throw new Error(
+          'Loading schema from file is not supported in React Native. ' +
+          'Remove the schemaPath option to use the embedded schema instead.'
+        );
+      }
+    } else {
+      // Use embedded schema for cross-platform compatibility
+      log('Using embedded control schema');
+      schemaContent = CONTROL_SCHEMA;
+    }
+
+    await this.db!.exec(schemaContent);
+    log('Schema loaded and executed');
+  }
+
+  /**
+   * Query all strands from the control database
+   */
+  async queryStrands(): Promise<StrandRow[]> {
+    this.ensureInitialized();
+    const results: StrandRow[] = [];
+    for await (const row of this.db!.eval('select Id, MemberPrivateKey, Type from CadreControl.Strand')) {
+      results.push({
+        Id: row.Id as string,
+        MemberPrivateKey: row.MemberPrivateKey as string | null,
+        Type: row.Type as 'o' | 'c',
+      });
+    }
+    return results;
+  }
+
+  /**
+   * Get the underlying database for advanced queries
+   */
+  getDatabase(): Database {
+    this.ensureInitialized();
+    return this.db!;
+  }
+
+  /**
+   * Insert the initial authority key (bootstrap - no existing authorities required)
+   */
+  async insertAuthorityKey(key: string): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting authority key: %s', key);
+
+    // For bootstrap, context values are not verified since no existing authorities
+    // Use fully qualified table name since schema is CadreControl
+    // StampId() provides the transaction's unique stamp from the optimystic transaction
+    await this.db!.exec(`
+      insert into CadreControl.AuthorityKey (Key)
+        with context AuthorityKey = null, Signature = null, StampId = StampId()
+        values ('${key}')
+    `);
+    log('Authority key inserted');
+  }
+
+  /**
+   * Insert a strand into the control database using authority signature.
+   * This starts a transaction, gets the StampId, signs it, and inserts the strand.
+   *
+   * @param strandId - Unique identifier for the strand
+   * @param type - Strand type: 'o' for open, 'c' for closed
+   * @param authorityKey - Public key of the authorizing authority
+   * @param signStampId - Function to sign the stamp ID with the authority's private key
+   * @param memberPrivateKey - Optional private key for membership in closed strands
+   */
+  async insertStrand(
+    strandId: string,
+    type: 'o' | 'c',
+    authorityKey: string,
+    signStampId: (stampId: string) => string,
+    memberPrivateKey?: string
+  ): Promise<void> {
+    this.ensureInitialized();
+    log('Inserting strand: %s (type: %s)', strandId, type);
+
+    const memberKeyValue = memberPrivateKey ? `'${memberPrivateKey}'` : 'null';
+
+    // Generate a unique stamp ID using the peer ID for distributed uniqueness
+    const peerId = this.config.libp2pNode.peerId.toString();
+    const stampId = generateStampId(peerId);
+
+    // Sign the stamp ID with the authority key
+    const signature = signStampId(stampId);
+
+    // Insert with the signed stamp ID
+    await this.db!.exec(`
+      insert into CadreControl.Strand (Id, Type, MemberPrivateKey)
+        with context AuthorityKey = '${authorityKey}', Signature = '${signature}', StampId = '${stampId}'
+        values ('${strandId}', '${type}', ${memberKeyValue})
+    `);
+
+    log('Strand inserted: %s', strandId);
+  }
+
+  /**
+   * Close the database and cleanup resources
+   */
+  async close(): Promise<void> {
+    if (this.collectionFactory) {
+      await this.collectionFactory.shutdown();
+      this.collectionFactory = null;
+    }
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+    this.initialized = false;
+    log('ControlDatabase closed');
+  }
+
+  private ensureInitialized(): void {
+    if (!this.initialized || !this.db) {
+      throw new Error('ControlDatabase not initialized. Call initialize() first.');
+    }
+  }
+}
+

package/src/enrollment.ts

@@ -0,0 +1,199 @@
+import debug from 'debug';
+import { generateKeyPair, privateKeyToProtobuf } from '@libp2p/crypto/keys';
+import { peerIdFromPrivateKey } from '@libp2p/peer-id';
+import type {
+  CreatePeerResult,
+  MemberRegistration,
+  MemberRegistrationResult
+} from './types.js';
+
+const log = debug('sereus:cadre:enrollment');
+
+/**
+ * Interface for verifying member signatures for strand joining
+ */
+export interface MemberVerifier {
+  /**
+   * Verify that the signature is valid for the given member registration
+   * @param registration The member registration data
+   * @param signature The signature to verify
+   * @returns true if signature is valid
+   */
+  verifyMember(registration: MemberRegistration, signature: string): Promise<boolean>;
+
+  /**
+   * Check if the member key is authorized to join the strand
+   * (e.g., was invited via FormationInvite)
+   */
+  isAuthorizedToJoin(strandId: string, memberKey: string): Promise<boolean>;
+}
+
+/**
+ * Interface for registering members in a strand
+ */
+export interface MemberRegistry {
+  /**
+   * Register a member in the strand's member list
+   */
+  registerMember(strandId: string, memberKey: string, peerIds: string[]): Promise<void>;
+
+  /**
+   * Check if a member is already registered in the strand
+   */
+  isMemberRegistered(strandId: string, memberKey: string): Promise<boolean>;
+}
+
+/**
+ * Enrollment API for creating peer identities and managing strand membership
+ *
+ * Peer Creation:
+ *   `createCadrePeer()` generates an Ed25519 keypair for a new node.
+ *   For cadre peer authorization, use the Seed Bootstrap API instead.
+ *
+ * Member Registration:
+ *   Accept invitations to join strands as a member.
+ */
+export class EnrollmentService {
+  private readonly memberVerifier?: MemberVerifier;
+  private readonly memberRegistry?: MemberRegistry;
+
+  constructor(options?: {
+    memberVerifier?: MemberVerifier;
+    memberRegistry?: MemberRegistry;
+  }) {
+    this.memberVerifier = options?.memberVerifier;
+    this.memberRegistry = options?.memberRegistry;
+    log('EnrollmentService created');
+  }
+
+  /**
+   * Create a new cadre peer identity
+   *
+   * Generates a new Ed25519 keypair for a cadre node.
+   * The private key should be stored securely by the node.
+   * The PeerId can be used with the Seed Bootstrap API for authorization.
+   */
+  async createCadrePeer(): Promise<CreatePeerResult> {
+    log('Creating new cadre peer identity');
+
+    // Generate Ed25519 keypair (same as libp2p uses)
+    const privateKey = await generateKeyPair('Ed25519');
+    const peerId = peerIdFromPrivateKey(privateKey);
+
+    // Export private key as protobuf bytes for storage
+    const privateKeyBytes = privateKeyToProtobuf(privateKey);
+
+    log('Created peer with ID: %s', peerId.toString());
+
+    return {
+      peerId,
+      privateKey: privateKeyBytes
+    };
+  }
+
+  // ============================================================================
+  // Member Registration API
+  // ============================================================================
+
+  /**
+   * Register a member into a strand.
+   *
+   * Called by an invited party to accept an invitation and join as a member.
+   * The signature proves ownership of the member key.
+   *
+   * @param registration The member registration data (strandId, key, peerIds)
+   * @param signature Signature over the registration proving key ownership
+   * @returns Success/failure with optional reason
+   */
+  async registerMember(
+    registration: MemberRegistration,
+    signature: string
+  ): Promise<MemberRegistrationResult> {
+    const { strandId, key, peerIds } = registration;
+
+    log('Registering member %s for strand %s with %d peers', key, strandId, peerIds.length);
+
+    // Check required dependencies
+    if (!this.memberVerifier) {
+      log('MemberVerifier not configured');
+      return { success: false, reason: 'MemberVerifier not configured' };
+    }
+
+    if (!this.memberRegistry) {
+      log('MemberRegistry not configured');
+      return { success: false, reason: 'MemberRegistry not configured' };
+    }
+
+    // Verify the signature
+    const isValidSignature = await this.memberVerifier.verifyMember(registration, signature);
+    if (!isValidSignature) {
+      log('Invalid signature for member registration: %s', key);
+      return { success: false, reason: 'Invalid signature' };
+    }
+
+    // Check if member is authorized to join (e.g., has a valid invitation)
+    const isAuthorized = await this.memberVerifier.isAuthorizedToJoin(strandId, key);
+    if (!isAuthorized) {
+      log('Member %s not authorized to join strand %s', key, strandId);
+      return { success: false, reason: 'Not authorized to join strand' };
+    }
+
+    // Check if already registered
+    const alreadyRegistered = await this.memberRegistry.isMemberRegistered(strandId, key);
+    if (alreadyRegistered) {
+      log('Member %s already registered in strand %s', key, strandId);
+      return { success: false, reason: 'Member already registered' };
+    }
+
+    // Register the member
+    try {
+      await this.memberRegistry.registerMember(strandId, key, peerIds);
+      log('Member %s successfully registered in strand %s', key, strandId);
+      return { success: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log('Failed to register member %s: %s', key, message);
+      return { success: false, reason: `Registration failed: ${message}` };
+    }
+  }
+
+  /**
+   * Validate a member registration without actually registering
+   * Useful for pre-flight checks
+   */
+  async validateMemberRegistration(
+    registration: MemberRegistration,
+    signature: string
+  ): Promise<{ valid: boolean; reason?: string }> {
+    const { strandId, key } = registration;
+
+    if (!this.memberVerifier) {
+      return { valid: false, reason: 'MemberVerifier not configured' };
+    }
+
+    if (!this.memberRegistry) {
+      return { valid: false, reason: 'MemberRegistry not configured' };
+    }
+
+    // Verify signature
+    const isValidSignature = await this.memberVerifier.verifyMember(registration, signature);
+    if (!isValidSignature) {
+      return { valid: false, reason: 'Invalid signature' };
+    }
+
+    // Check authorization
+    const isAuthorized = await this.memberVerifier.isAuthorizedToJoin(strandId, key);
+    if (!isAuthorized) {
+      return { valid: false, reason: 'Not authorized to join strand' };
+    }
+
+    // Check if already registered
+    const alreadyRegistered = await this.memberRegistry.isMemberRegistered(strandId, key);
+    if (alreadyRegistered) {
+      return { valid: false, reason: 'Member already registered' };
+    }
+
+    return { valid: true };
+  }
+}
+