@abloatai/transaction 0.37.0

package/dist/auth/credentialSource.js

@@ -0,0 +1,56 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=credentialSource.js.map

package/dist/auth/credentialSource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialSource.js","sourceRoot":"","sources":["../../src/auth/credentialSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,kFAAkF;AAClF,0EAA0E;AAC1E,uEAAuE;AACvE,OAAO,EAAE,4BAA4B,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAmBxF,MAAM,UAAU,0BAA0B,CACxC,YAA4B;IAE5B,IAAI,SAAS,GAAG,cAAc,CAAC,YAAY,CAAC,CAAC;IAE7C,OAAO;QACL,YAAY,EAAE,GAAG,EAAE,CAAC,SAAS;QAC7B,YAAY,CAAC,KAAK;YAChB,SAAS,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QACpC,CAAC;QACD,mBAAmB;YACjB,OAAO,2BAA2B,CAAC,SAAS,CAAC,CAAC;QAChD,CAAC;QACD,eAAe,CAAC,OAAO,GAAG,EAAE;YAC1B,MAAM,aAAa,GAAG,2BAA2B,CAAC,SAAS,CAAC,CAAC;YAC7D,OAAO,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;QACvF,CAAC;QACD,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,eAAe;YACrD,sBAAsB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,YAA8B,EAC9B,aAA6B;IAE7B,OAAO,cAAc,CAAC,YAAY,EAAE,EAAE,IAAI,aAAa,CAAC,IAAI,SAAS,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,2BAA2B,CACzC,KAAgC;IAEhC,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,UAAU,CAAC,CAAC,CAAC,UAAU,UAAU,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,YAAyC,EACzC,UAAkC,EAAE,EACpC,aAA6B;IAE7B,MAAM,aAAa,GAAG,2BAA2B,CAC/C,gBAAgB,CAAC,YAAY,EAAE,aAAa,CAAC,CAC9C,CAAC;IACF,OAAO,aAAa,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC;AACvF,CAAC;AAED,MAAM,UAAU,sBAAsB,CACpC,MAAuB,EACvB,YAAyC,EACzC,SAAS,GAAG,eAAe,EAC3B,aAA6B;IAE7B,MAAM,aAAa,GAAG,2BAA2B,CAC/C,gBAAgB,CAAC,YAAY,EAAE,aAAa,CAAC,CAC9C,CAAC;IACF,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,CAAC,GAAG,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACvC,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAgC;IACtD,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7C,CAAC"}

package/dist/auth/hostedEndpoints.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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";
+//# sourceMappingURL=hostedEndpoints.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hostedEndpoints.d.ts","sourceRoot":"","sources":["../../src/auth/hostedEndpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yCAAyC;AACzC,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,6BAAsC,CAAC;AAE7E;;6CAE6C;AAC7C,eAAO,MAAM,qBAAqB,6BAA4B,CAAC"}

package/dist/auth/hostedEndpoints.js

@@ -0,0 +1,22 @@
+/**
+ * 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;
+//# sourceMappingURL=hostedEndpoints.js.map

package/dist/auth/hostedEndpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostedEndpoints.js","sourceRoot":"","sources":["../../src/auth/hostedEndpoints.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yCAAyC;AACzC,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAEzD,4EAA4E;AAC5E,MAAM,CAAC,MAAM,yBAAyB,GAAG,WAAW,sBAAsB,EAAE,CAAC;AAE7E;;6CAE6C;AAC7C,MAAM,CAAC,MAAM,qBAAqB,GAAG,yBAAyB,CAAC"}

package/dist/auth/identity.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 { CredentialProvider } from './credentialResult.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 | CredentialProvider | null;
+    readonly configuredAuthToken: string | null;
+    readonly bootstrapHelper: BootstrapScope;
+    readonly auth: AuthCredentialSource;
+    readonly logger: Logger;
+}
+export interface ResolvedIdentity {
+    readonly userId: string;
+    readonly accountScope: string;
+    /** Concrete project selected by the credential. The org id is the default project. */
+    readonly projectId: string | null;
+    /** Data environment selected by the credential. Null for explicit/self-hosted identities. */
+    readonly environment: 'sandbox' | 'production' | null;
+    /** Concrete sandbox selected by the credential, when applicable. */
+    readonly sandboxId: string | null;
+    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>;
+//# sourceMappingURL=identity.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/auth/identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAI/D,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,kBAAkB,CAAC;AAK1B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAGhE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QACnC,QAAQ,CAAC,IAAI,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC;QACnD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,eAAe,EAAE;QAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IAC9D,QAAQ,CAAC,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5C,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,sFAAsF;IACtF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,EAAE,SAAS,GAAG,YAAY,GAAG,IAAI,CAAC;IACtD,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,4FAA4F;IAC5F,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACpD;AAED,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAyH3B"}

package/dist/auth/identity.js

@@ -0,0 +1,224 @@
+/**
+ * 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,
+                projectId: accountScope,
+                environment: null,
+                sandboxId: null,
+                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,
+        projectId: identity.projectId ?? identity.accountScope,
+        environment: identity.environment ?? null,
+        sandboxId: identity.sandboxId ?? null,
+        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 a CredentialProvider
+            // (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,
+        // The legacy capability exchange response predates the explicit plane
+        // fields returned by `/auth/identity`. A hosted secret-key client defaults
+        // to the org-default project; browser sessions use resolveViaIdentity and
+        // therefore receive the concrete project/environment/sandbox tuple.
+        projectId: exchange.scope.organizationId,
+        environment: null,
+        sandboxId: null,
+        // 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,
+    };
+}
+//# sourceMappingURL=identity.js.map

package/dist/auth/identity.js.map

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

package/dist/auth/index.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Exchanges an API key for a capability token and the scope it grants.
+ *
+ * The `Ablo({...})` factory calls this during startup when you provide an
+ * `apiKey` but no explicit capability token, organization, or user identity. It
+ * sends one `POST /v1/capabilities` request; the server responds with the
+ * granted scope and any user metadata, which the client uses to populate its
+ * session state. The API key is the only credential you handle directly — this
+ * exchange happens automatically behind it.
+ */
+import { type EphemeralKeyResponse, type IdentityResolveResponse } from './schemas.js';
+import type { ParticipantKind } from '../types/participant.js';
+import type { CapabilityMintResponse, GrantedOperation } from './capability.js';
+export { ABLO_DEFAULT_BASE_URL, ABLO_HOSTED_API_DOMAIN, ABLO_HOSTED_HTTP_BASE_URL, } from './hostedEndpoints.js';
+export { normalizeAbloHostedBaseUrl } from './apiKey.js';
+/**
+ * @deprecated Use {@link CapabilityMintResponse}. This is a type-only,
+ * one-release rename bridge; both names resolve to the same canonical Zod
+ * contract and no runtime parser or schema is duplicated.
+ */
+export type CapabilityExchangeResponse = CapabilityMintResponse;
+export type { EphemeralKeyResponse, IdentityResolveResponse, } from './schemas.js';
+export { parseCapabilityMintResponse } from './schemas.js';
+export { credentialEndpointErrorSchema, credentialEndpointKindSchema, credentialEndpointSuccessSchema, credentialEndpointErrorCode, parseCredentialEndpointSuccess, } from './credentialEndpointProtocol.js';
+export type { CredentialEndpointError, CredentialEndpointSuccess, } from './credentialEndpointProtocol.js';
+export type { CredentialProvider, CredentialProviderResult, } from './credentialResult.js';
+export { capabilityRotationRequestSchema, capabilityRotationResponseSchema, sessionRevocationResponseSchema, revokeCapability, rotateCapability, } from './capabilityLifecycle.js';
+export type { RevokeCapabilityRequest, RotateCapabilityRequest, } from './capabilityLifecycle.js';
+export { capabilityOperationSchema, capabilityCanSchema, capabilityCanSchemaFor, capabilityScopeSchema, capabilityRequestSchema, capabilityMintResponseSchema, grantedOperationSchema, grantedOperations, expandReadYourWrites, modelWireNames, capabilityModelAliases, unresolvableOperations, } from './capability.js';
+export type { CapabilityOperation, CapabilityCan, CapabilityGrant, CapabilityScope, CapabilityMintResponse, CapabilityRequest, CapabilityModelShape, GrantedOperation, } from './capability.js';
+export interface ExchangeApiKeyRequest {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly participantKind: ParticipantKind;
+    readonly participantId?: string;
+    readonly organizationId?: string;
+    readonly syncGroups?: readonly string[];
+    /** The grant's verb axis, already in wire form. Build it with
+     *  `grantedOperations(can)` rather than assembling `model.verb` by hand. */
+    readonly operations?: readonly GrantedOperation[];
+    /**
+     * Grants a wider scope than the narrow-by-default behavior. This is an internal
+     * escalation used only by the startup exchange; it is stripped from the
+     * published type declarations and is not meant to be set by application code.
+     * @internal
+     */
+    readonly wideScope?: boolean;
+    readonly ttlSeconds: number;
+    readonly label?: string;
+    readonly userMeta?: Record<string, unknown>;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export declare function exchangeApiKey(options: ExchangeApiKeyRequest): Promise<CapabilityMintResponse>;
+interface MintUserSessionBase {
+    /** Your secret API key (an `sk_` key). Minting a session is a server-side
+     *  operation, so it always presents the secret key, never a token derived
+     *  from it. */
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    /** The end user's identifier in your identity provider. It becomes the
+     *  session's `participantId`. */
+    readonly userId: string;
+    /** The organization to mint the session into, for a platform that manages many
+     *  organizations. Requires the secret key to carry the `ephemeral:mint-any-org`
+     *  capability. Omit to mint into the key's own organization. */
+    readonly organizationId?: string;
+    /** Points this session's schema at a shared project while its data stays scoped
+     *  to `organizationId`. Use this when each customer has its own organization but
+     *  they all share one schema: keep a single schema project, and every customer's
+     *  session resolves its schema from it instead of pushing the schema into each
+     *  organization separately. Requires the secret key to carry the
+     *  `ephemeral:mint-any-org` capability. Omit to resolve the schema from the
+     *  session's own organization. */
+    readonly schemaProject?: {
+        /** The organization that owns the shared schema project. */
+        readonly organizationId: string;
+        /** The project the schema was pushed under. */
+        readonly projectId: string;
+    };
+    readonly syncGroups?: readonly string[];
+    readonly ttlSeconds: number;
+    readonly label?: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export type MintUserSessionRequest = MintUserSessionBase & {
+    /** Required least-privilege operation allowlist. */
+    readonly operations: readonly GrantedOperation[];
+};
+/**
+ * Mints an end-user session key (an `ek_` key) by calling
+ * `POST /v1/ephemeral_keys`, using your secret key as authorization. Your
+ * backend calls this to issue a session that a browser can present as its bearer
+ * credential; the server trusts the resulting key because a secret key minted it.
+ *
+ * This is a distinct endpoint from `/v1/capabilities`, which exchanges keys for
+ * agents and systems and cannot mint sessions for human users.
+ */
+export declare function mintUserSessionKey(options: MintUserSessionRequest): Promise<EphemeralKeyResponse>;
+export interface ResolveIdentityRequest {
+    readonly baseUrl: string;
+    readonly authToken?: string;
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+/**
+ * Resolves the caller's identity from an authenticated request by calling
+ * `GET /auth/identity`. This lets browser and session flows learn who the
+ * current user is without requiring the application to pass a user id up front —
+ * for example, to key local storage.
+ */
+export declare function resolveIdentity(options: ResolveIdentityRequest): Promise<IdentityResolveResponse>;
+/**
+ * Keeps a capability token fresh so a long-lived client never disconnects when
+ * its token expires.
+ *
+ * A capability token has a shorter lifetime — one hour by default — than a
+ * typical browser session. Without a refresh, the WebSocket is force-closed at
+ * expiry (close code 1008) or the next reconnect fails with a 401, and either way
+ * the user sees a mid-session disconnect. The scheduler prevents that by
+ * re-minting the token ahead of time.
+ *
+ * Three triggers share one refresh path:
+ *
+ *   1. Proactive  — a timer set for `expiresAtMs - bufferMs - now`.
+ *   2. Visibility — when a hidden tab becomes visible and the token is already
+ *                   within the buffer window, refresh immediately. This covers a
+ *                   background tab whose timers were throttled while it was idle.
+ *   3. Reactive   — the caller invokes {@link RefreshScheduler.refreshNow} after
+ *                   observing an auth failure, such as a WebSocket close 1008 or
+ *                   4001.
+ *
+ * All three await the same in-flight promise, so concurrent triggers mint the
+ * token only once. Each successful refresh records the new expiry and reschedules
+ * the proactive timer.
+ *
+ * The refresh margin is `max(60s, ttl/10)` — six minutes for a one-hour token,
+ * and it scales down for shorter lifetimes.
+ */
+export interface RefreshSchedulerOptions {
+    /** Initial absolute expiry, ms since epoch (server-supplied). */
+    readonly initialExpiresAtMs: number;
+    /**
+     * Performs the token exchange and returns the new expiry. Errors propagate to
+     * `onError`; the scheduler stays alive and retries on its next trigger. It does
+     * not back off between retries, since the common failure here is a revoked API
+     * key, for which retrying would not help.
+     */
+    readonly refresh: () => Promise<{
+        expiresAtMs: number;
+    }>;
+    /** Called on every successful refresh. */
+    readonly onRefreshed?: (info: {
+        expiresAtMs: number;
+    }) => void;
+    /** Called on every refresh failure. */
+    readonly onError?: (error: Error) => void;
+    /**
+     * Override the buffer (ms ahead of expiry to refresh). Defaults to
+     * `max(60_000, ttlMs * 0.1)`. Tests use a tiny value to exercise
+     * scheduling without burning real time.
+     */
+    readonly bufferMs?: number;
+    /**
+     * If true, install a `visibilitychange` listener on `document` that
+     * triggers a refresh when the tab becomes visible and the token is
+     * within the buffer window. No-op if `document` is undefined (Node).
+     * Default: true in browser environments.
+     */
+    readonly attachVisibilityListener?: boolean;
+    /** Time source. Override in tests; defaults to `Date.now`. */
+    readonly now?: () => number;
+    /** Timer pair. Override in tests. */
+    readonly setTimer?: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    readonly clearTimer?: (handle: ReturnType<typeof setTimeout>) => void;
+}
+export interface RefreshScheduler {
+    /** Force a refresh now. Idempotent — concurrent calls share one promise. */
+    refreshNow(): Promise<{
+        expiresAtMs: number;
+    }>;
+    /** Stop scheduling. Safe to call multiple times. */
+    dispose(): void;
+    /** Current absolute expiry. Updated after each successful refresh. */
+    readonly expiresAtMs: number;
+}
+export declare function createRefreshScheduler(options: RefreshSchedulerOptions): RefreshScheduler;
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

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