@serfab/cadre-core 1.15.0 → 1.17.0

package/src/control-authorization.ts

@@ -59,6 +59,8 @@ export const CONTROL_TABLES = [
   'FormationUsage',
   'CadreInvite',
   'CadreInviteUsage',
+  'OwnerGrant',
+  'OwnerGrantUsage',
   'Revocation',
 ] as const;
 
@@ -76,17 +78,17 @@ export type ControlTable = typeof CONTROL_TABLES[number];
  * {@link ControlTable} rather than a fresh literal list, so a renamed table is a
  * compile error here instead of a silently dead branch.
  *
- * `CadreInvite` is the one member whose rows are never deleted: its tombstone is a
- * withdrawal over a row that stays (`NotRevoked` refuses re-seating the withdrawn
- * row; there is no `RevocationRecorded`, since nothing is ever removed), so it is
- * revocable without being removable — `control-database.ts`'s `RemovableTable`
- * excludes it.
+ * `CadreInvite` and `OwnerGrant` are the two members whose rows are never deleted: a
+ * tombstone there is a withdrawal over a row that stays (`NotRevoked` refuses re-seating
+ * the withdrawn row; there is no `RevocationRecorded`, since nothing is ever removed), so
+ * they are revocable without being removable — `control-database.ts`'s `RemovableTable`
+ * excludes them.
  *
  * Lives in this import-free module rather than beside its main consumer
  * (`control-database.ts`) so the lightweight signers — `peer-authorization.ts`'s
  * `revocationDigest` — can type against it without pulling in the runtime.
  */
-export type RevocableTable = Extract<ControlTable, 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'JoinedStrand' | 'JoinRequest' | 'DeviceToken' | 'CadreInvite'>;
+export type RevocableTable = Extract<ControlTable, 'OwnerKey' | 'CadrePeer' | 'ValidationKey' | 'Strand' | 'StrandPartyKey' | 'JoinedStrand' | 'JoinRequest' | 'DeviceToken' | 'CadreInvite' | 'OwnerGrant'>;
 
 /**
  * What a signature authorizes, scoped to one table rule — or, for
@@ -122,10 +124,11 @@ export type BoundControlDomain = Exclude<ControlDomain, UnboundControlDomain>;
  *    owner key.
  *  - `'consent'` — a peer self-signs its OWN `FormationUsage` or
  *    `CadreInviteUsage` redemption (the joiner proving it agreed to join), with
- *    its own key. Distinct from the approver's `'vouch'` over the same table so
- *    the two stored signatures are never interchangeable.
- *  - `'redeem'` — the holder of a `CadreInvite`'s private key proves possession
- *    on a `CadreInviteUsage` row. Distinct from the device's `'consent'` over the
+ *    its own key, or the key an `OwnerGrantUsage` seats signs that it is held.
+ *    Distinct from the approver's `'vouch'` over the same table so the two
+ *    stored signatures are never interchangeable.
+ *  - `'redeem'` — the holder of a `CadreInvite`'s or `OwnerGrant`'s private key
+ *    proves possession on the usage row. Distinct from the `'consent'` over the
  *    same fields: the two signatures are by different keys and neither may stand
  *    in for the other.
  *  - `'reissue'` — an owner re-writes an existing `Revocation` tombstone,
@@ -145,7 +148,6 @@ export type ControlAction = 'add' | 'remove' | 'vouch' | 'publish' | 'consent' |
 export interface CadreInviteSignedFields {
   key: string;
   peerId: string | null;
-  grantsOwner: boolean;
   expiresAt: string | null;
   totalUses: number | null;
   stampId: string;
@@ -156,14 +158,45 @@ export interface CadreInviteSignedFields {
  * (`control-database.ts`'s `cadreInviteAddMessage`, raw bytes) and the verifier
  * (`peer-authorization.ts`'s `cadreInviteAddDigest`, base64url) so the two cannot
  * drift. SQL mirror, in `CadreInvite.AuthorizedInsert`:
- * `new.Key, coalesce(new.PeerId, ''), cast(new.GrantsOwner as text),
- * coalesce(cast(new.ExpiresAt as text), ''), coalesce(cast(new.TotalUses as text), ''), new.StampId`.
+ * `new.Key, coalesce(new.PeerId, ''), coalesce(cast(new.ExpiresAt as text), ''),
+ * coalesce(cast(new.TotalUses as text), ''), new.StampId`.
  */
 export function cadreInviteRowFields(row: CadreInviteSignedFields): string[] {
   return [
     row.key,
     row.peerId ?? '',
-    row.grantsOwner ? '1' : '0',
+    row.expiresAt ?? '',
+    row.totalUses === null ? '' : String(row.totalUses),
+    row.stampId,
+  ];
+}
+
+/**
+ * The `OwnerGrant` columns its `'add'` signature binds, in the schema's order and with
+ * the row's stored forms (`expiresAt` canonical, as {@link CadreInviteSignedFields}).
+ * `label` is the label the seated `OwnerKey` row must carry: the issuer's choice, bound
+ * here so the holder cannot seat the key under another name. Structurally satisfied by
+ * an `OwnerGrantRow` (`types.ts`), which adds the issuer pair the signature does not cover.
+ */
+export interface OwnerGrantSignedFields {
+  key: string;
+  label: string | null;
+  expiresAt: string | null;
+  totalUses: number | null;
+  stampId: string;
+}
+
+/**
+ * The row-field half of an `OwnerGrant` `'add'` digest, shared by the signer
+ * (`control-database.ts`'s `ownerGrantAddMessage`) and the verifier
+ * (`peer-authorization.ts`'s `ownerGrantAddDigest`), as {@link cadreInviteRowFields} is.
+ * SQL mirror, in `OwnerGrant.AuthorizedInsert`: `new.Key, coalesce(new.Label, ''),
+ * coalesce(cast(new.ExpiresAt as text), ''), coalesce(cast(new.TotalUses as text), ''), new.StampId`.
+ */
+export function ownerGrantRowFields(row: OwnerGrantSignedFields): string[] {
+  return [
+    row.key,
+    row.label ?? '',
     row.expiresAt ?? '',
     row.totalUses === null ? '' : String(row.totalUses),
     row.stampId,

package/src/control-cohort.ts

@@ -1,128 +1,127 @@
-/**
- * Control-cohort dial selection: the pure policy behind
- * {@link CadreNode.reconcileControlCohort}. Decides WHICH known cadre siblings a
- * node proactively dials each pass to keep the `CadreControl` collections' cohort
- * connected (and thus replicating), without devolving into an N² mesh.
- *
- * FRET only needs a *connected* graph with the block clusters reachable, not a
- * full mesh. Storage/owner nodes are the stable, publicly-dialable backbone
- * that hold the control blocks, so the policy is **backbone-preferential with a
- * bounded out-degree**:
- *
- * - **Always dial every backbone (owner) member** — the owner set is
- *   small by design, and routing cohort formation through publicly-dialable
- *   owner nodes keeps the cohort ≥2 where owner-signed writes originate.
- * - **Fill the remainder** up to `targetDegree` with non-owner members,
- *   ordered deterministically (peerId sort) so every node makes the same stable
- *   choice across passes and load spreads predictably.
- *
- * For a small party (members ≤ degree) this degenerates to a full mesh, which is
- * correct, cheap, and matches what the convergence tests do by hand; for a large
- * party it bounds out-degree to `backbone + targetDegree`.
- */
-
-import { ed25519PublicKeyB64FromPeerId } from './ed25519-key.js';
-import type { CohortPeerRow } from './strand-cohort.js';
-
-/**
- * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
- * In the same spirit as the 5s strand-watch poll but lighter, since a control
- * cohort changes far less often than strand activity.
- *
- * An interval between pass starts, not a deadline on a pass. Passes are
- * single-flight, so a pass that runs longer than this is joined rather than
- * stacked, and the effective cadence becomes the pass length: one unreachable
- * sibling's dial alone can take the whole per-peer dial budget (86 s at the
- * default declared link).
- */
-export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15_000;
-
-/**
- * Default cap on the number of **non-owner** members a single reconcile pass
- * proactively dials. Backbone (owner) members are always dialed and do NOT
- * count against this cap.
- */
-export const DEFAULT_CONTROL_COHORT_TARGET_DEGREE = 6;
-
-// The per-sibling and per-address dial time limits live in `peer-dial.ts`
-// (`DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS`,
-// `DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS`), beside the dial they
-// bound, which `seed-bootstrap.ts` also uses and cannot import from here.
-
-/** Outcome of {@link selectControlCohortDials}: who to dial + what the cap dropped. */
-export interface ControlCohortSelection {
-  /**
-   * Siblings to dial this pass, backbone first then the bounded non-owner
-   * fill. Already self-excluded (the caller must pass self-excluded `siblings`).
-   * Still includes peers that may turn out to be already-connected — the caller
-   * diffs against live connections separately.
-   */
-  dials: CohortPeerRow[];
-  /** Non-owner members dropped by the `targetDegree` cap (0 when none). */
-  cappedNonOwner: number;
-}
-
-/** What one {@link CadreNode.reconcileControlCohort} pass did. */
-export interface ControlCohortReconcileResult {
-  /**
-   * Peer ids this pass dialled and whose dial resolved, in dial order: selected
-   * siblings on the steady-state pass, retained bootstrap peers on the cold-start
-   * pass (the pass takes one branch or the other, never both). A peer already
-   * connected when the pass began is never listed — the pass skips it. A resolved
-   * dial can still be refused moments later by the remote's membership gate, so
-   * an entry means "this pass opened a connection", not "that connection is still
-   * open".
-   */
-  dialed: string[];
-}
-
-/** Stable peerId ordering so the bounded fill is identical across passes/nodes. */
-function byPeerId(a: CohortPeerRow, b: CohortPeerRow): number {
-  if (a.peerId < b.peerId) return -1;
-  if (a.peerId > b.peerId) return 1;
-  return 0;
-}
-
-/**
- * Backbone-preferential, bounded-out-degree selection of control-cohort siblings
- * to dial.
- *
- * A member is **backbone** iff the ed25519 key derived from its peerId
- * (see {@link ed25519PublicKeyB64FromPeerId}) is in `ownerKeys`. All backbone
- * members are selected; non-owner members fill up to `targetDegree` in
- * deterministic peerId order.
- *
- * @param siblings - cadre members EXCLUDING self (the caller filters self out).
- * @param ownerKeys - the converged `OwnerKey` set; may be empty/partial
- *   before owner convergence, in which case no member classifies as backbone
- *   yet and the bounded fill still makes progress (preference sharpens later).
- * @param targetDegree - cap on non-owner dials (negative is treated as 0).
- */
-export function selectControlCohortDials(
-  siblings: CohortPeerRow[],
-  ownerKeys: ReadonlySet<string>,
-  targetDegree: number,
-): ControlCohortSelection {
-  const backbone: CohortPeerRow[] = [];
-  const rest: CohortPeerRow[] = [];
-
-  for (const peer of siblings) {
-    const pubKey = ed25519PublicKeyB64FromPeerId(peer.peerId);
-    if (pubKey !== null && ownerKeys.has(pubKey)) {
-      backbone.push(peer);
-    } else {
-      rest.push(peer);
-    }
-  }
-
-  backbone.sort(byPeerId);
-  rest.sort(byPeerId);
-
-  const cap = Math.max(0, targetDegree);
-  const fill = rest.slice(0, cap);
-
-  return {
-    dials: [...backbone, ...fill],
-    cappedNonOwner: rest.length - fill.length,
-  };
-}
+/**
+ * Control-cohort dial selection: the pure policy behind
+ * {@link CadreNode.reconcileControlCohort}. Decides WHICH known cadre siblings a
+ * node proactively dials each pass to keep the `CadreControl` collections' cohort
+ * connected (and thus replicating), without devolving into an N² mesh.
+ *
+ * FRET only needs a *connected* graph with the block clusters reachable, not a
+ * full mesh. Always-on (`storage` profile) machines are the stable, dialable
+ * backbone that hold the control blocks, so the policy is **backbone-preferential
+ * with a bounded out-degree**:
+ *
+ * - **Always dial every backbone (always-on) member** — a party runs few of them,
+ *   and they are the machines that stay reachable while phones sleep or roam.
+ * - **Fill the remainder** up to `targetDegree` with the other members (phones,
+ *   and machines that have not yet published a profile), ordered
+ *   deterministically (peerId sort) so every node makes the same stable choice
+ *   across passes and load spreads predictably.
+ *
+ * For a small party (members ≤ degree) this degenerates to a full mesh, which is
+ * correct, cheap, and matches what the convergence tests do by hand; for a large
+ * party it bounds out-degree to `backbone + targetDegree`.
+ */
+
+import type { CohortPeerRow } from './strand-cohort.js';
+
+/**
+ * Default recurring cadence for {@link CadreNode.reconcileControlCohort} (ms).
+ * In the same spirit as the 5s strand-watch poll but lighter, since a control
+ * cohort changes far less often than strand activity.
+ *
+ * An interval between pass starts, not a deadline on a pass. Passes are
+ * single-flight, so a pass that runs longer than this is joined rather than
+ * stacked, and the effective cadence becomes the pass length: one unreachable
+ * sibling's dial alone can take the whole per-peer dial budget (86 s at the
+ * default declared link).
+ */
+export const DEFAULT_CONTROL_COHORT_RECONCILE_MS = 15_000;
+
+/**
+ * Default cap on the number of **non-backbone** members a single reconcile pass
+ * proactively dials. Backbone (always-on) members are always dialed and do NOT
+ * count against this cap.
+ */
+export const DEFAULT_CONTROL_COHORT_TARGET_DEGREE = 6;
+
+// The per-sibling and per-address dial time limits live in `peer-dial.ts`
+// (`DEFAULT_CONTROL_COHORT_DIAL_TIMEOUT_MS`,
+// `DEFAULT_CONTROL_COHORT_PER_ADDRESS_DIAL_TIMEOUT_MS`), beside the dial they
+// bound, which `seed-bootstrap.ts` also uses and cannot import from here.
+
+/** Outcome of {@link selectControlCohortDials}: who to dial + what the cap dropped. */
+export interface ControlCohortSelection {
+  /**
+   * Siblings to dial this pass, backbone first then the bounded non-backbone
+   * fill. Already self-excluded (the caller must pass self-excluded `siblings`).
+   * Still includes peers that may turn out to be already-connected — the caller
+   * diffs against live connections separately.
+   */
+  dials: CohortPeerRow[];
+  /** Non-backbone members dropped by the `targetDegree` cap (0 when none). */
+  cappedNonBackbone: number;
+}
+
+/** What one {@link CadreNode.reconcileControlCohort} pass did. */
+export interface ControlCohortReconcileResult {
+  /**
+   * Peer ids this pass dialled and whose dial resolved, in dial order: selected
+   * siblings on the steady-state pass, retained bootstrap peers on the cold-start
+   * pass (the pass takes one branch or the other, never both). A peer already
+   * connected when the pass began is never listed — the pass skips it. A resolved
+   * dial can still be refused moments later by the remote's membership gate, so
+   * an entry means "this pass opened a connection", not "that connection is still
+   * open".
+   */
+  dialed: string[];
+}
+
+/** Stable peerId ordering so the bounded fill is identical across passes/nodes. */
+function byPeerId(a: CohortPeerRow, b: CohortPeerRow): number {
+  if (a.peerId < b.peerId) return -1;
+  if (a.peerId > b.peerId) return 1;
+  return 0;
+}
+
+/**
+ * Backbone-preferential, bounded-out-degree selection of control-cohort siblings
+ * to dial.
+ *
+ * A member is **backbone** iff its `CadrePeer` row declares the `storage` profile
+ * (an always-on machine). All backbone members are selected; the rest fill up to
+ * `targetDegree` in deterministic peerId order. A member whose profile is still
+ * unknown (it has not self-published) is not backbone until it publishes one.
+ * A profile is a dial preference only: it is self-declared, and a machine
+ * misdeclaring one costs extra dials, never access.
+ *
+ * @param siblings - cadre members EXCLUDING self (the caller filters self out).
+ * @param targetDegree - cap on non-backbone dials (negative is treated as 0).
+ */
+export function selectControlCohortDials(
+  siblings: CohortPeerRow[],
+  targetDegree: number,
+): ControlCohortSelection {
+  const backbone: CohortPeerRow[] = [];
+  const rest: CohortPeerRow[] = [];
+
+  // NOTE: the backbone is uncapped, so out-degree grows with the number of always-on
+  // machines (and with any sibling that declares `storage` without being one); if a party
+  // ever runs more than a handful, cap the backbone too.
+  for (const peer of siblings) {
+    if (peer.profile === 'storage') {
+      backbone.push(peer);
+    } else {
+      rest.push(peer);
+    }
+  }
+
+  backbone.sort(byPeerId);
+  rest.sort(byPeerId);
+
+  const cap = Math.max(0, targetDegree);
+  const fill = rest.slice(0, cap);
+
+  return {
+    dials: [...backbone, ...fill],
+    cappedNonBackbone: rest.length - fill.length,
+  };
+}