@abloatai/transaction 0.59.1 → 0.60.0

package/src/coordination/schema.ts

@@ -467,8 +467,8 @@ export type ClaimError = z.infer<typeof claimErrorSchema>;
  * frozen, and an older server may send a word not listed here. This is the
  * reader's side of it: a value that parses becomes the typed reason, and one
  * that does not is simply absent rather than smuggled through as prose.
- * {@link claimExpiredSchema} and {@link claimLostSchema} already spelled their
- * reasons as enums; this brings the refusals into line.
+ * {@link claimLostSchema} already spells its reasons as an enum; this brings
+ * the refusals into line.
  */
 export const claimEventReasonSchema = z.enum([
   'conflict',
@@ -644,17 +644,6 @@ export const claimQueueSchema = z.object({
 });
 export type ClaimQueue = z.infer<typeof claimQueueSchema>;
 
-/**
- * A held claim's TTL lapsed server-side. The claim is already inactive by the
- * time this arrives, so a consumer either re-claims with a fresh credential or
- * accepts the drop; there is nothing to release.
- */
-export const claimExpiredSchema = z.object({
-  claimId: z.string(),
-});
-export type ClaimExpired = z.infer<typeof claimExpiredSchema>;
-
-
 /**
  * The two states a claim can be observed in while it still exists.
  *
@@ -981,20 +970,9 @@ export type ClaimHeartbeatBatchAckPayload = z.infer<
 // ─────────────────────────────────────────────────────────────────────────
 //  Read interest — what a connection receives
 //
-//  Two frames set it, and they differ in exactly one way: whether the
-//  interest is leased.
-//
-//    • `claim`  — a PARTICIPANT claim. Adds a scope under a handle, with a
-//      TTL and an optional capability token, and announces the sender into
-//      that scope's roster. This is the frame `ablo.<model>.join(...)` sends;
-//      `release` drops it. Several may be open on one connection at once.
-//    • `update_subscription` — REPLACES the connection's whole read set. No
-//      handle, no lease, no roster entry.
-//
-//  Both are bounded by the connection credential's grant, and both name their
-//  groups the same way, so both parse their `syncGroups` through the same
-//  element schema. Neither is the row lease — that is `claim_begin`, in the
-//  pessimistic-claims block above, which shares only a word.
+//  `update_subscription` replaces the connection's whole read set. It is
+//  bounded by the connection credential's grant and is not a row lease;
+//  row leases use `claim_begin` in the pessimistic-claims block above.
 // ─────────────────────────────────────────────────────────────────────────
 
 /**
@@ -1012,67 +990,15 @@ export const MAX_FRAME_SYNC_GROUPS = 200;
  * that does not parse matches nothing, and subscribing to nothing quietly is
  * the failure this element type exists to prevent.
  *
- * Strict because this is untrusted client input, and shared because the two
- * frames below carry the same value: when they disagreed, `claim` accepted a
- * malformed group that `update_subscription` refused, and the connection
- * ended up leased to a scope it could never receive.
+ * Strict because this is untrusted client input.
  */
 const frameSyncGroupsSchema = z
   .array(syncGroupInputSchema)
   .max(MAX_FRAME_SYNC_GROUPS);
 
-/**
- * The `claim` payload a client sends — the frame behind `join`.
- *
- * It opens one participant claim: the connection is added to each named
- * scope's fan-out under `claimId`, announced into its presence roster, and
- * holds that interest until `release`, the TTL lapses, or the socket closes.
- * The handle is client-chosen because the client must be able to `release`
- * the exact claim it opened while others stay open.
- *
- * This shape was, for a long time, written three times — built as a literal in
- * the transport, restated as an interface on the server, and read back through
- * a cast in the frame handler — which is how the frame came to be the only
- * coordination message with no runtime check on the way in.
- */
-export const participantClaimPayloadSchema = z.object({
-  /** Client-chosen handle. Echoed on `claim_ack`; names the claim to `release`. */
-  claimId: z.string().min(1),
-  syncGroups: frameSyncGroupsSchema,
-  /**
-   * A narrower capability to present for this claim than the connection's own.
-   * Absent means the connection's credential governs it.
-   */
-  capabilityToken: z.string().optional(),
-  /**
-   * Crash cleanup, in seconds. The server caps it at the capability's own TTL;
-   * absent means the claim lives until `release` or disconnect.
-   */
-  ttlSeconds: z.number().optional(),
-});
-export type ParticipantClaimPayload = z.infer<
-  typeof participantClaimPayloadSchema
->;
-
-/**
- * The `release` payload — drop one participant claim by its handle.
- *
- * A projection of the claim it releases rather than a second object, so the
- * handle cannot be spelled one way when opened and another when dropped.
- * Idempotent by contract: the server accepts an unknown handle silently, so a
- * client releasing everything at shutdown never has to check what is still open.
- */
-export const participantReleasePayloadSchema =
-  participantClaimPayloadSchema.pick({ claimId: true });
-export type ParticipantReleasePayload = z.infer<
-  typeof participantReleasePayloadSchema
->;
-
 /**
  * The `update_subscription` payload a client sends. It replaces the
- * connection's read interest with the complete set of sync groups — the
- * unleased counterpart to {@link participantClaimPayloadSchema}, with no
- * handle, no TTL, and no roster entry.
+ * connection's read interest with the complete set of sync groups.
  */
 export const updateSubscriptionPayloadSchema = z.object({
   syncGroups: frameSyncGroupsSchema,

package/src/errorCodes.ts

@@ -39,7 +39,7 @@ import { z } from 'zod';
  * error documentation and returned on the `Ablo-Version` response header, so a
  * consumer can detect when its expected contract has drifted from the server's.
  */
-export const ERROR_CONTRACT_VERSION = '2026-08-15';
+export const ERROR_CONTRACT_VERSION = '2026-08-30';
 
 /** A coarse grouping of error codes, used to organize metrics and documentation. */
 export type ErrorCategory =
@@ -511,17 +511,13 @@ export const ERROR_CODES = {
   // A claim payload that cannot be parsed is a malformed request, not
   // contention — it is filed with `malformed_subscription` below rather than
   // with the 409s above, so the claim category stays purely about a target
-  // being held. This is the code for a claim that fails to name its target,
-  // over either transport — and for the participant claim behind `join`, which
-  // names scopes rather than a row but fails the same way and to the same
-  // caller. The copy covers both because the caller sees one word, `claim`, and
-  // needs to be told which shape was expected without being handed a lecture on
-  // the two frames.
+  // being held. This is the code for a row claim that fails to name its target,
+  // over either transport.
   malformed_claim: wire(
     'validation',
     400,
     false,
-    'The claim payload could not be parsed. A claim on a row must name the model and the entity it targets; a claim on a scope, which is what `join` opens, must name sync groups spelled `kind:id` or `default`. Check the payload shape and resend.'
+    'The claim payload could not be parsed. A row claim must name the model and entity it targets. Check the payload shape and resend.'
   ),
   malformed_subscription: wire(
     'validation',
@@ -558,11 +554,6 @@ export const ERROR_CODES = {
     'claim',
     'Claiming is unavailable on this model client. Construct it through the standard Ablo({ schema, apiKey }) client and retry.'
   ),
-  model_join_not_configured: client(
-    'claim',
-    'join() opens a presence/claim subscription and needs a live WebSocket, so it is unavailable on the HTTP transport and on model proxies built without a socket. Use the standard Ablo({ schema, apiKey }) client (default WebSocket transport).'
-  ),
-
   // ── stale context / idempotency (409) ──────────────────────────────
   // Not retryable at the transport: the rejected request carries its frozen
   // `readAt`, so resending the identical payload can never succeed. Recovery
@@ -1238,6 +1229,10 @@ export const ERROR_CODES = {
     false,
     'The offline grace window expired before this commit could be sent, so it was not applied. Re-apply the change once the connection returns.'
   ),
+  observation_buffer_overflow: client(
+    'transport',
+    'A WebSocket observer fell behind its bounded in-memory backlog. Restart observation to replay from the last durable checkpoint.'
+  ),
   queue_too_deep: wire(
     'transport',
     503,

package/src/errors.ts

@@ -871,6 +871,19 @@ function detailsFromBody(body: unknown): Record<string, unknown> | undefined {
   return Object.keys(rest).length > 0 ? rest : undefined;
 }
 
+function detailsFromNestedError(
+  nested: NestedErrorShape | undefined,
+): Record<string, unknown> | undefined {
+  if (!nested) return undefined;
+  const extras = detailsFromBody(nested) ?? {};
+  delete extras.details;
+  const direct = typeof nested.details === 'object' && nested.details !== null
+    ? nested.details as Record<string, unknown>
+    : {};
+  const merged = { ...extras, ...direct };
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
 export function translateHttpError(
   status: number,
   body: unknown,
@@ -911,6 +924,10 @@ export function translateHttpError(
     typeof body === 'object' && body !== null && 'request_id' in body
       ? (body as { request_id?: unknown }).request_id
       : undefined;
+  const details = {
+    ...(detailsFromBody(body) ?? {}),
+    ...(detailsFromNestedError(nested) ?? {}),
+  };
 
   return errorFromWire(message, {
     code,
@@ -918,7 +935,7 @@ export function translateHttpError(
     requestId: requestId ?? (typeof bodyRequestId === 'string' ? bodyRequestId : undefined),
     requiredCapability,
     claims,
-    details: detailsFromBody(body),
+    details: Object.keys(details).length > 0 ? details : undefined,
   });
 }
 

package/src/index.ts

@@ -31,6 +31,7 @@ export { Ablo } from './client/ablo.js';
 export type {
   AbloHttpClient,
   AbloHttpClientOptions,
+  AbloWebSocketClient,
   CapturedRow,
   HttpModelClient,
   HttpModelMutationParams,

package/src/sessions/client.ts

@@ -0,0 +1,121 @@
+/**
+ * Server-side session issuer.
+ *
+ * This is deliberately separate from `Ablo(...)`: the participant client owns
+ * schema model properties, while this client owns credential issuance and
+ * lifecycle administration. A schema model named `sessions` therefore remains
+ * available as `ablo.sessions` like every other model.
+ */
+
+import type { CredentialProvider } from '../auth/credentialResult.js';
+import {
+  assertBrowserSafety,
+  readProcessEnv,
+  rejectRemovedDatabaseUrlOption,
+  resolveApiKey,
+  resolveApiKeyValue,
+  resolveBaseURL,
+  resolveBootstrapBaseUrl,
+  warnIfCliKeyMismatch,
+} from '../auth/apiKey.js';
+import { modelWireNames } from '../auth/capability.js';
+import {
+  revokeCapability,
+  rotateCapability,
+} from '../auth/capabilityLifecycle.js';
+import { AbloAuthenticationError } from '../errors.js';
+import type { Schema, SchemaRecord } from '../schema/schema.js';
+import type {
+  AbloSession,
+  CreateSessionParams,
+  RevokeSessionParams,
+  RotateSessionParams,
+  SessionRevocation,
+  SessionRotation,
+} from './contract.js';
+import { createSession } from './create.js';
+import {
+  createSessionHandler,
+  type SessionHandler,
+  type SessionHandlerOptions,
+} from './handler.js';
+
+export interface SessionsOptions<S extends SchemaRecord> {
+  readonly schema: Schema<S>;
+  readonly apiKey?: string | CredentialProvider | null;
+  readonly baseURL?: string | null;
+  readonly bootstrapBaseUrl?: string;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly dangerouslyAllowBrowser?: boolean;
+}
+
+export interface SessionsClient<S extends SchemaRecord> {
+  create(params: CreateSessionParams<S>): Promise<AbloSession>;
+  handler<Principal>(options: SessionHandlerOptions<S, Principal>): SessionHandler;
+  revoke(params: RevokeSessionParams): Promise<SessionRevocation>;
+  rotate(params: RotateSessionParams): Promise<SessionRotation>;
+}
+
+/** Construct the server-side issuer for user and agent sessions. */
+export function Sessions<const S extends SchemaRecord>(
+  options: SessionsOptions<S>,
+): SessionsClient<S> {
+  const env = readProcessEnv();
+  const authInput = { options, env };
+  const configuredApiKey = resolveApiKey(authInput);
+  void warnIfCliKeyMismatch(authInput);
+  rejectRemovedDatabaseUrlOption(options);
+  assertBrowserSafety({
+    apiKey: configuredApiKey,
+    dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
+  });
+
+  const baseUrl = resolveBootstrapBaseUrl({
+    url: resolveBaseURL(authInput),
+    bootstrapBaseUrl: options.bootstrapBaseUrl,
+  }).replace(/\/+$/, '');
+  const modelTypenames = modelWireNames(options.schema.models);
+
+  async function secret(): Promise<string> {
+    const apiKey = await resolveApiKeyValue(configuredApiKey);
+    if (!apiKey) {
+      throw new AbloAuthenticationError(
+        'Sessions requires a secret (sk_) API key and must be constructed on the backend.',
+        { code: 'apikey_missing' },
+      );
+    }
+    return apiKey;
+  }
+
+  async function create(params: CreateSessionParams<S>): Promise<AbloSession> {
+    return createSession(params, {
+      apiKey: await secret(),
+      baseUrl,
+      modelTypenames,
+      ...(options.fetch ? { fetch: options.fetch } : {}),
+    });
+  }
+
+  return {
+    create,
+    handler: (handlerOptions) => createSessionHandler(create, handlerOptions),
+    async revoke({ id }) {
+      return revokeCapability({
+        apiKey: await secret(),
+        baseUrl,
+        id,
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+      });
+    },
+    async rotate({ id, graceSeconds, ttlSeconds }) {
+      return rotateCapability({
+        apiKey: await secret(),
+        baseUrl,
+        id,
+        ...(graceSeconds !== undefined ? { graceSeconds } : {}),
+        ...(ttlSeconds !== undefined ? { ttlSeconds } : {}),
+        ...(options.fetch ? { fetch: options.fetch } : {}),
+      });
+    },
+  };
+}

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';