@abloatai/ablo 0.7.0 → 0.8.0

package/dist/errorCodes.js

@@ -36,7 +36,7 @@
  * code, a changed HTTP status, an envelope field. Emitted in `errors.json`
  * and on the `Ablo-Version` response header so a consumer can detect drift.
  */
-export const ERROR_CONTRACT_VERSION = '2026-05-28';
+export const ERROR_CONTRACT_VERSION = '2026-05-29';
 const wire = (category, httpStatus, retryable, message) => ({ category, surface: 'wire', httpStatus, retryable, message });
 const client = (category, message) => ({ category, surface: 'client', retryable: false, message });
 /**
@@ -53,11 +53,30 @@ export const ERROR_CODES = {
     capability_id_missing: wire('auth', 401, false, 'A capability id was expected but not provided.'),
     exchange_failed: wire('auth', 401, false, 'The API-key credential exchange was rejected.'),
     identity_resolve_failed: wire('auth', 401, false, 'Identity resolution was rejected.'),
+    auth_no_credentials: wire('auth', 401, false, 'No recognized authentication credential was presented — no API key and no bearer JWT. Send `Authorization: Bearer <token>`.'),
+    identity_missing_organization: wire('auth', 401, false, 'Authentication succeeded but resolved to no organization context.'),
     session_expired: wire('auth', 401, false, 'The session is invalid or expired; re-authenticate.'),
+    // `jwt_invalid` is the residual fallback; the codes below split out the
+    // specific failure modes so an integrating customer can tell "I registered
+    // the wrong JWKS" from "my token has no org claim" from "wrong audience"
+    // rather than getting one opaque code for all of them.
+    jwt_invalid: wire('auth', 401, false, 'The bearer JWT could not be validated (unclassified).'),
+    jwt_malformed: wire('auth', 401, false, 'The bearer JWT is not a well-formed JWT and could not be decoded.'),
+    jwt_missing_issuer: wire('auth', 401, false, 'The bearer JWT has no `iss` (issuer) claim, so it cannot be routed to a trusted issuer.'),
+    jwt_issuer_untrusted: wire('auth', 401, false, "The bearer JWT's `iss` is not a registered trusted issuer. Register it via POST /v1/trusted-issuers, or check the token's issuer claim."),
+    jwt_signature_invalid: wire('auth', 401, false, "The bearer JWT's signature could not be verified against the issuer's JWKS (wrong key, rotated key, or forged token)."),
+    jwt_audience_mismatch: wire('auth', 401, false, "The bearer JWT's `aud` (audience) claim does not match the audience this issuer is registered with."),
+    jwt_missing_subject: wire('auth', 401, false, 'The bearer JWT has no `sub` (subject) claim to identify the user.'),
+    jwt_missing_organization: wire('auth', 401, false, 'The bearer JWT carries no organization context — neither a fixed org for the issuer nor the configured organization claim.'),
+    jwt_expired: wire('auth', 401, false, 'The bearer JWT has expired; obtain a fresh token.'),
+    jwt_org_membership_denied: wire('auth', 403, false, "The bearer JWT's subject is not an active member of the organization in its `org_id` claim (removed, suspended, or the claim does not match a membership)."),
     file_upload_auth_required: wire('auth', 401, false, 'File upload requires an authenticated session.'),
     browser_apikey_blocked: client('auth', 'Raw API keys must not be used from a browser context.'),
+    browser_database_url_blocked: client('auth', 'A database connection string must not be used from a browser context — it carries DB credentials.'),
+    datasource_registration_failed: client('auth', 'Failed to register the provided databaseUrl as this project data source.'),
     // ── permission / capability (403) ──────────────────────────────────
     capability_scope_denied: wire('capability', 403, false, "The connection's resolved scope does not cover the attempted action."),
+    issuer_register_forbidden: wire('permission', 403, false, 'Registering a trusted issuer requires a secret (sk_) API key.'),
     capability_invalid: wire('capability', 403, false, 'The capability is unknown, revoked, or expired.'),
     byo_role_cannot_enforce_rls: wire('permission', 403, false, 'The bring-your-own DB role cannot enforce row-level security.'),
     byo_role_unreadable: wire('permission', 403, false, 'The bring-your-own DB role could not be introspected.'),
@@ -80,6 +99,7 @@ export const ERROR_CODES = {
     commit_operation_required: wire('validation', 400, false, 'A commit must carry `operation` or `operations`.'),
     commit_operation_model_required: wire('validation', 400, false, 'A commit operation is missing its `model`.'),
     commit_operations_ambiguous: wire('validation', 400, false, 'A commit supplied both `operation` and `operations`.'),
+    commit_too_many_operations: wire('validation', 400, false, 'A commit exceeded the per-commit operation limit; split it into smaller batches.'),
     model_required_field_missing: wire('validation', 400, false, 'A required field was absent from the model payload.'),
     model_identifier_missing: wire('validation', 400, false, 'The model payload is missing its identifier.'),
     snapshot_reserved_key: wire('validation', 400, false, 'A snapshot used a reserved key name.'),
@@ -92,6 +112,18 @@ export const ERROR_CODES = {
     model_not_found: wire('not_found', 404, false, 'The referenced model row does not exist.'),
     mutate_update_entity_not_found: wire('not_found', 404, false, 'The entity targeted by an update does not exist.'),
     task_id_missing: wire('server', 502, true, 'The task-create response did not include an id.'),
+    // ── data integrity / DB constraints ────────────────────────────────
+    // Emitted when a write is rejected by a database integrity constraint
+    // (Postgres class-23). All NON-retryable: the same payload re-sent
+    // unchanged will fail identically, so the client must roll back, not
+    // retry. The server normalizer maps SQLSTATE → these codes and tucks the
+    // raw constraint/column/table detail into `details` rather than leaking
+    // the driver's message text onto the wire.
+    not_null_violation: wire('validation', 400, false, 'A required field was missing (database not-null constraint).'),
+    foreign_key_violation: wire('conflict', 409, false, 'A referenced entity does not exist, or is still referenced (database foreign-key constraint).'),
+    unique_violation: wire('conflict', 409, false, 'A value violates a uniqueness constraint.'),
+    check_violation: wire('validation', 400, false, 'A value violates a database check constraint.'),
+    constraint_violation: wire('validation', 400, false, 'A database integrity constraint was violated.'),
     // ── tenant / unknown model (400) ───────────────────────────────────
     server_execute_unknown_model: wire('tenant', 400, false, 'The server-execute request named a model not in the tenant schema.'),
     mutate_create_unknown_model: wire('tenant', 400, false, 'A create targeted a model not in the tenant schema.'),
@@ -152,6 +184,7 @@ export const ERROR_CODES = {
     turn_open_failed: wire('server', 500, true, 'The agent turn failed to open.'),
     turn_close_failed: wire('server', 500, true, 'The agent turn failed to close cleanly.'),
     // ── client-only invariants (never serialized) ──────────────────────
+    invalid_options: client('client', 'The Ablo client was constructed with invalid or incomplete options.'),
     no_ablo_provider: client('client', 'An Ablo hook was used outside of an Ablo provider.'),
     no_sync_group_provider: client('client', 'A sync-group hook was used outside of its provider.'),
     sync_context_missing_provider: client('client', 'Sync context was read outside of its provider.'),

package/dist/errors.d.ts

@@ -272,11 +272,62 @@ export declare class SyncSessionError extends AbloAuthenticationError {
      */
     static isSessionErrorResponse(status: number, body?: string): boolean;
 }
+/**
+ * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
+ * that an SDK consumer never catches an untagged error. An already-typed
+ * AbloError passes through untouched (so `code`/`httpStatus`/subclass survive);
+ * a bare `Error` keeps its message and is preserved as `cause` (carrying any
+ * `.code` someone attached); a non-Error is stringified.
+ *
+ * This is the client mirror of the server's `normalizeError` — applied at the
+ * SDK's public async boundaries so `instanceof AbloError` / `e.type` always
+ * hold for whatever a consumer catches, regardless of which internal layer
+ * (transport, IndexedDB, bootstrap, a third-party throw) produced it.
+ */
+export declare function toAbloError(err: unknown): AbloError;
+/**
+ * Build the appropriate typed {@link AbloError} from a wire error — the
+ * single code→class mapping shared by every transport that can reject a
+ * request (HTTP responses via {@link translateHttpError}, WebSocket
+ * `mutation_result`/`claim_ack` frames, agent-job receipts).
+ *
+ * Code-first, then status-driven. A known {@link ErrorCode} carries its own
+ * canonical `httpStatus` in the registry, so frame transports that don't have
+ * an HTTP status (the WebSocket commit path) still produce the right subclass
+ * — instead of a hand-rolled `new Error(message)` that drops out of the typed
+ * hierarchy and loses `code`/`httpStatus`/retryability.
+ */
+export declare function errorFromWire(message: string, opts?: {
+    code?: string;
+    /** Explicit transport status (HTTP). When omitted, derived from the
+     *  registry spec for `code` so frame transports map correctly too. */
+    httpStatus?: number;
+    requestId?: string;
+    requiredCapability?: RequiredCapability;
+}): AbloError;
 /**
  * Translate an HTTP response into the appropriate typed error.
  *
  * Single source of truth for status-code → class mapping — every SDK
  * fetch path that sees a non-2xx response should route through here
- * so the customer-visible error is always the right subclass.
+ * so the customer-visible error is always the right subclass. Delegates
+ * the actual class selection to {@link errorFromWire} (shared with the
+ * frame transports) after extracting code/message from the HTTP body.
  */
 export declare function translateHttpError(status: number, body: unknown, requestId?: string): AbloError;
+/**
+ * Whether an HTTP error body carries a code {@link translateHttpError} can read
+ * — a top-level `code`, a nested `error.code`, or a string `error`. Callers that
+ * own a meaningful fallback code (e.g. `turn_open_failed`) use this to decide
+ * between routing through `translateHttpError` (structured envelope present) and
+ * throwing their own typed error with the fallback (bare/non-Ablo body), instead
+ * of emitting a code-less error.
+ */
+export declare function hasWireCode(body: unknown): boolean;
+/**
+ * Extract the canonical error `code` from a raw HTTP error body STRING — the
+ * top-level `code` or a nested `error.code`. Returns undefined for non-JSON or
+ * code-less bodies. Used by session-error detection to tell a genuine expiry
+ * (`session_expired`/`jwt_expired`) apart from other auth failures.
+ */
+export declare function extractWireCode(body?: string): string | undefined;

package/dist/errors.js

@@ -18,6 +18,7 @@
  *
  * Both work on every subclass.
  */
+import { errorCodeSpec } from './errorCodes.js';
 export { ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode } from './errorCodes.js';
 // ── AbloError hierarchy — the typed error surface ────────────────────
 /** Common shape for all errors thrown by this SDK. */
@@ -237,29 +238,106 @@ export class SyncSessionError extends AbloAuthenticationError {
      * Check if an HTTP response status indicates a session error
      */
     static isSessionErrorResponse(status, body) {
-        if (status === 401)
-            return true;
-        if (status === 403) {
-            if (body) {
-                const lowerBody = body.toLowerCase();
-                if (lowerBody.includes('session') ||
-                    lowerBody.includes('unauthorized') ||
-                    lowerBody.includes('not authenticated') ||
-                    lowerBody.includes('token')) {
-                    return true;
-                }
-            }
-            return true;
+        // Prefer the structured error code: ONLY a genuine session / JWT EXPIRY
+        // should drive sign-out + re-auth. A non-expiry auth failure
+        // (api_key_required, jwt_issuer_untrusted, a 403 permission denial, …) must
+        // NOT — re-authenticating re-mints the same credential and loops, which is
+        // exactly the "flash then bounce to /signin" symptom. This mirrors the
+        // canonical wire mapping (401 → Authentication, 403 → Permission).
+        const code = extractWireCode(body);
+        if (code) {
+            return code === 'session_expired' || code === 'jwt_expired';
         }
-        return false;
+        // No structured code (bare body, non-Ablo proxy response): a 401 is taken as
+        // expiry — the historical default that drives re-auth — while a 403 is a
+        // permission failure, not a session error.
+        return status === 401;
     }
 }
+/**
+ * Coerce ANY thrown value into an {@link AbloError} — the last-line guarantee
+ * that an SDK consumer never catches an untagged error. An already-typed
+ * AbloError passes through untouched (so `code`/`httpStatus`/subclass survive);
+ * a bare `Error` keeps its message and is preserved as `cause` (carrying any
+ * `.code` someone attached); a non-Error is stringified.
+ *
+ * This is the client mirror of the server's `normalizeError` — applied at the
+ * SDK's public async boundaries so `instanceof AbloError` / `e.type` always
+ * hold for whatever a consumer catches, regardless of which internal layer
+ * (transport, IndexedDB, bootstrap, a third-party throw) produced it.
+ */
+export function toAbloError(err) {
+    if (err instanceof AbloError)
+        return err;
+    if (err instanceof Error) {
+        const rawCode = err.code;
+        const code = typeof rawCode === 'string' ? rawCode : undefined;
+        return new AbloError(err.message, { code, cause: err });
+    }
+    return new AbloError(String(err), { cause: err });
+}
+/**
+ * Build the appropriate typed {@link AbloError} from a wire error — the
+ * single code→class mapping shared by every transport that can reject a
+ * request (HTTP responses via {@link translateHttpError}, WebSocket
+ * `mutation_result`/`claim_ack` frames, agent-job receipts).
+ *
+ * Code-first, then status-driven. A known {@link ErrorCode} carries its own
+ * canonical `httpStatus` in the registry, so frame transports that don't have
+ * an HTTP status (the WebSocket commit path) still produce the right subclass
+ * — instead of a hand-rolled `new Error(message)` that drops out of the typed
+ * hierarchy and loses `code`/`httpStatus`/retryability.
+ */
+export function errorFromWire(message, opts = {}) {
+    const { code, requestId, requiredCapability } = opts;
+    // Effective status: an explicit HTTP status wins; otherwise fall back to
+    // the code's canonical status from the registry (undefined for unknown /
+    // forward-compat codes, which then map to the base AbloError).
+    const httpStatus = opts.httpStatus ?? (code ? errorCodeSpec(code)?.httpStatus : undefined);
+    // Wire boundary: an incoming code is an arbitrary string (a newer server
+    // may send a code this SDK predates). Cast to ErrorCode here — the one
+    // sanctioned crossing — so internal producers stay statically checked.
+    const publicCode = (code === 'intent_conflict' ? 'claim_conflict' : code);
+    const baseOpts = { code: publicCode, httpStatus, requestId };
+    // ── Code-first specials (transport-independent) ──────────────────────
+    // A scoped credential was denied — route through CapabilityError so callers
+    // can read `.requiredCapability` to attenuate-and-retry.
+    if (code === 'capability_scope_denied' || code === 'capability_invalid') {
+        return new CapabilityError(code, message, requiredCapability);
+    }
+    // Claim enforcement (rides 409): the target entity is held by another
+    // participant. Discriminate on code BEFORE the generic 409→idempotency
+    // mapping so a claim rejection surfaces as AbloClaimedError.
+    if (code === 'intent_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
+        return new AbloClaimedError(message, baseOpts);
+    }
+    // A write whose `readAt` watermark went stale — callers re-read and retry.
+    if (code === 'stale_context') {
+        return new AbloStaleContextError(message, baseOpts);
+    }
+    // ── Status-driven dispatch (HTTP parity) ─────────────────────────────
+    if (httpStatus === 401)
+        return new AbloAuthenticationError(message, baseOpts);
+    if (httpStatus === 403)
+        return new AbloPermissionError(message, baseOpts);
+    if (httpStatus === 409)
+        return new AbloIdempotencyError(message, baseOpts);
+    if (httpStatus === 422 || httpStatus === 400)
+        return new AbloValidationError(message, baseOpts);
+    if (httpStatus === 429)
+        return new AbloRateLimitError(message, baseOpts);
+    if (httpStatus !== undefined && httpStatus >= 500)
+        return new AbloServerError(message, baseOpts);
+    return new AbloError(message, baseOpts);
+}
 /**
  * Translate an HTTP response into the appropriate typed error.
  *
  * Single source of truth for status-code → class mapping — every SDK
  * fetch path that sees a non-2xx response should route through here
- * so the customer-visible error is always the right subclass.
+ * so the customer-visible error is always the right subclass. Delegates
+ * the actual class selection to {@link errorFromWire} (shared with the
+ * frame transports) after extracting code/message from the HTTP body.
  */
 export function translateHttpError(status, body, requestId) {
     const parsed = typeof body === 'object' && body !== null ? body : {};
@@ -274,33 +352,53 @@ export function translateHttpError(status, body, requestId) {
         flatError ??
         (typeof body === 'string' ? body : `HTTP ${status}`);
     const requiredCapability = nested?.requiredCapability ?? parsed.requiredCapability;
-    // Wire boundary: an incoming code is an arbitrary string (a newer server
-    // may send a code this SDK predates). Cast to ErrorCode here — the one
-    // sanctioned crossing — so internal producers stay statically checked.
-    const publicCode = (code === 'intent_conflict' ? 'claim_conflict' : code);
-    const baseOpts = { code: publicCode, httpStatus: status, requestId };
-    if (status === 401)
-        return new AbloAuthenticationError(message, baseOpts);
-    if (status === 403 || code === 'capability_scope_denied' || code === 'capability_invalid') {
-        if (code === 'capability_scope_denied' || code === 'capability_invalid') {
-            return new CapabilityError(code, message, requiredCapability);
-        }
-        return new AbloPermissionError(message, baseOpts);
+    return errorFromWire(message, { code, httpStatus: status, requestId, requiredCapability });
+}
+/**
+ * Whether an HTTP error body carries a code {@link translateHttpError} can read
+ * — a top-level `code`, a nested `error.code`, or a string `error`. Callers that
+ * own a meaningful fallback code (e.g. `turn_open_failed`) use this to decide
+ * between routing through `translateHttpError` (structured envelope present) and
+ * throwing their own typed error with the fallback (bare/non-Ablo body), instead
+ * of emitting a code-less error.
+ */
+export function hasWireCode(body) {
+    if (typeof body !== 'object' || body === null)
+        return false;
+    const b = body;
+    if (typeof b.code === 'string')
+        return true;
+    if (typeof b.error === 'string')
+        return true;
+    return (typeof b.error === 'object' &&
+        b.error !== null &&
+        typeof b.error.code === 'string');
+}
+/**
+ * Extract the canonical error `code` from a raw HTTP error body STRING — the
+ * top-level `code` or a nested `error.code`. Returns undefined for non-JSON or
+ * code-less bodies. Used by session-error detection to tell a genuine expiry
+ * (`session_expired`/`jwt_expired`) apart from other auth failures.
+ */
+export function extractWireCode(body) {
+    if (!body)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
     }
-    // Claim enforcement also rides 409 (a commit blocked by a foreign claim).
-    // Discriminate on the code BEFORE the generic idempotency mapping so a
-    // claim rejection surfaces as AbloClaimedError, not AbloIdempotencyError —
-    // same typed error the WebSocket commit path yields for these codes.
-    if (code === 'intent_conflict' || code === 'claim_conflict' || code === 'entity_claimed') {
-        return new AbloClaimedError(message, baseOpts);
+    catch {
+        return undefined;
     }
-    if (status === 409)
-        return new AbloIdempotencyError(message, baseOpts);
-    if (status === 422 || status === 400)
-        return new AbloValidationError(message, baseOpts);
-    if (status === 429)
-        return new AbloRateLimitError(message, baseOpts);
-    if (status >= 500)
-        return new AbloServerError(message, baseOpts);
-    return new AbloError(message, baseOpts);
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const b = parsed;
+    if (typeof b.code === 'string')
+        return b.code;
+    if (typeof b.error === 'object' &&
+        b.error !== null &&
+        typeof b.error.code === 'string') {
+        return b.error.code;
+    }
+    return undefined;
 }

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+ * const report = await ablo.weatherReports.retrieve('report_stockholm');
  * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
  *
  * type Entry = Ablo.Peer;
@@ -23,9 +23,13 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Consumer code should converge on `ablo.<model>.load(...)`, which routes
- * through the engine's `HydrationCoordinator` and dedupes single-flight
- * hydrations.
+ * Reads split by where the data comes from. `ablo.<model>.retrieve(id)` and
+ * `.list({ where })` are the async **server** reads (pool → IDB → network via
+ * the `HydrationCoordinator`, single-flight deduped); they're the default and
+ * what hosted/stateless callers want, since their local graph starts empty.
+ * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
+ * **local-graph** snapshots with no network round-trip — for reactive React
+ * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
  *
  * ── What to import (read this first) ────────────────────────────────
  * Default path — this is all most apps and agents ever need:
@@ -49,7 +53,7 @@ import { Ablo } from './client/Ablo.js';
 export default Ablo;
 export { dataSource, abloSource, signAbloSourceRequest, verifyAbloSourceRequest, } from './source/index.js';
 export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
 export type { CommitReceipt, RequiredCapability } from './errors.js';
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec } from './errors.js';
 export type { Register, DefaultSyncShape } from './types/global.js';

package/dist/index.js

@@ -5,7 +5,7 @@
  * import Ablo from '@abloatai/ablo';
  *
  * const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
- * await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+ * const report = await ablo.weatherReports.retrieve('report_stockholm');
  * await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
  *
  * type Entry = Ablo.Peer;
@@ -23,9 +23,13 @@
  *   @abloatai/ablo/react    — <AbloProvider>, useQuery, useMutate
  *   @abloatai/ablo/testing  — test harnesses + mocks
  *
- * Consumer code should converge on `ablo.<model>.load(...)`, which routes
- * through the engine's `HydrationCoordinator` and dedupes single-flight
- * hydrations.
+ * Reads split by where the data comes from. `ablo.<model>.retrieve(id)` and
+ * `.list({ where })` are the async **server** reads (pool → IDB → network via
+ * the `HydrationCoordinator`, single-flight deduped); they're the default and
+ * what hosted/stateless callers want, since their local graph starts empty.
+ * `ablo.<model>.get(id)` / `.getAll(...)` / `.getCount(...)` are synchronous
+ * **local-graph** snapshots with no network round-trip — for reactive React
+ * selectors (`useAblo((ablo) => ablo.<model>.get(id))`) once the graph is warm.
  *
  * ── What to import (read this first) ────────────────────────────────
  * Default path — this is all most apps and agents ever need:
@@ -78,7 +82,7 @@ export { defaultPolicy, capabilityPreemptPolicy } from './policy/index.js';
 // Typed error hierarchy — Stripe-style. One import gets every class
 // consumers need to discriminate failures (`e instanceof AbloX` or
 // `e.type === 'AbloX'`) plus the HTTP-response translator.
-export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
+export { SyncSessionError, AbloError, AbloAuthenticationError, AbloPermissionError, AbloRateLimitError, AbloIdempotencyError, AbloConnectionError, AbloValidationError, AbloServerError, AbloStaleContextError, AbloClaimedError, CapabilityError, translateHttpError, hasWireCode, errorFromWire, toAbloError, ERROR_CODES, ERROR_CONTRACT_VERSION, errorCodeSpec, isRetryableCode, } from './errors.js';
 // Advanced — most apps never import this. Custom (Zero-style) mutators:
 // `ablo.<model>.create/update/delete` already covers normal writes. Reach
 // for `defineMutators` only when you need a named, multi-step mutation with

package/dist/keys/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Canonical Ablo API-key format — the single source of truth for how keys
+ * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
+ * and the web control-plane (`generate-key.ts`) consume THIS module, so the
+ * format can no longer drift between the two mint sites (it used to live as
+ * a hand-copied twin kept in sync by a comment).
+ *
+ * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
+ * subpath and NEVER re-exported from the browser-facing `.` entry, so the
+ * client bundle never pulls in `node:crypto`.
+ *
+ * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
+ * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
+ * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
+ * still validate by hash — they parse here as `checksummed: false`.
+ */
+import { z } from 'zod';
+export declare const API_KEY_KINDS: readonly ["secret", "restricted", "ephemeral"];
+export type ApiKeyKind = (typeof API_KEY_KINDS)[number];
+export declare const API_KEY_ENVS: readonly ["live", "test"];
+export type ApiKeyEnv = (typeof API_KEY_ENVS)[number];
+/** A structurally-valid Ablo API key, parsed into its parts. */
+export interface ParsedApiKey {
+    /** The original plaintext. */
+    raw: string;
+    kind: ApiKeyKind;
+    env: ApiKeyEnv;
+    /** The chars after `<prefix>_<env>_` (body + checksum for new keys). */
+    body: string;
+    /** True when this is the new checksummed format (36-char base62 body). */
+    checksummed: boolean;
+}
+/**
+ * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
+ * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
+ * rejected (the offline-reject), while a legacy key parses as
+ * `checksummed: false` and passes (the server still hash-validates it).
+ */
+export declare const apiKeySchema: z.ZodPipe<z.ZodString, z.ZodTransform<ParsedApiKey, string>>;
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export declare function parseApiKey(raw: string): ParsedApiKey | null;
+/** True when the key uses the new checksummed format (regardless of validity). */
+export declare function isChecksummedKey(raw: string): boolean;
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export declare function keyChecksumMatches(raw: string): boolean;
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export declare function generateApiKey(env?: ApiKeyEnv, kind?: ApiKeyKind): {
+    plaintext: string;
+    hash: string;
+    prefix: string;
+};
+/**
+ * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
+ * bcrypt) — API keys are high-entropy random, so there's no dictionary to
+ * defend against. Used at both write (mint) and lookup.
+ */
+export declare function hashApiKey(plaintext: string): string;

package/dist/keys/index.js

@@ -0,0 +1,151 @@
+/**
+ * Canonical Ablo API-key format — the single source of truth for how keys
+ * are minted, hashed, and validated. Both the sync-server (`apiKeyStore`)
+ * and the web control-plane (`generate-key.ts`) consume THIS module, so the
+ * format can no longer drift between the two mint sites (it used to live as
+ * a hand-copied twin kept in sync by a comment).
+ *
+ * Node-only — uses `node:crypto`. Exposed via the `@abloatai/ablo/keys`
+ * subpath and NEVER re-exported from the browser-facing `.` entry, so the
+ * client bundle never pulls in `node:crypto`.
+ *
+ * Format (GitHub-style): `<sk|rk|ek>_<live|test>_<30 base62 body><6-char
+ * base62 CRC32 checksum>`. The identifiable prefix + CRC32 checksum let
+ * secret scanners detect leaks and let us reject typo'd/forged keys OFFLINE
+ * (no DB round-trip). Legacy keys (a ~43-char base64url body, no checksum)
+ * still validate by hash — they parse here as `checksummed: false`.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+// ── Vocabulary ──────────────────────────────────────────────────────────
+// The three-key Stripe model:
+//   secret (sk_)      — backend / server-to-server / agents. Full authority. Never in a browser.
+//   restricted (rk_)  — scoped SERVER key (agent session tokens / capabilities).
+//   ephemeral (ek_)   — short-lived, backend-minted, USER-scoped BROWSER session credential
+//                       (Stripe ephemeral keys). Carries participantKind:'user' + baked syncGroups.
+// (There is no publishable `pk_` — the minted session token, not a project
+//  identifier, is what the browser holds; it already names the org.)
+export const API_KEY_KINDS = ['secret', 'restricted', 'ephemeral'];
+export const API_KEY_ENVS = ['live', 'test'];
+const PREFIX_BY_KIND = {
+    secret: 'sk',
+    restricted: 'rk',
+    ephemeral: 'ek',
+};
+const KIND_BY_PREFIX = {
+    sk: 'secret',
+    rk: 'restricted',
+    ek: 'ephemeral',
+};
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/** Random base62 chars before the checksum. */
+const KEY_BODY_LEN = 30;
+/** base62(CRC32): 62^6 (~5.7e10) > 2^32, so a CRC32 always fits in 6 chars. */
+const CHECKSUM_LEN = 6;
+/** A new checksummed body is exactly this long and pure base62. */
+const CHECKSUMMED_BODY_LEN = KEY_BODY_LEN + CHECKSUM_LEN;
+/** `<sk|rk|ek>_<live|test>_<body>`; body charset covers base62 AND legacy base64url. */
+const KEY_RE = /^(sk|rk|ek)_(live|test)_([0-9A-Za-z\-_]+)$/;
+const BASE62_RE = /^[0-9A-Za-z]+$/;
+// ── Checksum (standard CRC-32, GitHub-compatible) ───────────────────────
+const CRC32_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(s) {
+    let c = 0xffffffff;
+    for (let i = 0; i < s.length; i++) {
+        c = (CRC32_TABLE[(c ^ s.charCodeAt(i)) & 0xff] ^ (c >>> 8)) >>> 0;
+    }
+    return (c ^ 0xffffffff) >>> 0;
+}
+/** 6-char base62 encoding of the CRC32 of `payload`. */
+function checksum6(payload) {
+    let n = crc32(payload);
+    let out = '';
+    for (let i = 0; i < CHECKSUM_LEN; i++) {
+        out = BASE62[n % 62] + out;
+        n = Math.floor(n / 62);
+    }
+    return out;
+}
+/** `len` cryptographically-random base62 chars (rejection-sampled, no bias). */
+function randomBase62(len) {
+    let out = '';
+    while (out.length < len) {
+        for (const b of randomBytes(len * 2)) {
+            if (b < 248) {
+                out += BASE62[b % 62];
+                if (out.length === len)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+function bodyIsChecksummed(body) {
+    return body.length === CHECKSUMMED_BODY_LEN && BASE62_RE.test(body);
+}
+/**
+ * Canonical schema for an Ablo API key. `parse`/`safeParse` returns a typed
+ * {@link ParsedApiKey}; a new checksummed-format key with a BAD checksum is
+ * rejected (the offline-reject), while a legacy key parses as
+ * `checksummed: false` and passes (the server still hash-validates it).
+ */
+export const apiKeySchema = z.string().transform((raw, ctx) => {
+    const m = KEY_RE.exec(raw);
+    if (!m) {
+        ctx.addIssue({ code: 'custom', message: 'not a valid Ablo API key format' });
+        return z.NEVER;
+    }
+    const [, prefix, env, body] = m;
+    const checksummed = bodyIsChecksummed(body);
+    if (checksummed && checksum6(raw.slice(0, -CHECKSUM_LEN)) !== body.slice(KEY_BODY_LEN)) {
+        ctx.addIssue({ code: 'custom', message: 'API key checksum mismatch' });
+        return z.NEVER;
+    }
+    return { raw, kind: KIND_BY_PREFIX[prefix], env: env, body, checksummed };
+});
+// ── Derived validators (thin wrappers over the same spec) ───────────────
+/** Parse + fully validate (incl. checksum). Returns null when invalid. */
+export function parseApiKey(raw) {
+    const r = apiKeySchema.safeParse(raw);
+    return r.success ? r.data : null;
+}
+/** True when the key uses the new checksummed format (regardless of validity). */
+export function isChecksummedKey(raw) {
+    const m = KEY_RE.exec(raw);
+    return m !== null && bodyIsChecksummed(m[3]);
+}
+/** Verify the embedded checksum. Meaningful only for checksummed-format keys. */
+export function keyChecksumMatches(raw) {
+    const m = KEY_RE.exec(raw);
+    if (!m || !bodyIsChecksummed(m[3]))
+        return false;
+    return checksum6(raw.slice(0, -CHECKSUM_LEN)) === m[3].slice(KEY_BODY_LEN);
+}
+// ── Mint + hash (node:crypto) ───────────────────────────────────────────
+/**
+ * Mint a key: `<prefix>_<env>_<body><checksum>`. Returns the plaintext (shown
+ * once), its SHA-256 hash (persisted), and the 12-char display prefix.
+ */
+export function generateApiKey(env = 'live', kind = 'secret') {
+    const body = randomBase62(KEY_BODY_LEN);
+    const payload = `${PREFIX_BY_KIND[kind]}_${env}_${body}`;
+    const plaintext = `${payload}${checksum6(payload)}`;
+    return { plaintext, hash: hashApiKey(plaintext), prefix: plaintext.slice(0, 12) };
+}
+/**
+ * Stable SHA-256 hex of a plaintext key. A fast hash is CORRECT here (not
+ * bcrypt) — API keys are high-entropy random, so there's no dictionary to
+ * defend against. Used at both write (mint) and lookup.
+ */
+export function hashApiKey(plaintext) {
+    return createHash('sha256').update(plaintext).digest('hex');
+}