@abloatai/ablo 0.34.1 → 0.36.0

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

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

package/dist/transaction/auth/index.js

@@ -0,0 +1,304 @@
+/**
+ * Exchanges an API key for a capability token and the scope it grants.
+ *
+ * The `Ablo({...})` factory calls this during startup when you provide an
+ * `apiKey` but no explicit capability token, organization, or user identity. It
+ * sends one `POST /auth/capability` request; the server responds with the
+ * granted scope and any user metadata, which the client uses to populate its
+ * session state. The API key is the only credential you handle directly — this
+ * exchange happens automatically behind it.
+ */
+import { parseCapabilityExchangeResponse, parseEphemeralKeyResponse, parseIdentityResolveResponse, } from './schemas.js';
+import { AbloAuthenticationError, hasWireCode, translateHttpError } from '../errors.js';
+// The capability vocabulary — what a grant is, on both axes, in one place.
+// Served from this barrel so every minter reaches it through one import.
+export { capabilityOperationSchema, capabilityCanSchema, capabilityScopeSchema, capabilityRequestSchema, grantedOperationSchema, grantedOperations, expandReadYourWrites, modelWireNames, capabilityModelAliases, unresolvableOperations, } from './capability.js';
+export async function exchangeApiKey(options) {
+    if (!options.apiKey) {
+        throw new AbloAuthenticationError('No API key found. Set ABLO_API_KEY in your environment — `npx ablo login` ' +
+            'then `npx ablo dev` writes it into .env.local for you — or pass ' +
+            '`apiKey` to Ablo({ ... }) directly.', { code: 'apikey_missing' });
+    }
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for capability exchange', { code: 'base_url_missing' });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/capability`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${options.apiKey}`,
+            },
+            body: JSON.stringify({
+                participantKind: options.participantKind,
+                ...(options.participantId ? { participantId: options.participantId } : {}),
+                syncGroups: options.syncGroups,
+                operations: options.operations,
+                wideScope: options.wideScope,
+                ttlSeconds: options.ttlSeconds,
+                label: options.label,
+                userMeta: options.userMeta,
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`apiKey exchange failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'exchange_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore — server returned non-JSON error
+        }
+        // Route the error through the wire-error translator so the server's envelope
+        // (`code`, `message`, `doc_url`) is preserved and mapped to the matching
+        // AbloError subclass. Fall back to `exchange_failed` only when the body
+        // carried no recognizable error code.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`apiKey exchange rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
+    }
+    return parseCapabilityExchangeResponse(await response.json());
+}
+/**
+ * Mints an end-user session key (an `ek_` key) by calling
+ * `POST /auth/ephemeral-keys`, using your secret key as authorization. Your
+ * backend calls this to issue a session that a browser can present as its bearer
+ * credential; the server trusts the resulting key because a secret key minted it.
+ *
+ * This is a distinct endpoint from `/auth/capability`, which exchanges keys for
+ * agents and systems and cannot mint sessions for human users.
+ */
+export async function mintUserSessionKey(options) {
+    if (!options.apiKey) {
+        throw new AbloAuthenticationError('No API key found. Set ABLO_API_KEY in your environment or pass `apiKey` ' +
+            'to Ablo({ ... }) directly — user sessions are minted by your backend.', { code: 'apikey_missing' });
+    }
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for user-session mint', { code: 'base_url_missing' });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/ephemeral-keys`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
+    let response;
+    try {
+        response = await fetcher(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${options.apiKey}`,
+            },
+            body: JSON.stringify({
+                user: { id: options.userId },
+                ...(options.organizationId ? { organizationId: options.organizationId } : {}),
+                // The public option is project-centric; map it to the flat wire keys the
+                // endpoint expects.
+                ...(options.schemaProject
+                    ? {
+                        schemaProjectId: options.schemaProject.projectId,
+                        schemaOwnerOrgId: options.schemaProject.organizationId,
+                    }
+                    : {}),
+                ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
+                ttlSeconds: options.ttlSeconds,
+                ...(options.label ? { label: options.label } : {}),
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`user-session mint failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'exchange_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore — server returned non-JSON error
+        }
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`user-session mint rejected (${response.status})`, { code: 'exchange_failed', httpStatus: response.status });
+    }
+    return parseEphemeralKeyResponse(await response.json());
+}
+/**
+ * Resolves the caller's identity from an authenticated request by calling
+ * `GET /auth/identity`. This lets browser and session flows learn who the
+ * current user is without requiring the application to pass a user id up front —
+ * for example, to key local storage.
+ */
+export async function resolveIdentity(options) {
+    if (!options.baseUrl) {
+        throw new AbloAuthenticationError('baseUrl is required for identity resolve', {
+            code: 'base_url_missing',
+        });
+    }
+    const fetcher = options.fetch ?? fetch;
+    const url = `${options.baseUrl.replace(/\/+$/, '')}/auth/identity`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => { controller.abort(); }, timeoutMs);
+    let response;
+    try {
+        const headers = { Accept: 'application/json' };
+        if (options.authToken) {
+            headers.Authorization = `Bearer ${options.authToken}`;
+        }
+        response = await fetcher(url, {
+            method: 'GET',
+            headers,
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        throw new AbloAuthenticationError(`identity resolve failed: ${err instanceof Error ? err.message : String(err)}`, { code: 'identity_network_error', cause: err });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = null;
+        try {
+            body = await response.json();
+        }
+        catch {
+            // ignore non-JSON auth errors
+        }
+        // Translate the error envelope the same way `exchangeApiKey` does, so the
+        // server's precise auth diagnosis (for example `jwt_issuer_untrusted` with
+        // its full message) reaches the caller instead of collapsing every 401 to a
+        // generic `identity_resolve_failed`.
+        const requestId = response.headers.get('x-request-id') ?? undefined;
+        throw hasWireCode(body)
+            ? translateHttpError(response.status, body, requestId)
+            : new AbloAuthenticationError(`identity resolve rejected (${response.status})`, { code: 'identity_resolve_failed', httpStatus: response.status });
+    }
+    return parseIdentityResolveResponse(await response.json());
+}
+const DEFAULT_BUFFER_FLOOR_MS = 60_000;
+const DEFAULT_BUFFER_RATIO = 0.1;
+export function createRefreshScheduler(options) {
+    const now = options.now ?? Date.now;
+    const setTimer = options.setTimer ?? setTimeout;
+    const clearTimer = options.clearTimer ?? clearTimeout;
+    let expiresAtMs = options.initialExpiresAtMs;
+    let timer = null;
+    let inFlight = null;
+    let disposed = false;
+    // Attach the visibility listener only in a browser-like environment. A
+    // non-browser runtime has no `document`, so the default behaves correctly
+    // without an explicit opt-out.
+    const wantsVisibility = options.attachVisibilityListener ?? true;
+    const hasDocument = typeof document !== 'undefined';
+    const visibilityActive = wantsVisibility && hasDocument;
+    function bufferFor(currentExpiresAtMs) {
+        if (typeof options.bufferMs === 'number')
+            return options.bufferMs;
+        const ttl = currentExpiresAtMs - now();
+        return Math.max(DEFAULT_BUFFER_FLOOR_MS, Math.floor(ttl * DEFAULT_BUFFER_RATIO));
+    }
+    function clearTimerIfAny() {
+        if (timer !== null) {
+            clearTimer(timer);
+            timer = null;
+        }
+    }
+    function schedule() {
+        if (disposed)
+            return;
+        clearTimerIfAny();
+        const buffer = bufferFor(expiresAtMs);
+        const delay = Math.max(0, expiresAtMs - buffer - now());
+        timer = setTimer(() => {
+            void refreshNow().catch(() => {
+                // onError already fired inside refreshNow; swallow here so
+                // the timer callback doesn't surface as an unhandled rejection.
+            });
+        }, delay);
+    }
+    function refreshNow() {
+        if (disposed) {
+            return Promise.reject(new Error('refreshScheduler: disposed'));
+        }
+        if (inFlight)
+            return inFlight;
+        inFlight = (async () => {
+            try {
+                const result = await options.refresh();
+                if (disposed)
+                    return result;
+                expiresAtMs = result.expiresAtMs;
+                options.onRefreshed?.({ expiresAtMs });
+                schedule();
+                return result;
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                options.onError?.(error);
+                // Reschedule even on failure so the next window still triggers.
+                // The user's apiKey may have been temporarily unreachable.
+                if (!disposed)
+                    schedule();
+                throw error;
+            }
+            finally {
+                inFlight = null;
+            }
+        })();
+        return inFlight;
+    }
+    function onVisibilityChange() {
+        if (disposed)
+            return;
+        if (typeof document === 'undefined')
+            return;
+        if (document.visibilityState !== 'visible')
+            return;
+        const buffer = bufferFor(expiresAtMs);
+        if (expiresAtMs - now() <= buffer) {
+            void refreshNow().catch(() => {
+                // already routed through onError
+            });
+        }
+    }
+    if (visibilityActive) {
+        document.addEventListener('visibilitychange', onVisibilityChange);
+    }
+    schedule();
+    return {
+        refreshNow,
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            clearTimerIfAny();
+            if (visibilityActive) {
+                document.removeEventListener('visibilitychange', onVisibilityChange);
+            }
+        },
+        get expiresAtMs() {
+            return expiresAtMs;
+        },
+    };
+}

package/dist/{auth → transaction/auth}/schemas.d.ts

@@ -8,7 +8,7 @@ export declare const CapabilityExchangeResponseSchema: z.ZodObject<{
     scope: z.ZodObject<{
         organizationId: z.ZodString;
         syncGroups: z.ZodArray<z.ZodString>;
-        operations: z.ZodArray<z.ZodString>;
+        operations: z.ZodArray<z.ZodTemplateLiteral<`${string}.update` | `${string}.create` | `${string}.delete` | `${string}.read`>>;
         participantKind: z.ZodEnum<{
             user: "user";
             agent: "agent";

package/dist/{auth → transaction/auth}/schemas.js

@@ -1,6 +1,12 @@
 import { z } from 'zod';
+import { participantKindSchema } from '../coordination/schema.js';
+import { capabilityScopeSchema } from './capability.js';
 import { AbloAuthenticationError } from '../errors.js';
-const AuthParticipantKindSchema = z.enum(['user', 'agent', 'system']);
+// Not a second enum. The auth responses carry the same participant vocabulary
+// the coordination plane parses, so they validate against the same schema — a
+// kind the delta plane accepts must not throw here on an otherwise-valid
+// identity-resolve response.
+const AuthParticipantKindSchema = participantKindSchema;
 export const AuthTokenSchema = z.string().trim().min(1);
 export const CapabilityExchangeResponseSchema = z
     .object({
@@ -8,18 +14,12 @@ export const CapabilityExchangeResponseSchema = z
     token: AuthTokenSchema,
     expiresAt: z.string().min(1),
     organizationId: z.string().min(1),
-    scope: z
-        .object({
-        organizationId: z.string().min(1),
-        syncGroups: z.array(z.string()),
-        operations: z.array(z.string()),
-        participantKind: AuthParticipantKindSchema,
-        participantId: z.string().min(1),
-    })
-        .passthrough(),
+    // The grant the mint settled on, in the one shape the key row stores and
+    // the gates read — not a second description of it.
+    scope: capabilityScopeSchema.loose(),
     userMeta: z.record(z.string(), z.unknown()),
 })
-    .passthrough();
+    .loose();
 export const IdentityResolveResponseSchema = z
     .object({
     participantKind: AuthParticipantKindSchema,
@@ -35,7 +35,7 @@ export const IdentityResolveResponseSchema = z
     syncGroups: z.array(z.string()),
     userMeta: z.record(z.string(), z.unknown()),
 })
-    .passthrough();
+    .loose();
 /**
  * The response shape of `POST /auth/ephemeral-keys`, the endpoint that mints an
  * end-user session key (an `ek_` key). The shape is flat, with no nested scope
@@ -53,7 +53,7 @@ export const EphemeralKeyResponseSchema = z
     participantId: z.string().min(1),
     syncGroups: z.array(z.string()),
 })
-    .passthrough();
+    .loose();
 function formatIssues(error) {
     return error.issues
         .map((issue) => {

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

@@ -1,5 +1,5 @@
 import type { SchemaRecord } from '../schema/schema.js';
-import type { AbloSession, CreateSessionParams } from './resourceTypes.js';
+import type { AbloSession, CreateSessionParams } from '../resources/httpResources.js';
 /**
  * The resolved control-plane details a mint needs: a secret key, a base URL,
  * and an optional `fetch`. When `fetch` is omitted, the auth helpers fall back
@@ -10,15 +10,15 @@ export interface MintSessionContext {
     readonly baseUrl: string;
     readonly fetch?: typeof fetch;
     /**
-     * Maps each schema key to its wire type name. Every public client supplies
-     * this; it stays optional only for isolated private-transport use. A
-     * capability is scoped by the lowercased type name the server checks, but
-     * `can` is keyed by schema key — so
+     * Each schema key mapped to its wire type name, from
+     * {@link modelWireNames} over the client's own schema. Required, and derived
+     * rather than assembled: `can` is keyed by schema key while a capability is
+     * scoped by the type name the server checks, so
      * `can: { documents: ['update'] }` on a model whose type name is overridden
-     * to `Document` must mint `document.update`, not `documents.update`, or the
-     * server denies the write with `capability_scope_denied`.
+     * to `Document` must mint `document.update`. A caller who leaves this out
+     * mints a grant the server denies on the first write.
      */
-    readonly modelTypenames?: Readonly<Record<string, string>>;
+    readonly modelTypenames: Readonly<Record<string, string>>;
 }
 /**
  * Mints a session token from an already-resolved secret key and base URL.

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

@@ -23,6 +23,7 @@
  * caller's responsibility.
  */
 import { exchangeApiKey, mintUserSessionKey } from '../auth/index.js';
+import { grantedOperations } from './capability.js';
 /**
  * Mints a session token from an already-resolved secret key and base URL.
  * Routes the `{ user }` or `{ agent }` request to the matching mint endpoint
@@ -58,13 +59,9 @@ export async function mintSession(params, ctx) {
             userMeta: params.userMeta ?? { id: res.participantId },
         };
     }
-    const operations = Object.entries(params.can).flatMap(([model, ops]) => {
-        // Translate the schema key the developer used in `can` into the wire type
-        // name the server checks — see `modelTypenames` above. The key fallback is
-        // private transport tolerance; every public client supplies the schema map.
-        const ns = ctx.modelTypenames?.[model] ?? model;
-        return (ops ?? []).map((op) => `${ns.toLowerCase()}.${op}`);
-    });
+    // One translation from the declared grant to the wire allowlist, shared with
+    // every other door that mints — see `auth/capability.ts`.
+    const operations = grantedOperations(params.can, ctx.modelTypenames);
     const res = await exchangeApiKey({
         apiKey,
         baseUrl,

package/dist/transaction/coordination/awaitClaimGrant.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Waits for a queued claim to reach the head of the line — the client side of
+ * the fair-queue handover. When a claim is contended, the server puts it in a
+ * queue and replies that it is queued (HTTP 202 on `/v1/claims`, or a
+ * `claim_queued` frame over the WebSocket). The grant is delivered later, when
+ * the claim reaches the head, as a `claim_granted` frame. This resolves once
+ * that frame arrives for the given `claimId`, so the caller's `claim` promise
+ * stays pending — event-driven, with no polling — until it is actually the
+ * caller's turn. It rejects if the claim is lost (`claim_lost`: taken away by a
+ * TTL lapse on disconnect, or revoked) or if an optional timeout elapses.
+ *
+ * It needs only a minimal `{ subscribe }` transport, so it can be tested
+ * against a fake; the duplex `WsTransport` satisfies it.
+ */
+import { type Logger } from '../logger.js';
+export interface GrantTransport {
+    subscribe(event: 'claim_acquired' | 'claim_granted' | 'claim_lost' | 'claim_queued' | 'claim_rejected', handler: (payload: Record<string, unknown>) => void): () => void;
+}
+export interface ClaimGrantInfo {
+    /**
+     * True when the grant arrived as `claim_granted` — the target was held when
+     * the caller asked, and the caller waited in the FIFO line behind the holder.
+     * False for the immediate `claim_acquired`, where the target was free.
+     *
+     * Callers read this to know the row may have changed while they queued. Claim
+     * visibility is scoped to the entity, so a broad, organization-wide
+     * subscription receives no presence or claim fan-out, and the local
+     * coordination snapshot cannot be trusted to tell whether the caller waited.
+     * The grant frame itself is the authoritative signal.
+     */
+    readonly waited: boolean;
+    /**
+     * The fencing token the server minted for this grant (Option B), read off the
+     * grant frame — the authoritative source, since the token is server-stamped.
+     * `undefined` when the server does not fence (no minter wired).
+     */
+    readonly fenceToken?: number;
+}
+export declare function awaitClaimGrant(transport: GrantTransport, claimId: string, options?: {
+    timeoutMs?: number;
+    /**
+     * Backpressure: reject instead of waiting if, when we join the line, the
+     * server reports `position >= maxQueueDepth` (i.e. that many claims are
+     * already ahead of us). Omit to wait however deep the queue is.
+     */
+    maxQueueDepth?: number;
+    /**
+     * Abort the wait from outside — the same signal that cancels everything
+     * else in the program. Rejects with `claim_wait_aborted`; once the grant
+     * has arrived the signal is ignored, so a held lease is never torn down
+     * by a late abort.
+     */
+    signal?: AbortSignal;
+    /** Where grant transitions are logged. Defaults to silent. */
+    logger?: Logger;
+}): Promise<ClaimGrantInfo>;