@serfab/cadre-core 0.6.0 → 0.8.1

package/README.md

@@ -91,12 +91,14 @@ await node.stop();
 
 ## Node Profiles
 
-| Profile | Storage Role | Use Case | Ring Participation |
-|---------|--------------|----------|-------------------|
-| **transaction** | Ring Zulu only | Mobile devices, intermittent connectivity | Transaction verification, caching |
-| **storage** | Ring Zulu + Storage Rings | Servers, NAS, always-on nodes | Full archival storage |
+| Profile | Storage Role | Use Case | Ring Zulu |
+|---------|--------------|----------|-----------|
+| **transaction** | Arachnode disabled; transaction verification via FRET only | Mobile devices, intermittent connectivity | No |
+| **storage** | Ring Zulu + storage rings (storage rings not yet implemented — stub) | Servers, NAS, always-on nodes | Yes |
 
-Both profiles participate in transaction consensus. The distinction is long-term storage commitment.
+Transaction-profile nodes verify transactions via FRET only, with Arachnode disabled. Storage-profile nodes additionally join Ring Zulu and (when implemented) the concentric storage rings.
+
+> **Note:** The storage-ring subsystem is currently a no-op stub (`arachnode-stub.ts`). See [Node Profiles in `docs/architecture.md`](../../docs/architecture.md#node-profiles) for the full design.
 
 ## Strand Filtering
 
@@ -104,7 +106,7 @@ Mobile apps typically shouldn't participate in all strands. Use filters to contr
 
 ```typescript
 // Only participate in strands for a specific app
-strandFilter: { mode: 'appId', appId: 'com.example.chat' }
+strandFilter: { mode: 'sAppId', sAppId: 'com.example.chat' }
 
 // Only participate in one specific strand
 strandFilter: { mode: 'strandId', strandId: 'strand-abc123' }
@@ -151,7 +153,7 @@ const { seed, encodedSeed } = await node.addDrone({
 });
 
 // Send to provider for drone initialization
-await provider.applySeed(droneInfo.containerId, encodedSeed);
+await provider.initializeNode(droneInfo.containerId, encodedSeed);
 ```
 
 ## API Reference
@@ -240,7 +242,6 @@ Available storage implementations:
 
 ## Related Packages
 
-- **[@serfab/strand-proto](../strand-proto/)** - Strand initialization protocol
 - **[@optimystic/db-core](https://github.com/gotchoices/optimystic)** - Distributed database core
 - **[@optimystic/db-p2p](https://github.com/gotchoices/optimystic)** - libp2p integration for Optimystic
 - **[@optimystic/db-p2p-storage-fs](https://github.com/gotchoices/optimystic)** - File system storage (Node.js)

package/dist/authority-key.d.ts

@@ -0,0 +1,41 @@
+import type { PrivateKey } from '@libp2p/interface';
+/**
+ * A household authority keypair expressed in the base64url Ed25519 form that
+ * `@optimystic/quereus-plugin-crypto` (`sign`/`verify`/`getPublicKey`) consumes.
+ */
+export interface AuthorityKeyPair {
+    /** 32-byte Ed25519 seed, base64url-encoded — the crypto-plugin private key. */
+    privateKeyB64: string;
+    /** 32-byte Ed25519 public key, base64url-encoded. */
+    publicKeyB64: string;
+}
+/**
+ * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
+ * control-database authority constraints.
+ *
+ * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
+ * seed (the actual scalar source), the last 32 are the public key — see
+ * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
+ * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
+ * derives the public key from it with standard Ed25519. The two derivations
+ * agree, so the node's peer identity and its authority key are one keypair:
+ * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns The base64url seed/public-key pair for authority operations.
+ * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
+ */
+export declare function authorityKeyFromLibp2p(privateKey: PrivateKey): AuthorityKeyPair;
+/**
+ * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
+ * — the same derivation the seed-bootstrap signer uses internally
+ * (`SeedBootstrapService` constructor). Use this to enroll a standalone
+ * (non-libp2p) authority key into the control DB via
+ * `ControlDatabase.ensureAuthorityKey` before minting an invite, when the
+ * authority key is *not* the node's peer identity (so `authorityKeyFromLibp2p`,
+ * which needs a libp2p key object, does not apply).
+ *
+ * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
+ * @returns The base64url-encoded Ed25519 public key.
+ */
+export declare function authorityPublicKeyFromPrivate(privateKeyB64: string): string;

package/dist/authority-key.js

@@ -0,0 +1,52 @@
+import { toString as uint8ArrayToString } from 'uint8arrays';
+import { getPublicKey } from '@optimystic/quereus-plugin-crypto';
+/**
+ * Bridge a libp2p Ed25519 private key into the base64url keypair used by the
+ * control-database authority constraints.
+ *
+ * libp2p stores an Ed25519 private key as 64 raw bytes: the first 32 are the
+ * seed (the actual scalar source), the last 32 are the public key — see
+ * `@libp2p/crypto`'s `Ed25519PrivateKey`. `@optimystic/quereus-plugin-crypto`
+ * (via `@noble/curves`) treats the 32-byte seed *as* the private key and
+ * derives the public key from it with standard Ed25519. The two derivations
+ * agree, so the node's peer identity and its authority key are one keypair:
+ * `getPublicKey(privateKeyB64)` === `publicKeyB64`.
+ *
+ * @param privateKey - The node's libp2p Ed25519 private key.
+ * @returns The base64url seed/public-key pair for authority operations.
+ * @throws If the key is not Ed25519 or the raw bytes aren't the expected length.
+ */
+export function authorityKeyFromLibp2p(privateKey) {
+    if (privateKey.type !== 'Ed25519') {
+        throw new Error(`authorityKeyFromLibp2p requires an Ed25519 key, got ${privateKey.type}`);
+    }
+    const raw = privateKey.raw;
+    if (raw.length !== 64) {
+        throw new Error(`Expected a 64-byte Ed25519 raw private key (seed||public), got ${raw.length} bytes`);
+    }
+    const seed = raw.subarray(0, 32);
+    const publicKeyRaw = privateKey.publicKey.raw;
+    if (publicKeyRaw.length !== 32) {
+        throw new Error(`Expected a 32-byte Ed25519 public key, got ${publicKeyRaw.length} bytes`);
+    }
+    return {
+        privateKeyB64: uint8ArrayToString(seed, 'base64url'),
+        publicKeyB64: uint8ArrayToString(publicKeyRaw, 'base64url'),
+    };
+}
+/**
+ * Derive the base64url Ed25519 public key from a base64url 32-byte private seed
+ * — the same derivation the seed-bootstrap signer uses internally
+ * (`SeedBootstrapService` constructor). Use this to enroll a standalone
+ * (non-libp2p) authority key into the control DB via
+ * `ControlDatabase.ensureAuthorityKey` before minting an invite, when the
+ * authority key is *not* the node's peer identity (so `authorityKeyFromLibp2p`,
+ * which needs a libp2p key object, does not apply).
+ *
+ * @param privateKeyB64 - The base64url-encoded 32-byte Ed25519 seed.
+ * @returns The base64url-encoded Ed25519 public key.
+ */
+export function authorityPublicKeyFromPrivate(privateKeyB64) {
+    return getPublicKey(privateKeyB64, 'ed25519', 'base64url', 'base64url');
+}
+//# sourceMappingURL=authority-key.js.map

package/dist/authority-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority-key.js","sourceRoot":"","sources":["../src/authority-key.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAcjE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,sBAAsB,CAAC,UAAsB;IAC3D,IAAI,UAAU,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,uDAAuD,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,GAAG,GAAG,UAAU,CAAC,GAAG,CAAC;IAC3B,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,kEAAkE,GAAG,CAAC,MAAM,QAAQ,CAAC,CAAC;IACxG,CAAC;IAED,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACjC,MAAM,YAAY,GAAG,UAAU,CAAC,SAAS,CAAC,GAAG,CAAC;IAC9C,IAAI,YAAY,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,8CAA8C,YAAY,CAAC,MAAM,QAAQ,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO;QACL,aAAa,EAAE,kBAAkB,CAAC,IAAI,EAAE,WAAW,CAAC;QACpD,YAAY,EAAE,kBAAkB,CAAC,YAAY,EAAE,WAAW,CAAC;KAC5D,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,6BAA6B,CAAC,aAAqB;IACjE,OAAO,YAAY,CAAC,aAAa,EAAE,SAAS,EAAE,WAAW,EAAE,WAAW,CAAW,CAAC;AACpF,CAAC"}