@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transaction/ablo.js

@@ -0,0 +1,33 @@
+/**
+ * `Ablo` — the entry point to the coordination layer.
+ *
+ * The factory constructs the stateless client: typed model resources, commits,
+ * claims, and session minting over request/response HTTP. It holds no socket,
+ * no store, and no local copy of anything — the bearer credential is the
+ * identity and the server resolves it on every request. This is the client a
+ * server-side actor installs: an agent, a worker, a cron job, a route handler.
+ *
+ * ```ts
+ * import { Ablo } from '@abloatai/ablo';
+ * import { schema } from './schema';
+ *
+ * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+ * await ablo.tasks.update({ id: taskId, data: { status: 'done' } });
+ * ```
+ *
+ * The reactive materialiser — local store, live queries, presence rendering —
+ * is the consumer package's entry point (`@abloatai/ablo`), which layers
+ * above this one and shares the same `ablo.<model>` surface (ADR 0016).
+ */
+import { createAbloHttpClient, } from './transport/httpClient.js';
+/**
+ * Create a coordination-layer client in one call.
+ *
+ * The core carries one transport today — request/response HTTP — so
+ * `transport: 'http'` is accepted for symmetry with the reactive package's
+ * factory and may be omitted. The duplex transport joins this slot when the
+ * socket carve lands (ADR 0016, follow-up 3a).
+ */
+export function Ablo(options) {
+    return createAbloHttpClient(options);
+}

package/dist/{client/auth.d.ts → transaction/auth/apiKey.d.ts}

@@ -11,6 +11,7 @@
  * override is an explicit option, so an app never picks up hidden behavior from
  * a stray environment variable.
  */
+import type { KeyEnvironment } from '../environment.js';
 /**
  * The credential-resolver callable type. It is defined alongside
  * {@link createEndpointCredentialResolver} in `./credentialEndpoint` and
@@ -19,19 +20,31 @@
  */
 import type { ApiKeySetter } from './credentialEndpoint.js';
 export type { ApiKeySetter };
+/**
+ * The client options that decide a credential.
+ *
+ * This is the ONE declaration of that set. The resolvers below read it, and the
+ * transport configs that accept these options derive from it rather than listing
+ * the fields again — a second list is how `authEndpoint` came to be supported at
+ * runtime, named in an error message, and absent from the type a caller writes
+ * against.
+ */
+export interface AuthClientOptions {
+    readonly apiKey?: string | ApiKeySetter | null;
+    /** A route that mints the token, instead of a key the process holds. */
+    readonly authEndpoint?: string | ApiKeySetter | null;
+    /** A token the caller already has, used as-is. */
+    readonly authToken?: string | null;
+    readonly baseURL?: string | null;
+    readonly dangerouslyAllowBrowser?: boolean;
+}
 export interface AuthResolveInput {
     /**
      * The full set of options the caller passed to the client constructor. Each
      * resolver reads only the fields it needs; passing the whole object avoids
      * threading many separate parameters through every helper.
      */
-    readonly options: {
-        readonly apiKey?: string | ApiKeySetter | null;
-        readonly authEndpoint?: string | ApiKeySetter | null;
-        readonly authToken?: string | null;
-        readonly baseURL?: string | null;
-        readonly dangerouslyAllowBrowser?: boolean;
-    };
+    readonly options: AuthClientOptions;
     readonly env: Record<string, string | undefined>;
 }
 /**
@@ -41,8 +54,30 @@ export interface AuthResolveInput {
  */
 export declare function readProcessEnv(): Record<string, string | undefined>;
 export declare function resolveApiKey(input: AuthResolveInput): string | ApiKeySetter | null;
+/**
+ * Narrow a resolved `apiKey` to the single resolver the credential lifecycle
+ * needs: an async `() => token | null`, or `null` when auth is static — a plain
+ * long-lived key string with no refresh, which is the common case.
+ *
+ * The short-lived per-user browser path passes a function `apiKey` (an
+ * {@link ApiKeySetter}), and the SDK then drives the whole credential lifecycle
+ * from it: mint-before-connect, the proactive refresh timer with its
+ * wake/online/focus re-mint, and the reactive `credential_stale` re-mint. The
+ * resolver follows the `ApiKeySetter` contract end to end: resolve a token,
+ * resolve `null` when the login is gone (terminal — surfaces `session_expired`
+ * and signs the user out), or throw on a transient failure (backs off, without
+ * signing out).
+ */
+export declare function resolveCredentialResolver(apiKey: string | ApiKeySetter | null): (() => Promise<string | null>) | null;
 export declare function resolveAuthToken(input: AuthResolveInput): string | null;
-type CliMode = 'sandbox' | 'production';
+/**
+ * The credential axis, not a second copy of it. `environment.ts` documents two
+ * incidents caused by conflating the plane a request runs on with the mode a
+ * credential was minted in, and states the credential axis must not grow when
+ * planes do — so the CLI mismatch path reads the canonical vocabulary rather
+ * than restating its members here.
+ */
+type CliMode = KeyEnvironment;
 type StaticApiKeySource = 'option' | 'env';
 interface StaticApiKey {
     readonly key: string;

package/dist/{client/auth.js → transaction/auth/apiKey.js}

@@ -56,6 +56,25 @@ export function resolveApiKey(input) {
     }
     return configured ?? input.env.ABLO_API_KEY ?? null;
 }
+/**
+ * Narrow a resolved `apiKey` to the single resolver the credential lifecycle
+ * needs: an async `() => token | null`, or `null` when auth is static — a plain
+ * long-lived key string with no refresh, which is the common case.
+ *
+ * The short-lived per-user browser path passes a function `apiKey` (an
+ * {@link ApiKeySetter}), and the SDK then drives the whole credential lifecycle
+ * from it: mint-before-connect, the proactive refresh timer with its
+ * wake/online/focus re-mint, and the reactive `credential_stale` re-mint. The
+ * resolver follows the `ApiKeySetter` contract end to end: resolve a token,
+ * resolve `null` when the login is gone (terminal — surfaces `session_expired`
+ * and signs the user out), or throw on a transient failure (backs off, without
+ * signing out).
+ */
+export function resolveCredentialResolver(apiKey) {
+    if (typeof apiKey === 'function')
+        return apiKey;
+    return null;
+}
 export function resolveAuthToken(input) {
     return input.options.authToken ?? null;
 }

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

@@ -0,0 +1,15 @@
+/**
+ * The hand-off the identity flow performs once a credential resolves: it names
+ * the account scope and the sync groups everything downstream should read under.
+ *
+ * The core defines the port; the consumer supplies the implementation. That
+ * keeps identity resolution — which is settlement's business — from depending on
+ * whatever happens to materialise rows on the other side of it (ADR 0016). The
+ * reactive engine's `BootstrapFetcher` satisfies this structurally.
+ */
+export interface BootstrapScope {
+    /** Bind subsequent reads to one account's cache partition. */
+    setCacheScope(cacheScope: string): void;
+    /** Narrow subsequent reads to the sync groups the credential authorises. */
+    setSyncGroups(syncGroups: readonly string[] | undefined): void;
+}

package/dist/transaction/auth/bootstrapScope.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,212 @@
+/**
+ * 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>;
+/**
+ * What `POST /v1/capabilities` answers with — **201**, the credential is minted.
+ *
+ * This is the first call any non-TypeScript client makes, and until it had a
+ * schema the published contract described it as `{ type: 'object' }`: a caller
+ * working from the reference could see that a capability could be minted and
+ * not where the token was in the reply.
+ *
+ * `scope` echoes what was MINTED, not what was asked. A `wideScope` mint stores
+ * the org-wide default and read-your-writes widens the verb axis, so a client
+ * that assumed its request came back verbatim would report a scope narrower
+ * than the one being enforced.
+ *
+ * `userMeta` is the caller's own blob, echoed. Ablo has no view into their user
+ * directory — the API key is what is trusted — so this is deliberately open.
+ */
+export declare const capabilityMintResponseSchema: z.ZodObject<{
+    capabilityId: z.ZodString;
+    token: z.ZodString;
+    expiresAt: z.ZodString;
+    organizationId: z.ZodString;
+    scope: 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>;
+    userMeta: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type CapabilityMintResponse = z.infer<typeof capabilityMintResponseSchema>;
+/**
+ * `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

@@ -0,0 +1,224 @@
+/**
+ * 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),
+});
+/**
+ * What `POST /v1/capabilities` answers with — **201**, the credential is minted.
+ *
+ * This is the first call any non-TypeScript client makes, and until it had a
+ * schema the published contract described it as `{ type: 'object' }`: a caller
+ * working from the reference could see that a capability could be minted and
+ * not where the token was in the reply.
+ *
+ * `scope` echoes what was MINTED, not what was asked. A `wideScope` mint stores
+ * the org-wide default and read-your-writes widens the verb axis, so a client
+ * that assumed its request came back verbatim would report a scope narrower
+ * than the one being enforced.
+ *
+ * `userMeta` is the caller's own blob, echoed. Ablo has no view into their user
+ * directory — the API key is what is trusted — so this is deliberately open.
+ */
+export const capabilityMintResponseSchema = z.object({
+    capabilityId: z.string().min(1),
+    token: z.string().min(1),
+    /** ISO 8601. */
+    expiresAt: z.string().min(1),
+    organizationId: z.string().min(1),
+    scope: capabilityScopeSchema,
+    userMeta: z.record(z.string(), z.unknown()),
+});
+/**
+ * `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/{auth → transaction/auth}/credentialSource.d.ts

@@ -9,7 +9,14 @@
  */
 export { WS_BEARER_SUBPROTOCOL_PREFIX, WS_SYNC_SUBPROTOCOL } from '../wire/protocol.js';
 export interface AuthCredentialSource {
-    getAuthToken(): string | null;
+    /**
+     * 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>;

package/dist/{client → transaction/auth}/identity.d.ts

@@ -14,11 +14,12 @@
  *
  * 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 { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
-import type { SyncLogger } from '../interfaces/index.js';
+import type { BootstrapScope } from '../auth/bootstrapScope.js';
+import type { Logger } from '../logger.js';
 import type { AuthCredentialSource } from '../auth/credentialSource.js';
-import type { ApiKeySetter } from './auth.js';
+import type { ApiKeySetter } from './apiKey.js';
 export interface IdentityResolveInput {
     readonly options: {
         readonly capabilityToken?: string;
@@ -34,12 +35,12 @@ export interface IdentityResolveInput {
         readonly organizationId?: string;
     };
     readonly url: string;
-    readonly kind: 'user' | 'agent' | 'system';
+    readonly kind: ParticipantKind;
     readonly configuredApiKey: string | ApiKeySetter | null;
     readonly configuredAuthToken: string | null;
-    readonly bootstrapHelper: BootstrapFetcher;
+    readonly bootstrapHelper: BootstrapScope;
     readonly auth: AuthCredentialSource;
-    readonly logger: SyncLogger;
+    readonly logger: Logger;
 }
 export interface ResolvedIdentity {
     readonly userId: string;
@@ -47,7 +48,7 @@ export interface ResolvedIdentity {
     readonly teamIds: string[] | undefined;
     readonly capabilityToken: string | undefined;
     readonly syncGroups: readonly string[] | undefined;
-    readonly participantKind: 'user' | 'agent' | 'system';
+    readonly participantKind: ParticipantKind;
     /** Set only on the hosted-cloud path; the caller keeps it to stop refreshes on shutdown. */
     readonly refreshScheduler: RefreshScheduler | null;
 }

package/dist/{client → transaction/auth}/identity.js

@@ -20,7 +20,7 @@ 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 './auth.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);