@abloatai/transaction 0.59.2 → 0.61.0

package/src/errors.ts

@@ -23,12 +23,24 @@ import { ABLO_DOCS_BASE_URL } from './auth/hostedEndpoints.js';
 import { errorCodeSpec, classifyRecovery } from './errorCodes.js';
 import {
   wireClaimSummarySchema,
+  wireParticipantKindSchema,
+  modelTargetSchema,
   descriptionFromMeta,
   type WireClaimSummary,
   type ModelClaim,
   type ModelTarget,
   type ParticipantKind,
 } from './coordination/schema.js';
+import {
+  claimConflictContextSchema,
+  normalizeClaimConflict,
+  type ClaimConflictContext,
+} from './claims/conflict.js';
+
+export type {
+  ClaimConflictContext,
+  ClaimConflictCounterparty,
+} from './claims/conflict.js';
 
 export type { ErrorCode, WireErrorCode, ErrorCategory, ErrorCodeSpec, RecoveryClass } from './errorCodes.js';
 export {
@@ -368,6 +380,44 @@ export interface ClaimContext {
 
 export type ClaimErrorClaim = WireClaimSummary | ClaimContext;
 
+function conflictFromClaims(
+  claims: readonly ClaimErrorClaim[] | undefined,
+): ClaimConflictContext | undefined {
+  const claim = claims?.[0];
+  if (!claim) return undefined;
+  const summary = wireClaimSummarySchema.safeParse(claim);
+  if (summary.success) {
+    const actor = 'actor' in claim && typeof claim.actor === 'string'
+      ? claim.actor
+      : undefined;
+    return normalizeClaimConflict({
+      heldByClaim: summary.data,
+      ...(actor !== undefined ? { heldBy: actor } : {}),
+    });
+  }
+  const context = claim as ClaimContext;
+  return normalizeClaimConflict({
+    ...(context.actor !== undefined ? { heldBy: context.actor } : {}),
+    ...(context.participantKind !== undefined
+      ? { heldByKind: context.participantKind }
+      : {}),
+    ...(context.claimId !== undefined ? { heldByClaimId: context.claimId } : {}),
+    ...(context.description !== undefined ? { description: context.description } : {}),
+    ...(context.expiresAt !== undefined ? { expiresAt: context.expiresAt } : {}),
+    ...(context.target !== undefined
+      ? { target: context.target }
+      : context.entityType !== undefined || context.entityId !== undefined
+        ? {
+            target: {
+              ...(context.entityType !== undefined ? { model: context.entityType } : {}),
+              ...(context.entityId !== undefined ? { id: context.entityId } : {}),
+              ...(context.field !== undefined ? { field: context.field } : {}),
+            },
+          }
+        : {}),
+  });
+}
+
 function claimDescription(claim: ClaimErrorClaim | undefined): string | undefined {
   if (!claim) return undefined;
   if ('description' in claim && typeof claim.description === 'string') {
@@ -434,6 +484,7 @@ export function formatClaimedErrorMessage(args: {
 export class AbloClaimedError extends AbloError {
   override readonly type = 'AbloClaimedError' as const;
   readonly claims?: readonly ClaimErrorClaim[];
+  readonly conflict?: ClaimConflictContext;
 
   constructor(
     message: string,
@@ -443,10 +494,22 @@ export class AbloClaimedError extends AbloError {
       requestId?: string;
       cause?: unknown;
       claims?: readonly ClaimErrorClaim[];
+      conflict?: ClaimConflictContext;
+      details?: Readonly<Record<string, unknown>>;
     },
   ) {
-    super(message, options);
+    const conflict = options?.conflict ?? conflictFromClaims(options?.claims);
+    const details = {
+      ...(options?.details ?? {}),
+      ...(options?.claims !== undefined ? { claims: options.claims } : {}),
+      ...(conflict !== undefined ? { conflict } : {}),
+    };
+    super(message, {
+      ...options,
+      ...(Object.keys(details).length > 0 ? { details } : {}),
+    });
     if (options?.claims !== undefined) this.claims = options.claims;
+    if (conflict !== undefined) this.conflict = conflict;
   }
 }
 
@@ -681,8 +744,13 @@ const NestedErrorShapeSchema = z
     field: OptionalWireStringSchema,
     requiredCapability: requiredCapabilityWireSchema.optional().catch(undefined),
     heldBy: OptionalWireStringSchema,
+    heldByKind: wireParticipantKindSchema.optional().catch(undefined),
+    heldByClaimId: OptionalWireStringSchema,
+    heldByExpiresAt: z.number().optional().catch(undefined),
     heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
     claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
+    conflict: claimConflictContextSchema.optional().catch(undefined),
+    target: modelTargetSchema.unwrap().partial().optional().catch(undefined),
   })
   .loose();
 
@@ -706,8 +774,13 @@ const ErrorBodyShapeSchema = z
     message: OptionalWireStringSchema,
     requiredCapability: requiredCapabilityWireSchema.optional().catch(undefined),
     heldBy: OptionalWireStringSchema,
+    heldByKind: wireParticipantKindSchema.optional().catch(undefined),
+    heldByClaimId: OptionalWireStringSchema,
+    heldByExpiresAt: z.number().optional().catch(undefined),
     heldByClaim: wireClaimSummarySchema.optional().catch(undefined),
     claims: z.array(wireClaimSummarySchema).optional().catch(undefined),
+    conflict: claimConflictContextSchema.optional().catch(undefined),
+    target: modelTargetSchema.unwrap().partial().optional().catch(undefined),
   })
   .loose();
 
@@ -763,11 +836,12 @@ export function errorFromWire(
     requestId?: string;
     requiredCapability?: RequiredCapability;
     claims?: readonly ClaimErrorClaim[];
+    conflict?: ClaimConflictContext;
     /** Everything the producer attached beyond the envelope's own fields. */
     details?: Readonly<Record<string, unknown>>;
   } = {},
 ): AbloError {
-  const { code, requestId, requiredCapability, claims, details } = opts;
+  const { code, requestId, requiredCapability, claims, conflict, details } = 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).
@@ -802,9 +876,16 @@ export function errorFromWire(
   if (
     code === 'claim_conflict' ||
     code === 'entity_claimed' ||
-    code === 'claim_lost'
+    code === 'claim_lost' ||
+    code === 'fence_token_stale' ||
+    code === 'model_claimed' ||
+    code === 'model_claimed_timeout' ||
+    code === 'claim_lease_unavailable' ||
+    code === 'claim_wait_aborted' ||
+    code === 'grant_timeout' ||
+    code === 'claim_queued'
   ) {
-    return new AbloClaimedError(message, { ...baseOpts, claims });
+    return new AbloClaimedError(message, { ...baseOpts, claims, conflict });
   }
   // A write whose `readAt` watermark went stale — callers re-read and retry.
   if (code === 'stale_context') {
@@ -854,6 +935,12 @@ const ENVELOPE_KEYS: ReadonlySet<string> = new Set([
   'requiredCapability',
   'claims',
   'heldByClaim',
+  'heldBy',
+  'heldByKind',
+  'heldByClaimId',
+  'heldByExpiresAt',
+  'conflict',
+  'target',
   // `reason` is deliberately NOT here: it is domain detail (a driver's words
   // beside the server's message), not an envelope field — the canonical
   // envelope schema has no such key — so it must survive into `details` for a
@@ -916,6 +1003,30 @@ export function translateHttpError(
       : nested?.heldByClaim
         ? [nested.heldByClaim]
         : undefined);
+  const conflict =
+    parsed.conflict ??
+    nested?.conflict ??
+    normalizeClaimConflict({
+      ...(parsed.heldBy ?? nested?.heldBy
+        ? { heldBy: parsed.heldBy ?? nested?.heldBy }
+        : {}),
+      ...(parsed.heldByKind ?? nested?.heldByKind
+        ? { heldByKind: parsed.heldByKind ?? nested?.heldByKind }
+        : {}),
+      ...(parsed.heldByClaimId ?? nested?.heldByClaimId
+        ? { heldByClaimId: parsed.heldByClaimId ?? nested?.heldByClaimId }
+        : {}),
+      ...(parsed.heldByExpiresAt ?? nested?.heldByExpiresAt
+        ? { heldByExpiresAt: parsed.heldByExpiresAt ?? nested?.heldByExpiresAt }
+        : {}),
+      ...(parsed.heldByClaim ?? nested?.heldByClaim
+        ? { heldByClaim: parsed.heldByClaim ?? nested?.heldByClaim }
+        : {}),
+      ...(parsed.target ?? nested?.target
+        ? { target: parsed.target ?? nested?.target }
+        : {}),
+    }) ??
+    conflictFromClaims(claims);
 
   // The envelope carries `request_id`, so a caller that has only the body still
   // gets the correlation id — without this it was dropped unless the caller
@@ -935,6 +1046,7 @@ export function translateHttpError(
     requestId: requestId ?? (typeof bodyRequestId === 'string' ? bodyRequestId : undefined),
     requiredCapability,
     claims,
+    conflict,
     details: Object.keys(details).length > 0 ? details : undefined,
   });
 }

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

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`