@abloatai/transaction 0.37.0

package/dist/auth/capabilityLifecycle.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { AbloAuthenticationError, hasWireCode, translateHttpError, } from '../errors.js';
+import { capabilityScopeSchema } from './capability.js';
+export const sessionRevocationResponseSchema = z.object({
+    id: z.string().min(1),
+    deleted: z.literal(true),
+    activeSessionsClosed: z.number().int().nonnegative(),
+});
+export const capabilityRotationRequestSchema = z.object({
+    graceSeconds: z.number().int().positive().optional(),
+    ttlSeconds: z.number().int().positive().optional(),
+});
+export const capabilityRotationResponseSchema = z.object({
+    capabilityId: z.string().min(1),
+    token: z.string().trim().min(1),
+    expiresAt: z.iso.datetime().nullable(),
+    organizationId: z.string().min(1),
+    scope: capabilityScopeSchema,
+    rotatedFrom: z.object({
+        capabilityId: z.string().min(1),
+        expiresAt: z.iso.datetime(),
+    }),
+});
+async function requestCapabilityLifecycle(options) {
+    if (!options.apiKey) {
+        throw new AbloAuthenticationError('Session lifecycle operations require a secret (sk_) API key.', { code: 'apikey_missing' });
+    }
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for session lifecycle operations.', { code: 'base_url_missing' });
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 10_000);
+    let response;
+    try {
+        response = await (options.fetch ?? fetch)(`${options.baseUrl.replace(/\/+$/, '')}/v1/capabilities/${encodeURIComponent(options.id)}${options.suffix ?? ''}`, {
+            method: options.method,
+            headers: {
+                Authorization: `Bearer ${options.apiKey}`,
+                ...(options.body ? { 'Content-Type': 'application/json' } : {}),
+            },
+            ...(options.body ? { body: JSON.stringify(options.body) } : {}),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        throw new AbloAuthenticationError(`session lifecycle request failed: ${error instanceof Error ? error.message : String(error)}`, { code: 'exchange_network_error', cause: error });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // A non-JSON error still receives a stable client-side code below.
+        }
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`session lifecycle request rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
+    }
+    return response.json();
+}
+export async function revokeCapability(options) {
+    const raw = await requestCapabilityLifecycle({
+        ...options,
+        method: 'DELETE',
+    });
+    const parsed = sessionRevocationResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new AbloAuthenticationError('Session revoke response was malformed.', { code: 'exchange_malformed_response', cause: parsed.error });
+    }
+    return parsed.data;
+}
+export async function rotateCapability(options) {
+    const body = {
+        ...(options.graceSeconds !== undefined
+            ? { graceSeconds: options.graceSeconds }
+            : {}),
+        ...(options.ttlSeconds !== undefined
+            ? { ttlSeconds: options.ttlSeconds }
+            : {}),
+    };
+    const raw = await requestCapabilityLifecycle({
+        ...options,
+        method: 'POST',
+        suffix: '/rotate',
+        ...(Object.keys(body).length > 0 ? { body } : {}),
+    });
+    const parsed = capabilityRotationResponseSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new AbloAuthenticationError('Session rotation response was malformed.', { code: 'exchange_malformed_response', cause: parsed.error });
+    }
+    return {
+        id: parsed.data.capabilityId,
+        token: parsed.data.token,
+        expiresAt: parsed.data.expiresAt,
+        organizationId: parsed.data.organizationId,
+        scope: parsed.data.scope,
+        rotatedFrom: {
+            id: parsed.data.rotatedFrom.capabilityId,
+            expiresAt: parsed.data.rotatedFrom.expiresAt,
+        },
+    };
+}
+//# sourceMappingURL=capabilityLifecycle.js.map

package/dist/auth/capabilityLifecycle.js.map

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

package/dist/auth/credentialEndpoint.d.ts

@@ -0,0 +1,10 @@
+import type { CredentialProvider } from './credentialResult.js';
+export interface CredentialEndpointOptions {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly timeoutMs?: number;
+    readonly allowCrossOrigin?: boolean;
+}
+export declare function isCredentialEndpoint(value: string): boolean;
+/** Strict, injectable client for the browser session-mint protocol. */
+export declare function createEndpointCredentialResolver(endpoint: string, options?: CredentialEndpointOptions): CredentialProvider;
+//# sourceMappingURL=credentialEndpoint.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentialEndpoint.d.ts","sourceRoot":"","sources":["../../src/auth/credentialEndpoint.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAQhE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE3D;AAsBD,uEAAuE;AACvE,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,yBAA8B,GACtC,kBAAkB,CAoCpB"}

package/dist/auth/credentialEndpoint.js

@@ -0,0 +1,58 @@
+import { credentialEndpointErrorCode, parseCredentialEndpointSuccess, } from './credentialEndpointProtocol.js';
+const DEFAULT_AUTH_TIMEOUT_MS = 10_000;
+export function isCredentialEndpoint(value) {
+    return value.startsWith('/') || /^https?:\/\//i.test(value);
+}
+function assertEndpointOrigin(endpoint, allowCrossOrigin) {
+    if (allowCrossOrigin || endpoint.startsWith('/'))
+        return;
+    if (typeof window === 'undefined')
+        return;
+    const endpointOrigin = new URL(endpoint, window.location.href).origin;
+    if (endpointOrigin !== window.location.origin) {
+        throw new Error('credential endpoint must be same-origin; set ' +
+            '`allowCrossOriginAuthEndpoint: true` only after configuring CORS and CSRF protection');
+    }
+}
+async function readJson(response) {
+    try {
+        return await response.json();
+    }
+    catch {
+        return null;
+    }
+}
+/** Strict, injectable client for the browser session-mint protocol. */
+export function createEndpointCredentialResolver(endpoint, options = {}) {
+    assertEndpointOrigin(endpoint, options.allowCrossOrigin ?? false);
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS;
+    return async () => {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const response = await fetchImpl(endpoint, {
+                method: 'POST',
+                credentials: 'include',
+                cache: 'no-store',
+                headers: { accept: 'application/json' },
+                signal: controller.signal,
+            });
+            const body = await readJson(response);
+            if (response.status === 401 &&
+                credentialEndpointErrorCode(body) === 'session_expired') {
+                return null;
+            }
+            if (!response.ok) {
+                const code = credentialEndpointErrorCode(body);
+                throw new Error(`credential endpoint ${endpoint} answered ${response.status}` +
+                    (code ? ` (${code})` : ''));
+            }
+            return parseCredentialEndpointSuccess(body);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    };
+}
+//# sourceMappingURL=credentialEndpoint.js.map

package/dist/auth/credentialEndpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialEndpoint.js","sourceRoot":"","sources":["../../src/auth/credentialEndpoint.ts"],"names":[],"mappings":"AACA,OAAO,EACL,2BAA2B,EAC3B,8BAA8B,GAC/B,MAAM,iCAAiC,CAAC;AAEzC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAQvC,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,oBAAoB,CAAC,QAAgB,EAAE,gBAAyB;IACvE,IAAI,gBAAgB,IAAI,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO;IACzD,IAAI,OAAO,MAAM,KAAK,WAAW;QAAE,OAAO;IAC1C,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;IACtE,IAAI,cAAc,KAAK,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,+CAA+C;YAC7C,sFAAsF,CACzF,CAAC;IACJ,CAAC;AACH,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,QAAkB;IACxC,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,gCAAgC,CAC9C,QAAgB,EAChB,UAAqC,EAAE;IAEvC,oBAAoB,CAAC,QAAQ,EAAE,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC;IACpD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,uBAAuB,CAAC;IAE/D,OAAO,KAAK,IAAI,EAAE;QAChB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAChE,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,QAAQ,EAAE;gBACzC,MAAM,EAAE,MAAM;gBACd,WAAW,EAAE,SAAS;gBACtB,KAAK,EAAE,UAAU;gBACjB,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;gBACvC,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAEtC,IACE,QAAQ,CAAC,MAAM,KAAK,GAAG;gBACvB,2BAA2B,CAAC,IAAI,CAAC,KAAK,iBAAiB,EACvD,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC;YACD,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,MAAM,IAAI,GAAG,2BAA2B,CAAC,IAAI,CAAC,CAAC;gBAC/C,MAAM,IAAI,KAAK,CACb,uBAAuB,QAAQ,aAAa,QAAQ,CAAC,MAAM,EAAE;oBAC3D,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAC7B,CAAC;YACJ,CAAC;YACD,OAAO,8BAA8B,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,OAAO,CAAC,CAAC;QACxB,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/auth/credentialEndpointProtocol.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export declare const credentialEndpointKindSchema: z.ZodEnum<{
+    ephemeral: "ephemeral";
+    restricted: "restricted";
+}>;
+export declare const credentialEndpointSuccessSchema: z.ZodObject<{
+    token: z.ZodString;
+    expiresAt: z.ZodISODateTime;
+    credentialKind: z.ZodEnum<{
+        ephemeral: "ephemeral";
+        restricted: "restricted";
+    }>;
+}, z.core.$strict>;
+export declare const credentialEndpointErrorSchema: z.ZodObject<{
+    error: z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CredentialEndpointSuccess = z.infer<typeof credentialEndpointSuccessSchema>;
+export type CredentialEndpointError = z.infer<typeof credentialEndpointErrorSchema>;
+export declare function parseCredentialEndpointSuccess(raw: unknown): CredentialEndpointSuccess;
+export declare function credentialEndpointErrorCode(raw: unknown): string | null;
+//# sourceMappingURL=credentialEndpointProtocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentialEndpointProtocol.d.ts","sourceRoot":"","sources":["../../src/auth/credentialEndpointProtocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,eAAO,MAAM,4BAA4B;;;EAGvC,CAAC;AAEH,eAAO,MAAM,+BAA+B;;;;;;;kBAI1C,CAAC;AAEH,eAAO,MAAM,6BAA6B;;;;;kBAKxC,CAAC;AAEH,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAC7C,OAAO,+BAA+B,CACvC,CAAC;AACF,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAC3C,OAAO,6BAA6B,CACrC,CAAC;AAEF,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,OAAO,GACX,yBAAyB,CAe3B;AAED,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAGvE"}

package/dist/auth/credentialEndpointProtocol.js

@@ -0,0 +1,34 @@
+import { z } from 'zod';
+import { classifyCredentialKind } from './credentialKind.js';
+export const credentialEndpointKindSchema = z.enum([
+    'ephemeral',
+    'restricted',
+]);
+export const credentialEndpointSuccessSchema = z.strictObject({
+    token: z.string().trim().min(1),
+    expiresAt: z.iso.datetime({ offset: true }),
+    credentialKind: credentialEndpointKindSchema,
+});
+export const credentialEndpointErrorSchema = z.strictObject({
+    error: z.strictObject({
+        code: z.string().min(1),
+        message: z.string().optional(),
+    }),
+});
+export function parseCredentialEndpointSuccess(raw) {
+    const parsed = credentialEndpointSuccessSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`credential endpoint returned a malformed success body: ${z.prettifyError(parsed.error)}`);
+    }
+    const actualKind = classifyCredentialKind(parsed.data.token);
+    if (actualKind !== parsed.data.credentialKind) {
+        throw new Error(`credential endpoint declared ${parsed.data.credentialKind} but returned ` +
+            `${actualKind ?? 'an unknown credential kind'}`);
+    }
+    return parsed.data;
+}
+export function credentialEndpointErrorCode(raw) {
+    const parsed = credentialEndpointErrorSchema.safeParse(raw);
+    return parsed.success ? parsed.data.error.code : null;
+}
+//# sourceMappingURL=credentialEndpointProtocol.js.map

package/dist/auth/credentialEndpointProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialEndpointProtocol.js","sourceRoot":"","sources":["../../src/auth/credentialEndpointProtocol.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,IAAI,CAAC;IACjD,WAAW;IACX,YAAY;CACb,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC,YAAY,CAAC;IAC5D,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/B,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IAC3C,cAAc,EAAE,4BAA4B;CAC7C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,YAAY,CAAC;IAC1D,KAAK,EAAE,CAAC,CAAC,YAAY,CAAC;QACpB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;QACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KAC/B,CAAC;CACH,CAAC,CAAC;AASH,MAAM,UAAU,8BAA8B,CAC5C,GAAY;IAEZ,MAAM,MAAM,GAAG,+BAA+B,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,0DAA0D,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAC1F,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,sBAAsB,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC7D,IAAI,UAAU,KAAK,MAAM,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CACb,gCAAgC,MAAM,CAAC,IAAI,CAAC,cAAc,gBAAgB;YACxE,GAAG,UAAU,IAAI,4BAA4B,EAAE,CAClD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,GAAY;IACtD,MAAM,MAAM,GAAG,6BAA6B,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACxD,CAAC"}

package/dist/auth/credentialKind.d.ts

@@ -0,0 +1,4 @@
+export type CredentialKind = 'secret' | 'ephemeral' | 'restricted' | 'publishable';
+/** Browser-safe prefix classification; server checksum validation stays server-side. */
+export declare function classifyCredentialKind(value: string): CredentialKind | null;
+//# sourceMappingURL=credentialKind.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentialKind.d.ts","sourceRoot":"","sources":["../../src/auth/credentialKind.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GACtB,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,aAAa,CAAC;AASlB,wFAAwF;AACxF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAK3E"}

package/dist/auth/credentialKind.js

@@ -0,0 +1,15 @@
+const KIND_BY_PREFIX = [
+    ['sk_', 'secret'],
+    ['ek_', 'ephemeral'],
+    ['rk_', 'restricted'],
+    ['pk_', 'publishable'],
+];
+/** Browser-safe prefix classification; server checksum validation stays server-side. */
+export function classifyCredentialKind(value) {
+    for (const [prefix, kind] of KIND_BY_PREFIX) {
+        if (value.startsWith(prefix))
+            return kind;
+    }
+    return null;
+}
+//# sourceMappingURL=credentialKind.js.map

package/dist/auth/credentialKind.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialKind.js","sourceRoot":"","sources":["../../src/auth/credentialKind.ts"],"names":[],"mappings":"AAMA,MAAM,cAAc,GAAmD;IACrE,CAAC,KAAK,EAAE,QAAQ,CAAC;IACjB,CAAC,KAAK,EAAE,WAAW,CAAC;IACpB,CAAC,KAAK,EAAE,YAAY,CAAC;IACrB,CAAC,KAAK,EAAE,aAAa,CAAC;CACvB,CAAC;AAEF,wFAAwF;AACxF,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,cAAc,EAAE,CAAC;QAC5C,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC;IAC5C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/auth/credentialPolicy.d.ts

@@ -0,0 +1,141 @@
+/**
+ * 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 type { exchangeApiKey, mintUserSessionKey, resolveIdentity } from './index.js';
+import { classifyCredentialKind, type CredentialKind } from './credentialKind.js';
+import type { CredentialProvider } from './credentialResult.js';
+/**
+ * The shape of the function that resolves a configured `apiKey` — which may be a
+ * string or an async setter — down to a concrete string, or `null` when no key
+ * is available. It is declared here structurally, rather than imported, to avoid
+ * a circular dependency between this module and the code that supplies the
+ * function. Any function with a matching shape satisfies it.
+ */
+type ResolveApiKeyValueFn = (apiKey: string | CredentialProvider | null) => Promise<string | null>;
+/**
+ * The four kinds of Ablo API key, one per prefix: `sk_` is secret, `ek_` is
+ * ephemeral, `rk_` is restricted, and `pk_` is publishable. The list is declared
+ * here, rather than imported, so this browser-safe module stays free of Node-only
+ * dependencies.
+ */
+export { classifyCredentialKind, type CredentialKind };
+/**
+ * The set of authentication primitives that {@link resolveCredential} delegates
+ * to. Injecting them keeps the network calls that mint and exchange credentials
+ * in one place and leaves this module responsible only for the routing decision.
+ * {@link resolveCredential} never calls `mintUserSessionKey` itself — an
+ * ephemeral `ek_` key is minted before the client connects and arrives ready to
+ * use — but it is listed here to describe the full primitive surface.
+ */
+export interface CredentialPrimitives {
+    readonly exchangeApiKey: typeof exchangeApiKey;
+    readonly mintUserSessionKey: typeof mintUserSessionKey;
+    readonly resolveIdentity: typeof resolveIdentity;
+    readonly resolveApiKeyValue: ResolveApiKeyValueFn;
+}
+export interface ResolveCredentialContext {
+    readonly primitives: CredentialPrimitives;
+    /**
+     * The arguments for the credential exchange, minus the `apiKey`. The caller
+     * derives the base URL and participant scope and supplies them here;
+     * {@link resolveCredential} fills in the resolved `apiKey` and calls
+     * `exchangeApiKey`.
+     */
+    readonly exchangeArgs: Omit<Parameters<typeof exchangeApiKey>[0], 'apiKey'>;
+}
+export interface ResolveCredentialInput {
+    /** Resolved string value of the configured `apiKey` (callable already invoked), or null. */
+    readonly apiKeyValue: string | null;
+    /** The configured `apiKey` (string or setter) — threaded onto the refresh path. */
+    readonly configuredApiKey: string | CredentialProvider | null;
+    /** Explicit caller-supplied capability token (`options.capabilityToken`). */
+    readonly capabilityToken: string | undefined;
+    /** Configured static `authToken`. */
+    readonly authToken: string | null;
+    /** True when the caller already knows its own identity, so no server round-trip is needed to resolve it. */
+    readonly hasExplicitIdentity: boolean;
+}
+/**
+ * The outcome of the connect-time decision, as a discriminated union over the
+ * route rather than the key kind: an `ek_` and an `rk_` key both take the
+ * `pre-minted` route, as does a bare capability token. The caller switches on
+ * `kind` and wires up the scope and side effects each route needs.
+ *
+ * Every variant carries the same three fields:
+ *   - `getBearer` — the token used to authenticate the bootstrap and `/auth/*`
+ *     requests, and to seed the credential source.
+ *   - `expiresAtMs` — when the credential expires, which drives the refresh
+ *     scheduler, or `null` when there is nothing to refresh.
+ *   - `controlPlaneKey` — the original configured API key when the route minted
+ *     its bearer through an exchange, so a refresh can mint again; otherwise
+ *     `null`.
+ */
+export type ResolvedCredential = 
+/** `pk_` — long-lived browser-safe read-only project key. Used directly as the
+ *  bearer; never exchanged, never refreshed. Identity resolved via `/auth/identity`. */
+{
+    readonly kind: 'publishable';
+    readonly getBearer: string;
+    readonly expiresAtMs: null;
+    readonly controlPlaneKey: null;
+}
+/** `sk_` (no explicit cap token) — hosted-cloud. Exchanged for a capability
+ *  token via `exchangeApiKey`; the refresh scheduler re-mints before expiry. */
+ | {
+    readonly kind: 'exchange';
+    /** Result of the initial `exchangeApiKey` call. */
+    readonly exchange: Awaited<ReturnType<typeof exchangeApiKey>>;
+    readonly getBearer: string;
+    readonly expiresAtMs: number;
+    /** The configured apiKey (string or setter) — read fresh on each refresh. */
+    readonly controlPlaneKey: string | CredentialProvider;
+}
+/** A pre-minted `ek_` or `rk_` key, or an explicit capability or auth token,
+ *  used as the bearer without any exchange. Identity resolved via `/auth/identity`. */
+ | {
+    readonly kind: 'pre-minted';
+    readonly getBearer: string;
+    readonly expiresAtMs: null;
+    readonly controlPlaneKey: null;
+}
+/** The caller already knows its own organization and user or agent id, so there
+ *  is no server round-trip; the optional bearer is the initial capability token. */
+ | {
+    readonly kind: 'explicit';
+    readonly getBearer: string | undefined;
+    readonly expiresAtMs: null;
+    readonly controlPlaneKey: 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 declare function resolveCredential(input: ResolveCredentialInput, ctx: ResolveCredentialContext): Promise<ResolvedCredential>;
+//# sourceMappingURL=credentialPolicy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentialPolicy.d.ts","sourceRoot":"","sources":["../../src/auth/credentialPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,sBAAsB,EACtB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE;;;;;;GAMG;AACH,KAAK,oBAAoB,GAAG,CAC1B,MAAM,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,KACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AAE5B;;;;;GAKG;AACH,OAAO,EAAE,sBAAsB,EAAE,KAAK,cAAc,EAAE,CAAC;AAIvD;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,cAAc,EAAE,OAAO,cAAc,CAAC;IAC/C,QAAQ,CAAC,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;IACvD,QAAQ,CAAC,eAAe,EAAE,OAAO,eAAe,CAAC;IACjD,QAAQ,CAAC,kBAAkB,EAAE,oBAAoB,CAAC;CACnD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,IAAI,CACzB,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC,CAAC,EACpC,QAAQ,CACT,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,4FAA4F;IAC5F,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,mFAAmF;IACnF,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAAC;IAC9D,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,qCAAqC;IACrC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,4GAA4G;IAC5G,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;CACvC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,kBAAkB;AAC5B;wFACwF;AACtF;IACE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;CAChC;AACH;gFACgF;GAC9E;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,eAAe,EAAE,MAAM,GAAG,kBAAkB,CAAC;CACvD;AACH;uFACuF;GACrF;IACE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;CAChC;AACH;oFACoF;GAClF;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,IAAI,CAAC;CAChC,CAAC;AAEN;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,GAAG,EAAE,wBAAwB,GAC5B,OAAO,CAAC,kBAAkB,CAAC,CAkF7B"}

package/dist/auth/credentialPolicy.js

@@ -0,0 +1,113 @@
+/**
+ * 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';
+import { classifyCredentialKind, } from './credentialKind.js';
+/**
+ * The four kinds of Ablo API key, one per prefix: `sk_` is secret, `ek_` is
+ * ephemeral, `rk_` is restricted, and `pk_` is publishable. The list is declared
+ * here, rather than imported, so this browser-safe module stays free of Node-only
+ * dependencies.
+ */
+export { classifyCredentialKind };
+/**
+ * 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) ??
+        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,
+    };
+}
+//# sourceMappingURL=credentialPolicy.js.map

package/dist/auth/credentialPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialPolicy.js","sourceRoot":"","sources":["../../src/auth/credentialPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEvD,OAAO,EACL,sBAAsB,GAEvB,MAAM,qBAAqB,CAAC;AAc7B;;;;;GAKG;AACH,OAAO,EAAE,sBAAsB,EAAuB,CAAC;AAkGvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,KAA6B,EAC7B,GAA6B;IAE7B,MAAM,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,mBAAmB,EAAE,GAAG,KAAK,CAAC;IAE/E,MAAM,IAAI,GAAG,WAAW,IAAI,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE9E,8EAA8E;IAC9E,gFAAgF;IAChF,kFAAkF;IAClF,MAAM,2BAA2B,GAC/B,IAAI,KAAK,WAAW,IAAI,IAAI,KAAK,YAAY,CAAC;IAEhD,MAAM,eAAe,GACnB,eAAe;QACf,CAAC,2BAA2B,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC;QACvD,SAAS;QACT,SAAS,CAAC;IAEZ,8EAA8E;IAC9E,8EAA8E;IAC9E,+BAA+B;IAC/B,IAAI,WAAW,IAAI,IAAI,IAAI,IAAI,KAAK,aAAa,IAAI,eAAe,IAAI,IAAI,EAAE,CAAC;QAC7E,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,SAAS,EAAE,WAAW;YACtB,WAAW,EAAE,IAAI;YACjB,eAAe,EAAE,IAAI;SACtB,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,8EAA8E;IAC9E,6BAA6B;IAC7B,IACE,WAAW,IAAI,IAAI;QACnB,eAAe,IAAI,IAAI;QACvB,CAAC,2BAA2B,EAC5B,CAAC;QACD,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,cAAc,CAAC;YACnD,GAAG,GAAG,CAAC,YAAY;YACnB,MAAM,EAAE,WAAW;SACpB,CAAC,CAAC;QACH,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,QAAQ;YACR,SAAS,EAAE,QAAQ,CAAC,KAAK;YACzB,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC;YAC3C,eAAe,EAAE,KAAK,CAAC,gBAAgB,IAAI,WAAW;SACvD,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,sCAAsC;IACtC,IAAI,CAAC,mBAAmB,EAAE,CAAC;QACzB,IAAI,eAAe,IAAI,IAAI,EAAE,CAAC;YAC5B,6EAA6E;YAC7E,2EAA2E;YAC3E,0EAA0E;YAC1E,0EAA0E;YAC1E,6CAA6C;YAC7C,MAAM,IAAI,uBAAuB,CAC/B,qEAAqE;gBACnE,8EAA8E;gBAC9E,6CAA6C,EAC/C,EAAE,IAAI,EAAE,iBAAiB,EAAE,CAC5B,CAAC;QACJ,CAAC;QACD,OAAO;YACL,IAAI,EAAE,YAAY;YAClB,SAAS,EAAE,eAAe;YAC1B,WAAW,EAAE,IAAI;YACjB,eAAe,EAAE,IAAI;SACtB,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,eAAe;IACf,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,SAAS,EAAE,eAAe;QAC1B,WAAW,EAAE,IAAI;QACjB,eAAe,EAAE,IAAI;KACtB,CAAC;AACJ,CAAC"}

package/dist/auth/credentialResult.d.ts

@@ -0,0 +1,7 @@
+import type { CredentialEndpointSuccess } from './credentialEndpointProtocol.js';
+export type CredentialProviderResult = string | CredentialEndpointSuccess | null;
+/** Rotating secret provider or short-lived browser credential provider. */
+export type CredentialProvider = () => Promise<CredentialProviderResult>;
+export declare function credentialToken(result: CredentialProviderResult): string | null;
+export declare function credentialExpiry(result: CredentialProviderResult): string | undefined;
+//# sourceMappingURL=credentialResult.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentialResult.d.ts","sourceRoot":"","sources":["../../src/auth/credentialResult.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAEjF,MAAM,MAAM,wBAAwB,GAChC,MAAM,GACN,yBAAyB,GACzB,IAAI,CAAC;AAET,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,CAAC,wBAAwB,CAAC,CAAC;AAEzE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,wBAAwB,GAC/B,MAAM,GAAG,IAAI,CAEf;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,wBAAwB,GAC/B,MAAM,GAAG,SAAS,CAIpB"}

package/dist/auth/credentialResult.js

@@ -0,0 +1,9 @@
+export function credentialToken(result) {
+    return typeof result === 'string' ? result : result?.token ?? null;
+}
+export function credentialExpiry(result) {
+    return typeof result === 'object' && result !== null
+        ? result.expiresAt
+        : undefined;
+}
+//# sourceMappingURL=credentialResult.js.map

package/dist/auth/credentialResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialResult.js","sourceRoot":"","sources":["../../src/auth/credentialResult.ts"],"names":[],"mappings":"AAUA,MAAM,UAAU,eAAe,CAC7B,MAAgC;IAEhC,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,IAAI,IAAI,CAAC;AACrE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAC9B,MAAgC;IAEhC,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAClD,CAAC,CAAC,MAAM,CAAC,SAAS;QAClB,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC"}

package/dist/auth/credentialSource.d.ts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"credentialSource.d.ts","sourceRoot":"","sources":["../../src/auth/credentialSource.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,EAAE,4BAA4B,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAExF,MAAM,WAAW,oBAAoB;IACnC;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IAClC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAAC;IACrD,mBAAmB,IAAI,MAAM,GAAG,SAAS,CAAC;IAC1C,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1E,mBAAmB,CAAC,MAAM,EAAE,eAAe,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxE;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAE9D,wBAAgB,0BAA0B,CACxC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAC3B,oBAAoB,CAmBtB;AAED,wBAAgB,gBAAgB,CAC9B,YAAY,CAAC,EAAE,eAAe,EAC9B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,SAAS,CAGpB;AAED,wBAAgB,eAAe,CAC7B,YAAY,EAAE,eAAe,GAAG,SAAS,EACzC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,EACpC,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKxB;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,eAAe,EACvB,YAAY,EAAE,eAAe,GAAG,SAAS,EACzC,SAAS,SAAkB,EAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,IAAI,CAON"}