plexsphere

Appearance

Operate peers and PSKs ​

The Key & Peer Manager exposes peer state in Postgres and emits three lifecycle events. There is no plexctl peers command yet, so this guide inspects peer state with psql and the per-Node SSE stream.

Prerequisites ​

  • Read access to the plexsphere Postgres role (psql).
  • A workstation with curl for the SSE stream at GET /v1/nodes/{id}/events.

Steps ​

List peers in a Domain ​

sql
SELECT id AS peer_id, lifecycle_state, registered_at
FROM peers WHERE domain_id = '<domain-uuid>';
-- peer_id     | lifecycle_state | registered_at
-- 0192f2f6-…  | active          | 2026-04-27 10:15:30+00
-- (1 row)

List live PSKs ​

sql
SELECT k.peer_id, k.key_id, k.assigned_at
FROM peer_psks k JOIN peers p ON p.id = k.peer_id
WHERE p.domain_id = '<domain-uuid>' AND k.retired_at IS NULL;
-- peer_id     | key_id     | assigned_at
-- 0192f2f6-…  | 0192f30a-… | 2026-04-27 10:15:31+00
-- (1 row)

The wrapped ciphertext is never selected.

Audit peer lifecycle events ​

The manager emits exactly three outbox event_type values — peer_registered, peer_psk_assigned, and peer_deregistered:

sql
SELECT id AS event_id, event_type, occurred_at
FROM outbox
WHERE event_type IN ('peer_registered', 'peer_psk_assigned', 'peer_deregistered')
ORDER BY occurred_at DESC LIMIT 20;
-- event_id    | event_type        | occurred_at
-- 0192f31c-…  | peer_psk_assigned | 2026-04-27 10:15:31+00
-- 0192f31b-…  | peer_registered   | 2026-04-27 10:15:30+00
-- (2 rows)

A peer_registered row without a matching peer_psk_assigned in the same transaction window indicates a partial enrolment to investigate.

Verification ​

Tail the per-Node SSE stream and confirm the same event types arrive:

shell
curl -N -H "Authorization: Bearer ${TOKEN}" \
  "${PLEXSPHERE_URL}/v1/nodes/${NODE_ID}/events" | grep -E 'peer_(registered|psk_assigned|deregistered)'
# event: peer_registered
# event: peer_psk_assigned

See also ​