@abloatai/transaction 0.55.0 → 0.57.0

package/src/source/adapters/prisma.ts

@@ -33,11 +33,22 @@ import {
   sourceChangeIntentHash,
 } from '../idempotency.js';
 import type { SchemaRecord, Schema } from '../../schema/schema.js';
+import { toSchemaJSON } from '../../schema/serialize.js';
+import { camelToSnake } from '../../schema/ddl.js';
 import {
   ABLO_POSTGRES_COMMIT_ECHO_PREFIX,
   type SourceListQuery,
   type SourceWhere,
 } from '../types.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  rethrowStrictCreateConflict,
+  sourceSyncGroups,
+  sourceSubjectRule,
+  sourceSubjectValues,
+} from '../subjectAuthorization.js';
 
 /** A Prisma model delegate — the subset of its methods the adapter calls. */
 export interface PrismaDelegate {
@@ -146,7 +157,19 @@ export function prismaDataSource<S extends SchemaRecord>(
   options: PrismaDataSourceOptions = {},
 ): DataSourceAdapter {
   const delegateName = options.delegateName ?? lowerFirst;
-  void schema; // held for typed reads and model validation
+  const lockTargets = new Map<string, { table: string; subjectColumn: string }>();
+  for (const [key, definition] of Object.entries(toSchemaJSON(schema).models)) {
+    if (!definition.subject) continue;
+    const target = {
+      table: definition.tableName ?? key,
+      subjectColumn:
+        definition.fields[definition.subject.field]?.column ??
+        camelToSnake(definition.subject.field),
+    };
+    lockTargets.set(key.toLowerCase(), target);
+    if (definition.typename) lockTargets.set(definition.typename.toLowerCase(), target);
+  }
+  const quoted = (identifier: string): string => `"${identifier.replaceAll('"', '""')}"`;
 
   const applyOperation = async (tx: PrismaRaw, op: Operation): Promise<Row> => {
     if (op.where) {
@@ -188,9 +211,18 @@ export function prismaDataSource<S extends SchemaRecord>(
       const delegate = delegateFor(prisma, delegateName(req.model));
       if (req.kind === 'load') {
         const row = await delegate.findUnique({ where: { id: req.id } });
-        return row ? [row] : [];
+        return authorizeSourceRead(schema, req, row ? [row] : []);
       }
-      return delegate.findMany(findManyArgs(req.query));
+      const args = findManyArgs(req.query);
+      const rule = sourceSubjectRule(schema, req.model);
+      const subjects = sourceSubjectValues(rule, req.scope?.syncGroups);
+      if (subjects?.length === 0) return [];
+      if (subjects) {
+        args.where = {
+          AND: [args.where ?? {}, { [rule!.field]: { in: subjects } }],
+        };
+      }
+      return authorizeSourceRead(schema, req, await delegate.findMany(args));
     },
 
     async commit(change: ChangeSet): Promise<AdapterCommitResult> {
@@ -211,22 +243,52 @@ export function prismaDataSource<S extends SchemaRecord>(
           return { rows: cachedRow.response };
         }
 
+        await lockSourceSubjectCreates(schema, change, async (_operation, key) => {
+          await tx.$queryRawUnsafe(
+            `SELECT pg_advisory_xact_lock(hashtextextended($1, 0))`,
+            key,
+          );
+        });
+
+        await authorizeSourceChange(schema, change, async (operation) => {
+          if (!operation.id) return null;
+          const rule = sourceSubjectRule(schema, operation.model);
+          const target = lockTargets.get(operation.model.toLowerCase());
+          if (!rule || !target) return null;
+          const rows = await tx.$queryRawUnsafe<Row[]>(
+            `SELECT id, ${quoted(target.subjectColumn)} AS ${quoted(rule.field)}
+               FROM ${quoted(target.table)}
+              WHERE id = $1
+              LIMIT 1
+              FOR UPDATE`,
+            operation.id,
+          );
+          return rows[0] ?? null;
+        });
+
         const rows: Row[] = [];
         for (const [index, op] of change.operations.entries()) {
-          const row = await applyOperation(tx, op);
+          let row: Row;
+          try {
+            row = await applyOperation(tx, op);
+          } catch (error) {
+            if (op.type === 'CREATE') rethrowStrictCreateConflict(error, op);
+            throw error;
+          }
           rows.push(row);
           const entityId = String(row.id ?? rowId(op));
           // Transactional outbox: one event per operation, written in this same transaction.
           await tx.$executeRawUnsafe(
             `INSERT INTO ablo_outbox (
-               id, model, entity_id, type, data,
+               id, model, entity_id, type, data, sync_groups,
                correlation_id, transaction_id, occurred_at
-             ) VALUES ($1, $2, $3, $4, $5::jsonb, $6, $7, $8)`,
+             ) VALUES ($1, $2, $3, $4, $5::jsonb, $6::text[], $7, $8, $9)`,
             `${change.correlationId}:${index}`,
             op.model,
             entityId,
             op.type,
             JSON.stringify(op.type === 'DELETE' ? null : row),
+            sourceSyncGroups(schema, op.model, row),
             change.correlationId,
             op.transactionId ?? null,
             Date.now(),
@@ -260,7 +322,7 @@ export function prismaDataSource<S extends SchemaRecord>(
     async events(cursor: string | null, limit: number): Promise<EventsPage> {
       const after = cursor ? cursor : '0';
       const rows = await prisma.$queryRawUnsafe<Record<string, unknown>[]>(
-        `SELECT cursor, id, model, entity_id, type, data, organization_id,
+        `SELECT cursor, id, model, entity_id, type, data, sync_groups, organization_id,
                 client_tx_id, correlation_id, transaction_id, occurred_at
          FROM ablo_outbox WHERE cursor > $1 ORDER BY cursor ASC LIMIT $2`,
         after,
@@ -273,6 +335,7 @@ export function prismaDataSource<S extends SchemaRecord>(
           entityId: r.entity_id,
           type: r.type,
           data: r.data ?? null,
+          syncGroups: r.sync_groups ?? [],
           organizationId: r.organization_id ?? null,
           clientTxId: r.client_tx_id ?? null,
           correlationId: r.correlation_id ?? null,

package/src/source/contract.ts

@@ -29,6 +29,7 @@ import {
   type SourceCommitEchoMarker,
   type SourceOperation,
 } from './types.js';
+import type { SourceRequestContext } from './types.js';
 
 const jsonObject = z.record(z.string(), z.unknown());
 
@@ -149,6 +150,14 @@ export const changeSetSchema = z.object({
   correlationId: correlationIdSchema,
   intentHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
   echo: sourceCommitEchoSchema.optional(),
+  scope: z.object({
+    participantId: z.string().optional(),
+    participantKind: z.enum(['user', 'agent', 'system']).optional(),
+    organizationId: z.string().optional(),
+    branchId: z.string().optional(),
+    projectId: z.string().optional(),
+    syncGroups: z.array(z.string()).optional(),
+  }).optional() satisfies z.ZodType<SourceRequestContext | undefined>,
 });
 export type ChangeSet = z.infer<typeof changeSetSchema>;
 
@@ -168,6 +177,8 @@ export const outboxEventSchema = z.object({
   /** The changed row, in the key shape `SourceEvent.data` defines: the model's
    *  declared schema fields, never the table's physical column names. */
   data: jsonObject.nullish(),
+  /** Exact record routes captured in the same transaction as the row change. */
+  syncGroups: z.array(z.string().min(1)).readonly(),
   organizationId: z.string().nullish(),
   /** Legacy source transaction id. Never use this field to settle a queued commit. */
   clientTxId: z.string().nullish(),

package/src/source/factory.ts

@@ -12,7 +12,16 @@ import type {
   InferCreate,
 } from '../schema/schema.js';
 import type { DataSourceAdapter } from './adapter.js';
+import type { AdapterReadRequest, Row } from './adapter.js';
 import { changeSetSchema } from './contract.js';
+import { AbloError, AbloPermissionError } from '../errors.js';
+import {
+  authorizeSourceChange,
+  authorizeSourceRead,
+  lockSourceSubjectCreates,
+  sourceSubjectRule,
+  sourceSubjectValues,
+} from './subjectAuthorization.js';
 import {
   SourceSignatureError,
   verifyAbloSourceRequest,
@@ -31,6 +40,7 @@ import type {
   SourceRequest,
   SourceRequestContext,
   SourceScope,
+  SourceSubjectTransactionHandler,
 } from './types.js';
 
 type SourceModels<S extends SchemaRecord, TAuth> = Partial<{
@@ -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);
@@ -195,6 +212,7 @@ async function handleViaAdapter(
         entityId: event.entityId,
         type: event.type,
         ...(event.data !== undefined && event.data !== null ? { data: event.data } : {}),
+        syncGroups: event.syncGroups,
         ...(event.organizationId ? { organizationId: event.organizationId } : {}),
         ...(event.clientTxId ? { clientTxId: event.clientTxId } : {}),
         ...(event.correlationId ? { correlationId: event.correlationId } : {}),
@@ -277,6 +295,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 +414,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 +429,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,

package/src/source/index.ts

@@ -37,6 +37,8 @@ export {
   type SourceHandlerContext,
   type SourceModelHandlers,
   type SourceCommitHandler,
+  type SourceSubjectTransactionBoundary,
+  type SourceSubjectTransactionHandler,
   type SourceApiKey,
   type SourceLoadRequest,
   type SourceListRequest,
@@ -61,6 +63,10 @@ export {
   type DataSourceOptions,
 } from './factory.js';
 
+export {
+  sourceSubjectCreateLockKey,
+} from './subjectAuthorization.js';
+
 export {
   createPushQueue,
   InMemoryPushQueueStorage,

package/src/source/migrations.ts

@@ -99,6 +99,7 @@ export function endpointOutboxMigrations(): readonly Migration[] {
   entity_id       TEXT NOT NULL,
   type            TEXT NOT NULL,
   data            JSONB,
+  sync_groups      TEXT[] NOT NULL,
   organization_id TEXT,
   client_tx_id    TEXT,
   correlation_id  TEXT,
@@ -114,6 +115,26 @@ export function endpointOutboxMigrations(): readonly Migration[] {
 ALTER TABLE ablo_outbox
   ADD COLUMN IF NOT EXISTS transaction_id TEXT;`,
     },
+    {
+      name: 'ablo_outbox_sync_groups',
+      up: `DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM information_schema.columns
+     WHERE table_schema = current_schema()
+       AND table_name = 'ablo_outbox'
+       AND column_name = 'sync_groups'
+  ) AND EXISTS (SELECT 1 FROM ablo_outbox) THEN
+    RAISE EXCEPTION USING
+      ERRCODE = '55000',
+      MESSAGE = 'ablo_outbox contains legacy events; verify the previous release consumed them, then purge those rows before adding sync_groups';
+  END IF;
+END $$;
+ALTER TABLE ablo_outbox
+  ADD COLUMN IF NOT EXISTS sync_groups TEXT[];
+ALTER TABLE ablo_outbox
+  ALTER COLUMN sync_groups SET NOT NULL;`,
+    },
   ];
 }
 

package/src/source/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();
+    }
+  }
+}