@cortexkit/common-auth 0.4.6 → 0.6.0

package/dist/fs/index.d.ts

@@ -1,6 +1,7 @@
 export type { AtomicWriteOptions } from './atomic-write.js';
 export { writeJsonAtomic } from './atomic-write.js';
 export { WRITER_LOCK_CONSTANTS } from './lock-constants.js';
+export type { LockLoss, RefreshFileLock } from './refresh-file-lock.js';
 export { acquireRefreshFileLock, isLostMarkerRaceError, } from './refresh-file-lock.js';
-export type { LockOptions } from './with-lock.js';
+export type { LockOptions, LockOwnershipDetails } from './with-lock.js';
 export { LockContentionError, LockOwnershipError, lockPathFor, withLock, } from './with-lock.js';

package/dist/fs/refresh-file-lock.d.ts

@@ -1,4 +1,18 @@
 export declare function isLostMarkerRaceError(error: unknown): boolean;
+export interface LockLoss {
+    readonly reason: 'taken-over' | 'expired' | 'unreadable' | 'renewal-failed' | 'marker-lost';
+    readonly expectedOwnerId: string;
+    readonly observedOwnerId?: string;
+    readonly observedExpiresAt?: number;
+}
+export interface RefreshFileLock {
+    readonly ownerId: string;
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+    /** Resolves once on detected loss; remains pending after an owner's release. */
+    whenLost(): Promise<LockLoss>;
+    hasLost(): boolean;
+}
 export declare function acquireRefreshFileLock(options: {
     name: string;
     ttlMs: number;
@@ -12,7 +26,4 @@ export declare function acquireRefreshFileLock(options: {
     renew?: boolean;
     renewIntervalMs?: number;
     onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-confirmed' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
-}): Promise<{
-    release: () => Promise<void>;
-    assertOwned: () => Promise<void>;
-} | null>;
+}): Promise<RefreshFileLock | null>;

package/dist/fs/refresh-file-lock.js

@@ -19,6 +19,30 @@ export async function acquireRefreshFileLock(options) {
     const now = options.now ?? Date.now;
     let renewTimer = null;
     let released = false;
+    let loss;
+    let resolveLoss;
+    const lostPromise = new Promise((resolve) => {
+        resolveLoss = resolve;
+    });
+    function recordLoss(reason, owner) {
+        if (loss || released)
+            return;
+        loss = Object.freeze({
+            reason,
+            expectedOwnerId: ownerId,
+            ...(typeof owner?.ownerId === 'string'
+                ? { observedOwnerId: owner.ownerId }
+                : {}),
+            ...(typeof owner?.expiresAt === 'number'
+                ? { observedExpiresAt: owner.expiresAt }
+                : {}),
+        });
+        if (renewTimer) {
+            clearRefreshLockRenewalTimeout(renewTimer);
+            renewTimer = null;
+        }
+        resolveLoss(loss);
+    }
     let renewalInFlight = null;
     // Only the owner of this exclusively-created marker may remove or renew a
     // lock. A contender recovering a stale marker can accidentally rename a newer
@@ -203,7 +227,7 @@ export async function acquireRefreshFileLock(options) {
         }
     }
     function scheduleRenewal() {
-        if (!options.renew || released)
+        if (!options.renew || released || loss)
             return;
         const intervalMs = options.renewIntervalMs ?? Math.max(1_000, Math.floor(options.ttlMs / 3));
         renewTimer = setRefreshLockRenewalTimeout(() => {
@@ -213,19 +237,25 @@ export async function acquireRefreshFileLock(options) {
                     const markerAcquired = await withEvictionMarker(async () => {
                         const owner = await readOwner();
                         const currentNow = now();
-                        if (released || owner?.ownerId !== ownerId) {
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
+                        if (owner?.ownerId !== ownerId) {
+                            recordLoss('taken-over', owner);
                             shouldReschedule = false;
                             return;
                         }
                         // An expired lease is no longer ours to extend; a contender may
                         // already be eligible to acquire it.
-                        if (Number(owner?.expiresAt) <= currentNow) {
+                        if (!(Number(owner?.expiresAt) > currentNow)) {
+                            recordLoss('expired', owner);
                             shouldReschedule = false;
                             return;
                         }
                         if (options.onStep)
                             await options.onStep('renewal-owner-confirmed');
-                        if (released) {
+                        if (released || loss) {
                             shouldReschedule = false;
                             return;
                         }
@@ -233,7 +263,7 @@ export async function acquireRefreshFileLock(options) {
                             return;
                         if (options.onStep)
                             await options.onStep('renewal-write-fenced');
-                        if (released) {
+                        if (released || loss) {
                             shouldReschedule = false;
                             return;
                         }
@@ -241,10 +271,15 @@ export async function acquireRefreshFileLock(options) {
                             return;
                         if (options.onStep)
                             await options.onStep('renewal-write-ready');
+                        if (released || loss) {
+                            shouldReschedule = false;
+                            return;
+                        }
                         await writeOwner();
                         if (!(await ownsEvictionMarker())) {
                             // If marker ownership cannot be read, stop claiming the lease
                             // and remove only a record that still carries our owner id.
+                            recordLoss('marker-lost');
                             shouldReschedule = false;
                             await relinquishLockAfterMarkerLoss();
                             return;
@@ -255,7 +290,17 @@ export async function acquireRefreshFileLock(options) {
                     }
                 }
                 catch {
-                    // Transient marker and filesystem failures retry on the next interval.
+                    // Retry transient failures only while the lease can still be verified.
+                    try {
+                        const owner = await readOwner();
+                        if (owner?.ownerId !== ownerId)
+                            recordLoss('taken-over', owner);
+                        else if (!(Number(owner?.expiresAt) > now()))
+                            recordLoss('expired', owner);
+                    }
+                    catch {
+                        recordLoss('renewal-failed');
+                    }
                 }
                 finally {
                     if (options.onStep) {
@@ -266,7 +311,7 @@ export async function acquireRefreshFileLock(options) {
                             // Errors from the onStep observer must not reject the renewal.
                         }
                     }
-                    if (shouldReschedule && !released)
+                    if (shouldReschedule && !released && !loss)
                         scheduleRenewal();
                 }
             })();
@@ -341,20 +386,35 @@ export async function acquireRefreshFileLock(options) {
         return null;
     scheduleRenewal();
     return {
+        ownerId,
+        whenLost: () => lostPromise,
+        hasLost: () => loss !== undefined,
         assertOwned: async () => {
+            let observed;
             try {
                 const owner = await readOwner();
+                observed = owner;
                 if (!released &&
+                    !loss &&
                     owner?.ownerId === ownerId &&
                     Number(owner?.expiresAt) > now())
                     return;
+                recordLoss(owner?.ownerId !== ownerId ? 'taken-over' : 'expired', owner);
             }
             catch {
                 // Unreadable ownership is not evidence of a valid lease.
+                recordLoss('unreadable');
             }
             throw new LockOwnershipError({
                 target: options.path,
                 name: options.name,
+                expectedOwnerId: ownerId,
+                ...(typeof observed?.ownerId === 'string'
+                    ? { observedOwnerId: observed.ownerId }
+                    : {}),
+                ...(typeof observed?.expiresAt === 'number'
+                    ? { observedExpiresAt: observed.expiresAt }
+                    : {}),
             });
         },
         release: async () => {

package/dist/fs/with-lock.d.ts

@@ -11,15 +11,16 @@ export declare class LockContentionError extends Error {
         timeoutMs: number;
     });
 }
+export interface LockOwnershipDetails {
+    target: string;
+    name: string;
+    expectedOwnerId?: string;
+    observedOwnerId?: string;
+    observedExpiresAt?: number;
+}
 export declare class LockOwnershipError extends Error {
-    readonly details: {
-        target: string;
-        name: string;
-    };
-    constructor(details: {
-        target: string;
-        name: string;
-    });
+    readonly details: LockOwnershipDetails;
+    constructor(details: LockOwnershipDetails);
 }
 export interface LockOptions {
     name: string;

package/dist/opencode2/index.d.ts

@@ -1,8 +1,8 @@
 export type { OpenCode2AuthFailureKind } from './errors.js';
 export { OpenCode2AuthError } from './errors.js';
-export { applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
+export { ATTEMPT_HEADER, applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
 export type { FormAnswer, PoolAuthorization, PoolLoginMethod, RegisterOpenCode2AuthMethodsOptions, } from './integration.js';
 export { isPlaceholderCredential, PLACEHOLDER_LIFETIME_MS, PLACEHOLDER_METADATA_KEY, PLACEHOLDER_PREFIX, placeholderCredential, placeholderSecret, registerOpenCode2AuthMethods, } from './integration.js';
 export type { ServerSentEvent } from './sse.js';
 export { watchServerSentEvents } from './sse.js';
-export type { AccountHeadersResult, AccountRequest, Attempt, AttemptEndReason, AttemptOutcome, ChooseAccountInput, EventVerdict, HeaderEdits, HostError, InstallOpenCode2AuthOptions, LimitSignal, OpenCode2AuthAdapter, OpenCode2AuthEventName, OpenCode2AuthEvents, OpenCode2AuthInstallation, OpenCode2AuthLogger, OpenCode2HookContext, RequestKind, RequestScope, RetryReason, SelectingHook, Transport, } from './types.js';
+export type { AccountHeadersResult, AccountRequest, Attempt, AttemptEndReason, AttemptOutcome, ChooseAccountInput, EventVerdict, HeaderEdits, HostError, InstallOpenCode2AuthOptions, LimitSignal, OpenCode2AuthAdapter, OpenCode2AuthEventName, OpenCode2AuthEvents, OpenCode2AuthInstallation, OpenCode2AuthLogger, OpenCode2HookContext, RequestKind, RequestScope, ResponseAccount, RetryReason, SelectingHook, Transport, } from './types.js';

package/dist/opencode2/index.js

@@ -1,4 +1,4 @@
 export { OpenCode2AuthError } from './errors.js';
-export { applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
+export { ATTEMPT_HEADER, applyHeaderEdits, DEFAULT_MAX_RECORDS, installOpenCode2Auth, } from './install.js';
 export { isPlaceholderCredential, PLACEHOLDER_LIFETIME_MS, PLACEHOLDER_METADATA_KEY, PLACEHOLDER_PREFIX, placeholderCredential, placeholderSecret, registerOpenCode2AuthMethods, } from './integration.js';
 export { watchServerSentEvents } from './sse.js';

package/dist/opencode2/install.d.ts

@@ -1,15 +1,25 @@
 import type { HeaderEdits, InstallOpenCode2AuthOptions, OpenCode2AuthAdapter, OpenCode2AuthInstallation, OpenCode2HookContext } from './types.js';
 export declare const DEFAULT_MAX_RECORDS = 512;
+/**
+ * The request header `model.request` sets to the attempt it started. The
+ * host builds the HTTP request and the WebSocket handshake from the headers
+ * `model.request` leaves, so `http.request` and `experimental.ws.handshake`
+ * read it to find their own attempt among several of one session and kind,
+ * and remove it: it never reaches the wire.
+ */
+export declare const ATTEMPT_HEADER = "x-common-auth-attempt";
 /** Applies edits to a plain header record, replacing every spelling of each name. */
 export declare function applyHeaderEdits(target: Record<string, string>, edits: HeaderEdits): void;
 /**
  * Installs multi-account auth on OpenCode 2's own provider drivers. Every
  * hook is scoped to `adapter.providerID`:
  *
- * - `model.request` picks the account for the request's `sessionID:kind`,
- *   which starts a new attempt, and sets its headers;
- * - `http.request` and `experimental.ws.handshake` set them again, because
- *   the host applies its own credential after `model.request`;
+ * - `model.request` picks the account for one model call of a session and
+ *   request kind, which starts a new attempt, sets its headers and marks the
+ *   request with the attempt (`ATTEMPT_HEADER`);
+ * - `http.request` and `experimental.ws.handshake` find the attempt by that
+ *   mark, remove it and set the account headers again, because the host
+ *   applies its own credential after `model.request`;
  * - `experimental.ws.send` (only when the adapter rewrites frames) rewrites
  *   each outgoing frame;
  * - `http.response` and `experimental.ws.receive` read quota, refusals,
@@ -19,19 +29,19 @@ export declare function applyHeaderEdits(target: Record<string, string>, edits:
  *   before any output, so `model.request` runs again and can pick another
  *   account, and refuses to retry once output has started.
  *
- * Attribution. An HTTP response belongs to the attempt whose `http.request`
- * produced its request object, and to nothing else. The host hands
- * `http.response` the request object the `http.request` hooks left, so a
- * different object means a later hook replaced it; nothing then proves which
- * send the response answers (an earlier attempt's send may still be in
- * flight, and only the newest attempt of each session and kind is kept), and
- * its feedback is dropped rather than guessed by recency. No marker can ride
- * on the request instead: the host builds the wire request from that same
- * object, so a marker would be sent to the provider. A WebSocket frame
- * belongs to the newest attempt of its session and kind only while that
- * attempt went out over WebSocket and has not ended: the host runs one
- * exchange at a time per session socket, so frames between one handshake
- * and the next belong to the earlier attempt. Anything else is attributed to
- * no attempt and reaches no adapter callback or listener.
+ * Attribution. A send belongs to the attempt named by the mark
+ * `model.request` left on it, so several attempts of one session and kind
+ * can be in flight at once, each on its own account. An HTTP response
+ * belongs to the attempt whose `http.request` produced its request object,
+ * and to nothing else. The host hands `http.response` the request object the
+ * `http.request` hooks left, so a different object means a later hook
+ * replaced it; nothing then proves which send the response answers, and its
+ * feedback is dropped rather than guessed by recency. A WebSocket frame
+ * names no attempt, so frames go to the newest open attempt of their session
+ * and kind that went out over WebSocket, and an older one is abandoned as
+ * soon as a newer attempt of that session and kind begins or goes out over
+ * WebSocket: the host runs one exchange at a time on a session's socket.
+ * Anything else is attributed to no attempt and reaches no adapter callback
+ * or listener.
  */
 export declare function installOpenCode2Auth<Q, A = unknown>(ctx: OpenCode2HookContext, adapter: OpenCode2AuthAdapter<Q, A>, options?: InstallOpenCode2AuthOptions): Promise<OpenCode2AuthInstallation<Q, A>>;