Agents auth follow-up: claim-scoped write tokens, shared-state auth, and distributed validity
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- typescript
Research direction
Start by tracing the runtime, forwarding server, entity main-stream writes, and shared-state append paths described in the issue. Audit callback handling for HTTP 200 responses containing { ok: false }. Done means shared-state writes are fenced, the latest token is valid across restarts and instances, and token validity follows the claim or lease lifecycle.
Written by the indexing model from the issue text.
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
autoClaimto 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
autoClaimto recover; - correctness therefore depends on auth fencing stale writers, not on producer epochs alone.
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 399
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from electric-sql/electric
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryOpen
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error valuePossibly taken @Tyagiquamar claimed this 19 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)Possibly taken @mohanedmoh claimed this 37 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4826 · 1 comment ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wakePossibly taken @adityavkk claimed this 133 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
electric-sql/electric#4687 ·
-
Listen IP addressOpenfeature request triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
electric-sql/electric#4150 · 1 comment ·
All issues in electric-sql/electric
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
"code source" and "numerique.gouv" links: "new window" mention duplicated in the accessible nameOpenaccessibility
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
numerique-gouv/lasuite-landingpage#315 ·
Maintainers usually reply within 1 day
-
needs:triage
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
HyeokjaeChoi/vaultme#585 ·
Maintainers usually reply within 1 day
-
enhancement priority/P2
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
beettlle/pi-smart-router#200 ·