@serfab/cadre-core 0.9.0 → 0.10.0

package/src/control-formation-recorder.ts

@@ -1,6 +1,14 @@
 import debug from 'debug';
 import { randomBytes } from '@optimystic/quereus-plugin-crypto';
-import type { ControlDatabase } from './control-database.js';
+import { FormationAbortedError, type ControlDatabase } from './control-database.js';
+import {
+  createHttpFormationApprover,
+  verifyFormationApproval,
+  FormationApprovalError,
+  type FormationApprover,
+  type FormationApproval,
+  type FormationApprovalRequest
+} from './formation-approval.js';
 import type { FormationUsageRecorder, ResolvedHostStrand } from './strand-solicitation.js';
 import type { OpenInvitation } from './types.js';
 
@@ -31,9 +39,28 @@ const NEVER_EXPIRES = new Date(8640000000000000);
  * Usage accounting follows the schema's `FormationUsage.Authorized` semantics:
  * a null `TotalUses` means unlimited uses; otherwise the invite is "used up"
  * once the recorded usage count reaches `TotalUses`.
+ *
+ * When the invite carries a `ValidationUrl`, both write paths first obtain an outside
+ * approval ({@link obtainApproval}) — the recorder is the one place where the nonce that is
+ * SIGNED and the nonce that is INSERTED are trivially the same value, since it also performs
+ * the write. That makes this class do network I/O; failures surface as
+ * {@link FormationApprovalError}s the manager maps to protocol rejection reasons.
  */
 export class ControlFormationUsageRecorder implements FormationUsageRecorder {
-  constructor(private readonly controlDatabase: ControlDatabase) {}
+  private readonly approver: FormationApprover;
+
+  /**
+   * `approver` defaults to the real HTTP hook client — deliberately ON: this recorder is
+   * constructed by the reference apps and the integration harness, not by `CadreNode`, so an
+   * opt-in approver would leave every real deployment unable to redeem a
+   * `ValidationUrl`-bearing invite. Tests inject a fake.
+   */
+  constructor(
+    private readonly controlDatabase: ControlDatabase,
+    options?: { approver?: FormationApprover }
+  ) {
+    this.approver = options?.approver ?? createHttpFormationApprover();
+  }
 
   /** A token is valid when a matching, unexpired `FormationInvite` exists. */
   async isTokenValid(token: string): Promise<{ valid: boolean; invitation?: OpenInvitation }> {
@@ -70,17 +97,126 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
     return uses >= invite.totalUses;
   }
 
+  /**
+   * Any `FormationInvite` row still unexpired and not fully consumed — the
+   * durable half of the control-network connection gate's "does this node
+   * expect a stranger?" question. Survives a restart and sees invites
+   * replicated in from sibling nodes of the same cadre.
+   */
+  async hasOutstandingInvitation(): Promise<boolean> {
+    return await this.controlDatabase.hasOutstandingFormationInvite();
+  }
+
+  /**
+   * Obtain the approval material for ONE redemption, when the invite demands it.
+   *
+   * `validationUrl === null` → `{}`: no approval required. The `usageStampId` nonce is
+   * ALWAYS supplied by the caller — the JOINER mints it, signs its own consent over it, and
+   * sends it in the contact message — so the approver signs over the identical nonce in both
+   * paths. Two local pre-checks run before anything is written:
+   *
+   * - {@link verifyFormationApproval} — did the hook sign the exact fields we hold?
+   * - {@link ControlDatabase.queryValidationKeyStampId} — is the approval's key enrolled?
+   *
+   * Both pre-checks exist purely for legibility — they turn a bad approval into a named
+   * {@link FormationApprovalError} instead of an opaque `CHECK constraint failed: Authorized`
+   * at commit. The database re-verifies against the STORED `ValidationKey` row and remains
+   * the security authority; do not "simplify" the database check away in favour of these.
+   */
+  private async obtainApproval(
+    request: Omit<FormationApprovalRequest, 'validationUrl'> & { validationUrl: string | null },
+    signal?: AbortSignal
+  ): Promise<{ validationKey?: string; validationSignature?: string }> {
+    const { validationUrl, ...fields } = request;
+    if (validationUrl === null) {
+      return {};
+    }
+    if (signal?.aborted) {
+      throw new FormationAbortedError(fields.token, 'approval');
+    }
+    const fullRequest: FormationApprovalRequest = { ...fields, validationUrl };
+    const approval = await this.askApprover(fullRequest, signal);
+    if (!verifyFormationApproval(fullRequest, approval)) {
+      throw new FormationApprovalError(
+        'malformed',
+        `Approval signature does not verify over this redemption (token ${fields.token})`
+      );
+    }
+    if (await this.controlDatabase.queryValidationKeyStampId(approval.validationKey) === null) {
+      throw new FormationApprovalError(
+        'unenrolled',
+        'Approval is signed by a key that is not an enrolled ValidationKey'
+      );
+    }
+    return approval;
+  }
+
+  /**
+   * Ask the approver, re-labelling a caller-abort as a {@link FormationAbortedError}.
+   *
+   * The HTTP client relays a caller-abort onto its own request and reports it as an
+   * `unavailable` {@link FormationApprovalError} — which the manager cannot tell from a
+   * genuinely dead hook, and so maps to a rejection reason and RETURNS. Every other abort on
+   * this path THROWS, which is what makes the manager rethrow and leave the reply to the
+   * listener's timeout path; a mid-hook abort belongs in the same class. The approval error
+   * is kept as `cause` so the transport-level detail is not lost.
+   */
+  private async askApprover(
+    request: FormationApprovalRequest,
+    signal?: AbortSignal
+  ): Promise<FormationApproval> {
+    try {
+      return await this.approver.requestApproval(request, signal);
+    } catch (err) {
+      if (signal?.aborted) {
+        throw new FormationAbortedError(request.token, 'approval', { cause: err });
+      }
+      throw err;
+    }
+  }
+
   /**
    * Record consent against an **already-existing** host strand (record-only): the
    * single `FormationUsage` insert auto-commits and the deferred `StrandExists`
    * CHECK is satisfied by the pre-existing strand. This is the provision-then-record
    * commitment — the strand was minted owner-signed up front, so we do NOT
-   * re-insert it (which would double-insert the same PK). `initiatorKey` is carried
-   * as the usage `PeerId` (advisory). Use {@link ControlDatabase.redeemInvitation}
-   * for the consent-creates-strand path instead.
+   * re-insert it (which would double-insert the same PK). `peerKey` is written as the
+   * usage `PeerKey`, which BOTH signed digests cover: the joiner's own consent signature
+   * (`peerSignature`, verified by the schema's `PeerConsented` CHECK) and — when the invite
+   * carries a `ValidationUrl` — the approver's sign-off, so it is the joiner an approval is
+   * spent on AND provably the joiner that agreed. Use
+   * {@link ControlDatabase.redeemInvitation} for the consent-creates-strand path instead.
+   *
+   * Reads the invite first (one extra read per redemption) to learn its `ValidationUrl`, and
+   * obtains the approval through {@link obtainApproval} when one is demanded.
    */
-  async recordUsage(token: string, initiatorKey: string, strandId: string): Promise<void> {
-    await this.controlDatabase.recordFormationUsage({ token, strandId, peerId: initiatorKey });
+  async recordUsage(params: {
+    token: string;
+    peerKey: string;
+    peerSignature: string;
+    usageStampId: string;
+    strandId: string;
+    disclosure: string;
+    signal?: AbortSignal;
+  }): Promise<void> {
+    const { token, peerKey, peerSignature, usageStampId, strandId, disclosure, signal } = params;
+    if (signal?.aborted) {
+      throw new FormationAbortedError(token, 'usage recording');
+    }
+    const invite = await this.controlDatabase.queryFormationInvite(token);
+    // NOTE: a missing invite row reads as "no approval required" here and in
+    // `provisionAndRecord`, so an invite that vanished between `resolveStrand` and this read
+    // would be written unapproved. Safe only because the database's `FormationUsage.Authorized`
+    // CHECK demands a matching `FormationInvite` and rolls the write back regardless; if that
+    // CHECK ever loosens, reject on `invite === null` instead of defaulting to null.
+    const approval = await this.obtainApproval({
+      token, usageStampId, strandId, peerKey, disclosure,
+      validationUrl: invite?.validationUrl ?? null,
+    }, signal);
+    await this.controlDatabase.recordFormationUsage({
+      token, strandId, peerKey, peerSignature, usageStampId, disclosure, signal,
+      totalUses: invite?.totalUses ?? null, ...approval,
+    });
     log('Recorded formation usage: token=%s strand=%s', token, strandId);
   }
 
@@ -129,21 +265,38 @@ export class ControlFormationUsageRecorder implements FormationUsageRecorder {
    * key — so the returned `memberPrivateKey` is null. `sAppId` is accepted for parity/future
    * use; `redeemInvitation` does not currently thread it into the `Strand` row.
    *
-   * A concurrent redemption of the same single-use invite collides on the
-   * `(Token, UseNumber)` PK and this call THROWS for the loser — the manager maps that to a
-   * clean protocol rejection (it never lets the dropped insert close the stream silently).
+   * A concurrent redemption of the same single-use invite still THROWS for the loser — the
+   * manager maps that to a clean protocol rejection (it never lets the dropped insert close
+   * the stream silently) — but no longer via a `(Token, UseNumber)` primary-key collision on
+   * this node: `redeemInvitation` reads the use number INSIDE the write lock, so two local
+   * redemptions serialize and the second one reads the number the first already committed.
+   * It is then refused because that number is past the invite's seat budget, reported as a
+   * named `InvitationExhaustedError` on every attempt (including the first, which is what a
+   * same-node race hits). A PK collision is still what a cross-node race surfaces as, and that
+   * one IS retried under a fresh use number rather than thrown.
    */
-  async provisionAndRecord(
-    token: string,
-    initiatorKey: string,
-    _sAppId: string
-  ): Promise<{ strandId: string; memberPrivateKey: string | null }> {
+  async provisionAndRecord(params: {
+    token: string;
+    peerKey: string;
+    peerSignature: string;
+    usageStampId: string;
+    sAppId: string;
+    disclosure: string;
+    signal?: AbortSignal;
+  }): Promise<{ strandId: string; memberPrivateKey: string | null }> {
+    const { token, peerKey, peerSignature, usageStampId, disclosure, signal } = params;
+    if (signal?.aborted) {
+      throw new FormationAbortedError(token, 'redemption');
+    }
     const strandId = `strand-${randomBytes(128, 'hex') as string}`;
+    const invite = await this.controlDatabase.queryFormationInvite(token);
+    const approval = await this.obtainApproval({
+      token, usageStampId, strandId, peerKey, disclosure,
+      validationUrl: invite?.validationUrl ?? null,
+    }, signal);
     await this.controlDatabase.redeemInvitation({
-      token,
-      strandId,
-      type: 'o',
-      peerId: initiatorKey,
+      token, strandId, peerKey, peerSignature, usageStampId, disclosure, signal,
+      totalUses: invite?.totalUses ?? null, ...approval,
     });
     log('Provisioned + recorded unbound strand: token=%s strand=%s', token, strandId);
     return { strandId, memberPrivateKey: null };