attention-manifest-protocol 0.4.2 → 0.4.3

package/lib/session/registry.d.ts

@@ -0,0 +1,130 @@
+import { SessionContexts } from "./context.js";
+import type { AgentId, SessionAuthentication, SessionCredential, SessionDescriptor, SessionForkInput, SessionId, SessionOpenInput, SessionRegistryOptions, SessionSummary } from "./types.js";
+type OpenedSession = {
+    descriptor: SessionDescriptor;
+    credential: SessionCredential;
+};
+/**
+ * Optional `SessionStore` extension for the token-rotation counter. The base
+ * port has no rotation column, so an adapter that wants the cap to survive a
+ * restart implements these two methods; adapters that do not keep the counter
+ * in memory only.
+ */
+export interface SessionRotationStore {
+    loadRotations(sessionId: SessionId): number | undefined;
+    saveRotations(sessionId: SessionId, rotations: number): void;
+}
+export declare class SessionRegistry {
+    readonly context: SessionContexts;
+    private readonly limits;
+    private readonly defaults;
+    private readonly store?;
+    private readonly clock;
+    private readonly records;
+    constructor(options?: SessionRegistryOptions);
+    /**
+     * Open a new session. Roots are resolved through `realpathSync` once, at
+     * this boundary, so replacing a parent directory later cannot move an
+     * already-authorized root. The raw token is returned exactly once.
+     */
+    open(input: SessionOpenInput): OpenedSession;
+    /**
+     * Verify a bearer token and refresh the idle deadline. The absolute deadline
+     * is never extended; a successful call advances `revision` and is persisted.
+     */
+    authenticate(sessionId: SessionId, token: string): SessionAuthentication;
+    /**
+     * Host-side descriptor lookup. It is safe to call for an expired or revoked
+     * session: the terminal status is returned for audit rather than revived.
+     * `authenticate` is the operation that refuses terminal sessions.
+     */
+    get(sessionId: SessionId): SessionDescriptor;
+    /**
+     * List descriptors, optionally filtered to one agent. Terminal records are
+     * included; a host that needs only live sessions filters on `status`.
+     */
+    list(agentId?: AgentId): SessionDescriptor[];
+    /**
+     * Diagnostics summary for one session. Terminal sessions stay inspectable.
+     */
+    summary(sessionId: SessionId): SessionSummary;
+    /**
+     * Refresh the idle deadline for an active session without checking a token.
+     * Host-only keepalive; a caller that needs the token path uses
+     * `authenticate`.
+     */
+    touch(sessionId: SessionId): SessionDescriptor;
+    /**
+     * Suspend an active session. Suspending an already suspended session is
+     * idempotent; terminal sessions are never revived.
+     */
+    suspend(sessionId: SessionId): SessionDescriptor;
+    /**
+     * Resume a suspended session. Only the absolute deadline blocks a resume;
+     * the idle deadline is refreshed by this call, so a host that explicitly
+     * reactivates a session does not have to race the idle timer.
+     */
+    resume(sessionId: SessionId): SessionDescriptor;
+    /**
+     * Revoke a session permanently. The descriptor and context are retained for
+     * audit, but the stored secret is replaced with an empty hash, so a restored
+     * registry cannot authenticate the old token either. `authenticate` checks
+     * `revoked` before the token, which makes the failure unambiguous. A session
+     * whose deadline has already passed is reported as `session_expired`; the
+     * host uses `close` to remove it.
+     */
+    revoke(sessionId: SessionId): SessionDescriptor;
+    /**
+     * Replace the bearer token, invalidating the previous one immediately.
+     * Active and suspended sessions may rotate, up to `maxTokenRotations`. When
+     * the store implements {@link SessionRotationStore}, the counter is persisted
+     * before the descriptor so a restart keeps the same budget.
+     */
+    rotate(sessionId: SessionId): SessionCredential;
+    /**
+     * Fork an active session. The child copies roots, permissions and context
+     * by value, gets a fresh id and token, and cannot outlive the absolute
+     * deadline of its parent.
+     */
+    fork(parentId: SessionId, input?: SessionForkInput): OpenedSession;
+    /**
+     * Lazily expire every active or suspended session whose absolute or idle
+     * deadline has passed. Returns the number of transitions performed.
+     */
+    sweep(now?: Date): number;
+    /**
+     * Revoke and forget a session: descriptor index, context and persisted row
+     * are removed. `revoke` is the audit-friendly variant that keeps the
+     * descriptor; `close` is the end-of-life cleanup.
+     */
+    close(sessionId: SessionId): void;
+    /**
+     * Load persisted descriptors and token hashes at construction. Terminal
+     * statuses are preserved exactly. The descriptor carries only the idle
+     * deadline, not the configured idle window, so the window is recovered from
+     * `idleExpiresAt - createdAt` and capped by the current registry default; a
+     * persisted store that exceeds `maxSessions` is rejected rather than
+     * silently breaking the capacity invariant.
+     */
+    private restore;
+    private storedDescriptorIsValid;
+    private normalizeRoots;
+    /**
+     * Capacity counts retained descriptors, including terminal records kept
+     * for audit. `close` is the operation that frees a slot.
+     */
+    private assertCapacity;
+    private require;
+    private expireIfDue;
+    private markExpired;
+    private saveRecord;
+    private persist;
+    private deletePersisted;
+    /**
+     * Best-effort rollback for a fork whose descriptor could not be persisted.
+     * The original store error is more useful than a cleanup error, so this
+     * never throws.
+     */
+    private discardContext;
+}
+export {};