aismemory 0.6.2 → 0.7.1

package/dist/token-manager.js

@@ -0,0 +1,237 @@
+/**
+ * TokenManager: owns all in-memory token state for the aismemory client.
+ *
+ * - First `getCredentials()` authenticates and resolves agent identity;
+ *   concurrent callers during that first acquire share one in-flight promise.
+ * - A renewal is scheduled at 75% of the token's TTL. On success the
+ *   token/expiresAt swap in place — identity (agentId/tenantId) is resolved
+ *   once, on the very first acquire, and never re-resolved.
+ * - Renewal failures retry with exponential backoff (5s → 10s → 20s ...
+ *   capped at 300s, ±20% jitter) while the current token remains valid.
+ *   Backoff state (retryDelayMs/lastAttemptAt/lastError) is shared between
+ *   the background renewal loop and any on-demand `getCredentials()` call
+ *   made while the token is expired, so a burst of sequential calls during
+ *   an outage makes at most one fresh authenticate() attempt per backoff
+ *   window instead of one per call.
+ * - Once the current token hits its hard expiry with renewal still failing,
+ *   `getCredentials()` rejects with `AisUnreachableError` until the next
+ *   successful renewal — retries never stop, and recovery needs no restart.
+ * - No code path ever serializes the token to disk; it lives only in the
+ *   closure state below for the process lifetime.
+ * - `invalidate()` drops the current token (without touching backoff state,
+ *   unless `{ resetBackoff: true }` is passed) so a caller that discovers the
+ *   server rejected it mid-session — e.g. a 401 from a JWT_SECRET rotation,
+ *   CORBOT-A5BBD580 — can force the next `getCredentials()` to acquire a
+ *   fresh one instead of re-serving the rejected token. `resetBackoff: true`
+ *   additionally clears any escalated backoff window, so a server-rejection
+ *   that arrives mid-outage (after prior renewal failures already escalated
+ *   retryDelayMs) still re-proves immediately instead of being held behind
+ *   the stale backoff gate (CORBOT-4F7CAA8E).
+ * - The background renewal loop and the on-demand backoff gate in
+ *   `getCredentials()` are driven off the SAME single-flight `inFlight`
+ *   promise and the same jittered `nextAttemptAt` timestamp — computed once
+ *   per failure — so a caller can never race the timer into a second,
+ *   concurrent `authenticate()` call, and a failed attempt is recorded into
+ *   backoff state exactly once no matter how many callers were waiting on it
+ *   (CORBOT-4F7CAA8E).
+ */
+/**
+ * Thrown by `getCredentials()` once the current token has hard-expired and
+ * background renewal is still failing. Renewal keeps retrying in the
+ * background; the next successful renewal makes `getCredentials()` resolve
+ * again with no restart required.
+ */
+export class AisUnreachableError extends Error {
+}
+const RENEW_FRACTION = 0.75;
+const BACKOFF_BASE_MS = 5_000;
+const BACKOFF_CAP_MS = 300_000;
+export function createTokenManager(opts) {
+    const now = opts.now ?? Date.now;
+    let current = null;
+    // Tracked separately from `current` so `invalidate()` (which drops
+    // `current` to force a fresh acquire) does not also make `acquire()`
+    // re-resolve identity — identity is resolved once, on the very first
+    // acquire, and never re-resolved for the life of the manager (see module
+    // docstring). Set once, alongside `current`, on the first successful
+    // acquire; never cleared.
+    let resolvedIdentity = null;
+    let inFlight = null;
+    let timer = null;
+    let retryDelayMs = 0;
+    let lastAttemptAt = 0;
+    // Absolute timestamp of the next permitted attempt, computed ONCE per
+    // failure (in recordFailure) as `lastAttemptAt + jitter(retryDelayMs)`.
+    // Both the background retry timer (renew()'s reschedule) and the on-demand
+    // gate in getCredentials() key off this SAME value, so they can never
+    // disagree about when the next attempt is due (CORBOT-4F7CAA8E / F1).
+    let nextAttemptAt = 0;
+    let hardExpiryEmitted = false;
+    let stopped = false;
+    let lastError = '';
+    function jitter(ms) {
+        return Math.round(ms * (0.8 + Math.random() * 0.4));
+    }
+    function schedule(delayMs, fn) {
+        if (stopped)
+            return;
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(fn, delayMs);
+        timer.unref?.();
+    }
+    function scheduleRenewal(expiresAt) {
+        const ttlMs = new Date(expiresAt).getTime() - now();
+        // Floored at 30s (not 1s): a very short or skewed TTL must not turn
+        // renewal into a near-1Hz hammer on the auth endpoint (F7).
+        schedule(Math.max(30_000, Math.floor(ttlMs * RENEW_FRACTION)), () => {
+            void renew();
+        });
+    }
+    /**
+     * Records a failed authenticate/resolveIdentity attempt into the shared
+     * backoff state. Called exactly once per failed attempt — from the single
+     * `.catch` on the shared `inFlight` promise in `acquireShared()` — no
+     * matter how many callers (getCredentials() waiters, or the background
+     * renewal loop) were waiting on that attempt (F2a). Escalates
+     * retryDelayMs, computes the jittered `nextAttemptAt` gate/schedule value
+     * once, emits `renew.retry`, and — once — the `renew.hard_expiry` event
+     * when the current token has passed hard expiry.
+     */
+    function recordFailure(err) {
+        lastError = err instanceof Error ? err.message : String(err);
+        lastAttemptAt = now();
+        retryDelayMs = retryDelayMs === 0 ? BACKOFF_BASE_MS : Math.min(retryDelayMs * 2, BACKOFF_CAP_MS);
+        nextAttemptAt = lastAttemptAt + jitter(retryDelayMs);
+        opts.onEvent?.('renew.retry', lastError);
+        if (current && new Date(current.expiresAt).getTime() <= now() && !hardExpiryEmitted) {
+            hardExpiryEmitted = true;
+            opts.onEvent?.('renew.hard_expiry', lastError);
+        }
+    }
+    async function acquire() {
+        const fresh = await opts.authenticate();
+        const expiresAtMs = new Date(fresh.expiresAt).getTime();
+        if (!Number.isFinite(expiresAtMs)) {
+            throw new Error(`TokenManager.acquire(): authenticate() returned an invalid expiresAt: ${JSON.stringify(fresh.expiresAt)}`);
+        }
+        if (expiresAtMs <= now()) {
+            throw new Error(`TokenManager.acquire(): authenticate() returned an expiresAt in the past: ${JSON.stringify(fresh.expiresAt)}`);
+        }
+        // Identity is resolved only on the very first acquire; every later
+        // acquire (renewal, or a re-acquire after invalidate()) reuses the
+        // cached agentId/tenantId.
+        let agentId;
+        let tenantId;
+        if (resolvedIdentity) {
+            agentId = resolvedIdentity.agentId;
+            tenantId = resolvedIdentity.tenantId;
+        }
+        else {
+            const ids = await opts.resolveIdentity(fresh.token);
+            agentId = ids.agentId;
+            tenantId = ids.tenantId;
+            resolvedIdentity = { agentId, tenantId };
+        }
+        current = { token: fresh.token, expiresAt: fresh.expiresAt, agentId, tenantId };
+        retryDelayMs = 0;
+        nextAttemptAt = 0;
+        hardExpiryEmitted = false;
+        scheduleRenewal(fresh.expiresAt);
+        return current;
+    }
+    /**
+     * Starts (or joins) the single in-flight acquire attempt. Both the
+     * background renewal loop (`renew()`) and an on-demand `getCredentials()`
+     * call on a missing/expired token route through this — so there is never
+     * more than one concurrent `authenticate()` call, and a failure is
+     * recorded into backoff state exactly once, by this function's own
+     * `.catch`, regardless of how many callers are awaiting the same flight
+     * (F1, F2a). A failure also schedules the next background retry here, so
+     * that retry loop starts even from a failed FIRST acquire — not only from
+     * a renewal failure (F3).
+     */
+    function acquireShared() {
+        if (!inFlight) {
+            inFlight = acquire()
+                .catch((err) => {
+                recordFailure(err);
+                schedule(Math.max(0, nextAttemptAt - now()), () => {
+                    void renew();
+                });
+                throw err;
+            })
+                .finally(() => {
+                inFlight = null;
+            });
+        }
+        return inFlight;
+    }
+    async function renew() {
+        try {
+            await acquireShared();
+            opts.onEvent?.('renew.success');
+        }
+        catch {
+            // Failure already recorded and the next retry already scheduled by
+            // acquireShared()'s own .catch — nothing left to do here.
+        }
+    }
+    return {
+        async getCredentials() {
+            if (current && new Date(current.expiresAt).getTime() > now()) {
+                return current;
+            }
+            // The current token is missing or expired. If a prior attempt (from
+            // here or from the background renewal loop) failed and we're still
+            // inside its jittered backoff window, don't make a fresh attempt —
+            // that would let a burst of sequential calls (e.g. several tool calls
+            // in one MCP chat turn) each hammer the auth endpoint during an
+            // outage, racing the properly-backed-off background timer and
+            // defeating the point of backoff. Fail fast with the last known error
+            // instead; the background timer (or the next call after the window
+            // elapses) makes the next real attempt. Skipped once a flight is
+            // already in progress — join it instead of gating it.
+            if (!inFlight && nextAttemptAt > 0 && now() < nextAttemptAt) {
+                throw new AisUnreachableError(`AIS unreachable — renewing automatically; no action needed. Last error: ${lastError}`);
+            }
+            try {
+                return await acquireShared();
+            }
+            catch {
+                throw new AisUnreachableError(`AIS unreachable — renewing automatically; no action needed. Last error: ${lastError}`);
+            }
+        },
+        /**
+         * Drops the current token so the next `getCredentials()` must acquire a
+         * fresh one — used when the server itself rejects a still-time-valid
+         * token (e.g. a mid-session JWT_SECRET rotation, CORBOT-A5BBD580).
+         * By default this does NOT touch backoff bookkeeping (`retryDelayMs` /
+         * `lastAttemptAt` / `nextAttemptAt`): a server that keeps rejecting
+         * tokens must not turn into an unthrottled hammer on the auth endpoint —
+         * the shared-backoff-window gate in `getCredentials()` still applies.
+         * Pass `{ resetBackoff: true }` when the caller has independent evidence
+         * the server is reachable right now (e.g. it just returned the 401 this
+         * invalidate() is responding to) — this clears the backoff window so the
+         * re-prove is not held behind a stale gate computed from unrelated prior
+         * failures (F2b). Does not cancel or reschedule the background renewal
+         * timer; a successful next acquire reschedules renewal exactly as it
+         * does today.
+         */
+        invalidate(invalidateOpts) {
+            current = null;
+            if (invalidateOpts?.resetBackoff) {
+                retryDelayMs = 0;
+                lastAttemptAt = 0;
+                nextAttemptAt = 0;
+                hardExpiryEmitted = false;
+            }
+        },
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+        },
+    };
+}
+//# sourceMappingURL=token-manager.js.map

package/dist/token-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-manager.js","sourceRoot":"","sources":["../src/token-manager.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aismemory",
-  "version": "0.6.2",
+  "version": "0.7.1",
   "description": "Persistent memory for AI agents. MCP server that connects to Agent Identity Service.",
   "mcpName": "ai.agentsandswarms/ais-memory",
   "type": "module",