@abloatai/ablo 0.34.1 → 0.35.0

package/dist/transaction/auth/capability.js

@@ -0,0 +1,199 @@
+/**
+ * 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/{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);

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;