Interface: HandoffStateStore

Defined in: packages/core/src/handoff/types.ts:19

Pluggable persistence interface for the Claim-Check pattern.

When carryOverState exceeds 2 KB, the SwarmGateway persists it under a UUID key and embeds only the key inside the HMAC token, keeping HTTP headers within safe limits (< 8 KB nginx/ALB limit).

Default implementation: InMemoryHandoffStateStore (same package). Platform adapters: implement this interface (e.g. @vurb/cloudflare).

Methods

delete()?

optional delete(stateId): Promise<void>;

Defined in: packages/core/src/handoff/types.ts:50

Delete the state without reading it.

Used in the two-phase read-then-delete pattern (see get above). Falls back to a no-op if not implemented.

Parameters

Parameter	Type
stateId	string

Returns

Promise<void>

---

get()?

optional get(stateId): Promise<Record<string, unknown> | undefined>;

Defined in: packages/core/src/handoff/types.ts:43

Read the state without deleting it.

(optional method): allows the two-phase read-then-delete pattern so that verifyDelegationToken can read the state into memory before deleting it. This prevents irrecoverable data loss if an error occurs between the read and the return of the claims to the caller.

Falls back to getAndDelete if not implemented (old implementations).

Parameters

Parameter	Type
stateId	string

Returns

Promise<Record<string, unknown> | undefined>

---

getAndDelete()

getAndDelete(stateId): Promise<Record<string, unknown> | undefined>;

Defined in: packages/core/src/handoff/types.ts:32

Retrieve and atomically delete the state (one-shot). Prevents state leaks after successful handoff hydration. Returns undefined if the key does not exist or has expired.

Parameters

Parameter	Type
stateId	string

Returns

Promise<Record<string, unknown> | undefined>

---

set()

set(
   stateId, 
   state, 
ttlSeconds): Promise<void>;

Defined in: packages/core/src/handoff/types.ts:26

Persist a state object under stateId with a TTL.

Parameters

Parameter	Type	Description
stateId	string	UUID key
state	Record<string, unknown>	Arbitrary carry-over state
ttlSeconds	number	Expiry in seconds

Returns

Promise<void>