@abloatai/ablo 0.35.0 → 0.37.0

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

@@ -1,177 +0,0 @@
-/**
- * Capability — the one definition of what a credential may do.
- *
- * A grant is declared once, in the vocabulary a developer writes:
- *
- *     can: { documents: ['read', 'update'] }
- *
- * Everything downstream derives from that declaration: the wire spelling
- * (`documents.update`) stored on the key row, the typed `can` a schema narrows
- * to its own models, the request body the mint route parses, the pattern the
- * published contract advertises, and the scope block echoed back on the minted
- * session.
- *
- * Before this module the same grant was spelled five times — a literal union in
- * the resource types, a `z.array(z.string())` on the wire, a hand-rolled
- * field-by-field parser in the mint route, an object literal in the response
- * type, and a hand-written `model.verb` array at each caller that mints without
- * the SDK. Nothing failed when they drifted; the drift surfaced as
- * `capability_scope_denied` on a grant the caller believed it held.
- *
- * Two axes decide blast radius. VERBS come from `can`; ROWS come from
- * `syncGroups`. They belong to one grant, which is why they are declared
- * together here rather than meeting for the first time on the wire.
- */
-import { z } from 'zod';
-/**
- * The verbs a grant can name — the whole vocabulary, in one place. Every other
- * spelling of an operation in the system derives from this enum: the SDK's
- * `can` values, the wire's `model.verb` pattern, and the JSON Schema the
- * published contract advertises.
- */
-export declare const capabilityOperationSchema: z.ZodEnum<{
-    update: "update";
-    create: "create";
-    delete: "delete";
-    read: "read";
-}>;
-export type CapabilityOperation = z.infer<typeof capabilityOperationSchema>;
-/**
- * One granted operation in its wire spelling: `<model>.<verb>`, lowercased.
- *
- * The template literal derives both halves — the verb set from
- * {@link capabilityOperationSchema}, the pattern in the published contract from
- * the template — so tightening the verb vocabulary can never leave a stale
- * regex or a stale doc behind. The model half is the name the server matches
- * against a model's registered aliases (type name, schema key, or table name),
- * so it stays permissive here and is resolved at the gate.
- */
-export declare const grantedOperationSchema: z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>;
-export type GrantedOperation = z.infer<typeof grantedOperationSchema>;
-/**
- * The declared grant, per model — the runtime shape of `can`. Model keys are
- * free-form at runtime because the server resolves them against the schema it
- * has; {@link CapabilityCan} narrows them to a known schema's models at the
- * type level.
- */
-export declare const capabilityCanSchema: z.ZodRecord<z.ZodString, z.ZodReadonly<z.ZodArray<z.ZodEnum<{
-    update: "update";
-    create: "create";
-    delete: "delete";
-    read: "read";
-}>>>>;
-/**
- * `can`, narrowed to one schema's model names. A projection of
- * {@link capabilityCanSchema} — the value type is the operation enum, the key
- * domain is the schema's models, so `can: { tasks: ['update'] }` fails to
- * compile against a schema with no `tasks` model.
- */
-export type CapabilityCan<S> = Partial<Record<keyof S & string, readonly CapabilityOperation[]>>;
-/**
- * Read-your-writes expansion: append `<model>.read` for every model the grant
- * can write.
- *
- * A scoped agent that may update a row must be able to read it, or the read
- * gate (query / bootstrap / entity self-heal / delta fan-out) starves the very
- * writes the grant allows. The write verbs stay the source of truth; reads are
- * derived and deduped, and models the grant cannot write stay unreadable —
- * that is the read-side blast-radius reduction.
- *
- * It lives beside the declaration, so it applies wherever a grant is built,
- * rather than only at whichever mint the callers happen to share. The server
- * applies it again at the mint chokepoint for callers that post raw JSON; the
- * function is idempotent, so the second application is a no-op.
- */
-export declare function expandReadYourWrites(operations: readonly GrantedOperation[]): GrantedOperation[];
-/**
- * The parts of a model definition a grant can name. Structural, so both the
- * SDK (which holds a `Schema`) and the mint route (which holds the tenant's
- * pushed artifact) derive names from the same rule.
- */
-export interface CapabilityModelShape {
-    readonly typename?: string;
-    readonly tableName?: string;
-}
-/**
- * Schema key → the wire name a grant must be minted with.
- *
- * THE derivation. A model whose type name is overridden — schema key
- * `documents`, type name `Document` — has to mint `document.update`, not
- * `documents.update`, and a caller who works that out by hand gets it wrong
- * once and learns at `capability_scope_denied`. Callers pass their schema's
- * models, never a map they assembled themselves.
- */
-export declare function modelWireNames(models: Readonly<Record<string, CapabilityModelShape>>): Record<string, string>;
-/**
- * Every name the enforcement gates accept for a model, lowercased. Three
- * vocabularies name one logical model — the wire type name (`lineitem`), the
- * schema key (`lineItems`), and the table name (`line_items`) — so a grant
- * minted in any of them is honored, and the mint can tell a real model from a
- * typo without guessing which vocabulary the caller used.
- */
-export declare function capabilityModelAliases(models: Readonly<Record<string, CapabilityModelShape>>): Set<string>;
-/**
- * The granted operations whose model half names nothing in the schema.
- *
- * A grant is checked against the schema at MINT, the way a write to an unpushed
- * model already fails with `server_execute_unknown_model` — so a typo in
- * `lineitem.update` is a rejected mint rather than a credential that looks
- * healthy and is denied on its first write. Without this the `model` half is a
- * hole: an opaque string nothing validates until enforcement time.
- */
-export declare function unresolvableOperations(operations: readonly GrantedOperation[], aliases: ReadonlySet<string>): GrantedOperation[];
-/**
- * Serializes a declared `can` into the wire allowlist — the ONE translation
- * from what a developer writes to what the server stores and enforces.
- *
- * `wireNames` comes from {@link modelWireNames} over the client's own schema.
- * It is required rather than optional: an omitted map silently mints the schema
- * key verbatim, which is right for most models and wrong for every model with
- * a type-name override — the kind of default that is correct until it isn't.
- */
-export declare function grantedOperations(can: Readonly<Record<string, readonly CapabilityOperation[] | undefined>>, wireNames: Readonly<Record<string, string>>): GrantedOperation[];
-/**
- * The grant at rest: what the credential ended up with, on both axes, plus the
- * participant it acts as. The mint echoes this block, the key row stores it,
- * and the gates read it — so a session's reported scope and its enforced scope
- * are the same shape by construction.
- */
-export declare const capabilityScopeSchema: z.ZodObject<{
-    organizationId: z.ZodString;
-    syncGroups: z.ZodArray<z.ZodString>;
-    operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
-    participantKind: z.ZodEnum<{
-        user: "user";
-        agent: "agent";
-        system: "system";
-    }>;
-    participantId: z.ZodString;
-}, z.core.$strip>;
-export type CapabilityScope = z.infer<typeof capabilityScopeSchema>;
-/**
- * `POST /v1/capabilities` — mint a capability for a participant.
- *
- * Where an ephemeral key is a session for a person, a capability is a scoped,
- * revocable grant for an agent or a system. Narrow by default: an agent or
- * system capability must name its `operations` unless the caller explicitly
- * asks for `wideScope`, which is itself privileged.
- *
- * This is the parsed body — the mint route validates against it rather than
- * reading fields one at a time, so the shape and the validation rules cannot
- * drift from each other or from the published contract.
- */
-export declare const capabilityRequestSchema: z.ZodObject<{
-    participantKind: z.ZodEnum<{
-        user: "user";
-        agent: "agent";
-        system: "system";
-    }>;
-    participantId: z.ZodOptional<z.ZodString>;
-    syncGroups: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodUnion<readonly [z.ZodLiteral<"default">, z.core.$ZodBranded<z.ZodTemplateLiteral<`${string}:${string}`>, "SyncGroup", "out">]>>>>;
-    operations: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>>>;
-    ttlSeconds: z.ZodNumber;
-    label: z.ZodOptional<z.ZodString>;
-    wideScope: z.ZodOptional<z.ZodBoolean>;
-    userMeta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-export type CapabilityRequest = z.infer<typeof capabilityRequestSchema>;

package/dist/transaction/auth/capability.js

@@ -1,199 +0,0 @@
-/**
- * Capability — the one definition of what a credential may do.
- *
- * A grant is declared once, in the vocabulary a developer writes:
- *
- *     can: { documents: ['read', 'update'] }
- *
- * Everything downstream derives from that declaration: the wire spelling
- * (`documents.update`) stored on the key row, the typed `can` a schema narrows
- * to its own models, the request body the mint route parses, the pattern the
- * published contract advertises, and the scope block echoed back on the minted
- * session.
- *
- * Before this module the same grant was spelled five times — a literal union in
- * the resource types, a `z.array(z.string())` on the wire, a hand-rolled
- * field-by-field parser in the mint route, an object literal in the response
- * type, and a hand-written `model.verb` array at each caller that mints without
- * the SDK. Nothing failed when they drifted; the drift surfaced as
- * `capability_scope_denied` on a grant the caller believed it held.
- *
- * Two axes decide blast radius. VERBS come from `can`; ROWS come from
- * `syncGroups`. They belong to one grant, which is why they are declared
- * together here rather than meeting for the first time on the wire.
- */
-import { z } from 'zod';
-import { participantKindSchema } from '../coordination/schema.js';
-import { syncGroupInputSchema } from '../schema/roles.js';
-/**
- * The verbs a grant can name — the whole vocabulary, in one place. Every other
- * spelling of an operation in the system derives from this enum: the SDK's
- * `can` values, the wire's `model.verb` pattern, and the JSON Schema the
- * published contract advertises.
- */
-export const capabilityOperationSchema = z.enum(['read', 'create', 'update', 'delete']);
-/**
- * One granted operation in its wire spelling: `<model>.<verb>`, lowercased.
- *
- * The template literal derives both halves — the verb set from
- * {@link capabilityOperationSchema}, the pattern in the published contract from
- * the template — so tightening the verb vocabulary can never leave a stale
- * regex or a stale doc behind. The model half is the name the server matches
- * against a model's registered aliases (type name, schema key, or table name),
- * so it stays permissive here and is resolved at the gate.
- */
-export const grantedOperationSchema = z.templateLiteral([
-    z.string().regex(/^[^.\s]+$/),
-    '.',
-    capabilityOperationSchema,
-]);
-/**
- * The declared grant, per model — the runtime shape of `can`. Model keys are
- * free-form at runtime because the server resolves them against the schema it
- * has; {@link CapabilityCan} narrows them to a known schema's models at the
- * type level.
- */
-export const capabilityCanSchema = z.record(z.string().min(1), z.array(capabilityOperationSchema).readonly());
-/**
- * Read-your-writes expansion: append `<model>.read` for every model the grant
- * can write.
- *
- * A scoped agent that may update a row must be able to read it, or the read
- * gate (query / bootstrap / entity self-heal / delta fan-out) starves the very
- * writes the grant allows. The write verbs stay the source of truth; reads are
- * derived and deduped, and models the grant cannot write stay unreadable —
- * that is the read-side blast-radius reduction.
- *
- * It lives beside the declaration, so it applies wherever a grant is built,
- * rather than only at whichever mint the callers happen to share. The server
- * applies it again at the mint chokepoint for callers that post raw JSON; the
- * function is idempotent, so the second application is a no-op.
- */
-export function expandReadYourWrites(operations) {
-    const out = new Set(operations);
-    for (const op of operations) {
-        const [model] = op.split('.');
-        if (model)
-            out.add(`${model}.read`);
-    }
-    return [...out];
-}
-/**
- * Schema key → the wire name a grant must be minted with.
- *
- * THE derivation. A model whose type name is overridden — schema key
- * `documents`, type name `Document` — has to mint `document.update`, not
- * `documents.update`, and a caller who works that out by hand gets it wrong
- * once and learns at `capability_scope_denied`. Callers pass their schema's
- * models, never a map they assembled themselves.
- */
-export function modelWireNames(models) {
-    return Object.fromEntries(Object.entries(models).map(([key, def]) => [key, def.typename ?? key]));
-}
-/**
- * Every name the enforcement gates accept for a model, lowercased. Three
- * vocabularies name one logical model — the wire type name (`lineitem`), the
- * schema key (`lineItems`), and the table name (`line_items`) — so a grant
- * minted in any of them is honored, and the mint can tell a real model from a
- * typo without guessing which vocabulary the caller used.
- */
-export function capabilityModelAliases(models) {
-    const aliases = new Set();
-    for (const [key, def] of Object.entries(models)) {
-        aliases.add(key.toLowerCase());
-        if (def.typename)
-            aliases.add(def.typename.toLowerCase());
-        if (def.tableName)
-            aliases.add(def.tableName.toLowerCase());
-    }
-    return aliases;
-}
-/**
- * The granted operations whose model half names nothing in the schema.
- *
- * A grant is checked against the schema at MINT, the way a write to an unpushed
- * model already fails with `server_execute_unknown_model` — so a typo in
- * `lineitem.update` is a rejected mint rather than a credential that looks
- * healthy and is denied on its first write. Without this the `model` half is a
- * hole: an opaque string nothing validates until enforcement time.
- */
-export function unresolvableOperations(operations, aliases) {
-    // The model half holds no dot (see `grantedOperationSchema`), so the first
-    // separator is the only one.
-    return operations.filter((op) => !aliases.has(op.slice(0, op.indexOf('.'))));
-}
-/**
- * Serializes a declared `can` into the wire allowlist — the ONE translation
- * from what a developer writes to what the server stores and enforces.
- *
- * `wireNames` comes from {@link modelWireNames} over the client's own schema.
- * It is required rather than optional: an omitted map silently mints the schema
- * key verbatim, which is right for most models and wrong for every model with
- * a type-name override — the kind of default that is correct until it isn't.
- */
-export function grantedOperations(can, wireNames) {
-    const declared = Object.entries(can).flatMap(([model, ops]) => {
-        const wireName = (wireNames[model] ?? model).toLowerCase();
-        return (ops ?? []).map((op) => `${wireName}.${op}`);
-    });
-    return expandReadYourWrites(declared);
-}
-/**
- * The grant at rest: what the credential ended up with, on both axes, plus the
- * participant it acts as. The mint echoes this block, the key row stores it,
- * and the gates read it — so a session's reported scope and its enforced scope
- * are the same shape by construction.
- */
-export const capabilityScopeSchema = z.object({
-    organizationId: z.string().min(1),
-    /**
-     * The ROW axis — which sync groups this credential may act within. Read back
-     * as plain strings rather than the branded form the request enforces: this is
-     * what the key row already holds, including rows minted before that gate.
-     */
-    syncGroups: z.array(z.string()),
-    /** The VERB axis — the allowlist as minted, after read-your-writes. */
-    operations: z.array(grantedOperationSchema),
-    participantKind: participantKindSchema,
-    participantId: z.string().min(1),
-});
-/**
- * `POST /v1/capabilities` — mint a capability for a participant.
- *
- * Where an ephemeral key is a session for a person, a capability is a scoped,
- * revocable grant for an agent or a system. Narrow by default: an agent or
- * system capability must name its `operations` unless the caller explicitly
- * asks for `wideScope`, which is itself privileged.
- *
- * This is the parsed body — the mint route validates against it rather than
- * reading fields one at a time, so the shape and the validation rules cannot
- * drift from each other or from the published contract.
- */
-export const capabilityRequestSchema = z.object({
-    participantKind: participantKindSchema,
-    participantId: z.string().min(1).optional(),
-    /**
-     * The ROW axis. Validated as the engine's branded sync-group form
-     * (`default` or `<namespace>:<id>`): a malformed group stored on the key row
-     * would subscribe the connection to NOTHING and fail silently at fan-out
-     * time, so it is rejected loudly at the boundary.
-     */
-    syncGroups: z.array(syncGroupInputSchema).readonly().optional(),
-    /** The VERB axis, as `model.verb` — e.g. `tasks.update`. */
-    operations: z.array(grantedOperationSchema).readonly().optional(),
-    ttlSeconds: z.number().int().positive(),
-    label: z.string().min(1).optional(),
-    /**
-     * Opt out of narrow-by-default scoping. Without it, agent and system
-     * capabilities require non-empty `operations`; with it, the caller must
-     * additionally hold an admin/owner role or present a secret key.
-     */
-    wideScope: z.boolean().optional(),
-    /**
-     * Caller-attested identity for the end user this capability acts for — the
-     * on-behalf-of pattern. Ablo does not validate it and has no view into the
-     * caller's user directory; the API key is what is trusted, and this blob is
-     * echoed back to the client.
-     */
-    userMeta: z.record(z.string(), z.unknown()).optional(),
-});

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

@@ -1,61 +0,0 @@
-/**
- * Support for the endpoint-string form of `apiKey`.
- *
- * With `Ablo({ schema, apiKey: '/api/ablo-session' })`, you point the client at
- * your own session-mint route and the client owns the exchange: it POSTs to the
- * endpoint, parses the minted token, keeps it fresh, and classifies failures
- * onto the resolver's three outcomes. The string form covers the common case;
- * the function form of `apiKey` remains the escape hatch for custom headers,
- * bodies, or non-HTTP mints.
- *
- * The form is detected by prefix: a string starting with `/`, `http://`, or
- * `https://` is an endpoint, and anything else is a literal key. Ablo keys are
- * prefixed (`sk_`/`pk_`/`ek_`/`rk_`), so the two shapes cannot collide. An
- * `ABLO_API_KEY` environment value is never treated as an endpoint — it is
- * always a literal key (see `resolveApiKey`).
- *
- * Wire contract:
- *   POST <endpoint>  (same-origin, `credentials: 'include'` so cookies flow)
- *   → 200 `{ token, expiresAt? }`       a fresh short-lived `ek_`/`rk_`
- *   → 200 `{ token: null }` or 401/403  the login itself is gone (sign out)
- *   → anything else                     transient — retry, do not sign out
- *
- * The three-way mapping is the reason to build this in. Hand-written token
- * fetchers routinely get it wrong — mapping any non-OK response to `null` signs
- * the user out on a 500. Encoded here once, every consumer inherits the correct
- * split between a terminal sign-out and a transient retry.
- */
-/**
- * An async callable that resolves the current credential. It serves two uses:
- * credential rotation (for example against AWS STS, GCP IAM, or Vault) and the
- * short-lived per-user browser path (minting a fresh `ek_`/`rk_` from the
- * signed-in session). It is re-exported from `./auth` so existing import paths
- * keep working, and defined here so the resolver it types has no import cycle.
- *
- * The contract has three outcomes: resolve a token; resolve `null` when the
- * login itself is gone (terminal — the credential lifecycle treats this as
- * `session_expired` and signs out); or throw on a transient failure (back off
- * and retry, without signing out). A long-lived static `apiKey` string needs
- * none of this and is used as-is.
- */
-export type ApiKeySetter = () => Promise<string | null>;
-/**
- * Is this `apiKey` string a session-mint endpoint rather than a literal key?
- * Prefix rule: `/relative/path`, `http://…`, or `https://…`.
- */
-export declare function isCredentialEndpoint(value: string): boolean;
-/**
- * Builds the resolver behind an endpoint-string `apiKey`. It follows the
- * {@link ApiKeySetter} contract end to end:
- *   - resolves the minted token string on success;
- *   - resolves `null` when the login is gone (a 401 or 403, or an explicit
- *     `{ token: null }`) — terminal, so the client signs out;
- *   - throws on anything transient (a network failure, a 5xx or 429, or a
- *     malformed response) — so the lifecycle backs off and retries without
- *     signing out.
- *
- * A relative endpoint invoked on a server (where `fetch` has no origin) throws,
- * which is transient by contract; the credential lifecycle translates that exact
- * failure into an actionable "use an absolute URL server-side" warning.
- */
-export declare function createEndpointCredentialResolver(endpoint: string): ApiKeySetter;

package/dist/transaction/auth/credentialEndpoint.js

@@ -1,86 +0,0 @@
-/**
- * Support for the endpoint-string form of `apiKey`.
- *
- * With `Ablo({ schema, apiKey: '/api/ablo-session' })`, you point the client at
- * your own session-mint route and the client owns the exchange: it POSTs to the
- * endpoint, parses the minted token, keeps it fresh, and classifies failures
- * onto the resolver's three outcomes. The string form covers the common case;
- * the function form of `apiKey` remains the escape hatch for custom headers,
- * bodies, or non-HTTP mints.
- *
- * The form is detected by prefix: a string starting with `/`, `http://`, or
- * `https://` is an endpoint, and anything else is a literal key. Ablo keys are
- * prefixed (`sk_`/`pk_`/`ek_`/`rk_`), so the two shapes cannot collide. An
- * `ABLO_API_KEY` environment value is never treated as an endpoint — it is
- * always a literal key (see `resolveApiKey`).
- *
- * Wire contract:
- *   POST <endpoint>  (same-origin, `credentials: 'include'` so cookies flow)
- *   → 200 `{ token, expiresAt? }`       a fresh short-lived `ek_`/`rk_`
- *   → 200 `{ token: null }` or 401/403  the login itself is gone (sign out)
- *   → anything else                     transient — retry, do not sign out
- *
- * The three-way mapping is the reason to build this in. Hand-written token
- * fetchers routinely get it wrong — mapping any non-OK response to `null` signs
- * the user out on a 500. Encoded here once, every consumer inherits the correct
- * split between a terminal sign-out and a transient retry.
- */
-/**
- * Is this `apiKey` string a session-mint endpoint rather than a literal key?
- * Prefix rule: `/relative/path`, `http://…`, or `https://…`.
- */
-export function isCredentialEndpoint(value) {
-    return value.startsWith('/') || /^https?:\/\//i.test(value);
-}
-/**
- * Builds the resolver behind an endpoint-string `apiKey`. It follows the
- * {@link ApiKeySetter} contract end to end:
- *   - resolves the minted token string on success;
- *   - resolves `null` when the login is gone (a 401 or 403, or an explicit
- *     `{ token: null }`) — terminal, so the client signs out;
- *   - throws on anything transient (a network failure, a 5xx or 429, or a
- *     malformed response) — so the lifecycle backs off and retries without
- *     signing out.
- *
- * A relative endpoint invoked on a server (where `fetch` has no origin) throws,
- * which is transient by contract; the credential lifecycle translates that exact
- * failure into an actionable "use an absolute URL server-side" warning.
- */
-export function createEndpointCredentialResolver(endpoint) {
-    return async () => {
-        // `fetch()` rejections (offline, DNS, a relative URL on a server) propagate
-        // as-is: a throw is the transient signal in the resolver contract.
-        const res = await fetch(endpoint, {
-            method: 'POST',
-            credentials: 'include',
-        });
-        // The login itself is gone — terminal. Only these two statuses sign out.
-        if (res.status === 401 || res.status === 403)
-            return null;
-        // 5xx / 429 / anything unexpected: the login may be perfectly valid —
-        // transient, retry later.
-        if (!res.ok) {
-            throw new Error(`credential endpoint ${endpoint} answered ${res.status} — transient, will retry`);
-        }
-        let body;
-        try {
-            body = await res.json();
-        }
-        catch {
-            throw new Error(`credential endpoint ${endpoint} returned non-JSON — expected { token }`);
-        }
-        // Distinguish "explicitly signed out" (`{ token: null }`) from "not a mint
-        // endpoint at all" (no `token` key). A misconfiguration must fail loudly and
-        // transiently, never as a silent sign-out.
-        if (typeof body !== 'object' || body === null || !('token' in body)) {
-            throw new Error(`credential endpoint ${endpoint} returned no \`token\` field — expected { token }`);
-        }
-        const token = body.token;
-        if (token === null || token === undefined)
-            return null;
-        if (typeof token !== 'string') {
-            throw new Error(`credential endpoint ${endpoint} returned a non-string \`token\``);
-        }
-        return token;
-    };
-}

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

@@ -1,148 +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 type { exchangeApiKey, mintUserSessionKey, resolveIdentity } from './index.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 | (() => Promise<string | null>) | 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 type CredentialKind = 'secret' | 'ephemeral' | 'restricted' | '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 declare function classifyCredentialKind(value: string): CredentialKind | null;
-/**
- * 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 | (() => Promise<string | null>) | 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 | (() => Promise<string | null>);
-}
-/** 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>;
-export {};