@abloatai/transaction 0.59.2 → 0.60.0

package/src/sessions/contract.ts

@@ -0,0 +1,116 @@
+import type {
+  CapabilityCan,
+  CapabilityOperation,
+  EffectiveAuthority,
+} from '../auth/capability.js';
+import type { CredentialEndpointSuccess } from '../auth/credentialEndpointProtocol.js';
+import type { SchemaRecord } from '../schema/schema.js';
+import type { SyncGroupInput } from '../schema/roles.js';
+
+/** The bearer-bearing part of a session returned by `sessions.create()`. */
+export interface SessionCredential {
+  readonly object: 'session';
+  /** The short-lived `ek_` or `rk_` bearer used by the scoped client. */
+  readonly token: string;
+  /** ISO-8601 hard expiry for this credential. */
+  readonly expiresAt: string;
+}
+
+/** Result accepted from a session provider or canonical browser mint endpoint. */
+export type SessionProviderResult =
+  | SessionCredential
+  | CredentialEndpointSuccess
+  | null;
+
+/** Re-mints the same logical actor's scoped session for a long-lived client. */
+export type SessionProvider = () => Promise<SessionProviderResult>;
+
+/** Browser-safe route that mints the signed-in actor's short-lived session. */
+export interface SessionEndpoint {
+  readonly endpoint: string;
+  readonly timeoutMs?: number;
+  readonly allowCrossOrigin?: boolean;
+}
+
+/** Every supported source for `Ablo({ session })`. */
+export type SessionSource = SessionCredential | SessionProvider | SessionEndpoint;
+
+/** Public session scope; transport-specific sync naming stays below this boundary. */
+export type SessionScope = Omit<EffectiveAuthority, 'syncGroups'> & {
+  readonly groups: readonly string[];
+};
+
+export function sessionScope(authority: EffectiveAuthority): SessionScope {
+  const { syncGroups, ...scope } = authority;
+  return { ...scope, groups: syncGroups };
+}
+
+/** A single data operation a scoped session may perform on a model. */
+export type SessionOperation = CapabilityOperation;
+
+/** Parameters for issuing a short-lived end-user (`ek_`) session. */
+export interface CreateUserSessionParams<S extends SchemaRecord> {
+  readonly user: { readonly id: string };
+  readonly organizationId?: string;
+  readonly schemaProject?: {
+    readonly organizationId: string;
+    readonly projectId: string;
+  };
+  readonly groups?: readonly SyncGroupInput[];
+  readonly can: CapabilityCan<S>;
+  readonly ttlSeconds?: number;
+  readonly userMeta?: Record<string, unknown>;
+  readonly agent?: never;
+}
+
+/** Parameters for issuing a short-lived scoped agent (`rk_`) session. */
+export interface CreateAgentSessionParams<S extends SchemaRecord> {
+  readonly agent: { readonly id: string };
+  readonly onBehalfOf?: { readonly user: { readonly id: string } };
+  readonly can: CapabilityCan<S>;
+  readonly groups?: readonly SyncGroupInput[];
+  readonly ttlSeconds?: number;
+  readonly userMeta?: Record<string, unknown>;
+  readonly user?: never;
+}
+
+/** The one typed issuance input; its subject selects user or agent identity. */
+export type CreateSessionParams<S extends SchemaRecord> =
+  | CreateUserSessionParams<S>
+  | CreateAgentSessionParams<S>;
+
+/** A minted session. `token` is the secret the holder presents as its bearer. */
+export interface AbloSession extends SessionCredential {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly scope: SessionScope;
+  readonly userMeta: Record<string, unknown>;
+}
+
+export interface SessionRevocation {
+  readonly id: string;
+  readonly deleted: true;
+  readonly activeSessionsClosed: number;
+}
+
+export interface SessionRotation {
+  readonly id: string;
+  readonly token: string;
+  readonly expiresAt: string | null;
+  readonly organizationId: string;
+  readonly scope: SessionScope;
+  readonly rotatedFrom: {
+    readonly id: string;
+    readonly expiresAt: string;
+  };
+}
+
+export interface RevokeSessionParams {
+  readonly id: string;
+}
+
+export interface RotateSessionParams {
+  readonly id: string;
+  readonly graceSeconds?: number;
+  readonly ttlSeconds?: number;
+}

package/src/{auth/sessionMint.ts → sessions/create.ts}

@@ -18,27 +18,28 @@
  *                 registered names.
  *
  * The caller supplies the already-resolved secret key and base URL in
- * {@link MintSessionContext}. Choosing which key to pass — the original secret
+ * {@link CreateSessionContext}. Choosing which key to pass — the original secret
  * key, not a derived key that an earlier exchange may have produced — is the
  * caller's responsibility.
  */
 import {
   exchangeApiKey,
   mintUserSessionKey,
-} from './runtime.js';
+} from '../auth/runtime.js';
 import {
   capabilityCanSchemaFor,
   grantedOperations,
-} from './capability.js';
+} from '../auth/capability.js';
 import type { SchemaRecord } from '../schema/schema.js';
-import type { AbloSession, CreateSessionParams } from '../client/resources/httpResources.js';
+import type { AbloSession, CreateSessionParams } from './contract.js';
+import { sessionScope } from './contract.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
  * to the runtime's global `fetch`.
  */
-export interface MintSessionContext {
+export interface CreateSessionContext {
   readonly apiKey: string;
   readonly baseUrl: string;
   readonly fetch?: typeof fetch;
@@ -59,9 +60,9 @@ export interface MintSessionContext {
  * Routes the `{ user }` or `{ agent }` request to the matching mint endpoint
  * and reshapes the response into an {@link AbloSession}.
  */
-export async function mintSession<S extends SchemaRecord>(
+export async function createSession<S extends SchemaRecord>(
   params: CreateSessionParams<S>,
-  ctx: MintSessionContext,
+  ctx: CreateSessionContext,
 ): Promise<AbloSession> {
   const { apiKey, baseUrl } = ctx;
   // Static typing and runtime validation consume the same schema-bound grant
@@ -77,7 +78,7 @@ export async function mintSession<S extends SchemaRecord>(
       userId: params.user.id,
       ...(params.organizationId ? { organizationId: params.organizationId } : {}),
       ...(params.schemaProject ? { schemaProject: params.schemaProject } : {}),
-      ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+      ...(params.groups ? { syncGroups: [...params.groups] } : {}),
       operations,
       ttlSeconds: params.ttlSeconds ?? 900,
       ...(ctx.fetch ? { fetch: ctx.fetch } : {}),
@@ -90,7 +91,7 @@ export async function mintSession<S extends SchemaRecord>(
       organizationId: res.organizationId,
       // The ephemeral mint stores scope on the key row; reshape its flat
       // response into the session resource's scope block.
-      scope: {
+      scope: sessionScope({
         organizationId: res.organizationId,
         projectId: res.projectId,
         branchId: res.branchId,
@@ -99,7 +100,7 @@ export async function mintSession<S extends SchemaRecord>(
         participantKind: 'user',
         participantId: res.participantId,
         deliveryPartition: res.deliveryPartition,
-      },
+      }),
       userMeta: params.userMeta ?? { id: res.participantId },
     };
   }
@@ -113,7 +114,7 @@ export async function mintSession<S extends SchemaRecord>(
     participantKind: 'agent',
     participantId: params.agent.id,
     ...(params.onBehalfOf ? { onBehalfOf: params.onBehalfOf } : {}),
-    ...(params.syncGroups ? { syncGroups: [...params.syncGroups] } : {}),
+    ...(params.groups ? { syncGroups: [...params.groups] } : {}),
     operations,
     ttlSeconds: params.ttlSeconds ?? 900,
     ...(params.userMeta ? { userMeta: params.userMeta } : {}),
@@ -125,7 +126,7 @@ export async function mintSession<S extends SchemaRecord>(
     token: res.token,
     expiresAt: res.expiresAt,
     organizationId: res.organizationId,
-    scope: res.scope,
+    scope: sessionScope(res.scope),
     userMeta: res.userMeta,
   };
 }

package/src/sessions/handler.ts

@@ -0,0 +1,96 @@
+/**
+ * Server-owned browser session exchange.
+ *
+ * Authentication providers prove who is calling; this boundary converts that
+ * proof into the one Ablo session resource consumed by browser clients. It
+ * owns the HTTP protocol so applications do not repeat origin, cache, status,
+ * or credential-envelope handling in every framework route.
+ */
+
+import type { SchemaRecord } from '../schema/schema.js';
+import type {
+  AbloSession,
+  CreateSessionParams,
+} from './contract.js';
+import {
+  credentialEndpointErrorSchema,
+  credentialEndpointSuccessSchema,
+} from '../auth/credentialEndpointProtocol.js';
+import { classifyCredentialKind } from '../auth/credentialKind.js';
+
+export interface SessionHandlerOptions<
+  S extends SchemaRecord,
+  Principal,
+> {
+  /** Verify the application's cookie, bearer, or framework auth session. */
+  authenticate(request: Request): Principal | null | Promise<Principal | null>;
+  /** Derive Ablo identity, groups, and access exclusively on the server. */
+  grant(input: {
+    readonly principal: Principal;
+    readonly request: Request;
+  }): CreateSessionParams<S> | null | Promise<CreateSessionParams<S> | null>;
+}
+
+export type SessionHandler = (request: Request) => Promise<Response>;
+
+const NO_STORE_HEADERS = { 'Cache-Control': 'no-store' } as const;
+
+function errorResponse(
+  status: number,
+  code: string,
+  message: string,
+): Response {
+  return Response.json(
+    credentialEndpointErrorSchema.parse({ error: { code, message } }),
+    { status, headers: NO_STORE_HEADERS },
+  );
+}
+
+function isSameOrigin(request: Request): boolean {
+  const origin = request.headers.get('origin');
+  if (!origin) return request.headers.get('sec-fetch-site') !== 'cross-site';
+  try {
+    return new URL(origin).origin === new URL(request.url).origin;
+  } catch {
+    return false;
+  }
+}
+
+/** Build a framework-neutral POST handler around one authenticated session grant. */
+export function createSessionHandler<S extends SchemaRecord, Principal>(
+  create: (params: CreateSessionParams<S>) => Promise<AbloSession>,
+  options: SessionHandlerOptions<S, Principal>,
+): SessionHandler {
+  return async (request) => {
+    if (request.method !== 'POST') {
+      return errorResponse(405, 'method_not_allowed', 'Use POST to create a session.');
+    }
+    if (!isSameOrigin(request)) {
+      return errorResponse(403, 'origin_mismatch', 'Cross-origin session creation rejected.');
+    }
+
+    const principal = await options.authenticate(request);
+    if (principal === null) {
+      return errorResponse(401, 'session_expired', 'Sign in again.');
+    }
+
+    const grant = await options.grant({ principal, request });
+    if (grant === null) {
+      return errorResponse(403, 'policy_denied', 'This identity is not authorized.');
+    }
+
+    const session = await create(grant);
+    const credentialKind = classifyCredentialKind(session.token);
+    if (credentialKind !== 'ephemeral' && credentialKind !== 'restricted') {
+      throw new Error('sessions.create returned a credential that cannot authenticate a session.');
+    }
+    return Response.json(
+      credentialEndpointSuccessSchema.parse({
+        token: session.token,
+        expiresAt: session.expiresAt,
+        credentialKind,
+      }),
+      { headers: NO_STORE_HEADERS },
+    );
+  };
+}

package/src/sessions/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Session subsystem.
+ *
+ * Start here and descend into the public contract, issuance, server handler,
+ * source normalization, or credential lifecycle. Transports consume the
+ * normalized access contract and do not reconstruct session policy.
+ */
+export * from './contract.js';
+export * from './client.js';
+export * from './create.js';
+export * from './handler.js';
+export * from './source.js';
+export * from './lifecycle.js';

package/src/{transport/connection/credentialLifecycle.ts → sessions/lifecycle.ts}

@@ -1,20 +1,20 @@
 /**
  * Keeps the short-lived access credential fresh. It owns the re-mint hook, a
  * single-flight guard that stops concurrent triggers from minting more than
- * once, and a browser-only proactive refresh — a timer plus an OS-wake listener
- * — that renews the credential ahead of expiry. It reaches the rest of the
+ * once, and proactive refresh — an expiry-aware timer plus a browser OS-wake
+ * listener — that renews the credential ahead of expiry. It reaches the rest of the
  * client only through the small {@link CredentialLifecycleContext} interface,
  * so the two can reference each other without an import cycle.
  */
 
-import type { RecoveryClass } from '../../errorCodes.js';
-import { noopLogger, type Logger } from '../../logger.js';
+import type { RecoveryClass } from '../errorCodes.js';
+import { noopLogger, type Logger } from '../logger.js';
 import {
   credentialExpiry,
   credentialToken,
   type CredentialProvider,
   type CredentialProviderResult,
-} from '../../auth/credentialResult.js';
+} from '../auth/credentialResult.js';
 
 /**
  * Tri-state outcome of a credential re-mint, mirroring the `getToken`

package/src/sessions/source.ts

@@ -0,0 +1,94 @@
+/**
+ * Runtime lifecycle for a renewable session supplied to `Ablo({ session })`.
+ *
+ * A session provider mints a credential, while this boundary decides when to
+ * reuse it. Keeping that policy here prevents HTTP requests and the WebSocket
+ * bootstrap from independently minting duplicate sessions for the same actor.
+ */
+
+import type {
+  CredentialProvider,
+  CredentialProviderResult,
+} from '../auth/credentialResult.js';
+import type {
+  SessionProvider,
+  SessionProviderResult,
+  SessionSource,
+} from './contract.js';
+import { AbloValidationError } from '../errors.js';
+import {
+  createEndpointCredentialResolver,
+  isCredentialEndpoint,
+} from '../auth/credentialEndpoint.js';
+import { protectBrowserCredentialProvider } from '../auth/browserCredentialSafety.js';
+
+const SESSION_REFRESH_SKEW_MS = 30_000;
+
+function remainsUsable(session: Exclude<SessionProviderResult, null>, now: number): boolean {
+  const expiresAt = Date.parse(session.expiresAt);
+  return Number.isFinite(expiresAt) && expiresAt - now > SESSION_REFRESH_SKEW_MS;
+}
+
+/** Cache one minted session until it approaches expiry; concurrent refreshes share one mint. */
+export function cachedSessionProvider(provider: SessionProvider): CredentialProvider {
+  let current: Exclude<SessionProviderResult, null> | null = null;
+  let refreshing: Promise<SessionProviderResult> | null = null;
+
+  return async () => {
+    if (current && remainsUsable(current, Date.now())) return current;
+    refreshing ??= provider().then((next) => {
+      current = next;
+      return next;
+    }).finally(() => {
+      refreshing = null;
+    });
+    return refreshing;
+  };
+}
+
+/** The one credential input a live transport consumes. */
+export interface SessionAccess {
+  readonly renewable: boolean;
+  credential(): Promise<CredentialProviderResult>;
+}
+
+/** Normalize a static or renewable session before it reaches a transport. */
+export function createSessionAccess(
+  source: SessionSource | null | undefined,
+  credential: () => Promise<CredentialProviderResult>,
+): SessionAccess {
+  return {
+    renewable:
+      typeof source === 'function'
+      || (typeof source === 'object' && source !== null && 'endpoint' in source),
+    credential,
+  };
+}
+
+/** Resolve the public session forms into the credential shape auth consumes. */
+export function resolveSessionCredential(
+  source: SessionSource,
+  options: {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly dangerouslyAllowBrowser?: boolean;
+  },
+): string | CredentialProvider {
+  if (typeof source === 'function') {
+    return protectBrowserCredentialProvider(
+      cachedSessionProvider(source),
+      options.dangerouslyAllowBrowser,
+    );
+  }
+  if (!('endpoint' in source)) return source.token;
+  if (!isCredentialEndpoint(source.endpoint)) {
+    throw new AbloValidationError(
+      '`session.endpoint` expects a URL or path such as \'/api/ablo-session\'.',
+      { code: 'invalid_options', param: 'session.endpoint' },
+    );
+  }
+  return protectBrowserCredentialProvider(createEndpointCredentialResolver(source.endpoint, {
+    fetch: options.fetch,
+    timeoutMs: source.timeoutMs,
+    allowCrossOrigin: source.allowCrossOrigin,
+  }), options.dangerouslyAllowBrowser);
+}

package/src/transport/connection/index.ts

@@ -1,4 +1,3 @@
 /** Shared connection lifecycle boundary. */
 export * from './manager.js';
-export * from './credentialLifecycle.js';
 export * from './networkProbe.js';

package/src/transport/connection/manager.ts

@@ -42,7 +42,7 @@
 
 import { probeNetwork, type ProbeResult } from './networkProbe.js';
 import type { AuthTokenGetter } from '../../auth/credentialSource.js';
-import type { CredentialRefreshOutcome } from './credentialLifecycle.js';
+import type { CredentialRefreshOutcome } from '../../sessions/lifecycle.js';
 import { noopLogger, type Logger } from '../../logger.js';
 import {
   noopSocketObservability,

package/src/transport/http/client.ts

@@ -21,7 +21,6 @@ import {
   createHttpTransport,
   type HttpTransport,
 } from './transport.js';
-import { modelWireNames } from '../../auth/capability.js';
 import type { HttpClientConfig } from './options.js';
 import type {
   CommitResource,
@@ -33,9 +32,6 @@ import type {
   ModelReadOptions,
   ModelMutationOptions,
   ModelList,
-  CreateSessionParams,
-  AbloSession,
-  SessionResource,
 } from '../../client/resources/httpResources.js';
 import { collectModelList, modelList } from '../../client/resources/httpResources.js';
 import { resolveCreateId } from '../../client/resources/modelCreate.js';
@@ -91,8 +87,8 @@ export interface AbloHttpClientOptions<S extends SchemaRecord>
    * @default 30_000
    */
   readonly timeoutMs?: number;
-  /** Initial area of interest for `transport: 'websocket'`. */
-  readonly syncGroups?: readonly string[];
+  /** Initial groups observed by a session-backed WebSocket client. */
+  readonly groups?: readonly string[];
   /** Application frame names accepted by `subscribe` on the WebSocket transport. */
   readonly collaborationEvents?: readonly string[];
   /** Durable resume position for WebSocket observation. */
@@ -123,7 +119,7 @@ export type HttpModelMutationParams<P> = Omit<P, 'reads'> & {
  * coordinated writes.
  * It deliberately omits the stateful client's local-only
  * reads (the `local` namespace) and live subscriptions (`onChange`), which need
- * a resident graph and a persistent socket; those are absent from the type, so
+ * a local graph and a persistent socket; those are absent from the type, so
  * reaching for one is a compile error rather than a runtime gap.
  *
  * This is also the base the reactive per-model surface is composed from, rather
@@ -199,7 +195,7 @@ export interface HttpModelClient<T, C = T> {
 
 /**
  * The type of the stateless HTTP client: a typed {@link HttpModelClient} per
- * schema model, plus `commits`, `dispose`, and the session-mint surface. It
+ * schema model, plus `commits` and lifecycle operations. It
  * exposes only what request/response transport can do, so reaching for a
  * stateful-only capability — the `local` reads, `onChange`, or the synchronous
  * `claim.state`/`queue`/`reorder` reads — is a compile error rather than a value
@@ -235,13 +231,6 @@ export type AbloHttpClient<S extends SchemaRecord> = {
   dispose(): Promise<void>;
   /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
   getAuthToken(): Promise<string | null>;
-  /**
-   * Mints a short-lived, scoped session token. Minting is itself a stateless
-   * request, so it is available here even though the local-cache reads are not.
-   * Pass `{ user }` to mint an end-user key (`ek_`) or `{ agent, can }` to mint a
-   * scoped agent key (`rk_`). See {@link CreateSessionParams}.
-  */
-  readonly sessions: SessionResource<S>;
 };
 
 /** The same typed resource client, with server-pushed capabilities carried by WebSocket. */
@@ -252,9 +241,9 @@ export type AbloWebSocketClient<S extends SchemaRecord> = AbloHttpClient<S> & {
     listener: (...args: CoreSyncEventMap[K]) => void,
   ): () => void;
   updateSubscription(
-    syncGroups: readonly string[],
+    groups: readonly string[],
     options?: { timeoutMs?: number },
-  ): Promise<{ syncGroups: string[] }>;
+  ): Promise<{ groups: string[] }>;
   readonly presence: {
     update(input?: {
       readonly status?: 'online' | 'away' | 'offline';
@@ -281,7 +270,6 @@ const PROTOCOL_MEMBERS = new Set<string>([
   'logs',
   'identity',
   'getAuthToken',
-  'sessions',
 ]);
 
 /** Narrows a bare property name to a transport key so the facade can index it typed. */
@@ -538,23 +526,20 @@ function createHttpModelClient<T, C = T>(
 }
 
 /**
- * Builds the stateless, typed HTTP client. Each `client.<model>` resolves to the
- * protocol client's model accessor, while `commits`, `dispose`, and the other
- * protocol members pass through unchanged. No socket is ever opened; the bearer
- * credential is the identity.
+ * Builds the typed headless client. An API-key identity uses HTTP. A session
+ * identity uses one lazily opened WebSocket by default for commits and live
+ * coordination until `dispose()`; point reads and administration remain HTTP.
  */
-/** @internal Constructed only through the public `Ablo({ transport: 'http' })` factory. */
+/** @internal Constructed only through the public `Ablo()` factory. */
 export function createAbloHttpClient<S extends SchemaRecord>(
   options: AbloHttpClientOptions<S>,
 ): AbloHttpClient<S> | AbloWebSocketClient<S> {
   const { schema, onCommitReceipt, ...rest } = options;
-  const usesWebSocket = options.transport === 'websocket';
+  const usesWebSocket = options.transport === 'websocket'
+    || (options.transport === undefined && options.session != null);
   const readSetContext = createReadSetContext();
   const transport: HttpTransport = createHttpTransport({
     ...rest,
-    // Derived from the schema this client is bound to, never assembled by hand
-    // — see `auth/capability.ts`.
-    modelTypenames: modelWireNames(schema.models),
     onCommitReceipt: (observation) => {
       recordHttpCommitReceipt(readSetContext, observation);
       onCommitReceipt?.(observation);
@@ -597,8 +582,8 @@ export function createAbloHttpClient<S extends SchemaRecord>(
       await transport.ready();
       const session = await createWebSocketSession({
         baseUrl: rest.baseURL ?? undefined,
-        getAuthToken: async () => (await transport.getAuthToken()) ?? undefined,
-        syncGroups: options.syncGroups,
+        access: transport.access,
+        syncGroups: options.groups,
         collaborationEvents: options.collaborationEvents,
         cursorStore: options.cursorStore,
         cursorKey: options.cursorKey,
@@ -707,8 +692,13 @@ export function createAbloHttpClient<S extends SchemaRecord>(
         };
       }
       if (usesWebSocket && prop === 'updateSubscription') {
-        return async (groups: readonly string[], subscriptionOptions?: { timeoutMs?: number }) =>
-          (await webSocketSession()).updateSubscription(groups, subscriptionOptions);
+        return async (groups: readonly string[], subscriptionOptions?: { timeoutMs?: number }) => {
+          const result = await (await webSocketSession()).updateSubscription(
+            groups,
+            subscriptionOptions,
+          );
+          return { groups: result.syncGroups };
+        };
       }
       if (usesWebSocket && prop === 'presence') {
         return {

package/src/transport/http/options.ts

@@ -37,7 +37,10 @@ export interface HttpClientConfig<S extends SchemaRecord = SchemaRecord>
   commitOutbox?: DurableWriteStore;
   /** Compatibility input and internal child-client identity seam. */
   commitOutboxScope?: CommitOutboxScope;
-  /** Which transport carries this client's traffic. */
+  /**
+   * Which transport carries this client's traffic. Defaults to WebSocket for
+   * a scoped `session` and HTTP for an API key or direct auth token.
+   */
   transport?: 'websocket' | 'http' | undefined;
   /** @internal Exact receipt phases observed while dispatching one HTTP commit. */
   onCommitReceipt?: (observation: {