@agent-native/core 0.154.3 → 0.154.4

package/dist/oauth-tokens/lifecycle.d.ts

@@ -0,0 +1,87 @@
+export interface OAuthCredentialOwner {
+    scope: "user" | "org";
+    id: string;
+}
+export interface OAuthCredentialIdentity {
+    provider: string;
+    accountId: string;
+    resource: string;
+    owner: OAuthCredentialOwner;
+}
+export interface OAuthCredentialTokens {
+    access_token: string;
+    refresh_token?: string;
+    [key: string]: unknown;
+}
+interface OAuthLifecycleMetadata {
+    version: 1;
+    provider: string;
+    resource: string;
+    owner: string;
+    reconnectReason?: "refresh_failed";
+}
+export interface OAuthCredential {
+    tokens: OAuthCredentialTokens;
+    tokenExpiresAt?: number;
+    oauthLifecycle?: OAuthLifecycleMetadata;
+    [key: string]: unknown;
+}
+interface CredentialSnapshot<T extends OAuthCredential> {
+    credential: T;
+    revision: number;
+    legacyRevision: number;
+}
+export type OAuthCredentialState<T extends OAuthCredential = OAuthCredential> = {
+    kind: "missing";
+} | {
+    kind: "malformed";
+    revision: number;
+    legacyRevision: number;
+    reason: "structure" | "identity" | "validation";
+} | ({
+    kind: "connected" | "expired" | "reconnect_required";
+} & CredentialSnapshot<T>);
+export interface OAuthCredentialAccessResult<T extends OAuthCredential = OAuthCredential> {
+    state: OAuthCredentialState<T>;
+    accessToken: string | null;
+}
+export interface OAuthRefreshContext<T extends OAuthCredential> {
+    identity: OAuthCredentialIdentity;
+    credential: T;
+}
+export interface OAuthRevocationResult {
+    remote: "succeeded" | "failed" | "unsupported" | "not_attempted";
+    local: "deleted" | "missing" | "replaced";
+}
+interface LifecycleDependencies {
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    holderId: () => string;
+}
+export declare function saveOAuthCredential<T extends OAuthCredential>(identity: OAuthCredentialIdentity, credential: T, options?: {
+    legacyAccountKey?: boolean;
+}): Promise<void>;
+export declare function readOAuthCredentialState<T extends OAuthCredential = OAuthCredential>(identity: OAuthCredentialIdentity, options?: {
+    allowLegacy?: boolean;
+    legacyAccountKey?: boolean;
+    now?: number;
+    validateCredential?: (credential: T) => boolean;
+}): Promise<OAuthCredentialState<T>>;
+export declare function resolveOAuthCredentialAccess<T extends OAuthCredential = OAuthCredential>(identity: OAuthCredentialIdentity, options: {
+    refresh: (context: OAuthRefreshContext<T>) => Promise<T>;
+    allowLegacy?: boolean;
+    legacyAccountKey?: boolean;
+    validateCredential?: (credential: T) => boolean;
+    expirySkewMs?: number;
+    leaseMs?: number;
+    waitMs?: number;
+    maxWaitMs?: number;
+    dependencies?: Partial<LifecycleDependencies>;
+}): Promise<OAuthCredentialAccessResult<T>>;
+export declare function revokeOAuthCredential<T extends OAuthCredential>(identity: OAuthCredentialIdentity, options?: {
+    revoke?: (context: OAuthRefreshContext<T>) => Promise<"succeeded" | "unsupported">;
+    allowLegacy?: boolean;
+    legacyAccountKey?: boolean;
+    validateCredential?: (credential: T) => boolean;
+}): Promise<OAuthRevocationResult>;
+export {};

package/dist/oauth-tokens/lifecycle.js

@@ -0,0 +1,434 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mutateSetting } from "../settings/store.js";
+import { deleteOAuthTokensIfRevision, getOAuthTokenSnapshot, getOAuthTokenSnapshotForUserOwner, replaceOAuthTokensIfRevision, saveOAuthTokens, } from "./store.js";
+const DEFAULT_EXPIRY_SKEW_MS = 60_000;
+const DEFAULT_LEASE_MS = 15_000;
+const DEFAULT_WAIT_MS = 50;
+const DEFAULT_MAX_WAIT_MS = 20_000;
+const LIFECYCLE_VERSION = 1;
+const defaultDependencies = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    holderId: () => randomUUID(),
+};
+function ownerKey(owner) {
+    const id = owner.id.trim();
+    if (!id)
+        throw new Error("OAuth credential owner is required.");
+    return `${owner.scope}:${owner.scope === "user" ? id.toLowerCase() : id}`;
+}
+function legacyOwnerKey(owner) {
+    const id = owner.id.trim();
+    if (!id)
+        throw new Error("OAuth credential owner is required.");
+    return `${owner.scope}:${id}`;
+}
+function assertIdentity(identity) {
+    if (!identity.provider.trim())
+        throw new Error("OAuth provider is required.");
+    if (!identity.accountId.trim()) {
+        throw new Error("OAuth account id is required.");
+    }
+    if (!identity.resource.trim())
+        throw new Error("OAuth resource is required.");
+    ownerKey(identity.owner);
+}
+function lifecycleMetadata(identity, reconnectReason) {
+    return {
+        version: LIFECYCLE_VERSION,
+        provider: identity.provider,
+        resource: identity.resource,
+        owner: ownerKey(identity.owner),
+        ...(reconnectReason ? { reconnectReason } : {}),
+    };
+}
+function withLifecycle(identity, credential, reconnectReason) {
+    return {
+        ...credential,
+        oauthLifecycle: lifecycleMetadata(identity, reconnectReason),
+    };
+}
+function metadataMatches(identity, metadata) {
+    return Boolean(metadata &&
+        metadata.version === LIFECYCLE_VERSION &&
+        metadata.provider === identity.provider &&
+        metadata.resource === identity.resource &&
+        metadata.owner === ownerKey(identity.owner));
+}
+function leaseKey(identity) {
+    const digest = createHash("sha256")
+        .update(JSON.stringify([
+        identity.provider,
+        identity.accountId,
+        identity.resource,
+        ownerKey(identity.owner),
+    ]))
+        .digest("hex");
+    return `oauth-refresh-lease:${digest}`;
+}
+function storageAccountId(identity, legacyAccountKey = false) {
+    if (legacyAccountKey)
+        return identity.accountId;
+    const resourceHash = createHash("sha256")
+        .update(identity.resource)
+        .digest("hex");
+    return `${identity.accountId}:resource:${resourceHash}`;
+}
+async function acquireLease(identity, holder, revision, legacyCredential, leaseMs, now) {
+    const next = await mutateSetting(leaseKey(identity), (current) => {
+        const currentHolder = typeof current?.holder === "string" ? current.holder : "";
+        const expiresAt = typeof current?.expiresAt === "number" ? current.expiresAt : 0;
+        const currentRevision = typeof current?.revision === "number" ? current.revision : -1;
+        if (currentHolder && currentHolder !== holder) {
+            if (expiresAt > now ||
+                // A crashed holder may already have redeemed this revision's rotating
+                // refresh token. Treat an expired same-revision lease as abandoned so
+                // the caller reconnects instead of risking a second redemption.
+                currentRevision === revision ||
+                (currentRevision === -1 && legacyCredential)) {
+                return current;
+            }
+        }
+        return { holder, revision, expiresAt: now + leaseMs };
+    });
+    if (next.holder === holder && next.revision === revision)
+        return "acquired";
+    if ((next.revision === revision || typeof next.revision !== "number") &&
+        typeof next.expiresAt === "number" &&
+        next.expiresAt <= now) {
+        return "abandoned";
+    }
+    return "held";
+}
+async function releaseLease(identity, holder) {
+    await mutateSetting(leaseKey(identity), (current) => current?.holder === holder ? { holder: "", expiresAt: 0 } : (current ?? {})).catch(() => undefined);
+}
+function startLeaseHeartbeat(identity, holder, revision, legacyCredential, leaseMs, dependencies) {
+    let renewal;
+    const timer = setInterval(() => {
+        if (renewal)
+            return;
+        renewal = acquireLease(identity, holder, revision, legacyCredential, leaseMs, dependencies.now())
+            .then(() => undefined)
+            .catch(() => undefined)
+            .finally(() => {
+            renewal = undefined;
+        });
+    }, Math.max(1, Math.floor(leaseMs / 3)));
+    timer.unref?.();
+    return async () => {
+        clearInterval(timer);
+        await renewal;
+    };
+}
+export async function saveOAuthCredential(identity, credential, options = {}) {
+    assertIdentity(identity);
+    await saveOAuthTokens(identity.provider, storageAccountId(identity, options.legacyAccountKey), withLifecycle(identity, credential), ownerKey(identity.owner));
+}
+async function readStoredOAuthCredentialState(identity, options = {}) {
+    assertIdentity(identity);
+    const accountId = storageAccountId(identity, options.legacyAccountKey);
+    const canonicalOwner = ownerKey(identity.owner);
+    let storageOwner = canonicalOwner;
+    let stored = await getOAuthTokenSnapshot(identity.provider, accountId, storageOwner);
+    const legacyOwner = legacyOwnerKey(identity.owner);
+    if (!stored && options.allowLegacy && legacyOwner !== canonicalOwner) {
+        storageOwner = legacyOwner;
+        stored = await getOAuthTokenSnapshot(identity.provider, accountId, storageOwner);
+    }
+    if (!stored && options.allowLegacy && identity.owner.scope === "user") {
+        stored = await getOAuthTokenSnapshotForUserOwner(identity.provider, accountId, canonicalOwner);
+        if (stored?.owner)
+            storageOwner = stored.owner;
+    }
+    if (!stored)
+        return { kind: "missing" };
+    const parsed = stored.tokens;
+    if (!parsed.tokens || typeof parsed.tokens.access_token !== "string") {
+        return {
+            kind: "malformed",
+            revision: stored.revision,
+            legacyRevision: stored.legacyRevision,
+            storageOwner,
+            storageVersion: stored.storageVersion,
+            reason: "structure",
+        };
+    }
+    if ((!options.allowLegacy &&
+        !metadataMatches(identity, parsed.oauthLifecycle)) ||
+        (parsed.oauthLifecycle && !metadataMatches(identity, parsed.oauthLifecycle))) {
+        return {
+            kind: "malformed",
+            revision: stored.revision,
+            legacyRevision: stored.legacyRevision,
+            storageOwner,
+            storageVersion: stored.storageVersion,
+            reason: "identity",
+        };
+    }
+    const credential = parsed;
+    if (options.validateCredential && !options.validateCredential(credential)) {
+        return {
+            kind: "malformed",
+            revision: stored.revision,
+            legacyRevision: stored.legacyRevision,
+            storageOwner,
+            storageVersion: stored.storageVersion,
+            reason: "validation",
+        };
+    }
+    if (credential.oauthLifecycle?.reconnectReason) {
+        return {
+            kind: "reconnect_required",
+            credential,
+            revision: stored.revision,
+            legacyRevision: stored.legacyRevision,
+            storageOwner,
+            storageVersion: stored.storageVersion,
+        };
+    }
+    const now = options.now ?? Date.now();
+    if (typeof credential.tokenExpiresAt === "number" &&
+        credential.tokenExpiresAt <= now) {
+        return {
+            kind: "expired",
+            credential,
+            revision: stored.revision,
+            legacyRevision: stored.legacyRevision,
+            storageOwner,
+            storageVersion: stored.storageVersion,
+        };
+    }
+    return {
+        kind: "connected",
+        credential,
+        revision: stored.revision,
+        legacyRevision: stored.legacyRevision,
+        storageOwner,
+        storageVersion: stored.storageVersion,
+    };
+}
+function publicCredentialState(state) {
+    if (state.kind === "missing")
+        return state;
+    if (state.kind === "malformed") {
+        return {
+            kind: state.kind,
+            revision: state.revision,
+            legacyRevision: state.legacyRevision,
+            reason: state.reason,
+        };
+    }
+    return {
+        kind: state.kind,
+        credential: state.credential,
+        revision: state.revision,
+        legacyRevision: state.legacyRevision,
+    };
+}
+export async function readOAuthCredentialState(identity, options = {}) {
+    return publicCredentialState(await readStoredOAuthCredentialState(identity, options));
+}
+async function markReconnectRequired(identity, snapshot, legacyAccountKey) {
+    await replaceOAuthTokensIfRevision(identity.provider, storageAccountId(identity, legacyAccountKey), snapshot.storageOwner, snapshot.revision, snapshot.legacyRevision, snapshot.storageVersion, withLifecycle(identity, snapshot.credential, "refresh_failed"));
+}
+export async function resolveOAuthCredentialAccess(identity, options) {
+    assertIdentity(identity);
+    const dependencies = { ...defaultDependencies, ...options.dependencies };
+    const expirySkewMs = options.expirySkewMs ?? DEFAULT_EXPIRY_SKEW_MS;
+    const leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
+    const waitMs = options.waitMs ?? DEFAULT_WAIT_MS;
+    const maxWaitMs = options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+    const startedAt = dependencies.now();
+    let state = await readStoredOAuthCredentialState(identity, {
+        allowLegacy: options.allowLegacy,
+        legacyAccountKey: options.legacyAccountKey,
+        now: startedAt,
+        validateCredential: options.validateCredential,
+    });
+    if (state.kind === "connected" &&
+        (typeof state.credential.tokenExpiresAt !== "number" ||
+            state.credential.tokenExpiresAt - startedAt > expirySkewMs)) {
+        return { state, accessToken: state.credential.tokens.access_token };
+    }
+    if (state.kind === "missing" ||
+        state.kind === "malformed" ||
+        state.kind === "reconnect_required") {
+        return { state, accessToken: null };
+    }
+    if (!state.credential.tokens.refresh_token) {
+        return {
+            state,
+            accessToken: state.kind === "connected"
+                ? state.credential.tokens.access_token
+                : null,
+        };
+    }
+    const baselineRevision = state.revision;
+    const holder = dependencies.holderId();
+    while (dependencies.now() - startedAt <= maxWaitMs) {
+        const lease = await acquireLease(identity, holder, state.revision, !state.credential.oauthLifecycle, leaseMs, dependencies.now());
+        if (lease === "abandoned") {
+            await markReconnectRequired(identity, state, options.legacyAccountKey === true);
+            const reconnect = await readStoredOAuthCredentialState(identity, {
+                allowLegacy: options.allowLegacy,
+                legacyAccountKey: options.legacyAccountKey,
+                now: dependencies.now(),
+                validateCredential: options.validateCredential,
+            });
+            return {
+                state: reconnect,
+                accessToken: reconnect.kind === "connected"
+                    ? reconnect.credential.tokens.access_token
+                    : null,
+            };
+        }
+        if (lease === "held") {
+            await dependencies.sleep(waitMs);
+            state = await readStoredOAuthCredentialState(identity, {
+                allowLegacy: options.allowLegacy,
+                legacyAccountKey: options.legacyAccountKey,
+                now: dependencies.now(),
+                validateCredential: options.validateCredential,
+            });
+            if (state.kind === "connected" &&
+                (state.revision !== baselineRevision ||
+                    typeof state.credential.tokenExpiresAt !== "number" ||
+                    state.credential.tokenExpiresAt - dependencies.now() > expirySkewMs)) {
+                return { state, accessToken: state.credential.tokens.access_token };
+            }
+            if (state.kind === "missing" ||
+                state.kind === "malformed" ||
+                state.kind === "reconnect_required") {
+                return { state, accessToken: null };
+            }
+            continue;
+        }
+        try {
+            state = await readStoredOAuthCredentialState(identity, {
+                allowLegacy: options.allowLegacy,
+                legacyAccountKey: options.legacyAccountKey,
+                now: dependencies.now(),
+                validateCredential: options.validateCredential,
+            });
+            if (state.kind === "missing" ||
+                state.kind === "malformed" ||
+                state.kind === "reconnect_required") {
+                return { state, accessToken: null };
+            }
+            if (state.kind === "connected" &&
+                (typeof state.credential.tokenExpiresAt !== "number" ||
+                    state.credential.tokenExpiresAt - dependencies.now() > expirySkewMs)) {
+                return {
+                    state,
+                    accessToken: state.credential.tokens.access_token,
+                };
+            }
+            try {
+                const stopHeartbeat = startLeaseHeartbeat(identity, holder, state.revision, !state.credential.oauthLifecycle, leaseMs, dependencies);
+                const refreshed = withLifecycle(identity, await options
+                    .refresh({ identity, credential: state.credential })
+                    .finally(stopHeartbeat));
+                const stillOwnsLease = await acquireLease(identity, holder, state.revision, !state.credential.oauthLifecycle, leaseMs, dependencies.now());
+                if (stillOwnsLease !== "acquired") {
+                    await dependencies.sleep(waitMs);
+                    continue;
+                }
+                const saved = await replaceOAuthTokensIfRevision(identity.provider, storageAccountId(identity, options.legacyAccountKey), state.storageOwner, state.revision, state.legacyRevision, state.storageVersion, refreshed);
+                const latest = await readStoredOAuthCredentialState(identity, {
+                    allowLegacy: options.allowLegacy,
+                    legacyAccountKey: options.legacyAccountKey,
+                    now: dependencies.now(),
+                    validateCredential: options.validateCredential,
+                });
+                if (!saved && latest.kind === "connected") {
+                    return {
+                        state: latest,
+                        accessToken: latest.credential.tokens.access_token,
+                    };
+                }
+                return {
+                    state: latest,
+                    accessToken: latest.kind === "connected"
+                        ? latest.credential.tokens.access_token
+                        : null,
+                };
+            }
+            catch {
+                const stillOwnsLease = await acquireLease(identity, holder, state.revision, !state.credential.oauthLifecycle, leaseMs, dependencies.now());
+                if (stillOwnsLease !== "acquired") {
+                    await dependencies.sleep(waitMs);
+                    continue;
+                }
+                const latest = await readStoredOAuthCredentialState(identity, {
+                    allowLegacy: options.allowLegacy,
+                    legacyAccountKey: options.legacyAccountKey,
+                    now: dependencies.now(),
+                    validateCredential: options.validateCredential,
+                });
+                if (latest.kind === "connected") {
+                    return {
+                        state: latest,
+                        accessToken: latest.credential.tokens.access_token,
+                    };
+                }
+                if (latest.kind === "expired") {
+                    await markReconnectRequired(identity, latest, options.legacyAccountKey === true);
+                    const reconnect = await readStoredOAuthCredentialState(identity, {
+                        allowLegacy: options.allowLegacy,
+                        legacyAccountKey: options.legacyAccountKey,
+                        now: dependencies.now(),
+                        validateCredential: options.validateCredential,
+                    });
+                    return { state: reconnect, accessToken: null };
+                }
+                return { state: latest, accessToken: null };
+            }
+        }
+        finally {
+            await releaseLease(identity, holder);
+        }
+    }
+    state = await readStoredOAuthCredentialState(identity, {
+        allowLegacy: options.allowLegacy,
+        legacyAccountKey: options.legacyAccountKey,
+        now: dependencies.now(),
+        validateCredential: options.validateCredential,
+    });
+    return {
+        state,
+        accessToken: state.kind === "connected" ? state.credential.tokens.access_token : null,
+    };
+}
+export async function revokeOAuthCredential(identity, options = {}) {
+    const state = await readStoredOAuthCredentialState(identity, {
+        allowLegacy: options.allowLegacy,
+        legacyAccountKey: options.legacyAccountKey,
+        validateCredential: options.validateCredential,
+    });
+    if (state.kind === "missing") {
+        return { remote: "not_attempted", local: "missing" };
+    }
+    let remote = options.revoke
+        ? "failed"
+        : "unsupported";
+    if (options.revoke && state.kind !== "malformed") {
+        try {
+            remote = await options.revoke({
+                identity,
+                credential: state.credential,
+            });
+        }
+        catch {
+            remote = "failed";
+        }
+    }
+    else if (state.kind === "malformed") {
+        remote = "not_attempted";
+    }
+    if (state.kind === "malformed" && state.reason !== "structure") {
+        return { remote, local: "replaced" };
+    }
+    const deleted = await deleteOAuthTokensIfRevision(identity.provider, storageAccountId(identity, options.legacyAccountKey), state.storageOwner, state.revision, state.legacyRevision, state.storageVersion);
+    return { remote, local: deleted ? "deleted" : "replaced" };
+}

package/dist/oauth-tokens/migrations.js

@@ -33,4 +33,14 @@ export const OAUTH_TOKEN_MIGRATIONS = [
         name: "oauth-tokens-owner-backfill",
         sql: "UPDATE oauth_tokens SET owner = account_id WHERE owner IS NULL",
     },
+    {
+        version: 5,
+        name: "oauth-tokens-revision-column",
+        sql: "ALTER TABLE oauth_tokens ADD COLUMN IF NOT EXISTS revision BIGINT",
+    },
+    {
+        version: 6,
+        name: "oauth-tokens-revision-backfill",
+        sql: "UPDATE oauth_tokens SET revision = updated_at WHERE revision IS NULL",
+    },
 ];

package/dist/oauth-tokens/store.d.ts

@@ -1,4 +1,26 @@
 export declare function getOAuthTokens(provider: string, accountId: string, owner?: string): Promise<Record<string, unknown> | null>;
+export interface OAuthTokenSnapshot {
+    tokens: Record<string, unknown>;
+    owner: string | null;
+    revision: number;
+    legacyRevision: number;
+    storageVersion: string;
+}
+/**
+ * Read one credential bundle together with the row revision used by
+ * refresh/revocation compare-and-swap writes.
+ */
+export declare function getOAuthTokenSnapshot(provider: string, accountId: string, owner: string): Promise<OAuthTokenSnapshot | null>;
+/** Read a legacy user-owned row without treating organization ids as case-insensitive. */
+export declare function getOAuthTokenSnapshotForUserOwner(provider: string, accountId: string, owner: string): Promise<OAuthTokenSnapshot | null>;
+/**
+ * Replace an existing credential bundle only when the caller still owns the
+ * revision it read. This prevents a slow refresh/revoke flow from overwriting
+ * a newer authorization completed in another process.
+ */
+export declare function replaceOAuthTokensIfRevision(provider: string, accountId: string, owner: string, expectedRevision: number, expectedLegacyRevision: number, expectedStorageVersion: string, tokens: Record<string, unknown>): Promise<boolean>;
+/** Delete only the exact credential revision the caller inspected. */
+export declare function deleteOAuthTokensIfRevision(provider: string, accountId: string, owner: string, expectedRevision: number, expectedLegacyRevision: number, expectedStorageVersion: string): Promise<boolean>;
 /**
  * Thrown when an OAuth save would re-bind an `(provider, account_id)` row
  * to a different owner than already holds it. Callers should catch this and