Agents auth follow-up: claim-scoped write tokens, shared-state auth, and distributed validity

Open
#4,286 0 comments 0 reactions 0 assignees View on GitHub

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 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.
Dominant language
TypeScript
Stars
10.4k
Forks
399
PR merge metrics
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from electric-sql/electric

All issues in electric-sql/electric

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.