@serfab/cadre-core 0.12.0 → 1.0.0

package/src/control-schema.ts

@@ -142,6 +142,17 @@ declare schema CadreControl {
         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
+        FounderOwnerKey text null,  -- ed25519 (base64url) owner key of the MACHINE that published this row
+                                    -- (== insert context.OwnerKey; in the reference model each machine's
+                                    -- owner key is the key behind its PeerId, so this names the founding
+                                    -- machine — the one machine that runs the strand's one-time founder
+                                    -- bootstrap). cadre-core derives "am I the founder?" at launch by
+                                    -- comparing it to the node's own owner key (cadre-node.ts
+                                    -- launchStrand). Null on a consent-seated strand — the consent branch
+                                    -- of AuthorizedInsert carries no signature, so there is no
+                                    -- trustworthy signer to record (see the NOTE on that branch below).
+                                    -- Provenance, not content: cadre-node.ts strandRowMismatches
+                                    -- deliberately excludes it from the identical-content comparison.
         StampId text not null unique,   -- single-use authorization nonce (anti-replay).
                                         -- \`unique\` holds over LIVE rows only; a removed row's stamp is retired
                                         -- permanently into Revocation (NotRevoked below).
@@ -172,8 +183,16 @@ declare schema CadreControl {
         -- Mirrors OwnerKey.NoUpdate / FormationInvite.Immutable.
         constraint NoUpdate check on update (false),
         constraint AuthorizedInsert check on insert (
-            -- Authorized by an owner signing over THIS row (Id, Type, MemberPrivateKey, StampId); single-use via unique StampId
-            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.Strand', 'add', new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
+            -- Authorized by an owner signing over THIS row (Id, Type, MemberPrivateKey, StampId); single-use via unique StampId.
+            -- FounderOwnerKey persists WHO published the row, so the founding machine can later
+            -- recognise its own strand (founder derivation, cadre-node.ts launchStrand). The
+            -- equality pins the stored column to the VERIFIED signer — same shape as
+            -- CadrePeer.VouchOwner — so a writer cannot record a founder it is not. Deliberately
+            -- NOT added to the signed digest: the equality already binds it to the signature's
+            -- context.OwnerKey, and widening the digest would churn every existing
+            -- insertStrand field-order contract for nothing.
+            (exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.Strand', 'add', new.Id, new.Type, coalesce(new.MemberPrivateKey, ''), new.StampId), context.Signature, A.Key, 'ed25519'))
+                and new.FounderOwnerKey = context.OwnerKey)
 
                 -- or authorized WITHOUT a signature by a redemption record naming THIS EXACT ROW: a
                 -- FormationUsage row carrying both this strand's Id and its one-off StampId
@@ -240,6 +259,15 @@ declare schema CadreControl {
                 or (
                     new.Type = 'o'
                     and new.MemberPrivateKey is null
+                    -- NOTE: a consent-seated strand records NO founder machine — this branch
+                    -- carries no signature, so there is no trustworthy signer to persist.
+                    -- Consequence: the restart-before-founding orphan shape (a relaunch cannot
+                    -- derive founder-ness from the row) persists for consent-formed strands
+                    -- only; the responder that provisions one must keep passing an explicit
+                    -- founder flag at launch. Revisit if consent-formed strands ever hit the
+                    -- empty-Header symptom in practice: FormationUsage names the redeeming
+                    -- peer (PeerKey), which is the candidate derivation source.
+                    and new.FounderOwnerKey is null
                     and exists (
                         select 1 from FormationUsage FU
                             where FU.StrandId = new.Id
@@ -277,6 +305,66 @@ declare schema CadreControl {
         )
     ) with context (OwnerKey text, Signature text);
 
+    -- ONE party's own membership identity for one strand: the private key whose public
+    -- half seats this party's \`Strand.Member\` / \`Strand.Manager\` rows. Deliberately a
+    -- SEPARATE key from Strand.MemberPrivateKey — that column is the strand-wide read
+    -- secret formation hands to EVERY joining party, so an identity derived from it is
+    -- one every joiner can forge (gotchoices/sereus#4). A side table rather than a
+    -- Strand column because a JOINER holds no control Strand row at all (reference apps
+    -- attach formed strands from an in-memory row) yet must persist its own party key
+    -- too; keyed by strand id it serves founder and joiner uniformly, and it leaves the
+    -- heavily-audited Strand insert digest untouched. Deliberately NO closed-strands-only
+    -- cross-table check: the joiner writes this row with no local Strand row to check
+    -- against. Party-private in the same sense as MemberPrivateKey — replicated in
+    -- plaintext to every machine the party owns (docs/strands.md → "Closed-Strand Member
+    -- Key Handling"; that replication is what lets any of the party's machines sign
+    -- membership writes) — but unlike MemberPrivateKey it is NEVER put on the formation
+    -- wire.
+    table StrandPartyKey (
+        Id text primary key,            -- the strand id this key is for
+        PrivateKey text not null,       -- THIS party's ed25519 strand member private key, base64
+                                        -- protobuf — the same encoding as Strand.MemberPrivateKey;
+                                        -- decode with cadre-core's strandMemberKeyPair.
+        StampId text not null unique,   -- single-use authorization nonce (anti-replay).
+                                        -- \`unique\` holds over LIVE rows only; a removed row's stamp is
+                                        -- retired permanently into Revocation (NotRevoked below).
+        -- A removed row's StampId is retired into Revocation, and this refuses any insert
+        -- naming a retired stamp: the approval that seated this row can never re-seat it
+        -- after removal. Same rationale as OwnerKey.NotRevoked, stated in full there.
+        constraint NotRevoked check on insert (
+            not exists (select 1 from Revocation R where R.TableName = 'StrandPartyKey' and R.StampId = new.StampId)
+        ),
+        -- Retirement is MANDATORY: a delete must carry the matching Revocation row in the same
+        -- transaction, or the stamp would free up again. Deferred (subquery), so the sibling
+        -- insert is visible at commit regardless of statement order. The tombstone must also
+        -- name the removed ROW, not just its stamp — see Revocation.RowKey.
+        constraint RevocationRecorded check on delete (
+            exists (select 1 from Revocation R where R.TableName = 'StrandPartyKey' and R.StampId = old.StampId and R.RowKey = old.Id)
+        ),
+        -- Insert + delete only; a rotation is remove-then-insert (fresh stamp, fresh
+        -- signature). Required because AuthorizedInsert / AuthorizedDelete below cover
+        -- neither update — an in-place rewrite would swap the party's identity key with
+        -- no signature at all. Mirrors ValidationKey.NoUpdate.
+        constraint NoUpdate check on update (false),
+        constraint AuthorizedInsert check on insert (
+            -- Owners authorize by signing over THIS row (Id, PrivateKey, StampId);
+            -- single-use via unique StampId. Binding PrivateKey means a captured approval
+            -- can only ever reproduce the exact key it approved, never seat an
+            -- attacker-chosen identity under the party's name.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.StrandPartyKey', 'add', new.Id, new.PrivateKey, new.StampId), context.Signature, A.Key, 'ed25519'))
+        ),
+        constraint AuthorizedDelete check on delete (
+            -- Delete is authorized by a signature over the DISTINCT 'remove'-tagged digest
+            -- bound to the STORED row (Id, StampId), so the enrollment approval — which
+            -- never expires — can never be replayed as a removal.
+            -- DELIBERATELY no REAP branch (cf. ValidationKey.AuthorizedDelete): like
+            -- Strand.MemberPrivateKey, PrivateKey is a secret stored nowhere else, so this
+            -- delete's effect is unrecoverable and stays strictly owner-signed. Same
+            -- reasoning as Strand.AuthorizedDelete.
+            exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.StrandPartyKey', 'remove', old.Id, old.StampId), context.Signature, A.Key, 'ed25519'))
+        )
+    ) with context (OwnerKey text, Signature text);
+
     -- A peer (node) that is part of the cadre, carrying a self-published,
     -- freshness-stamped, self-signed address record (see PeerAddressRecord in cadre-core).
     -- The row IS the peer-address record: a resolver reads it, re-verifies Sig against
@@ -676,25 +764,26 @@ declare schema CadreControl {
 
     -- Token is no longer a primary-key prefix (the key is the redemption nonce), so the
     -- per-token filters — the cap count in Authorized above, and cadre-core's
-    -- countFormationUsage / isTokenUsed / hasOutstandingFormationInvite — are served by a
-    -- table scan: a bare equality on a non-key column is a shape the optimystic vtab declines
-    -- to claim, so the engine applies the filter itself.
+    -- countFormationUsage / isTokenUsed / hasOutstandingFormationInvite — are served by this
+    -- index rather than by a full scan of a table that is append-only and grows for the life
+    -- of the party.
     --
-    -- There WAS an \`index FormationUsageByToken on FormationUsage (Token)\` here, declared by
-    -- \`formation-unique-token-redesign\` purely to spare that scan. It was removed 2026-08-25
-    -- because the tripwire that change recorded ("an under-reporting descent would admit a
-    -- seat the invitation did not pay for — a failure mode a scan could not produce") fired:
-    -- a secondary-index descent on a second machine returns only the rows THAT machine wrote,
-    -- so a cap counted through it under-reports without bound across machines. Measured with
-    -- the engine's own \`index:seek\` trace — each machine's copy of the index sub-collection
-    -- sits at a different revision while their copies of the table itself agree, and the
-    -- refresh that runs immediately before the descent does not close the gap. Tracked in
-    -- \`tickets/blocked/secondary-index-seek-blind-to-sibling-rows.md\`, and upstream as
-    -- \`bug-index-subcollection-sits-one-revision-behind-on-the-sibling\`.
+    -- The cap count is only ever as correct as this index's convergence across machines. That
+    -- convergence failed once: from 2026-08-04 to 2026-08-25 a descent on a second machine
+    -- returned only the rows THAT machine wrote, so the index was removed and the reads went
+    -- back to the scan. The engine defect was fixed upstream and re-measured here on
+    -- 2026-09-17, so the index is declared again. Its guard is the integration-tests scenario
+    -- \`strand-formation-concurrent-redemption\`, which asserts BOTH machines' views of a raced
+    -- redemption and therefore goes red if that convergence regresses.
     --
-    -- DO NOT re-declare it to speed the count up until that is fixed upstream. Re-adding this
-    -- one line is also how the reproducer comes back: it is what makes
-    -- \`strand-formation-concurrent-redemption\` fail.
+    -- NOTE: the write side has its own exposure. Every FormationUsage insert now maintains this
+    -- sub-collection as well as the table, and an intermittent engine failure once hit exactly that
+    -- step on other tables (a table's rows committed while its index did not; closed 2026-09-17 with
+    -- the upstream sync fixes, \`tickets/complete/strand-unique-index-sync-stale-revision\`). Nothing
+    -- has been observed here, and redemptions are rare writes; but if joins start failing
+    -- intermittently with an index-sync error naming FormationUsage, this declaration is the first
+    -- thing to suspect.
+    index FormationUsageByToken on FormationUsage (Token);
 
     -- Append-only retirement record for the one-off StampId nonces of removed OwnerKey /
     -- CadrePeer / ValidationKey / Strand rows. Without it a removal was undoable: the add
@@ -716,10 +805,20 @@ declare schema CadreControl {
     -- A tombstone committed while the node was alone is local-only (never broadcast); the
     -- ReissuedAt counter below exists so an owner can re-write — and therefore re-broadcast —
     -- such a tombstone once peers are reachable, without changing what it means.
+    -- One row retires nothing: the singleton ledger marker ('Revocation', 'ledger', 'opened'),
+    -- filed once by an owner's connected reconcile pass (ControlDatabase.openRevocationLedger).
+    -- It exists only so this table is never a never-written block. The storage layer consults
+    -- a block's cohort on EVERY read of a block it does not hold, and every membership lookup
+    -- and every guarded insert (NotRevoked) reads this table; once any row exists the block is
+    -- held and re-checked on the storage layer's normal read-repair schedule, like every other
+    -- populated table. It cannot read as a retirement: every reader of this table filters on
+    -- its own guarded TableName, 'Revocation' is not one, and ControlDatabase.queryRevocations
+    -- skips the marker, so nothing reaps or re-issues it.
     table Revocation (
-        TableName text,             -- 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'DeviceToken' (confined by RowIsGone below)
+        TableName text,             -- 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'DeviceToken',
+                                    -- or 'Revocation' for the ledger marker only (all confined by RowIsGone below)
         RowKey text not null,       -- primary key of the removed row: OwnerKey.Key / ValidationKey.Key /
-                                    -- CadrePeer.PeerId / DeviceToken.PeerId / Strand.Id
+                                    -- CadrePeer.PeerId / DeviceToken.PeerId / Strand.Id / StrandPartyKey.Id
                                     -- Every guarded table's RevocationRecorded CHECK requires the
                                     -- accompanying tombstone to carry the removed row's key here, so
                                     -- a REMOVAL cannot file a misnamed tombstone. A tombstone with no
@@ -759,12 +858,19 @@ declare schema CadreControl {
         -- it, stamp1) then re-admitted (stamp2) would leave a node that converges on the
         -- re-add FIRST rejecting the stamp1 tombstone forever, never learning that stamp is
         -- retired. The stamp-only form passes there (stamp1 is not live).
+        -- The last branch admits the ledger marker (see the table comment) and nothing else under
+        -- TableName 'Revocation': the whole triple is pinned, so with the primary key
+        -- (TableName, StampId) it is a singleton and the append-only growth surface is unchanged.
+        -- 'opened' cannot collide with a real stamp (43 base64url characters, generateStampId),
+        -- and the primary key includes TableName anyway.
         constraint RowIsGone check on insert (
             (new.TableName = 'OwnerKey' and not exists (select 1 from OwnerKey K where K.StampId = new.StampId))
                 or (new.TableName = 'CadrePeer' and not exists (select 1 from CadrePeer P where P.StampId = new.StampId))
                 or (new.TableName = 'ValidationKey' and not exists (select 1 from ValidationKey V where V.StampId = new.StampId))
                 or (new.TableName = 'Strand' and not exists (select 1 from Strand S where S.StampId = new.StampId))
+                or (new.TableName = 'StrandPartyKey' and not exists (select 1 from StrandPartyKey K where K.StampId = new.StampId))
                 or (new.TableName = 'DeviceToken' and not exists (select 1 from DeviceToken D where D.StampId = new.StampId))
+                or (new.TableName = 'Revocation' and new.RowKey = 'ledger' and new.StampId = 'opened')
         ),
         -- Appending a tombstone is an OWNER action, like every other write in this schema.
         -- Ungated, any writer that could reach the control database could retire a stamp:
@@ -798,6 +904,12 @@ declare schema CadreControl {
         -- than that one.
         -- RowIsGone and NoDelete are unchanged: they guard an owner retiring a stamp early
         -- or withdrawing one later, which authorization does not cover.
+        -- The ledger marker is signed under this same rule, over
+        -- digest('CadreControl.Revocation', 'remove', 'Revocation', 'ledger', 'opened'). The
+        -- 'remove' tag on a row that retires nothing is deliberate: reusing the one append rule
+        -- keeps every append owner-signed without adding an unsigned or differently tagged
+        -- branch, and a captured marker signature can only re-file the identical row, whose
+        -- primary key is already taken.
         constraint Authorized check on insert (
             exists (select 1 from OwnerKey A where A.Key = context.OwnerKey and verify(digest('CadreControl.Revocation', 'remove', new.TableName, new.RowKey, new.StampId), context.Signature, A.Key, 'ed25519'))
         ),