@consiliency/agent-board-schema 1.12.0 → 1.23.0

package/migrations/20260822000200_agent_board_mint_harden_fingerprint_backfill.sql

@@ -0,0 +1,207 @@
+-- =============================================================================
+-- MINTHARDEN (#138) — data-derived signing-key fingerprint BACKFILL.
+-- =============================================================================
+-- 20260822000100 routed every fingerprint WRITER through _raw_key_fingerprint (raw
+-- 32 bytes) and installed a table-boundary integrity trigger. This migration corrects
+-- the EXISTING rows: string-era mint child keys (20260718001000 derived over the
+-- base64url STRING) and any stored non-canonical public_key alias. 20260719001200
+-- shipped NO backfill, so string-era ENROLL rows are in scope too — the predicate is
+-- data-derived (every raw row where the stored fingerprint/public_key diverges from the
+-- canonical raw derivation), NOT a path- or key_id-scoped list (CLAUDE.md rule #1).
+--
+-- ⚠ OPERATOR RUNBOOK — READ BEFORE DEPLOYING TO A LIVE FLEET ⚠
+-- Re-deriving a fingerprint to the canonical raw-byte value ALIGNS the DB with what
+-- clients already compute (child_keygen keyRef + the enroll/session EFs derive the raw
+-- fingerprint), so a correctly-behaving agent is NOT locked out by the re-derivation.
+-- The two hazards are gated fail-closed:
+--
+--   1. CROSS-OWNER COLLISION (fatal, always). If two keys owned by DIFFERENT owners
+--      compute to the SAME raw fingerprint, one keypair backs two identities — live
+--      squat evidence. The migration ABORTS with the collision listing and does NOT
+--      auto-revoke. Resolve by hand FIRST: possession cannot distinguish the rightful
+--      holder, so revoke ALL bindings for the colliding fingerprint (status='revoked')
+--      and tombstone it (a permanently-revoked placeholder row) so it cannot be
+--      re-registered, then re-run. Plan any agent re-keying BEFORE deploying.
+--
+--   2. SAME-OWNER ALIAS DUPLICATES (gated). If the SAME owner holds the same key under
+--      two rows (a canonical key + its non-canonical alias), the redundant alias rows
+--      are DELETED (keeping the earliest) — a destructive step, so it runs ONLY when
+--      the operator sets  SET agent_board.fingerprint_backfill_dedup = 'on';  in the
+--      migration session. Absent the guard, the migration ABORTS with the listing so
+--      the operator decides explicitly. (A fresh replay has no such duplicates.)
+--
+-- The safe re-derivation runs unconditionally (it is corrective). schema_version stays 8.
+-- =============================================================================
+
+-- ---------------------------------------------------------------------------
+-- 1. _raw_key_canonical — TOLERANT canonical form of a stored public_key (returns NULL
+--    rather than raising on a non-32-byte value), so the backfill can canonicalize a
+--    legacy alias without _raw_key_fingerprint's strict canonical rejection tripping.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._raw_key_canonical(p_public_key text)
+returns text
+language plpgsql
+immutable
+set search_path = agent_board, public
+as $$
+declare
+  v_raw bytea;
+begin
+  if p_public_key is null then
+    return null;
+  end if;
+  begin
+    v_raw := decode(translate(p_public_key, '-_', '+/') || '=', 'base64');
+  exception when others then
+    return null;
+  end;
+  if octet_length(v_raw) <> 32 then
+    return null;
+  end if;
+  return rtrim(translate(encode(v_raw, 'base64'), '+/', '-_'), '=');
+end;
+$$;
+
+comment on function agent_board._raw_key_canonical(text) is
+  'Tolerant canonical base64url form of a raw Ed25519 public_key (NULL if it does not '
+  'decode to 32 bytes). Backfill-only: lets a legacy non-canonical alias be canonicalized '
+  'without _raw_key_fingerprint''s strict alias rejection aborting the pass.';
+
+revoke all on function agent_board._raw_key_canonical(text) from public, anon, authenticated;
+grant execute on function agent_board._raw_key_canonical(text) to service_role;
+
+-- ---------------------------------------------------------------------------
+-- 2. Cross-owner collision report (reusable + pgTAP-pinned). Groups raw signing keys by
+--    their canonical raw-byte fingerprint and surfaces any fingerprint spanning >1 owner.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._raw_fingerprint_backfill_collisions()
+returns table(
+  computed_fingerprint text,
+  owner_count bigint,
+  agent_ids uuid[],
+  owner_user_ids uuid[],
+  key_ids uuid[]
+)
+language sql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+  with fp as (
+    select k.id as key_id, k.agent_id, a.owner_user_id,
+           agent_board._raw_key_fingerprint(agent_board._raw_key_canonical(k.public_key)) as computed_fingerprint
+      from agent_board.agent_signing_keys k
+      join agent_board.agents a on a.id = k.agent_id
+     where k.public_key_format = 'raw_ed25519_base64url'
+       and agent_board._raw_key_canonical(k.public_key) is not null
+  )
+  select computed_fingerprint,
+         count(distinct owner_user_id) as owner_count,
+         array_agg(distinct agent_id) as agent_ids,
+         array_agg(distinct owner_user_id) as owner_user_ids,
+         array_agg(key_id) as key_ids
+    from fp
+   group by computed_fingerprint
+  having count(distinct agent_id) > 1;
+$$;
+
+comment on function agent_board._raw_fingerprint_backfill_collisions() is
+  'Backfill preflight: raw signing keys grouped by canonical raw-byte fingerprint where the '
+  'group spans more than one AGENT (one keypair backing multiple identities — whether across '
+  'owners or two agents of the same owner). Auto-dedup must never delete a DIFFERENT agent''s '
+  'binding, so any such group aborts the backfill fail-closed for an operator decision.';
+
+revoke all on function agent_board._raw_fingerprint_backfill_collisions() from public, anon, authenticated;
+grant execute on function agent_board._raw_fingerprint_backfill_collisions() to service_role;
+
+-- ---------------------------------------------------------------------------
+-- 3. The backfill pass.
+-- ---------------------------------------------------------------------------
+do $$
+declare
+  v_listing text;
+  v_dup_listing text;
+  v_dup_groups int;
+  v_deleted int := 0;
+  v_updated int := 0;
+  v_dedup_enabled boolean := (nullif(current_setting('agent_board.fingerprint_backfill_dedup', true), '') = 'on');
+begin
+  -- (a) CROSS-IDENTITY collisions (one keypair spanning >1 AGENT, whether across owners
+  -- or two agents of one owner) -> fail closed (always). Auto-dedup must never delete a
+  -- DIFFERENT agent's active binding, so the operator resolves these by hand.
+  if exists (select 1 from agent_board._raw_fingerprint_backfill_collisions()) then
+    select string_agg(
+             format('  %s : agents %s owners %s (keys %s)',
+                    computed_fingerprint, agent_ids, owner_user_ids, key_ids),
+             E'\n' order by computed_fingerprint)
+      into v_listing
+      from agent_board._raw_fingerprint_backfill_collisions();
+    raise exception E'FINGERPRINT BACKFILL ABORTED — one keypair backs multiple AGENTS (cross-identity collision). Resolve per the migration runbook (decide which agent keeps the key; revoke the other bindings + tombstone the fingerprint) BEFORE re-running:\n%', v_listing
+      using errcode = '23505';
+  end if;
+
+  -- (b) SAME-AGENT alias duplicates only. Group raw keys by (agent, canonical fingerprint);
+  -- a group with >1 row is the SAME agent holding the SAME key twice (a canonical row + its
+  -- alias) — safe to collapse. (Cross-agent sharing already aborted in (a), so every group
+  -- here is single-agent.) Deleting rows is destructive, so it is GATED behind an explicit
+  -- session guard; absent it, abort with the listing so the operator decides.
+  with grp as (
+    select k.id as key_id, k.agent_id, k.created_at,
+           agent_board._raw_key_fingerprint(agent_board._raw_key_canonical(k.public_key)) as fp
+      from agent_board.agent_signing_keys k
+     where k.public_key_format = 'raw_ed25519_base64url'
+       and agent_board._raw_key_canonical(k.public_key) is not null
+  ),
+  dups as (
+    select agent_id, fp, count(*) as n
+      from grp
+     group by agent_id, fp
+    having count(*) > 1
+  )
+  select count(*), string_agg(format('  agent %s fingerprint %s (%s rows)', agent_id, fp, n), E'\n')
+    into v_dup_groups, v_dup_listing
+    from dups;
+
+  if coalesce(v_dup_groups, 0) > 0 then
+    if not v_dedup_enabled then
+      raise exception E'FINGERPRINT BACKFILL ABORTED — same-agent duplicate key rows (alias pairs on one agent). Set  SET agent_board.fingerprint_backfill_dedup = ''on'';  to delete the redundant aliases (earliest row kept), or resolve by hand:\n%', v_dup_listing
+        using errcode = '23505';
+    end if;
+    -- Guarded destructive dedup: keep the earliest row per (agent, fingerprint), delete the
+    -- rest (byte-identical aliases of the SAME agent's own key).
+    with grp as (
+      select k.id as key_id, k.agent_id, k.created_at,
+             agent_board._raw_key_fingerprint(agent_board._raw_key_canonical(k.public_key)) as fp
+        from agent_board.agent_signing_keys k
+       where k.public_key_format = 'raw_ed25519_base64url'
+         and agent_board._raw_key_canonical(k.public_key) is not null
+    ),
+    ranked as (
+      select key_id,
+             row_number() over (partition by agent_id, fp order by created_at, key_id) as rn
+        from grp
+    )
+    delete from agent_board.agent_signing_keys k
+     using ranked r
+     where k.id = r.key_id and r.rn > 1;
+    get diagnostics v_deleted = row_count;
+    raise notice 'MINTHARDEN fingerprint backfill: deleted % same-agent alias duplicate row(s)', v_deleted;
+  end if;
+
+  -- (c) Data-derived re-derivation (corrective, always). Canonicalize public_key and set
+  -- fingerprint to the raw derivation for every raw row where either diverges. The
+  -- integrity trigger validates each corrected row (session_replication_role unchanged).
+  update agent_board.agent_signing_keys k
+     set public_key = agent_board._raw_key_canonical(k.public_key),
+         fingerprint = agent_board._raw_key_fingerprint(agent_board._raw_key_canonical(k.public_key)),
+         updated_at = now()
+   where k.public_key_format = 'raw_ed25519_base64url'
+     and agent_board._raw_key_canonical(k.public_key) is not null
+     and (
+       k.public_key is distinct from agent_board._raw_key_canonical(k.public_key)
+       or k.fingerprint is distinct from agent_board._raw_key_fingerprint(agent_board._raw_key_canonical(k.public_key))
+     );
+  get diagnostics v_updated = row_count;
+  raise notice 'MINTHARDEN fingerprint backfill: re-derived % raw signing-key row(s)', v_updated;
+end;
+$$;

package/migrations/20260823000100_agent_board_fleet_machine_hijack.sql

@@ -0,0 +1,106 @@
+-- #141 register_fleet_machine fleet-ownership hijack fix.
+--
+-- machine_fingerprint is GLOBALLY unique (idx_agent_board_fleet_machines_fingerprint_unique),
+-- so the prior `on conflict (machine_fingerprint) do update set owner_agent_id = excluded...,
+-- lifecycle_state = 'active', revoked_at = null` let ANY trust-domain owner re-register an
+-- existing fingerprint and (a) steal owner_agent_id of another owner's machine and
+-- (b) un-revoke a deliberately revoked machine. Once #133 CLAIMGATE makes fingerprint
+-- ownership equal claim authority, that is an authority-transfer + lockout primitive.
+--
+-- This migration reproduces register_fleet_machine VERBATIM except the conflict handling:
+--   * The `do update` is gated `where owner_agent_id = <resolved actor>`. A cross-owner
+--     fingerprint conflict matches no row, updates nothing, `returning` yields no row, and
+--     we then RAISE 42501. This is evaluated atomically against the conflicting row, so it
+--     is also free of the select-then-insert TOCTOU that a pre-check guard would carry.
+--   * owner_agent_id is NEVER in the update set — ownership is immutable via re-register.
+--   * lifecycle_state / revoked_at are NEVER in the update set — a re-register does NOT
+--     resurrect a deliberately revoked machine (revocation authority lives in the
+--     append-only fleet_revocation_events; flipping lifecycle here would only desync it).
+--     Same-owner re-register still updates descriptive fields (label / domain / source /
+--     metadata) exactly as before.
+-- The fn is granted to authenticated (#118 discipline); create-or-replace preserves the
+-- ACL, but revoke/grant are restated for clarity and the comment records the guard.
+
+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 agent_board.fleet_machines%rowtype;
+  v_actor_agent_id uuid;
+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;
+
+  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
+  returning * into v_machine;
+
+  -- A fingerprint conflict on a row owned by a DIFFERENT owner matches no update row
+  -- above, so v_machine is null here: refuse the ownership-hijack attempt (#141).
+  if v_machine.id is null then
+    raise exception 'machine fingerprint is registered to another owner' using errcode = '42501';
+  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).';