@abloatai/ablo 0.3.0

package/dist/auth/index.js

@@ -0,0 +1,246 @@
+/**
+ * Internal apiKey → capability exchange.
+ *
+ * Called by the `Ablo({...})` factory's `ready()` flow when the
+ * consumer passed `apiKey` without an explicit `capabilityToken` /
+ * `organizationId` / `user.id`. SDK calls `/auth/capability` once,
+ * server returns the scope + userMeta blobs (Phases 1A + 1B),
+ * SDK populates internal state from the response.
+ *
+ * Consumer never sees this happen. Same shape as Stripe / Anthropic
+ * SDKs hide their internal auth-handshake — the apiKey is the only
+ * credential the consumer touches.
+ */
+import { AbloAuthenticationError } from '../errors.js';
+export async function exchangeApiKey(options) {
+    if (!options.apiKey) {
+        throw new AbloAuthenticationError('apiKey is required for capability exchange', { code: 'apikey_missing' });
+    }
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for capability exchange', { code: 'base_url_missing' });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/capability`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${options.apiKey}`,
+            },
+            body: JSON.stringify({
+                participantKind: options.participantKind,
+                ...(options.participantId ? { participantId: options.participantId } : {}),
+                syncGroups: options.syncGroups,
+                operations: options.operations,
+                wideScope: options.wideScope,
+                ttlSeconds: options.ttlSeconds,
+                label: options.label,
+                userMeta: options.userMeta,
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`apiKey exchange failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'exchange_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore — server returned non-JSON error
+        }
+        const errBody = body;
+        throw new AbloAuthenticationError(`apiKey exchange rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
+            code: errBody?.error ?? 'exchange_failed',
+            httpStatus: response.status,
+        });
+    }
+    const raw = (await response.json());
+    if (!isCapabilityExchangeResponse(raw)) {
+        throw new AbloAuthenticationError('apiKey exchange response was malformed — missing required fields', { code: 'exchange_malformed_response' });
+    }
+    return raw;
+}
+function isCapabilityExchangeResponse(raw) {
+    if (!raw || typeof raw !== 'object')
+        return false;
+    const o = raw;
+    if (typeof o.token !== 'string')
+        return false;
+    if (typeof o.expiresAt !== 'string')
+        return false;
+    if (typeof o.organizationId !== 'string')
+        return false;
+    if (typeof o.scope !== 'object' || o.scope === null)
+        return false;
+    if (typeof o.userMeta !== 'object' || o.userMeta === null)
+        return false;
+    return true;
+}
+/**
+ * Resolve the caller's Ablo identity from the authenticated request
+ * context. Used by browser/session/capability flows where the SDK should
+ * not require a public `userId` prop just to open local storage.
+ */
+export async function resolveIdentity(options) {
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for identity resolve', {
+            code: 'base_url_missing',
+        });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/identity`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        const headers = { Accept: 'application/json' };
+        if (options.authToken) {
+            headers.Authorization = `Bearer ${options.authToken}`;
+        }
+        response = await fetcher(url, {
+            method: 'GET',
+            headers,
+            credentials: 'include',
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`identity resolve failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'identity_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore non-JSON auth errors
+        }
+        const errBody = body;
+        throw new AbloAuthenticationError(`identity resolve rejected (${response.status}): ${errBody?.reason ?? response.statusText}`, {
+            code: errBody?.error ?? 'identity_resolve_failed',
+            httpStatus: response.status,
+        });
+    }
+    return (await response.json());
+}
+const DEFAULT_BUFFER_FLOOR_MS = 60_000;
+const DEFAULT_BUFFER_RATIO = 0.1;
+export function createRefreshScheduler(options) {
+    const now = options.now ?? Date.now;
+    const setTimer = options.setTimer ?? setTimeout;
+    const clearTimer = options.clearTimer ?? clearTimeout;
+    let expiresAtMs = options.initialExpiresAtMs;
+    let timer = null;
+    let inFlight = null;
+    let disposed = false;
+    // Default visibility attach: only when running in a browser-like env.
+    // The Node-side agent worker never has `document`, so the default
+    // does the right thing without explicit opt-out.
+    const wantsVisibility = options.attachVisibilityListener ?? true;
+    const hasDocument = typeof document !== 'undefined';
+    const visibilityActive = wantsVisibility && hasDocument;
+    function bufferFor(currentExpiresAtMs) {
+        if (typeof options.bufferMs === 'number')
+            return options.bufferMs;
+        const ttl = currentExpiresAtMs - now();
+        return Math.max(DEFAULT_BUFFER_FLOOR_MS, Math.floor(ttl * DEFAULT_BUFFER_RATIO));
+    }
+    function clearTimerIfAny() {
+        if (timer !== null) {
+            clearTimer(timer);
+            timer = null;
+        }
+    }
+    function schedule() {
+        if (disposed)
+            return;
+        clearTimerIfAny();
+        const buffer = bufferFor(expiresAtMs);
+        const delay = Math.max(0, expiresAtMs - buffer - now());
+        timer = setTimer(() => {
+            void refreshNow().catch(() => {
+                // onError already fired inside refreshNow; swallow here so
+                // the timer callback doesn't surface as an unhandled rejection.
+            });
+        }, delay);
+    }
+    function refreshNow() {
+        if (disposed) {
+            return Promise.reject(new Error('refreshScheduler: disposed'));
+        }
+        if (inFlight)
+            return inFlight;
+        inFlight = (async () => {
+            try {
+                const result = await options.refresh();
+                if (disposed)
+                    return result;
+                expiresAtMs = result.expiresAtMs;
+                options.onRefreshed?.({ expiresAtMs });
+                schedule();
+                return result;
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                options.onError?.(error);
+                // Reschedule even on failure so the next window still triggers.
+                // The user's apiKey may have been temporarily unreachable.
+                if (!disposed)
+                    schedule();
+                throw error;
+            }
+            finally {
+                inFlight = null;
+            }
+        })();
+        return inFlight;
+    }
+    function onVisibilityChange() {
+        if (disposed)
+            return;
+        if (typeof document === 'undefined')
+            return;
+        if (document.visibilityState !== 'visible')
+            return;
+        const buffer = bufferFor(expiresAtMs);
+        if (expiresAtMs - now() <= buffer) {
+            void refreshNow().catch(() => {
+                // already routed through onError
+            });
+        }
+    }
+    if (visibilityActive) {
+        document.addEventListener('visibilitychange', onVisibilityChange);
+    }
+    schedule();
+    return {
+        refreshNow,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearTimerIfAny();
+            if (visibilityActive) {
+                document.removeEventListener('visibilitychange', onVisibilityChange);
+            }
+        },
+        get expiresAtMs() {
+            return expiresAtMs;
+        },
+    };
+}