@zackbart/connecta 0.32.0 → 0.34.0

package/dist/access-tokens.d.ts

@@ -1,38 +1,182 @@
-import type { IdentityReference, InboundAuth, KVStorage } from "./types.js";
+import type { InboundAuth, KVStorage } from "./types.js";
 import type { AccessTokensModule } from "./module-contracts.js";
-export interface AccessTokenMetadata {
-    id: string;
+/**
+ * One declared agent's token slot as management sees it. Never secret
+ * material. `revision` is opaque: it changes on every commit to the slot and
+ * is what `expect` names to make an operation conditional on this view.
+ */
+export type AgentTokenSlot = {
     name: string;
-    tokenPrefix: string;
-    createdAt: string;
-    revokedAt?: string;
-}
-export interface CreatedAccessToken {
+    state: "none";
+    revision: string;
+} | {
+    name: string;
+    state: "issued";
+    issuedAt: string;
+    revision: string;
+} | {
+    name: string;
+    state: "revoked";
+    revokedAt: string;
+    revision: string;
+};
+/** A newly issued secret, returned once, and the slot that now admits it. */
+export interface IssuedAgentToken {
     token: string;
-    accessToken: AccessTokenMetadata;
+    agent: AgentTokenSlot;
 }
+/** Why a token operation was refused, for routes and provisioning scripts. */
+export declare class AccessTokenError extends Error {
+    readonly code: "unknown_agent" | "conflict" | "slot_changed" | "not_adoptable" | "aborted" | "outcome_unknown";
+    readonly name = "AccessTokenError";
+    constructor(code: "unknown_agent" | "conflict" | "slot_changed" | "not_adoptable" | "aborted" | "outcome_unknown", message: string);
+}
+/** Options every token mutation takes. */
+export interface AccessTokenOperationOptions {
+    /**
+     * The request this operation serves. Checked before the commit point, the
+     * slot's compare-and-set: an abort before it publishes nothing. An abort
+     * after a rotation commits revokes the slot, since the secret cannot be
+     * delivered.
+     */
+    signal?: AbortSignal;
+    /**
+     * The request's own deadline, in epoch milliseconds, when it has one. The
+     * operation ends at the earlier of this and `OPERATION_WINDOW_MS` after it
+     * starts.
+     */
+    deadline?: number;
+    /**
+     * The slot `revision` the caller decided from. When set, the operation
+     * refuses with `slot_changed` before minting or writing anything if the
+     * slot's current revision differs, and its commit compare-and-sets from
+     * exactly the slot with that revision, so a change that lands between the
+     * read and the commit refuses the same way instead of being overwritten.
+     */
+    expect?: string;
+}
+/** Whether `value` has the shape of a slot revision. */
+export declare function isSlotRevision(value: unknown): value is string;
 /**
- * Deployment-scoped personal access tokens. Secret material is never
+ * Agent tokens: one slot per agent declared in code. Secret material is never
  * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
- * token, while separately enumerable metadata powers operator management.
+ * token, and only that digest persists. A token admits only while its record
+ * is bound to a currently declared agent and that agent's slot names it.
  */
 export declare class AccessTokenManager {
     private readonly storage;
     readonly auth: InboundAuth;
-    private readonly maxActive;
+    private readonly agents;
+    private readonly agentOrder;
     constructor(storage: KVStorage, options?: {
-        maxActive?: number;
+        agents?: readonly string[];
     });
+    private declared;
     private read;
-    list(): Promise<AccessTokenMetadata[]>;
-    create(name: unknown, createdBy: string | IdentityReference): Promise<CreatedAccessToken>;
-    rename(id: string, name: unknown): Promise<AccessTokenMetadata | null>;
-    revoke(id: string, revokedBy: string): Promise<AccessTokenMetadata | null>;
-    private updateRecord;
-    private updateActive;
+    private readSlot;
+    /** One slot per declared agent, in declaration order. */
+    list(): Promise<AgentTokenSlot[]>;
+    /**
+     * Issue the agent's first token, or replace its current one.
+     *
+     * 1. The slot is read. With `expect`, a slot whose revision differs refuses
+     *    with `slot_changed` before any secret is minted.
+     * 2. The new record and its lookup are written. They are inert: admission
+     *    requires the slot to name the record.
+     * 3. `signal` is checked.
+     * 4. One compare-and-set of the slot, from exactly what was read to
+     *    `issued` with the new record, is the only commit point. From it the
+     *    new secret admits and the previous one refuses. Of concurrent
+     *    rotations exactly one commits; the others publish nothing and refuse
+     *    with `slot_changed` when they named `expect`, a conflict otherwise.
+     * 5. If the request has ended once the commit is decided, the secret cannot
+     *    be delivered, so the slot moves forward to `revoked`. Everything after
+     *    the commit runs inside one `OperationWindow`; if it cannot settle in
+     *    time this rejects with `outcome_unknown` ("rotate again"), never success.
+     *
+     * Nothing is ever deleted except this call's own record and lookup, while
+     * they are known to be uncommitted. The previous record and lookup stay
+     * behind, inert, because the slot no longer names them.
+     */
+    rotate(name: string, issuedBy?: string, options?: AccessTokenOperationOptions): Promise<IssuedAgentToken>;
+    /** Whether the agent's slot names `tokenId`, read back inside the window. */
+    private slotNames;
+    /**
+     * Move the slot forward to `revoked` if it still names `tokenId`, inside the
+     * window. An unsettled outcome is reported, never swallowed.
+     */
+    private revokeIfNamed;
+    /**
+     * Revoke the agent's token. One compare-and-set of the slot to `revoked` is
+     * the commit; `signal` is checked after the read and before it. The record
+     * and lookup stay behind, inert. With `expect`, a slot whose revision
+     * differs refuses with `slot_changed` before anything is written, and so
+     * does a slot that changes between the read and the commit; without it,
+     * whatever the slot names by then is revoked instead.
+     */
+    revoke(name: string, options?: AccessTokenOperationOptions): Promise<AgentTokenSlot>;
+    /**
+     * Settle a conditional revocation whose commit went unanswered, inside the
+     * window. Only a slot carrying this call's own `revocationId` is its
+     * success. A slot still as read is revoked again from exactly that slot,
+     * with the same id; anything else is `slot_changed`.
+     */
+    private settleRevocation;
+    /**
+     * Trusted provisioning: let a declared agent keep using a machine token
+     * issued before agents. The legacy record is never changed.
+     *
+     * 1. A write-once claim, `access-token:v1:adopted:<legacy id>`, is set from
+     *    absent to the agent's name. It is never deleted: once any adoption has
+     *    started, the legacy token belongs to that agent forever, even after it
+     *    is revoked or rotated away, so a retired secret can never be adopted
+     *    again. It is inert to admission; an abort after it leaves the token
+     *    adoptable only by the same agent.
+     * 2. A new record carrying `agent` and the legacy digest is written; it is
+     *    inert until the slot names it.
+     * 3. `signal` is checked.
+     * 4. One compare-and-set of the slot from none to `issued` with the new
+     *    record is the commit. Adopt delivers no secret, so once committed it is
+     *    completed even if the request ended.
+     * 5. The digest's lookup is moved from the legacy record to the new one by
+     *    compare-and-set; from then the existing secret admits as the agent.
+     *
+     * The commit and everything after it run inside one `OperationWindow`.
+     * Retrying an adoption whose slot already names a record with this digest
+     * completes step 5 and succeeds. With `expect`, a slot whose revision
+     * differs refuses with `slot_changed` before the claim, and so does a
+     * commit that loses its compare-and-set. Human-bound, revoked, and claimed tokens are
+     * refused, as is an agent whose slot names anything else.
+     */
+    adopt(tokenId: string, name: string, options?: AccessTokenOperationOptions): Promise<AgentTokenSlot>;
+    /**
+     * Step 4 of adoption, idempotent and inside the window: point the digest's
+     * lookup at the record the slot names. If another agent's adoption took the
+     * lookup first, this slot can never admit, so it moves forward to `revoked`
+     * and this refuses.
+     */
+    private completeAdoption;
+    /** The declared agent whose issued slot names a record with this digest, if any, read inside the window. */
+    private agentCarrying;
+    /**
+     * Trusted provisioning: the legacy records `adopt` can take, oldest first:
+     * unbound, unrevoked, never claimed by an adoption, still the owner of their
+     * digest's lookup, and with a digest no declared agent's slot carries. Ids, names and creation times
+     * only; never secret material.
+     */
+    unboundTokens(): Promise<Array<{
+        id: string;
+        name: string;
+        createdAt: string;
+    }>>;
     private authorize;
 }
-/** Opt in using the same storage namespace that held the v0.23 records. */
-export declare function accessTokens(storage: KVStorage, options?: {
-    maxActive?: number;
-}): AccessTokensModule;
+/** accessTokens() takes no options: the agents declared in code bound its slots. */
+type AccessTokensOptions = Record<never, never>;
+/**
+ * Agent token authentication and management over the deployment's storage.
+ * Reuse the storage that held earlier tokens so their records stay readable;
+ * `createConnecta` binds the module to `agents`.
+ */
+export declare function accessTokens(storage: KVStorage, options?: AccessTokensOptions): AccessTokensModule;
+export {};