@abloatai/transaction 0.56.0 → 0.58.0

package/src/source/adapters/subjectAuthorization.ts

@@ -0,0 +1,182 @@
+import { AbloPermissionError, AbloValidationError } from '../../errors.js';
+import {
+  composeEntitySyncGroups,
+  syncGroupsForRow,
+  InvalidRecordSubjectError,
+  scopeKindOf,
+  subjectAuthorized,
+  type Schema,
+  type SchemaRecord,
+  type SubjectRule,
+} from '../../schema/index.js';
+import type { AdapterReadRequest, Row } from './adapter.js';
+import type { ChangeSet, Operation } from './contract.js';
+
+function sourceModelEntry<S extends SchemaRecord>(schema: Schema<S>, model: string) {
+  return Object.entries(schema.models).find(([key, def]) =>
+    key === model || key.toLowerCase() === model.toLowerCase() ||
+    def.typename === model || def.typename?.toLowerCase() === model.toLowerCase(),
+  );
+}
+
+function deny(): never {
+  throw new AbloPermissionError('The resolved scope does not cover the requested row.', {
+    code: 'capability_scope_denied',
+    httpStatus: 403,
+  });
+}
+
+export function sourceSubjectRule<S extends SchemaRecord>(
+  schema: Schema<S>,
+  model: string,
+): SubjectRule | undefined {
+  const entry = sourceModelEntry(schema, model);
+  return entry?.[1].subject;
+}
+
+/** Derive the durable record routes while the row is transactionally visible. */
+export function sourceSyncGroups<S extends SchemaRecord>(
+  schema: Schema<S>,
+  model: string,
+  row: Row,
+): readonly string[] {
+  const entry = sourceModelEntry(schema, model);
+  if (!entry) return [];
+  const [key, definition] = entry;
+  const parents: { kind: string; field: string }[] = [];
+  const selfKind = scopeKindOf(definition, key);
+  for (const relation of Object.values(definition.relations ?? {})) {
+    if (relation.type !== 'belongsTo' || relation.options?.parent !== true) continue;
+    const target = schema.models[relation.target];
+    const kind = target && scopeKindOf(target, relation.target);
+    if (kind) parents.push({ kind, field: relation.foreignKey });
+  }
+  try {
+    return syncGroupsForRow(
+      {
+        selfKind,
+        parents,
+        ...(definition.subject
+          ? { subject: { kind: definition.subject.group, field: definition.subject.field } }
+          : {}),
+      },
+      row,
+      composeEntitySyncGroups(row, definition),
+    );
+  } catch (error) {
+    if (!(error instanceof InvalidRecordSubjectError)) throw error;
+    throw new AbloValidationError(
+      `Source row ${model}/${String(row.id ?? '')} lacks subject field "${error.field}".`,
+      { code: 'source_event_invalid', cause: error },
+    );
+  }
+}
+
+/** Subject values represented by a trusted group set, preserving group order. */
+export function sourceSubjectValues(
+  rule: SubjectRule | undefined,
+  groups: readonly string[] | undefined,
+): readonly string[] | undefined {
+  if (!rule) return undefined;
+  const prefix = `${rule.group}:`;
+  return [...new Set(
+    (groups ?? [])
+      .filter((group) => group.startsWith(prefix))
+      .map((group) => group.slice(prefix.length))
+      .filter((value) => value.length > 0),
+  )];
+}
+
+/**
+ * Stable absent-row lock keys for caller-selected subject-scoped CREATE ids.
+ * Adapters acquire these in sorted order before loading current rows, so two
+ * authorized writers cannot both observe an absent id. Database uniqueness is
+ * still the final boundary against external writers that ignore this lock.
+ */
+function sourceSubjectCreateLockOperations<S extends SchemaRecord>(
+  schema: Schema<S>,
+  change: ChangeSet,
+): readonly Operation[] {
+  return change.operations
+    .filter((operation) =>
+      operation.type === 'CREATE' &&
+      typeof operation.id === 'string' &&
+      operation.id.length > 0 &&
+      sourceSubjectRule(schema, operation.model) !== undefined)
+    .sort((left, right) =>
+      `${left.model.toLowerCase()}\u0000${left.id}`.localeCompare(
+        `${right.model.toLowerCase()}\u0000${right.id}`,
+      ));
+}
+
+export function sourceSubjectCreateLockKey(operation: Operation): string {
+  return `ablo:subject-create:${operation.model.toLowerCase()}:${operation.id ?? ''}`;
+}
+
+/** Acquire every absent-key CREATE lock in canonical order. */
+export async function lockSourceSubjectCreates<S extends SchemaRecord>(
+  schema: Schema<S>,
+  change: ChangeSet,
+  acquire: (operation: Operation, key: string) => Promise<void>,
+): Promise<void> {
+  for (const operation of sourceSubjectCreateLockOperations(schema, change)) {
+    await acquire(operation, sourceSubjectCreateLockKey(operation));
+  }
+}
+
+function errorCode(error: unknown): unknown {
+  return error && typeof error === 'object' ? (error as { code?: unknown }).code : undefined;
+}
+
+/** Translate ORM/driver primary-key conflicts without exposing the winning row. */
+export function rethrowStrictCreateConflict(error: unknown, operation: Operation): never {
+  const code = errorCode(error) ?? errorCode(
+    error && typeof error === 'object' ? (error as { cause?: unknown }).cause : undefined,
+  );
+  if (code === '23505' || code === 'P2002') {
+    throw new AbloValidationError(
+      `A row already exists for ${operation.model}/${operation.id ?? ''}.`,
+      { code: 'entity_already_exists', httpStatus: 409, cause: error },
+    );
+  }
+  throw error;
+}
+
+export function authorizeSourceRead<S extends SchemaRecord>(
+  schema: Schema<S>,
+  req: AdapterReadRequest,
+  rows: readonly Row[],
+): readonly Row[] {
+  const rule = sourceSubjectRule(schema, req.model);
+  if (!rule) return rows;
+  const groups = req.scope?.syncGroups;
+  const authorized = rows.filter((row) => subjectAuthorized(rule, row, groups));
+  if (req.kind === 'load' && rows.length > 0 && authorized.length === 0) deny();
+  return authorized;
+}
+
+function authorizePayload(rule: SubjectRule, row: Row, groups: readonly string[] | undefined): void {
+  if (!subjectAuthorized(rule, row, groups)) deny();
+}
+
+export async function authorizeSourceChange<S extends SchemaRecord>(
+  schema: Schema<S>,
+  change: ChangeSet,
+  load: (operation: Operation) => Promise<Row | null>,
+): Promise<void> {
+  for (const operation of change.operations) {
+    const rule = sourceSubjectRule(schema, operation.model);
+    if (!rule) continue;
+    const current = operation.id ? await load(operation) : null;
+    if (current) authorizePayload(rule, current, change.scope?.syncGroups);
+    if (operation.type === 'CREATE') {
+      authorizePayload(rule, operation.input ?? {}, change.scope?.syncGroups);
+    } else if (!current) {
+      deny();
+    }
+    if (current && operation.input && Object.hasOwn(operation.input, rule.field) &&
+        !Object.is(current[rule.field], operation.input[rule.field])) {
+      deny();
+    }
+  }
+}

package/src/source/{connector.ts → connector/client.ts}

@@ -26,6 +26,7 @@
 
 import {
   SOURCE_CONNECTOR_PROTOCOL_VERSION,
+  SOURCE_CONNECTOR_SUPERSEDED_CLOSE_CODE,
   SOURCE_CONNECTOR_WS_PATH,
   sourceConnectorSubprotocols,
   encodeFrame,
@@ -35,8 +36,8 @@ import {
   type RequestFrame,
   type ResponseFrame,
   type ReadyFrame,
-} from './connectorProtocol.js';
-import { ABLO_HOSTED_HTTP_BASE_URL } from '../auth/hostedEndpoints.js';
+} from './protocol.js';
+import { ABLO_HOSTED_HTTP_BASE_URL } from '../../auth/hostedEndpoints.js';
 
 /**
  * The default Ablo base URL the connector dials, to which it appends
@@ -130,6 +131,20 @@ export interface SourceConnector {
   run(signal: AbortSignal): Promise<void>;
 }
 
+/** The connector lost its source lease to a newer process and will not reconnect. */
+export class SourceConnectorSupersededError extends Error {
+  readonly code = 'source_connector_superseded';
+
+  constructor() {
+    super(
+      'A newer local connector took ownership of this source; this connector has stopped.',
+    );
+    this.name = 'SourceConnectorSupersededError';
+  }
+}
+
+type ConnectionOutcome = 'retry' | 'ready' | 'superseded';
+
 export function createSourceConnector(
   options: SourceConnectorOptions,
 ): SourceConnector {
@@ -148,7 +163,7 @@ export function createSourceConnector(
         if (signal.aborted) return;
 
         options.onStatus?.('connecting');
-        const becameReady = await connectOnce({
+        const outcome = await connectOnce({
           url,
           apiKey: options.apiKey,
           handler: options.handler,
@@ -158,9 +173,10 @@ export function createSourceConnector(
           onError: options.onError,
           signal,
         });
+        if (outcome === 'superseded') return;
         // A connection that reached `ready` resets the backoff so the next
         // drop reconnects immediately; one that never readied keeps escalating.
-        attempt = becameReady ? 0 : attempt + 1;
+        attempt = outcome === 'ready' ? 0 : attempt + 1;
       }
     },
   };
@@ -169,8 +185,10 @@ export function createSourceConnector(
 /**
  * Runs one connection: open the socket, register, then serve requests until the
  * socket closes or `signal` aborts. Resolves to whether the connection reached the
- * `ready` state, which the caller uses to reset the reconnect backoff. It never
- * rejects, because a dropped transport is expected and simply drives a reconnect.
+ * `ready` state, which the caller uses to reset the reconnect backoff, or the
+ * terminal `superseded` fence, which stops this process from taking ownership
+ * back from its replacement. It never rejects because ordinary transport drops
+ * are expected and simply drive a reconnect.
  */
 function connectOnce(params: {
   readonly url: string;
@@ -181,8 +199,8 @@ function connectOnce(params: {
   readonly onStatus: ((status: ConnectorStatus) => void) | undefined;
   readonly onError: ((error: unknown) => void) | undefined;
   readonly signal: AbortSignal;
-}): Promise<boolean> {
-  return new Promise<boolean>((resolve) => {
+}): Promise<ConnectionOutcome> {
+  return new Promise<ConnectionOutcome>((resolve) => {
     let ws: ConnectorWebSocket;
     try {
       ws = params.factory(
@@ -191,18 +209,18 @@ function connectOnce(params: {
       );
     } catch (err) {
       params.onError?.(err);
-      resolve(false);
+      resolve('retry');
       return;
     }
 
     let ready = false;
     let settled = false;
-    const finish = (): void => {
+    const finish = (outcome: ConnectionOutcome = ready ? 'ready' : 'retry'): void => {
       if (settled) return;
       settled = true;
       params.signal.removeEventListener('abort', onAbort);
       params.onStatus?.('disconnected');
-      resolve(ready);
+      resolve(outcome);
     };
 
     const onAbort = (): void => {
@@ -243,7 +261,12 @@ function connectOnce(params: {
       // `close` always follows `error`; finish() runs there.
     });
 
-    ws.addEventListener('close', () => {
+    ws.addEventListener('close', (event) => {
+      if (event.code === SOURCE_CONNECTOR_SUPERSEDED_CLOSE_CODE) {
+        params.onError?.(new SourceConnectorSupersededError());
+        finish('superseded');
+        return;
+      }
       finish();
     });
 

package/src/source/connector/index.ts

@@ -0,0 +1,3 @@
+/** Outbound Data Source connector boundary: client runtime and wire protocol. */
+export * from './client.js';
+export * from './protocol.js';

package/src/source/{connectorProtocol.ts → connector/protocol.ts}

@@ -22,8 +22,8 @@
 
 import { z } from 'zod';
 
-import { environmentSchema } from '../environment.js';
-import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
+import { environmentSchema } from '../../environment.js';
+import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../../auth/credentialSource.js';
 
 /**
  * The wire-protocol version. It increases on any breaking change to a frame's
@@ -43,6 +43,14 @@ export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
  */
 export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
 
+/**
+ * Private WebSocket close code used when a newer connector takes ownership of
+ * the same source. This is a fencing decision, not a transient disconnect: the
+ * superseded process must stop reconnecting or two `ablo dev --local`
+ * processes will continuously replace each other.
+ */
+export const SOURCE_CONNECTOR_SUPERSEDED_CLOSE_CODE = 4009;
+
 /**
  * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
  * handshake: the source subprotocol followed by the bearer credential, encoded as

package/src/source/delivery/index.ts

@@ -0,0 +1,2 @@
+/** Data Source push-delivery boundary. */
+export * from './pushQueue.js';

package/src/source/{pushQueue.ts → delivery/pushQueue.ts}

@@ -23,8 +23,8 @@
  * interface against your own outbox table for production durability.
  */
 
-import { ABLO_SOURCE_HEADERS, signAbloSourceRequest } from './signing.js';
-import type { SourceEvent } from './types.js';
+import { ABLO_SOURCE_HEADERS, signAbloSourceRequest } from '../endpoint/signing.js';
+import type { SourceEvent } from '../types.js';
 
 /** One queued delivery: a batch of source events plus its retry bookkeeping. */
 export interface PushQueueItem {

package/src/source/{factory.ts → endpoint/factory.ts}

@@ -10,9 +10,18 @@ import type {
   Schema,
   SchemaRecord,
   InferCreate,
-} from '../schema/schema.js';
-import type { DataSourceAdapter } from './adapter.js';
-import { changeSetSchema } from './contract.js';
+} from '../../schema/schema.js';
+import type { DataSourceAdapter } from '../adapters/adapter.js';
+import type { AdapterReadRequest, Row } from '../adapters/adapter.js';
+import { changeSetSchema } from '../adapters/contract.js';
+import { AbloError, AbloPermissionError } from '../../errors.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  sourceSubjectRule,
+  sourceSubjectValues,
+} from '../adapters/subjectAuthorization.js';
 import {
   SourceSignatureError,
   verifyAbloSourceRequest,
@@ -31,7 +40,8 @@ import type {
   SourceRequest,
   SourceRequestContext,
   SourceScope,
-} from './types.js';
+  SourceSubjectTransactionHandler,
+} from '../types.js';
 
 type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
   readonly [K in keyof S & string]: SourceModelHandlers<
@@ -86,6 +96,12 @@ export type DataSourceOptions<S extends SchemaRecord, TAuth = unknown> = {
    * run inside one transaction you control.
    */
   readonly commit?: SourceCommitHandler<TAuth>;
+  /**
+   * Required for a hand-written commit touching any subject-scoped model.
+   * The hook owns one customer-database transaction and calls `run` with a
+   * locking row loader and the batch commit bound to that same transaction.
+   */
+  readonly subjectTransaction?: SourceSubjectTransactionHandler<TAuth>;
   /**
    * Reports changes that happened outside the SDK — cron jobs, dashboard edits,
    * batch imports — which Ablo polls for. Each event you return becomes a delta and
@@ -165,6 +181,7 @@ async function handleViaAdapter(
       correlationId,
       intentHash: body.intentHash,
       echo: body.echo,
+      scope,
     });
     if (!parsed.success) {
       return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
@@ -187,14 +204,19 @@ async function handleViaAdapter(
   }
 
   if (body.type === 'events') {
+    if (body.acknowledgedThrough) {
+      await adapter.acknowledgeEvents(body.acknowledgedThrough);
+    }
     const page = await adapter.events(body.cursor ?? null, body.limit ?? 100);
     return json({
       events: page.events.map((event) => ({
         id: event.id,
+        version: event.version,
         model: event.model,
         entityId: event.entityId,
         type: event.type,
         ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
+        ...(event.syncGroups ? { syncGroups: event.syncGroups } : {}),
         ...(event.organizationId ? { organizationId: event.organizationId } : {}),
         ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
         ...(event.correlationId ? { correlationId: event.correlationId } : {}),
@@ -277,6 +299,34 @@ function sameModel(operations: readonly SourceOperation[]): string | null {
   return operations.every((op) => op.model === first) ? first : null;
 }
 
+function subjectDenial(error: unknown): Response | null {
+  return error instanceof AbloPermissionError && error.code === 'capability_scope_denied'
+    ? json({ error: error.code, message: error.message }, error.httpStatus ?? 403)
+    : null;
+}
+
+function typedSourceError(error: unknown): Response | null {
+  const denial = subjectDenial(error);
+  if (denial) return denial;
+  return error instanceof AbloError && error.code && error.httpStatus
+    ? json({ error: error.code, message: error.message }, error.httpStatus)
+    : null;
+}
+
+function parseHandWrittenChange<TAuth>(
+  body: Extract<SourceRequest, { type: 'commit' }>,
+  context: SourceHandlerContext<TAuth>,
+) {
+  const correlationId = body.correlationId ?? body.clientTxId;
+  return changeSetSchema.safeParse({
+    operations: body.operations,
+    correlationId,
+    intentHash: body.intentHash,
+    echo: body.echo,
+    scope: context.scope,
+  });
+}
+
 /**
  * Creates a Data Source endpoint you host in front of your own database.
  *
@@ -368,7 +418,13 @@ export function dataSource<const S extends SchemaRecord, TAuth = unknown>(
     // generic layer where rows are plain JSON, so there is no per-model handler
     // lookup on this path.
     if (options.adapter) {
-      return handleViaAdapter(options.adapter, body, context.scope);
+      try {
+        return await handleViaAdapter(options.adapter, body, context.scope);
+      } catch (error) {
+        const typed = typedSourceError(error);
+        if (typed) return typed;
+        throw error;
+      }
     }
 
     if (body.type === 'load') {
@@ -377,20 +433,104 @@ export function dataSource<const S extends SchemaRecord, TAuth = unknown>(
         return json({ error: 'source_load_not_configured', model: body.model }, 404);
       }
       const row = await handlers.load({ id: body.id, context });
-      return json({ row });
+      try {
+        const authorized = authorizeSourceRead(
+          options.schema,
+          { kind: 'load', model: body.model, id: body.id, ...(context.scope ? { scope: context.scope } : {}) },
+          row ? [row as Row] : [],
+        );
+        return json({ row: authorized[0] ?? null });
+      } catch (error) {
+        const typed = typedSourceError(error);
+        if (typed) return typed;
+        throw error;
+      }
     }
 
     if (body.type === 'list') {
       const handlers = getModelHandlers(options, body.model);
-      if (!handlers?.list) {
+      const rule = sourceSubjectRule(options.schema, body.model);
+      if (rule && !handlers?.subjectList) {
+        return json({
+          error: 'source_subject_list_not_configured',
+          message: `Subject-scoped model "${body.model}" requires subjectList() so filtering occurs before pagination.`,
+        }, 403);
+      }
+      if (!rule && !handlers?.list) {
         return json({ error: 'source_list_not_configured', model: body.model }, 404);
       }
-      const result = await handlers.list({ query: body.query ?? {}, context });
+      const result = rule
+        ? await handlers!.subjectList!({
+            query: body.query ?? {},
+            subject: {
+              field: rule.field,
+              values: sourceSubjectValues(rule, context.scope?.syncGroups) ?? [],
+            },
+            context,
+          })
+        : await handlers!.list!({ query: body.query ?? {}, context });
       const normalized = normalizeListResult(result);
-      return json(normalized);
+      const request: AdapterReadRequest = {
+        kind: 'list',
+        model: body.model,
+        ...(body.query ? { query: body.query } : {}),
+        ...(context.scope ? { scope: context.scope } : {}),
+      };
+      return json({
+        ...normalized,
+        rows: authorizeSourceRead(options.schema, request, normalized.rows as readonly Row[]),
+      });
     }
 
     if (body.type === 'commit') {
+      const hasSubject = body.operations.some((operation) =>
+        sourceSubjectRule(options.schema, operation.model));
+      if (hasSubject) {
+        if (!options.subjectTransaction) {
+          return json({
+            error: 'source_subject_transaction_required',
+            message: 'Subject-scoped custom commits require subjectTransaction() so authorization and mutation share one transaction.',
+          }, 403);
+        }
+        const parsed = parseHandWrittenChange(body, context);
+        if (!parsed.success) {
+          return json({ error: 'source_commit_invalid', message: parsed.error.message }, 400);
+        }
+        try {
+          let ranBoundary = false;
+          const result = await options.subjectTransaction(
+            {
+              operations: body.operations,
+              correlationId: body.correlationId ?? body.clientTxId,
+              clientTxId: body.clientTxId,
+              intentHash: body.intentHash,
+              echo: body.echo,
+              context,
+            },
+            async ({ lockCreate, load, commit }) => {
+              if (ranBoundary) {
+                throw new Error('subjectTransaction run() may be called only once');
+              }
+              ranBoundary = true;
+              await lockSourceSubjectCreates(
+                options.schema,
+                parsed.data,
+                (operation) => lockCreate(operation),
+              );
+              await authorizeSourceChange(options.schema, parsed.data, load);
+              return commit();
+            },
+          );
+          if (!ranBoundary) {
+            throw new Error('subjectTransaction must call run() inside its database transaction');
+          }
+          return json(result);
+        } catch (error) {
+          const typed = typedSourceError(error);
+          if (typed) return typed;
+          throw error;
+        }
+      }
       if (options.commit) {
         const result = await options.commit({
           operations: body.operations,
@@ -428,6 +568,7 @@ export function dataSource<const S extends SchemaRecord, TAuth = unknown>(
       }
       const result = await options.events({
         cursor: body.cursor,
+        acknowledgedThrough: body.acknowledgedThrough,
         limit: body.limit,
         context,
       });

package/src/source/endpoint/index.ts

@@ -0,0 +1,4 @@
+/** Signed Data Source endpoint boundary: factory, signing, and framework adapter. */
+export * from './factory.js';
+export * from './signing.js';
+export * from './next.js';

package/src/source/{next.ts → endpoint/next.ts}

@@ -5,7 +5,7 @@
  * `POST` so your route file can export it in one line.
  *
  *   // app/api/ablo/source/route.ts
- *   import { dataSourceNext } from '@abloatai/transaction/source/next';
+ *   import { dataSourceNext } from '@abloatai/transaction/source/endpoint';
  *   import { prismaDataSource } from '@abloatai/transaction/source';
  *   import { schema } from '@/ablo/schema';
  *   import { prisma } from '@/lib/prisma';
@@ -20,7 +20,7 @@
  * directly and export its result however that framework expects.
  */
 
-import type { SchemaRecord } from '../schema/schema.js';
+import type { SchemaRecord } from '../../schema/schema.js';
 import { dataSource, type DataSourceOptions } from './factory.js';
 
 /**

package/src/source/{signing.ts → endpoint/signing.ts}

@@ -1,5 +1,5 @@
 /**
- * Canonically signs and verifies source requests using the Standard Webhooks scheme.
+ * Canonically signs and verifies source endpoint requests using the Standard Webhooks scheme.
  *
  * Every request Ablo sends to a data source is signed with that source's API
  * key, and the receiving endpoint verifies the signature before any handler