electric-sql / electric-sql/electric
Agents auth follow-up: claim-scoped write tokens, shared-state auth, and distributed validity
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 375
- Avg merge
- 3d 1h
- Merged PRs (30d)
- 18
Description
## Summary
The recent stale-epoch fix for Electric Agents moved entity-stream write fencing from durable-stream producer epochs to claim-scoped write tokens plus `autoClaim` on the runtime producer. That is the right direction, but it leaves a broader auth/distribution follow-up.
## Current state
- Entity main-stream writes now use claim-scoped write tokens minted on successful wake claim.
- Entity main-stream writes are validated against the currently active claim token when one exists.
- Runtime producers use `autoClaim` to recover when durable streams has a higher remembered producer epoch.
## Follow-up gaps
### 1. Shared-state writes are still effectively unauthenticated
Shared-state producers can now also `autoClaim`, but shared-state append paths do not currently enforce bearer-token auth the same way entity main streams do.
That means stale or unauthorized shared-state writers are not fenced by the same claim-token mechanism.
### 2. Claim-token validity is process-local and not lease-coupled
Active claim write tokens are currently held in memory on the server.
Consequences:
- after server restart, active claim state is lost;
- in a distributed/cloud deployment, different server instances will not share claim-token validity;
- token validity is not currently refreshed/expired based on webhook heartbeat or lease expiry.
We need a real mechanism for tracking the latest and only valid write authority for a claimed stream across instances. This does **not** require JWT specifically; durable/shared server-side state is fine.
### 3. Entity-token fallback is still compatibility behavior, not a strict final invariant
Today the entity write token is still accepted when no active claim token is present.
That is useful for compatibility, but it means the invariant is only:
> while an active claim is present, only that claim token may write
and not yet:
> only the current claimed worker may write
### 4. Callback-forward / done semantics should be audited
The runtime and forwarding server mostly key off HTTP success today. We should confirm whether callback responses can be `200` with `{ ok: false }`, and tighten handling if so.
## Goal
Design and implement the actual auth model for Agents writes in a distributed deployment:
- define write authority for entity streams and shared-state streams;
- make "latest valid token" tracking work across server restarts / multiple instances;
- couple claim-token validity to claim/lease lifecycle;
- close the shared-state auth gap.
## Context
This came up while fixing stale producer epoch errors like:
- wake consumer epoch is low after restart/reclaim;
- durable streams remembers a higher producer epoch for the same producer id;
- runtime must use `autoClaim` to recover;
- correctness therefore depends on auth fencing stale writers, not on producer epochs alone.
Contributor guide
Assessment
This issue has not been assessed yet.