@serfab/cadre-core 0.9.0 → 0.11.0

package/src/enrollment.ts

@@ -1,199 +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 };
-  }
-}
-
+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 };
+  }
+}
+

package/src/file-durable-slot.ts

@@ -0,0 +1,61 @@
+/**
+ * Node-only {@link DurableSlot} backend: one JSON file per party under `dir`,
+ * at `<dir>/<name>.<encoded partyId>.json` (0600, atomically replaced on every
+ * save), so one directory can hold the same node-local record for several
+ * parties without cross-party leakage.
+ *
+ * This is the whole platform-specific part of the file-backed node-local
+ * stores (`trusted-owner-store-file.ts`, `bootstrap-peer-store-file.ts`); the
+ * load policy, envelope and write chain are cross-platform in
+ * `node-local-snapshot.ts`. Like its two importers, this module imports
+ * `node:fs/promises`, so it is kept OUT of the package's cross-platform
+ * default entry and is not itself an exported subpath.
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { encodeFileSafeComponent, isNotFound, writeFileAtomically } from './fs-atomic.js';
+import type { DurableSlot } from './node-local-snapshot.js';
+
+export class FileDurableSlot implements DurableSlot {
+	/** Filename-safe form of the party id, shared by the record and temp paths. */
+	private readonly encodedParty: string;
+
+	constructor(
+		private readonly dir: string,
+		private readonly name: string,
+		partyId: string
+	) {
+		this.encodedParty = encodeFileSafeComponent(partyId);
+	}
+
+	/**
+	 * The record's bytes as text. An absent file (ENOENT — including an absent
+	 * directory) is `undefined`, a cold start. Every other read failure
+	 * (EACCES, EISDIR, EIO, …) THROWS, per {@link DurableSlot.load}: the caller
+	 * must not mistake an unreadable file for an empty one and snapshot-write
+	 * over it.
+	 */
+	async load(): Promise<string | undefined> {
+		try {
+			return (await readFile(this.filePath())).toString('utf8');
+		} catch (error) {
+			if (isNotFound(error)) return undefined;
+			throw new Error(`FileDurableSlot: ${this.filePath()} is present but unreadable`, { cause: error });
+		}
+	}
+
+	async save(text: string): Promise<void> {
+		await writeFileAtomically(this.dir, this.tempPath(), this.filePath(), new TextEncoder().encode(text));
+	}
+
+	private filePath(): string {
+		return join(this.dir, `${this.name}.${this.encodedParty}.json`);
+	}
+
+	/** Sibling temp path for the atomic replace (random component: collide-free). */
+	private tempPath(): string {
+		const unique = randomBytes(6).toString('hex');
+		return join(this.dir, `${this.name}.${this.encodedParty}.${unique}.tmp`);
+	}
+}