@abloatai/ablo 0.35.0 → 0.37.0

package/dist/transaction/auth/credentialPolicy.js

@@ -1,125 +0,0 @@
-/**
- * Decides what a credential is and how to use it when a client connects. A
- * caller configures an Ablo client with an API key, and this module answers two
- * questions about that value: which of the four key kinds it is, and which
- * connect-time route it takes.
- *
- * The routing decision is the only thing that lives here. This module does not
- * perform the network calls that mint or exchange credentials;
- * {@link resolveCredential} delegates those to primitives the caller supplies,
- * so the decision of what to do stays separate from the work of doing it.
- *
- * {@link classifyCredentialKind} is a plain string check with no Node
- * dependencies, so it is safe to run in a browser bundle. It recognizes the key
- * prefixes `sk_` (secret), `rk_` (restricted), `ek_` (ephemeral), and `pk_`
- * (publishable), but does not validate a key's checksum or environment segment.
- */
-import { AbloAuthenticationError } from '../errors.js';
-const KIND_BY_PREFIX = [
-    ['sk_', 'secret'],
-    ['ek_', 'ephemeral'],
-    ['rk_', 'restricted'],
-    ['pk_', 'publishable'],
-];
-/**
- * Classifies a credential by its prefix, returning its {@link CredentialKind}, or
- * `null` when the value carries no recognized Ablo key prefix — for example a
- * capability or auth token the caller supplied, or an empty string. This is a
- * plain string check that is safe to run in a browser; it decides only which of
- * the four kinds a value is, and does not validate the key's checksum or
- * environment segment.
- */
-export function classifyCredentialKind(value) {
-    for (const [prefix, kind] of KIND_BY_PREFIX) {
-        if (value.startsWith(prefix))
-            return kind;
-    }
-    return null;
-}
-/**
- * Routes a configured API key to its connect-time outcome. It classifies the
- * key, then returns one of four {@link ResolvedCredential} variants, delegating
- * any credential exchange to the injected `exchangeApiKey` primitive. The caller
- * switches on the result's `kind` to wire up scope and the refresh scheduler.
- *
- * The routes, in the order they are tried:
- *   0. A `pk_` key with no explicit capability token becomes `publishable`: used
- *      directly as the bearer, with no refresh.
- *   1. Any other exchangeable key (one that is not a pre-minted `ek_` or `rk_`)
- *      with no explicit capability token becomes `exchange`: a round-trip mints a
- *      capability token, and the refresh scheduler renews it before it expires.
- *   2. Otherwise, when the caller's identity is not yet known, the result is
- *      `pre-minted`: the capability token is used as-is. Throws `session_expired`
- *      when there is no token to authenticate `/auth/identity`.
- *   3. Otherwise, when the caller already knows its identity, the result is
- *      `explicit`, with no round-trip.
- */
-export async function resolveCredential(input, ctx) {
-    const { apiKeyValue, capabilityToken, authToken, hasExplicitIdentity } = input;
-    const kind = apiKeyValue != null ? classifyCredentialKind(apiKeyValue) : null;
-    // A pre-minted capability bearer (an ephemeral `ek_` or restricted `rk_` key)
-    // is not exchangeable: it was minted before connect and is used directly as the
-    // bearer on Route 2, never sent through `exchangeApiKey`, which expects an `sk_`.
-    const isPreMintedCapabilityBearer = kind === 'ephemeral' || kind === 'restricted';
-    const initialCapToken = capabilityToken ??
-        (isPreMintedCapabilityBearer ? apiKeyValue ?? undefined : undefined) ??
-        authToken ??
-        undefined;
-    // Route 0: a publishable `pk_` key — long-lived, browser-safe, and read-only.
-    // Used directly as the bearer; it is never exchanged, so it never expires and
-    // there is nothing to refresh.
-    if (apiKeyValue != null && kind === 'publishable' && capabilityToken == null) {
-        return {
-            kind: 'publishable',
-            getBearer: apiKeyValue,
-            expiresAtMs: null,
-            controlPlaneKey: null,
-        };
-    }
-    // Route 1: an exchangeable key (such as a secret `sk_`) with no caller-supplied
-    // capability token. A pre-minted `ek_` or `rk_` is not exchangeable and falls
-    // through to the next route.
-    if (apiKeyValue != null &&
-        capabilityToken == null &&
-        !isPreMintedCapabilityBearer) {
-        const exchange = await ctx.primitives.exchangeApiKey({
-            ...ctx.exchangeArgs,
-            apiKey: apiKeyValue,
-        });
-        return {
-            kind: 'exchange',
-            exchange,
-            getBearer: exchange.token,
-            expiresAtMs: Date.parse(exchange.expiresAt),
-            controlPlaneKey: input.configuredApiKey ?? apiKeyValue,
-        };
-    }
-    // Route 2: pre-minted — use the capability token as-is. Reached when the
-    // caller's identity was not supplied.
-    if (!hasExplicitIdentity) {
-        if (initialCapToken == null) {
-            // With no key to exchange and no caller-supplied identity, this token is the
-            // only thing that could authenticate `/auth/identity`. When it is absent —
-            // commonly a function `apiKey` resolver returning `null` for a missing or
-            // expired session — report the re-authenticable condition here instead of
-            // making a round-trip that is bound to fail.
-            throw new AbloAuthenticationError('No auth token available to resolve identity — the session token is ' +
-                'missing or expired. Ensure your `apiKey` resolver returns a valid token, or ' +
-                'pass a static `apiKey` / `capabilityToken`.', { code: 'session_expired' });
-        }
-        return {
-            kind: 'pre-minted',
-            getBearer: initialCapToken,
-            expiresAtMs: null,
-            controlPlaneKey: null,
-        };
-    }
-    // Route 3: explicit — the caller already knows its own organization and user
-    // or agent id.
-    return {
-        kind: 'explicit',
-        getBearer: initialCapToken,
-        expiresAtMs: null,
-        controlPlaneKey: null,
-    };
-}

package/dist/transaction/auth/credentialSource.d.ts

@@ -1,30 +0,0 @@
-/**
- * The single mutable holder for the active bearer credential every transport
- * uses.
- *
- * Each transport reads the current token from this object at request or connect
- * time — the HTTP request paths and the WebSocket URL authorizer alike. When the
- * token is refreshed, it is written here once, and every reader observes the new
- * value through its getter rather than being updated one by one.
- */
-export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from '../wire/protocol.js';
-export interface AuthCredentialSource {
-    /**
-     * Declared as a standalone closure rather than a method because callers pass
-     * it on by reference — the transport and the core client each take
-     * `getAuthToken` alone and call it with no receiver. The implementation is a
-     * closure over the token, so that is safe; typing it as a method would say
-     * otherwise and make every hand-off read as a lost `this`.
-     */
-    getAuthToken: () => string | null;
-    setAuthToken(token: string | null | undefined): void;
-    authorizationHeader(): string | undefined;
-    withAuthHeaders(headers?: Record<string, string>): Record<string, string>;
-    applyAuthQueryParam(params: URLSearchParams, paramName?: string): void;
-}
-export type AuthTokenGetter = () => string | null | undefined;
-export declare function createAuthCredentialSource(initialToken?: string | null): AuthCredentialSource;
-export declare function resolveAuthToken(getAuthToken?: AuthTokenGetter, fallbackToken?: string | null): string | undefined;
-export declare function authorizationHeaderForToken(token: string | null | undefined): string | undefined;
-export declare function withAuthHeaders(getAuthToken: AuthTokenGetter | undefined, headers?: Record<string, string>, fallbackToken?: string | null): Record<string, string>;
-export declare function applyAuthToQueryParams(params: URLSearchParams, getAuthToken: AuthTokenGetter | undefined, paramName?: string, fallbackToken?: string | null): void;

package/dist/transaction/auth/credentialSource.js

@@ -1,55 +0,0 @@
-/**
- * The single mutable holder for the active bearer credential every transport
- * uses.
- *
- * Each transport reads the current token from this object at request or connect
- * time — the HTTP request paths and the WebSocket URL authorizer alike. When the
- * token is refreshed, it is written here once, and every reader observes the new
- * value through its getter rather than being updated one by one.
- */
-// The WebSocket bearer-subprotocol constants are defined in `../wire/protocol.js`
-// as part of the wire contract shared between client and server. They are
-// re-exported here so this module stays a stable import site for them.
-export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from '../wire/protocol.js';
-export function createAuthCredentialSource(initialToken) {
-    let authToken = normalizeToken(initialToken);
-    return {
-        getAuthToken: () => authToken,
-        setAuthToken(token) {
-            authToken = normalizeToken(token);
-        },
-        authorizationHeader() {
-            return authorizationHeaderForToken(authToken);
-        },
-        withAuthHeaders(headers = {}) {
-            const authorization = authorizationHeaderForToken(authToken);
-            return authorization ? { ...headers, Authorization: authorization } : { ...headers };
-        },
-        applyAuthQueryParam(params, paramName = 'authorization') {
-            applyAuthToQueryParams(params, () => authToken, paramName);
-        },
-    };
-}
-export function resolveAuthToken(getAuthToken, fallbackToken) {
-    return normalizeToken(getAuthToken?.() ?? fallbackToken) ?? undefined;
-}
-export function authorizationHeaderForToken(token) {
-    const normalized = normalizeToken(token);
-    return normalized ? `Bearer ${normalized}` : undefined;
-}
-export function withAuthHeaders(getAuthToken, headers = {}, fallbackToken) {
-    const authorization = authorizationHeaderForToken(resolveAuthToken(getAuthToken, fallbackToken));
-    return authorization ? { ...headers, Authorization: authorization } : { ...headers };
-}
-export function applyAuthToQueryParams(params, getAuthToken, paramName = 'authorization', fallbackToken) {
-    const authorization = authorizationHeaderForToken(resolveAuthToken(getAuthToken, fallbackToken));
-    if (authorization) {
-        params.set(paramName, authorization);
-    }
-}
-function normalizeToken(token) {
-    if (!token)
-        return null;
-    const trimmed = token.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}

package/dist/transaction/auth/hostedEndpoints.d.ts

@@ -1,21 +0,0 @@
-/**
- * The hosted Ablo Cloud endpoint constants, with no dependencies of their own.
- *
- * This is the single place the hosted API host is declared. URL resolution, the
- * CLI's default URL, the data-source connector's base, the generated OpenAPI
- * server entry, and the network probe's default all import from here, so
- * changing the API domain is a one-line edit.
- *
- * These constants are kept dependency-free deliberately: several low-level
- * modules consume them, and routing those modules through the auth layer would
- * pull the error registry and credential policy into otherwise-clean paths and
- * risk an import cycle.
- */
-/** The hosted API domain (no scheme). */
-export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
-/** The hosted HTTP origin — `https://` + {@link ABLO_HOSTED_API_DOMAIN}. */
-export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
-/** Default `baseURL` when the caller passes none. Same value as
- *  {@link ABLO_HOSTED_HTTP_BASE_URL}; kept as a distinct name because it is
- *  the documented client-options default. */
-export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";

package/dist/transaction/auth/hostedEndpoints.js

@@ -1,21 +0,0 @@
-/**
- * The hosted Ablo Cloud endpoint constants, with no dependencies of their own.
- *
- * This is the single place the hosted API host is declared. URL resolution, the
- * CLI's default URL, the data-source connector's base, the generated OpenAPI
- * server entry, and the network probe's default all import from here, so
- * changing the API domain is a one-line edit.
- *
- * These constants are kept dependency-free deliberately: several low-level
- * modules consume them, and routing those modules through the auth layer would
- * pull the error registry and credential policy into otherwise-clean paths and
- * risk an import cycle.
- */
-/** The hosted API domain (no scheme). */
-export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
-/** The hosted HTTP origin — `https://` + {@link ABLO_HOSTED_API_DOMAIN}. */
-export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;
-/** Default `baseURL` when the caller passes none. Same value as
- *  {@link ABLO_HOSTED_HTTP_BASE_URL}; kept as a distinct name because it is
- *  the documented client-options default. */
-export const ABLO_DEFAULT_BASE_URL = ABLO_HOSTED_HTTP_BASE_URL;

package/dist/transaction/auth/identity.d.ts

@@ -1,55 +0,0 @@
-/**
- * Resolves a participant's identity and scope when an {@link Ablo} client is
- * constructed, following whichever of three authentication paths the caller's
- * options select:
- *
- *   1. **Hosted cloud** — the caller passed an `apiKey`. The client exchanges it
- *      for a capability token and scope, then starts a scheduler that re-mints the
- *      token before it expires, so the rotation is invisible to the caller.
- *   2. **Self-derived** — the caller passed a bearer or capability token but not
- *      an identity. The client asks the identity endpoint to recover the
- *      participant id and scope from the token.
- *   3. **Explicit** — a self-hosted caller passed the organization id and a user
- *      or agent id directly. No server round-trip; the client trusts the caller.
- *
- * Each branch is a separate function below, so it can be read and tested on its own.
- */
-import type { ParticipantKind } from '../types/participant.js';
-import { type RefreshScheduler } from '../auth/index.js';
-import type { BootstrapScope } from '../auth/bootstrapScope.js';
-import type { Logger } from '../logger.js';
-import type { AuthCredentialSource } from '../auth/credentialSource.js';
-import type { ApiKeySetter } from './apiKey.js';
-export interface IdentityResolveInput {
-    readonly options: {
-        readonly capabilityToken?: string;
-        readonly bootstrapBaseUrl?: string;
-        readonly user?: {
-            id: string;
-            teamIds?: string[];
-        };
-        readonly agentId?: string;
-        readonly syncGroups?: string[];
-    };
-    readonly internalOptions: {
-        readonly organizationId?: string;
-    };
-    readonly url: string;
-    readonly kind: ParticipantKind;
-    readonly configuredApiKey: string | ApiKeySetter | null;
-    readonly configuredAuthToken: string | null;
-    readonly bootstrapHelper: BootstrapScope;
-    readonly auth: AuthCredentialSource;
-    readonly logger: Logger;
-}
-export interface ResolvedIdentity {
-    readonly userId: string;
-    readonly accountScope: string;
-    readonly teamIds: string[] | undefined;
-    readonly capabilityToken: string | undefined;
-    readonly syncGroups: readonly string[] | undefined;
-    readonly participantKind: ParticipantKind;
-    /** Set only on the hosted-cloud path; the caller keeps it to stop refreshes on shutdown. */
-    readonly refreshScheduler: RefreshScheduler | null;
-}
-export declare function resolveParticipantIdentity(input: IdentityResolveInput): Promise<ResolvedIdentity>;

package/dist/transaction/auth/identity.js

@@ -1,210 +0,0 @@
-/**
- * Resolves a participant's identity and scope when an {@link Ablo} client is
- * constructed, following whichever of three authentication paths the caller's
- * options select:
- *
- *   1. **Hosted cloud** — the caller passed an `apiKey`. The client exchanges it
- *      for a capability token and scope, then starts a scheduler that re-mints the
- *      token before it expires, so the rotation is invisible to the caller.
- *   2. **Self-derived** — the caller passed a bearer or capability token but not
- *      an identity. The client asks the identity endpoint to recover the
- *      participant id and scope from the token.
- *   3. **Explicit** — a self-hosted caller passed the organization id and a user
- *      or agent id directly. No server round-trip; the client trusts the caller.
- *
- * Each branch is a separate function below, so it can be read and tested on its own.
- */
-import { AbloAuthenticationError } from '../errors.js';
-import { exchangeApiKey } from '../auth/index.js';
-import { mintUserSessionKey } from '../auth/index.js';
-import { resolveIdentity } from '../auth/index.js';
-import { createRefreshScheduler, } from '../auth/index.js';
-import { resolveCredential, } from '../auth/credentialPolicy.js';
-import { resolveApiKeyValue, resolveBootstrapBaseUrl } from './apiKey.js';
-export async function resolveParticipantIdentity(input) {
-    const { options, internalOptions, url, kind, configuredApiKey, configuredAuthToken, bootstrapHelper, auth, logger, } = input;
-    const apiKeyValue = await resolveApiKeyValue(configuredApiKey);
-    // Resolve the http(s) base URL, coercing ws/wss to http/https even when
-    // `bootstrapBaseUrl` is an explicit override (see auth.ts).
-    const baseUrl = resolveBootstrapBaseUrl({
-        url,
-        bootstrapBaseUrl: options.bootstrapBaseUrl,
-    });
-    // An organization id plus a caller-supplied participant id is the explicit path:
-    // the caller already knows its own identity, so no server round-trip is needed.
-    const hasExplicitIdentity = internalOptions.organizationId != null &&
-        (kind === 'agent' ? options.agentId != null : options.user?.id != null);
-    // The credential-routing decision lives in `credentialPolicy`: it classifies the
-    // apiKey by prefix (`sk_`/`ek_`/`rk_`/`pk_`) and picks a route. The hosted
-    // exchange is the one mint the policy performs (via the injected
-    // `exchangeApiKey`); every other route simply returns the bearer to use. The
-    // switch below applies scope and sets up the refresh scheduler for each case.
-    const cred = await resolveCredential({
-        apiKeyValue,
-        configuredApiKey,
-        capabilityToken: options.capabilityToken,
-        authToken: configuredAuthToken,
-        hasExplicitIdentity,
-    }, {
-        primitives: {
-            exchangeApiKey,
-            mintUserSessionKey,
-            resolveIdentity,
-            resolveApiKeyValue,
-        },
-        exchangeArgs: {
-            baseUrl,
-            participantKind: (kind === 'agent' ? 'agent' : 'system'),
-            participantId: options.agentId ?? options.user?.id,
-            wideScope: true,
-            ttlSeconds: 3600,
-        },
-    });
-    switch (cred.kind) {
-        case 'publishable':
-            // `pk_` is a long-lived, browser-safe, read-only project key. It is used
-            // directly as the bearer and is never exchanged for a short-lived
-            // capability, so it never expires and there is nothing to refresh. The
-            // server resolves the organization and read-only scope from the key itself;
-            // we still call `/auth/identity` with the `pk_` bearer to learn the account
-            // scope and sync groups for the bootstrap cache.
-            return resolveViaIdentity({
-                bearer: cred.getBearer,
-                baseUrl,
-                options,
-                bootstrapHelper,
-                auth,
-            });
-        case 'exchange':
-            // Hosted-cloud (`sk_`): the policy exchanged the apiKey for a capability
-            // token; here we apply the returned scope and set up the refresh scheduler.
-            return resolveHosted({
-                cred,
-                configuredApiKey,
-                baseUrl,
-                kind,
-                options,
-                bootstrapHelper,
-                auth,
-                logger,
-            });
-        case 'pre-minted':
-            // Self-derived: a pre-minted `ek_`/`rk_` bearer or an explicit capability
-            // token authenticates `/auth/identity` directly (no exchange, no refresh).
-            return resolveViaIdentity({
-                bearer: cred.getBearer,
-                baseUrl,
-                options,
-                bootstrapHelper,
-                auth,
-            });
-        case 'explicit': {
-            // Explicit self-hosted identity: the caller supplied its own organization id
-            // and user or agent id.
-            const userId = kind === 'agent' ? options.agentId : options.user.id;
-            const accountScope = internalOptions.organizationId;
-            bootstrapHelper.setCacheScope(accountScope);
-            bootstrapHelper.setSyncGroups(options.syncGroups);
-            auth.setAuthToken(cred.getBearer);
-            return {
-                userId,
-                accountScope,
-                teamIds: kind === 'user' ? options.user?.teamIds : undefined,
-                capabilityToken: cred.getBearer,
-                syncGroups: options.syncGroups,
-                participantKind: kind,
-                refreshScheduler: null,
-            };
-        }
-    }
-}
-/**
- * Resolves identity through the `/auth/identity` endpoint for the publishable
- * (`pk_`) and pre-minted (`ek_`/`rk_` or explicit capability token) routes. The
- * bearer is used as-is, the server resolves the identity, and any caller-passed
- * sync groups are merged with the server-resolved set.
- */
-async function resolveViaIdentity(input) {
-    const { bearer, baseUrl, options, bootstrapHelper, auth } = input;
-    const identity = await resolveIdentity({ baseUrl, authToken: bearer });
-    // Merge the caller's sync groups with the server-resolved set rather than
-    // letting the server response overwrite them. A client may compose groups such
-    // as `['default', 'org:<id>', 'user:<id>', 'team:<id>']` from the resolved
-    // session and pass them in; the identity endpoint can return an empty set (for
-    // example, for cookie-authenticated users), and an empty set makes the server
-    // bootstrap fall back to `['default']`, so no deltas fan out and live updates
-    // appear only on a hard reload. Merging keeps the caller's groups intact.
-    const callerGroups = options.syncGroups ?? [];
-    const mergedSyncGroups = callerGroups.length > 0
-        ? [...new Set([...callerGroups, ...identity.syncGroups])]
-        : identity.syncGroups;
-    bootstrapHelper.setCacheScope(identity.accountScope);
-    bootstrapHelper.setSyncGroups(mergedSyncGroups);
-    auth.setAuthToken(bearer);
-    return {
-        userId: identity.participantId,
-        accountScope: identity.accountScope,
-        teamIds: undefined,
-        capabilityToken: bearer,
-        syncGroups: mergedSyncGroups,
-        participantKind: identity.participantKind,
-        refreshScheduler: null,
-    };
-}
-async function resolveHosted(input) {
-    // The managed-cloud shape, `Ablo({ schema, apiKey })`. The credential policy has
-    // already exchanged the apiKey via `exchangeApiKey`; here we apply the returned
-    // scope and set up the refresh scheduler.
-    const { exchange } = input.cred;
-    const baseUrl = input.baseUrl;
-    // The refresh path re-runs `exchangeApiKey` with a freshly-resolved apiKey, so
-    // it needs the same argument bag the policy used for the initial exchange.
-    const participantKind = input.kind === 'agent' ? 'agent' : 'system';
-    const exchangeArgs = {
-        baseUrl,
-        participantKind,
-        participantId: input.options.agentId ?? input.options.user?.id,
-        wideScope: true,
-        ttlSeconds: 3600,
-    };
-    input.bootstrapHelper.setCacheScope(exchange.scope.organizationId);
-    input.bootstrapHelper.setSyncGroups(exchange.scope.syncGroups);
-    input.auth.setAuthToken(exchange.token);
-    // Capability tokens carry a server-set TTL (3600s by default). Without proactive
-    // refresh, the socket would be force-closed at expiry, or the next reconnect
-    // would fail with a 401. The scheduler re-mints ahead of that, so the consumer
-    // never sees the rotation.
-    const refreshScheduler = createRefreshScheduler({
-        initialExpiresAtMs: Date.parse(exchange.expiresAt),
-        refresh: async () => {
-            // Read the apiKey fresh each time — supports the ApiKeySetter
-            // (rotating credentials) shape.
-            const freshApiKey = await resolveApiKeyValue(input.configuredApiKey);
-            if (!freshApiKey) {
-                throw new AbloAuthenticationError('apiKey unavailable during refresh', { code: 'apikey_missing' });
-            }
-            const next = await exchangeApiKey({
-                ...exchangeArgs,
-                apiKey: freshApiKey,
-            });
-            input.auth.setAuthToken(next.token);
-            return { expiresAtMs: Date.parse(next.expiresAt) };
-        },
-        onError: (err) => {
-            input.logger.debug('cap token refresh failed; will retry', {
-                error: err.message,
-            });
-        },
-    });
-    return {
-        userId: exchange.scope.participantId,
-        accountScope: exchange.scope.organizationId,
-        // teamIds isn't needed because the server already encoded
-        // team-level access into scope.syncGroups.
-        teamIds: undefined,
-        capabilityToken: exchange.token,
-        syncGroups: exchange.scope.syncGroups,
-        participantKind: input.kind,
-        refreshScheduler,
-    };
-}