@serfab/quereus-plugin-sereus 0.8.0

package/src/strand-schema.ts

@@ -0,0 +1,160 @@
+/**
+ * Embedded strand membership/RBAC schema for cross-platform compatibility.
+ *
+ * This is the authoritative runtime copy of the `Strand` membership schema. It
+ * is duplicated from `schemas/strand.qsql` so that React Native and other
+ * filesystem-less environments get the schema without a runtime file read —
+ * the same pattern `CONTROL_SCHEMA` (cadre-core) uses for the control schema.
+ *
+ * `STRAND_SCHEMA` holds only the *body* (the inner table declarations). The
+ * shared composition (`composeStrand`) wraps it in
+ * `declare schema Strand { ... } apply schema Strand;`, mirroring how the sApp
+ * schema is wrapped in `declare schema App { ... }`.
+ *
+ * Drift discipline: the table declarations here MUST stay byte-equivalent to the
+ * body of `schemas/strand.qsql` (the on-disk canonical copy). Any edit here must
+ * be mirrored there and vice versa — the same invariant the planned
+ * `control-schema-drift-guard` enforces for the control schema.
+ *
+ * Crypto idiom (matches `schemas/control.qsql` and the sApp RBAC fixture
+ * `packages/integration-tests/fixtures/simple-sapp.qsql`): every signed write
+ * proves itself with `verify(digest(<concatenated payload>, 'sha256', 'utf8'),
+ * <signature>, <pubkey>, 'ed25519')`. Member keys are ed25519, so the explicit
+ * curve arg is REQUIRED (verify() otherwise defaults to secp256k1).
+ *
+ * Population note: this ticket applies the schema and makes its constraints
+ * active — it does NOT write membership rows at runtime. Inserting the `Header`,
+ * the founding `Authority`/`Member`, and the invite/peer flows is owned by
+ * `strand-membership-lifecycle-population`.
+ */
+export const STRAND_SCHEMA = `    table Header (
+        Id text,    -- UUID of this network - generated at inception - immutable
+
+        -- Types: 'o' = Open, 'c' = Closed
+        -- Any peers can join an open network, but only members can join a closed network
+        -- Open can still control writes in the app, but only Closed prevents reads
+        Type text check (Type in ('o', 'c')),
+
+        -- The app that this strand faciliates - public key from author to prevent tampering
+        sAppId text,
+
+        -- The version of the sApp that this strand faciliates
+        sAppVersion text,
+
+        -- The schema of the sApp that this strand faciliates
+        sAppSchema text,
+
+        -- The author's signature on the schema to guarantee authorship
+        sAppSignature text,
+
+        -- The engine (rules logic system) that is assumed to manage this strand
+        Engine text,
+
+        -- The version of the engine that is assumed to manage this strand
+        EngineVersion text,
+
+        primary key (/* empty - singleton */),
+        constraint InsertOnly check on update, delete (false),  -- One-time insert only for now - TODO: revisit for versioning
+    );
+
+    -- An invitation to join a strand as a member
+    table Invite (
+        Key text primary key,
+        Expiration datetime null,
+        -- TODO: ability to deactivate?
+        constraint InsertOnly check on update, delete (false),
+        constraint OnlyClosed check (
+            exists (select 1 from Header H where H.Type = 'c')
+        ),
+        constraint InviteValid check on insert (
+            -- Can only be inserted by an authority,
+            exists (select 1 from Authority A
+                where A.MemberKey = context.AuthorityKey
+                    and verify(digest(new.Key || '|' || coalesce(new.Expiration, ''), 'sha256', 'utf8'), context.AuthoritySignature, A.MemberKey, 'ed25519')
+            )
+                -- and must also prove invite private key held by issuing authority
+                and verify(digest(new.Key || '|' || coalesce(new.Expiration, ''), 'sha256', 'utf8'), context.InviteSignature, new.Key, 'ed25519')
+        )
+    ) with context (AuthorityKey text null, AuthoritySignature text null, InviteSignature text null);
+
+    -- Invite [InviteKey] has been used to add [MemberKey] as a member
+    table ConsumedInvite (
+        InviteKey text primary key,
+        MemberKey text,
+        constraint InsertOnly check on update, delete (false),
+        constraint InviteExists check (exists (select 1 from Invite I where I.Key = new.InviteKey)),
+        constraint MemberExists check (exists (select 1 from Member M where M.Key = new.MemberKey)),
+        constraint ValidUsage check on insert (
+            exists (select 1 from Invite I where I.Key = new.InviteKey and verify(digest(new.InviteKey || '|' || new.MemberKey, 'sha256', 'utf8'), context.InviteSignature, new.InviteKey, 'ed25519'))
+        ),
+        constraint MemberValid check (exists (select 1 from Member M where M.Key = new.MemberKey))
+    ) with context (InviteSignature text null);
+
+    -- A party in the closed strand network
+    table Member (
+        Key text primary key,
+        constraint NoUpdate check on update (false),
+        constraint OnlyClosed check (
+            exists (select 1 from Header H where H.Type = 'c')
+        ),
+        constraint Authorized check on insert (
+            -- There are no other records - first member needs no authorization
+            (select count(1) from Member) <= 1
+
+                -- or added directly by authority
+                or exists (
+                    select 1 from Authority A
+                        where A.MemberKey = context.AuthorityKey
+                            and verify(digest(new.Key, 'sha256', 'utf8'), context.AuthoritySignature, A.MemberKey, 'ed25519')
+                )
+
+                -- or added by invite
+                or exists (
+                    select 1 from ConsumedInvite CI where CI.MemberKey = new.Key
+                )
+        ),
+        -- TODO: handle member revocation constraint
+    ) with context (AuthorityKey text null, AuthoritySignature text null);
+
+    -- A member-associated peer (node)
+    table MemberPeer (
+        MemberKey text,
+        PeerId text,
+        primary key (MemberKey, PeerId),
+        constraint MemberExists check (exists (select 1 from Member M where M.Key = new.MemberKey)),
+        constraint Authorized check (
+            verify(
+                digest(coalesce(new.MemberKey, old.MemberKey) || '|' || coalesce(new.PeerId, old.PeerId), 'sha256', 'utf8'),
+                context.Signature,
+                coalesce(new.MemberKey, old.MemberKey),
+                'ed25519'
+            )
+        ),
+    ) with context (Signature text null);
+
+    -- An authority is a member that can issue invites, authorize members, and rotate authorities
+    table Authority (
+        MemberKey text primary key,
+        constraint OnlyClosed check (
+            exists (select 1 from Header H where H.Type = 'c')
+        ),
+        constraint Authorized check (
+            -- There are no existing records - first authority needs no authorization
+            (select count(1) from Authority) <= 1
+
+                -- or authorized by this former authority
+                or (
+                    old.MemberKey is not null
+                        and old.MemberKey = context.AuthorityKey
+                        and verify(digest(old.MemberKey, 'sha256', 'utf8'), context.Signature, old.MemberKey, 'ed25519')
+                )
+
+                -- or authorized by another existing authority
+                or exists (
+                    select 1 from Authority A
+                        where A.MemberKey = context.AuthorityKey
+                            and verify(digest(coalesce(new.MemberKey, old.MemberKey), 'sha256', 'utf8'), context.Signature, A.MemberKey, 'ed25519')
+                )
+        )
+    ) with context (AuthorityKey text null, Signature text null);
+`;

package/src/types.ts

@@ -0,0 +1,69 @@
+import type { Libp2p } from '@libp2p/interface';
+import type { IRepo } from '@optimystic/db-core';
+import type { IRawStorage } from '@optimystic/db-p2p';
+
+export interface StrandConnectionOptions {
+	/** UUID of the strand to connect to */
+	strandId: string;
+	/** Bootstrap multiaddrs for peer discovery */
+	bootstrapNodes?: string[];
+	/** sApp schema DDL to apply (optional - omit if schema already exists on strand) */
+	schema?: string;
+	/** sApp author public key */
+	sAppId?: string;
+	/** sApp version */
+	sAppVersion?: string;
+	/** libp2p listening port (default: 0 = random) */
+	port?: number;
+	/** Enable optimystic caching (default: true) */
+	enableCache?: boolean;
+	/** FRET profile (default: 'edge') */
+	fretProfile?: 'edge' | 'core';
+	/** Inject an existing libp2p node instead of creating one */
+	libp2pNode?: Libp2p;
+	/** Required when libp2pNode is provided */
+	coordinatedRepo?: IRepo;
+	/**
+	 * Lifecycle mode. `'networked'` (default) uses the network transactor and
+	 * is appropriate for multi-peer participation. `'bootstrap'` switches to a
+	 * local transactor so a solo node can apply schema and accept DML with no
+	 * peer round trips; pair it with a persistent `storage` to survive restart.
+	 */
+	mode?: 'bootstrap' | 'networked';
+	/**
+	 * Persistent raw storage. When provided:
+	 *  - it is passed to `createLibp2pNode` as `storage` so the libp2p data path uses it,
+	 *  - in `bootstrap` mode it is also handed to the optimystic plugin as
+	 *    `rawStorageFactory: () => storage` so the local transactor persists DML
+	 *    on the same instance (avoids cache divergence between the two consumers).
+	 *
+	 * The plugin treats `storage` as borrowed — it is NOT closed on `shutdown()`.
+	 */
+	storage?: IRawStorage;
+	/** @internal Override transactor type. Used by unit tests with `'test'`. When set, takes precedence only if `mode` is not specified. */
+	transactor?: string;
+}
+
+export interface SereusPluginResult {
+	vtables: [];
+	functions: [];
+	collations: [];
+	/**
+	 * Catalog-hydration counts from the warm-restart hydrate that runs before
+	 * `apply schema App;`. On a cold start (empty storage) both are 0; on a warm
+	 * restart they report the persisted tables/indexes the catalog was primed
+	 * with — so a test can assert hydration actually ran. `undefined` only if
+	 * composition threw before hydrate.
+	 */
+	hydrated?: { tables: number; indexes: number };
+	/** Shuts down the libp2p node and collection factory. Call when done. */
+	shutdown: () => Promise<void>;
+}
+
+/**
+ * Extended Libp2p node type with coordinatedRepo attached by createLibp2pNode.
+ * @internal
+ */
+export interface Libp2pNodeWithRepo extends Libp2p {
+	coordinatedRepo: IRepo;
+}