@consiliency/agent-board-schema 1.44.0 → 1.48.0

package/migrations/20260927000100_agent_board_fleet_domain_no_downgrade.sql

@@ -0,0 +1,393 @@
+-- #395 re-registration may not move a bound machine into a LESS APPROVED trust domain.
+--
+-- THE HOLE. register_fleet_machine's `on conflict (machine_fingerprint) do update` sets
+-- trust_domain_id = excluded.trust_domain_id, so a re-registration MOVES the machine. Three
+-- facts compose (#395):
+--   1. the destination domain is accepted at lifecycle_state in ('active','pending')
+--      (20260823000100:52) — a never-approved domain is a legal destination;
+--   2. lifecycle_state is deliberately NOT updated on conflict (#141), so the machine stays
+--      'active' through the move;
+--   3. fleet_machine_agents rows key on machine_id, which does not change — the bindings
+--      SURVIVE the move.
+-- evaluate_fleet_sender_policy (last definer 20260826000100:161-168) joins fma + fm and never
+-- reads ftd, so after the move the sender is still fleet-bound under a domain nobody approved.
+-- The owner needs no privilege for this: the `where owner_agent_id = v_actor_agent_id` gate
+-- exists to refuse a THIRD-PARTY hijack (#141) and permits the owner's own self-move.
+--
+-- THE REMEDY, and the two it is not. This migration refuses the MOVE. It deliberately does NOT
+--   * make evaluate_fleet_sender_policy read ftd.lifecycle_state — widest blast radius, and it
+--     would also change the domain-DEMOTION semantics (active -> pending on an already-bound
+--     domain is permitted and is not a send off-switch) that were left alone on purpose; or
+--   * treat a domain move as re-enrollment and reset the bindings — most disruptive.
+-- Send-path semantics are unchanged by this migration. Nothing here reads or writes
+-- fleet_machine_agents, evaluate_fleet_sender_policy, or any revocation ledger.
+--
+-- THE ORDERING, stated so it is a rule and not an intuition. Approval rank over
+-- fleet_trust_domains.lifecycle_state (agent_board._fleet_trust_domain_approval_rank):
+--
+--     active      2   approved, in force
+--     pending     1   registered, never yet approved
+--     quarantined 0   approval WITHDRAWN
+--     suspended   0   approval WITHDRAWN
+--     revoked     0   approval WITHDRAWN
+--
+-- The three withdrawn states sit BELOW pending, not between pending and active: each one means
+-- an approval that was taken away, which is not a stronger claim than "never approved". They
+-- are ranked equal to each other because nothing in this schema distinguishes their authority —
+-- the send path reads none of them (it reads the fleet_revocation_events ledger), so ordering
+-- them against each other would be a distinction with no reader.
+--
+-- THE RULE: the re-registration is refused when
+--     rank(destination domain) < rank(the machine's CURRENT domain).
+-- An EQUAL rank is permitted — a legitimate relocation between two active domains, or between
+-- two pending ones, still works. An UPGRADE (pending -> active) is permitted. A FIRST
+-- registration has no current domain and is unaffected (the guard lives in the ON CONFLICT
+-- branch, which a fresh insert never enters).
+--
+-- REACHABILITY, so the guard is not read as wider than it is. Because the destination gate
+-- already restricts the destination to ('active','pending'), the ONLY refusal this rule can
+-- produce today is active -> pending, which is exactly #395. The comparison is written in terms
+-- of the general rank anyway so that widening the destination gate, or adding a lifecycle value,
+-- cannot silently open a second hole: an unranked state yields NULL, `>=` over NULL is not true,
+-- and the re-registration is REFUSED. Every arm of this guard fails CLOSED.
+--
+-- CONCURRENCY, stated at its measured size rather than as "atomic" (#397). The two halves of the
+-- comparison have DIFFERENT guarantees, and the earlier version of this file claimed the stronger
+-- one for both:
+--
+--   * The MACHINE half is atomic. The comparison is a conjunct of the ON CONFLICT DO UPDATE's
+--     WHERE, evaluated by the same statement that would perform the move, against the conflicting
+--     row that statement has already locked. No select-then-update window — the same reason #141
+--     put its ownership gate there rather than in a pre-check.
+--   * The DESTINATION half cannot be pinned without a row lock on fleet_trust_domains, and that
+--     lock is NOT ours to take: it was added to this very function once (PR #158, ab38805) and
+--     REVERTED for deadlocking 40P01 against reclaim_fleet_machine, which locks the machine row
+--     first and then takes an FK KEY SHARE on the destination domain. Restoring a global
+--     domain ≺ machine order means re-ordering a merged core function; #159 owns that and is open.
+--     `service_role` holds UPDATE on fleet_trust_domains, so a concurrent demotion of the
+--     destination is a real event, not a hypothetical.
+--
+-- MEASURED, not reasoned: moving the destination read INTO the upsert as a correlated subquery
+-- — the obvious repair — does NOT close the window. Under READ COMMITTED an upsert that waits on
+-- the conflicting row's lock re-reads THAT ROW's latest version when it resumes, but evaluates
+-- every other relation against the statement's ORIGINAL snapshot, so the domain's lifecycle is
+-- still read as of before the wait. Both forms were run against a two-session probe (session B
+-- holds the machine row, demotes the destination, commits; session A's move resumes) and both
+-- allowed the move.
+--
+-- So the destination is re-checked AFTER the move, in a SEPARATE statement, which under READ
+-- COMMITTED takes a FRESH snapshot and therefore sees a demotion that committed while we waited.
+-- It raises, which aborts the transaction and unwinds the move. Same probe: refused, machine left
+-- in its original domain. The post-check runs ONLY when the domain actually changed
+-- (`is distinct from`), so a same-domain re-register — including the revoked-machine case #141
+-- protects — is never failed by it. A FIRST registration has no prior domain, and what covers it is
+-- the LOST-RACE REFUSAL below, NOT the absence of a check — an earlier version of this sentence
+-- said a fresh insert "cannot be a downgrade at all", which is true of an insert and false of the
+-- insert that LOSES a first-registration race and lands on the conflict path.
+--
+-- ROUND 2 (#397), because the first version of that paragraph was wrong in a way worth recording.
+-- The skip predicate compares the landed domain against a PRE-READ, and the pre-read was unlocked.
+-- "The destination equals what I read before the wait" is NOT "nothing moved": a concurrent
+-- session that RELOCATES the machine separates them, and if our upsert then moves the machine back
+-- to the domain our stale read named, the skip fires and the fresh-snapshot check never runs. Two
+-- interleavings did exactly that and were reproduced before this was changed:
+--   P3 — another session moves the machine D1→D2 uncommitted; we re-register into D1 (our pre-read
+--        says D1); it demotes D1 and commits; we resume, move D2→D1, and D1 == our stale pre-read.
+--   P4 — we re-register into the machine's OWN domain D1; the lock holder relocates the machine to
+--        X and demotes D1; we resume, genuinely move X→D1, and again D1 == the pre-read. (We block
+--        at the UPSERT, not at the pre-read — a plain SELECT does not wait, which is why the
+--        pre-read is stale rather than merely early.)
+-- The pre-read now takes FOR UPDATE on the MACHINE row — the same row the upsert locks, so the
+-- acquisition order is unchanged and no fleet_trust_domains lock is involved (see the read itself
+-- for why that distinction is the difference between this and the reverted #158 lock). It observes
+-- post-wait truth, nothing can relocate the machine between it and the upsert, and the skip
+-- predicate means what it says.
+--
+-- ROUND 3 (#397) replaced what this paragraph used to describe, and the correction is the point.
+-- Round 2 gave the no-prior-row path a fallback that compared the landed domain against the
+-- DESTINATION RANK IT HAD CACHED. A review seat showed that is not a baseline: PROMOTE the source
+-- domain during the race and the cached destination rank still matches itself (1 >= 1), so a
+-- machine moves out of a now-active domain into a pending one and the comparison never notices
+-- (isolation P6-promote, reproduced before this was changed).
+--
+-- There is nothing to recover in that case — the domain the machine was in belonged to a row we
+-- never read, and the upsert has overwritten it — so the lost race is now REFUSED (40001,
+-- retryable) rather than approximated, and the decision below reads BOTH ranks in ONE statement
+-- instead of comparing values captured at different times. That pairing is what ends the shape
+-- every round of this issue has had; see the two blocks in the body for the construction argument
+-- and for the class that still survives.
+--
+-- RESIDUAL, scoped rather than claimed away: a demotion that commits AFTER the post-check's
+-- snapshot still lands. That outcome is serial-equivalent to `register` followed by `demote the
+-- destination`, which is a PERMITTED operation this migration deliberately does not change
+-- (FLEETBOOT: "demotion is not a send off-switch"). Closing it needs the domain lock, i.e. #159.
+--
+-- REFUSAL SHAPE. 42501, consistent with this function's other refusals. When the do-update
+-- matches nothing there are now TWO possible reasons, so the row is re-read to name the actual
+-- one: a different owner still raises #141's message VERBATIM (it is documented behaviour), and
+-- the new case names the domain move. The re-read is stable because the conflicting row is
+-- locked by the upsert above.
+--
+-- CLASS (rule 1). The writers of fleet_machines.trust_domain_id are register_fleet_machine and
+-- reclaim_fleet_machine — catalog-derived and pinned in agent_board_fleet_machine_hijack.test.sql,
+-- so a future third writer names itself. reclaim_fleet_machine does NOT need this guard and is
+-- exempt on a stronger gate, not a weaker one: its p_new_trust_domain_id must be
+-- lifecycle_state = 'active' AND owned by the new owner (20260829000100:135-142), so its
+-- destination is always rank 2 and it cannot express a downgrade. That exemption is asserted
+-- POSITIVELY (a pending destination raises 42501) in agent_board_fleet_machine_reclaim.test.sql
+-- rather than left as an absence.
+--
+-- #118 discipline: create-or-replace preserves the ACL and COMMENT, but both are restated below.
+
+-- ------------------------------------------------------------------------------------------
+-- The approval ordering, as a function so it has ONE definition that a test can interrogate.
+-- SECURITY INVOKER, IMMUTABLE, and total on its input: an unknown state returns NULL, which
+-- every caller must treat as "refuse" (a NULL comparison is not true). Adding a lifecycle value
+-- to the fleet_trust_domains CHECK without ranking it here fails the CHECK-derived class
+-- assertion in agent_board_fleet_machine_hijack.test.sql BY NAME.
+-- ------------------------------------------------------------------------------------------
+create or replace function agent_board._fleet_trust_domain_approval_rank(p_lifecycle_state text)
+returns integer
+language sql
+immutable
+set search_path = agent_board, public
+as $$
+  select case p_lifecycle_state
+           when 'active' then 2
+           when 'pending' then 1
+           when 'quarantined' then 0
+           when 'suspended' then 0
+           when 'revoked' then 0
+           else null
+         end
+$$;
+
+revoke all on function agent_board._fleet_trust_domain_approval_rank(text) from public, anon;
+grant execute on function agent_board._fleet_trust_domain_approval_rank(text) to authenticated, service_role;
+
+comment on function agent_board._fleet_trust_domain_approval_rank(text) is
+  'Approval ordering over fleet_trust_domains.lifecycle_state (#395): active=2, pending=1, quarantined/suspended/revoked=0 (approval WITHDRAWN ranks below never-approved). Returns NULL for any state outside the column CHECK, so a caller comparing ranks refuses rather than fails open. Used by register_fleet_machine to refuse a re-registration that would move a machine into a less approved domain.';
+
+-- ------------------------------------------------------------------------------------------
+-- register_fleet_machine — reproduced from 20260823000100 (its last definer) VERBATIM except:
+--   * v_dest_rank / v_existing declarations;
+--   * the destination-rank read after the existing destination gate;
+--   * the rank conjunct on the ON CONFLICT DO UPDATE's WHERE;
+--   * the two-reason refusal that replaces the single #141 raise (whose message is unchanged);
+--   * the prior-domain capture and the post-move re-check (#397).
+-- ------------------------------------------------------------------------------------------
+create or replace function agent_board.register_fleet_machine(
+  p_owner_agent_id uuid,
+  p_trust_domain_id uuid,
+  p_machine_label text,
+  p_machine_fingerprint text,
+  p_enrollment_source text default 'portal',
+  p_metadata jsonb default '{}'::jsonb
+)
+returns table(machine_id uuid, trust_domain_id uuid, lifecycle_state text, enrolled_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_machine record;
+  v_existing agent_board.fleet_machines%rowtype;
+  v_actor_agent_id uuid;
+  v_dest_rank integer;
+  v_prior_domain uuid;
+  v_landed_rank integer;
+  v_source_rank integer;
+  v_upserted_rows integer;
+begin
+  if nullif(trim(p_machine_label), '') is null or nullif(trim(p_machine_fingerprint), '') is null then
+    raise exception 'machine label and fingerprint are required' using errcode = '22023';
+  end if;
+
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_owner_agent_id, 'p_owner_agent_id');
+
+  if not exists (
+    select 1
+      from agent_board.fleet_trust_domains ftd
+     where ftd.id = p_trust_domain_id
+       and ftd.owner_agent_id = v_actor_agent_id
+       and ftd.lifecycle_state in ('active', 'pending')
+  ) then
+    raise exception 'trust domain is not active for owner' using errcode = '42501';
+  end if;
+
+  -- #395: the destination's approval rank, read once. NULL is impossible while the gate above
+  -- admits only ranked states; it is still compared fail-closed below.
+  select agent_board._fleet_trust_domain_approval_rank(ftd.lifecycle_state)
+    into v_dest_rank
+    from agent_board.fleet_trust_domains ftd
+   where ftd.id = p_trust_domain_id;
+
+  -- #397 (round 2): the conflicting row's domain BEFORE the move, read UNDER THE ROW LOCK.
+  --
+  -- The lock is the whole point, and its absence was a bypass. An unlocked read here answers
+  -- "what domain was this machine in at some committed instant before we waited", and the
+  -- post-move skip predicate below then treats that as "we did not relocate the machine". Those
+  -- two diverge exactly when a CONCURRENT session relocates the machine while our upsert waits:
+  -- if it moves the machine elsewhere and our upsert then moves it back to the domain our stale
+  -- read named, the predicate reads "unchanged", the fresh-snapshot check is skipped, and an
+  -- active machine commits in a demoted domain — the original hole. Two interleavings did exactly
+  -- that (isolation P3/P4, both reproduced before this line was written).
+  --
+  -- FOR UPDATE makes the read wait for whoever holds the row and observe the POST-WAIT truth, and
+  -- nothing can relocate the machine between here and the upsert because we hold it.
+  --
+  -- ON fleet_machines ONLY — deliberately not a join with FOR UPDATE, which would lock the
+  -- fleet_trust_domains row too. THAT is the lock #158/ab38805 added and had reverted for
+  -- deadlocking 40P01 against reclaim_fleet_machine (#159). This lock is the SAME row the upsert
+  -- below locks anyway, taken a moment earlier, so the acquisition order is unchanged: machine
+  -- row first, fleet_trust_domains only through the insert's FK KEY SHARE — which is exactly
+  -- reclaim_fleet_machine's own order. Isolation P5/P5-reverse drive the two against each other
+  -- in both directions and show serialization with no 40P01.
+  --
+  -- Null when there is no conflicting row: a first registration takes no lock here and skips the
+  -- post-check; the ON CONFLICT conjunct is what covers it if a concurrent insert makes one appear.
+  select fm.trust_domain_id
+    into v_prior_domain
+    from agent_board.fleet_machines fm
+   where fm.machine_fingerprint = trim(p_machine_fingerprint)
+     for update;
+
+
+  insert into agent_board.fleet_machines(
+    trust_domain_id,
+    owner_agent_id,
+    machine_label,
+    machine_fingerprint,
+    lifecycle_state,
+    enrollment_source,
+    enrolled_at,
+    revoked_at,
+    metadata
+  )
+  values (
+    p_trust_domain_id,
+    v_actor_agent_id,
+    trim(p_machine_label),
+    trim(p_machine_fingerprint),
+    'active',
+    coalesce(nullif(p_enrollment_source, ''), 'portal'),
+    now(),
+    null,
+    coalesce(p_metadata, '{}'::jsonb) || jsonb_build_object('redacted', true, 'metadata-safe', true)
+  )
+  on conflict (machine_fingerprint)
+  do update set
+    trust_domain_id = excluded.trust_domain_id,
+    machine_label = excluded.machine_label,
+    enrollment_source = excluded.enrollment_source,
+    enrolled_at = coalesce(agent_board.fleet_machines.enrolled_at, excluded.enrolled_at),
+    metadata = excluded.metadata,
+    -- owner_agent_id, lifecycle_state, revoked_at intentionally NOT updated (#141):
+    -- ownership is immutable via re-register and a revoked machine is not resurrected.
+    updated_at = now()
+  where agent_board.fleet_machines.owner_agent_id = v_actor_agent_id
+    -- #395: and the move may not LOWER the machine's domain approval. The subquery reads the
+    -- CONFLICTING row's current domain; NULL on either side makes this not-true, i.e. refuse.
+    and v_dest_rank >= (
+      select agent_board._fleet_trust_domain_approval_rank(ftd.lifecycle_state)
+        from agent_board.fleet_trust_domains ftd
+       where ftd.id = agent_board.fleet_machines.trust_domain_id
+    )
+  returning *, (xmax <> 0) as was_update into v_machine;
+  get diagnostics v_upserted_rows = row_count;
+
+  if v_upserted_rows = 0 then
+    -- Two reasons now match no row. Name the real one. The conflicting row is locked by the
+    -- upsert above (ON CONFLICT DO UPDATE locks before evaluating its WHERE), so this is stable.
+    select * into v_existing
+      from agent_board.fleet_machines fm
+     where fm.machine_fingerprint = trim(p_machine_fingerprint);
+
+    -- A fingerprint conflict on a row owned by a DIFFERENT owner: refuse the ownership-hijack
+    -- attempt (#141). Also the fail-closed default if the row cannot be re-read at all.
+    if v_existing.id is null or v_existing.owner_agent_id <> v_actor_agent_id then
+      raise exception 'machine fingerprint is registered to another owner' using errcode = '42501';
+    end if;
+
+    -- Own machine, refused by the approval-rank guard (#395).
+    raise exception 're-registration would move machine into a less approved trust domain (destination %, current %)',
+      p_trust_domain_id, v_existing.trust_domain_id using errcode = '42501';
+  end if;
+
+  -- #397 ROUND 3 — THE LOST RACE IS REFUSED, NOT GUESSED AT.
+  --
+  -- The pre-read above locks the conflicting row when there IS one. When there is not, we took no
+  -- lock — and our insert can still land on the CONFLICT path, because a concurrent first
+  -- registration of the same fingerprint commits while we block on the unique index. Round 2 tried
+  -- to cover that by comparing against the destination rank we had cached, and round 3's panel
+  -- showed why that is not a baseline: promote the SOURCE domain during the wait and the cached
+  -- destination rank still matches itself, so a machine moves out of a now-active domain into a
+  -- pending one and the comparison never notices.
+  --
+  -- There is no trustworthy baseline to recover here: the domain the machine was in belonged to a
+  -- row we never read, and the upsert has already overwritten it. So this refuses instead of
+  -- approximating. `xmax <> 0` distinguishes the conflict path from a genuine insert (a fresh
+  -- tuple carries xmax = 0), which makes the condition exact rather than inferred.
+  --
+  -- 40001, not 42501: this is a serialization failure and the caller should RETRY, not conclude it
+  -- lacks authority. The retry finds the row committed, locks it, and takes the ordinary path — so
+  -- the refusal costs one round trip and closes the whole no-baseline class.
+  if v_prior_domain is null and v_machine.was_update then
+    raise exception 'concurrent registration of machine fingerprint % — retry', trim(p_machine_fingerprint)
+      using errcode = '40001';
+  end if;
+
+  -- #397 ROUND 3 — THE DECISION: ONE BASELINE, ONE INSTANT.
+  --
+  -- Every earlier variant of this guard compared two ranks captured at DIFFERENT times, and each
+  -- round closed one instance of that shape while leaving the shape itself. This statement ends
+  -- the shape: it reads the landed domain's rank and the source domain's rank TOGETHER, in one
+  -- statement, hence from one snapshot, AFTER the move, while we hold the machine row.
+  --
+  -- What that pins by construction, rather than by enumerating interleavings:
+  --   * the machine's identity and its SOURCE domain id cannot change under us — we have held the
+  --     row since before the upsert (that is round 2's fix, and it is what makes `is distinct from`
+  --     mean "this statement relocated the machine");
+  --   * the LANDED domain id is the one our own upsert wrote, under that same lock;
+  --   * the two lifecycle values are read by ONE STATEMENT, hence from ONE SNAPSHOT, so neither a
+  --     demotion of the destination nor a promotion of the source can sit BETWEEN them. This is a
+  --     property of the single statement and NOT of the absence of a wait: READ COMMITTED lets
+  --     another transaction commit between successive COMMANDS, so splitting this select in two
+  --     would give the two reads two snapshots and reopen the cross-time comparison every earlier
+  --     round of #397 closed one instance of. No behavioural test can see that split — both reads
+  --     agree single-session — so it is gated STRUCTURALLY by assertion 28 of
+  --     agent_board_fleet_machine_hijack.test.sql, which requires both rank calls and the
+  --     `into v_landed_rank, v_source_rank` target list to be reachable without crossing a `;`.
+  --     DO NOT split this statement.
+  -- Nothing else feeds the decision. v_dest_rank is a pre-filter on the upsert's WHERE and is NOT
+  -- authoritative: it can only make the statement refuse EARLIER, never permit something this
+  -- check would refuse.
+  --
+  -- SURVIVING CLASS, stated exactly: a lifecycle change that commits AFTER this read. It is
+  -- indistinguishable from one serialized after the whole registration, i.e. from `register` then
+  -- `demote`, which is permitted and deliberately unchanged. Excluding it needs a lock on
+  -- fleet_trust_domains, which is #159's to add (see the pre-read for why it is not taken here).
+  if v_prior_domain is not null and v_machine.trust_domain_id is distinct from v_prior_domain then
+    select agent_board._fleet_trust_domain_approval_rank(landed.lifecycle_state),
+           agent_board._fleet_trust_domain_approval_rank(source.lifecycle_state)
+      into v_landed_rank, v_source_rank
+      from agent_board.fleet_trust_domains landed,
+           agent_board.fleet_trust_domains source
+     where landed.id = v_machine.trust_domain_id
+       and source.id = v_prior_domain;
+
+    if v_landed_rank is null or v_source_rank is null or v_landed_rank < v_source_rank then
+      raise exception 're-registration would move machine into a less approved trust domain (destination %, current %) — measured after the move, from one snapshot',
+        v_machine.trust_domain_id, v_prior_domain using errcode = '42501';
+    end if;
+  end if;
+
+  return query select v_machine.id, v_machine.trust_domain_id, v_machine.lifecycle_state, v_machine.enrolled_at;
+end;
+$$;
+
+revoke all on function agent_board.register_fleet_machine(uuid, uuid, text, text, text, jsonb) from public, anon;
+grant execute on function agent_board.register_fleet_machine(uuid, uuid, text, text, text, jsonb) to authenticated, service_role;
+
+comment on function agent_board.register_fleet_machine(uuid, uuid, text, text, text, jsonb) is
+  'Registers/updates a fleet machine for the resolved actor. Anti-hijack (#141): a fingerprint conflict owned by a different owner raises 42501 (ownership is immutable via re-register); re-register never resurrects a revoked machine (revocation authority lives in fleet_revocation_events). No-downgrade (#395): a re-registration may not MOVE the machine into a trust domain LESS APPROVED than its current one (approval rank: active > pending > quarantined = suspended = revoked, per _fleet_trust_domain_approval_rank) and raises 42501 if it would; an equal-rank relocation, an upgrade, and a first registration are unaffected. An unranked lifecycle value refuses rather than fails open. Concurrency (#397): the rank comparison is a conjunct of the ON CONFLICT DO UPDATE, so it is atomic against the conflicting MACHINE row, but the destination domain''s lifecycle cannot be pinned without a fleet_trust_domains lock (reverted once for deadlocking against reclaim_fleet_machine; #159 owns the lock order). A demotion that commits while the upsert waits is caught by a post-move re-check in a fresh statement, which raises 42501 and unwinds the move; a demotion committing after that check still lands and is serial-equivalent to register-then-demote, which is permitted.';