@objectstack/plugin-approvals 16.1.0 → 17.0.0-rc.0

package/src/approver-org-scope.ts

@@ -0,0 +1,261 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * [ADR-0105 D9] Cross-organization approver targeting — resolving WHICH
+ * organization's directory an approver is looked up in.
+ *
+ * One organization id used to do three jobs at once in `openNodeRequest`:
+ * where the request row lives, where its inbox index rows live, and where its
+ * approvers are looked up. The first two are the request's own organization by
+ * definition. The third is not: a group CFO holds her `cfo` position in the
+ * GROUP organization while the purchase order she signs off lives in the PLANT
+ * organization. Binding all three together meant
+ * `expandPositionUsers('cfo', <plant>)` matched nobody and the slot fell into
+ * `onEmptyApprovers` — a group escalation could not be expressed at all.
+ *
+ * This module resolves only the third job. The request keeps living in its own
+ * organization, and D2's membership union is what lets a group-side approver
+ * READ it — see `assertApproversCanRead` below for why that is a precondition
+ * worth checking rather than assuming.
+ */
+
+/** Cycle guard for the `parent_organization_id` walk (mirrors the BU subtree walk). */
+const MAX_ORG_DEPTH = 32;
+
+const SYSTEM_CTX = { isSystem: true } as const;
+
+export interface ApproverOrgScopeEngine {
+  find(object: string, options: any): Promise<any[]>;
+}
+
+export interface ApproverOrgScopeDeps {
+  engine: ApproverOrgScopeEngine;
+  /**
+   * The tenancy posture in force, when the host could resolve one. `undefined`
+   * means "unknown" — a stack booted without the tenancy service — and is
+   * treated as permissive so a minimal test/embedded stack is not broken by a
+   * guard it cannot answer.
+   */
+  posture?: () => string | undefined;
+  logger?: { warn?: (msg: any, ...rest: any[]) => void; debug?: (msg: any, ...rest: any[]) => void };
+}
+
+/**
+ * Every failure here THROWS `VALIDATION_FAILED`, matching how `expression`
+ * approvers already fail (#3447 P2): an approver declaration that cannot be
+ * resolved is a ROUTING BUG, never "condition not met". Silently falling back
+ * to the request's own organization would be the worst option available — a
+ * flow that reads as "escalate to group" would quietly approve inside the
+ * plant, and the deployment that changed posture would reroute its approvals
+ * with no signal at all.
+ *
+ * Messages name the offending value because their primary reader is the AI
+ * author fixing the flow on the next validate pass.
+ */
+function fail(message: string): never {
+  throw new Error(`VALIDATION_FAILED: ${message}`);
+}
+
+async function findOrg(
+  engine: ApproverOrgScopeEngine,
+  where: Record<string, unknown>,
+): Promise<any | null> {
+  try {
+    const rows = await engine.find('sys_organization', {
+      filter: where,
+      fields: ['id', 'slug', 'parent_organization_id'],
+      limit: 1,
+      context: SYSTEM_CTX,
+    } as any);
+    return Array.isArray(rows) && rows[0] ? rows[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The id chain from `orgId` up to its root, inclusive. Fail-closed on cycles. */
+async function ancestorChain(
+  engine: ApproverOrgScopeEngine,
+  orgId: string,
+): Promise<string[]> {
+  const chain: string[] = [];
+  const seen = new Set<string>();
+  let cursor: string | null = orgId;
+  for (let depth = 0; cursor && depth < MAX_ORG_DEPTH; depth++) {
+    if (seen.has(cursor)) break; // cycle in the grouping metadata — stop, do not loop
+    seen.add(cursor);
+    chain.push(cursor);
+    const row = await findOrg(engine, { id: cursor });
+    const parent = row?.parent_organization_id;
+    cursor = parent ? String(parent) : null;
+  }
+  return chain;
+}
+
+/**
+ * Resolve an approver's `organization` declaration to a concrete organization
+ * id for directory lookups. Returns the request's own organization when the
+ * declaration is absent — the unchanged default path, which does no reads.
+ */
+export async function resolveApproverDirectoryOrg(
+  deps: ApproverOrgScopeDeps,
+  declaration: string | null | undefined,
+  requestOrgId: string | null | undefined,
+  approverType: string,
+  isOrgScopedType: boolean,
+): Promise<string | null | undefined> {
+  const declared = typeof declaration === 'string' ? declaration.trim() : '';
+  if (!declared) return requestOrgId;
+
+  // An `organization` on `user` / `field` / `manager` / `team` is not a
+  // narrower routing — those types never consult an org-scoped directory, so
+  // the declaration would have no effect. Refuse rather than ignore: a flow
+  // author who wrote it believed it did something.
+  if (!isOrgScopedType) {
+    fail(
+      `approver type '${approverType}' resolves people without an organization directory, `
+      + `so 'organization: ${declared}' would have no effect — remove it `
+      + `(ADR-0105 D9 applies to position / org_membership_level / department / expression)`,
+    );
+  }
+
+  // Posture guard. ADR-0105 D9 applies to `group` only: in `isolated`, cross-org
+  // approval remains system-context mirroring (cloud #2937 contract), and in
+  // `single` there is no second organization to target. Refusing here — rather
+  // than in a lint — is deliberate: posture is ENVIRONMENT configuration, so the
+  // same portable flow metadata may be deployed into any posture and no static
+  // check can see which. A deployment migrating group → isolated must fail
+  // loudly instead of silently rerouting its approvals.
+  const posture = deps.posture?.();
+  if (posture && posture !== 'group') {
+    fail(
+      `cross-organization approver targeting ('organization: ${declared}') requires the `
+      + `'group' tenancy posture; this deployment resolves '${posture}' (ADR-0105 D9)`,
+    );
+  }
+
+  const requestOrg = requestOrgId ? String(requestOrgId) : '';
+  if (!requestOrg) {
+    fail(
+      `'organization: ${declared}' cannot be resolved for a request that carries no `
+      + `organization — cross-organization targeting needs an organization to resolve from`,
+    );
+  }
+
+  const chain = await ancestorChain(deps.engine, requestOrg);
+
+  if (declared === '$root') {
+    const root = chain[chain.length - 1];
+    if (root === requestOrg && chain.length === 1) {
+      fail(
+        `'organization: $root' resolved to the request's own organization — this organization `
+        + `has no 'parent_organization_id' lineage. Declare the group hierarchy (ADR-0105 D6) `
+        + `or drop the targeting`,
+      );
+    }
+    return root;
+  }
+
+  if (declared === '$parent') {
+    const parent = chain[1];
+    if (!parent) {
+      fail(
+        `'organization: $parent' has no parent to resolve to — the request's organization is `
+        + `already the root of its group (ADR-0105 D6 'parent_organization_id')`,
+      );
+    }
+    return parent;
+  }
+
+  // A slug names one specific organization — the shape the symbols cannot
+  // express (a SIBLING, e.g. a shared-services centre approving payables for
+  // every plant). Slugs rather than ids because flow metadata is portable
+  // across environments and organization ids are minted per deployment.
+  const target = await findOrg(deps.engine, { slug: declared });
+  if (!target?.id) {
+    fail(
+      `no organization with slug '${declared}' — 'organization' takes an organization SLUG `
+      + `or a symbol ($root / $parent), never an id (ids are per-deployment, flows are portable)`,
+    );
+  }
+  const targetId = String(target.id);
+  if (targetId === requestOrg) return targetId;
+
+  // Legality: the target must share a grouping root with the request's
+  // organization. "Shares a root" rather than "is an ancestor" because the
+  // sibling case is a first-class use. The rule depends only on the
+  // organization tree — never on who submitted — so one flow routes identically
+  // for every submitter, which is what makes a routing bug reproducible.
+  const targetChain = await ancestorChain(deps.engine, targetId);
+  const targetRoot = targetChain[targetChain.length - 1];
+  const requestRoot = chain[chain.length - 1];
+  if (!targetRoot || !requestRoot || targetRoot !== requestRoot) {
+    fail(
+      `organization '${declared}' is not in the same group as the request's organization `
+      + `— cross-organization approval routes WITHIN one group (they must share a `
+      + `'parent_organization_id' root, ADR-0105 D6/D9)`,
+    );
+  }
+  return targetId;
+}
+
+/**
+ * Drop approvers who could not READ the request they were routed to, and say
+ * so.
+ *
+ * ADR-0105 D9 notes that reads by cross-org approvers "are covered by D2
+ * (membership union)". True — but D2's union is `organization_id IN
+ * accessible_org_ids`, and the request row is stamped with the REQUEST's
+ * organization. So a group-side approver reaches it only if she also holds a
+ * membership there. That is the intended group shape (group staff are members
+ * of every plant while holding their positions in the group org — the shape the
+ * ADR-0105 acceptance dogfood already models), but nothing enforces it.
+ *
+ * Left unchecked the failure is SILENT and expensive: routing succeeds, the
+ * request and inbox rows are written, and the approver then opens a task she
+ * cannot open — the wall hides the record. Filtering here converts that into
+ * the empty-slate path the node already has a policy for
+ * (`onEmptyApprovers`), and logs exactly who was dropped and why, so the fix
+ * ("grant the membership" or "retarget") is legible without a debugger.
+ */
+export async function filterApproversWhoCanRead(
+  deps: ApproverOrgScopeDeps,
+  userIds: string[],
+  requestOrgId: string | null | undefined,
+  context: { approverType: string; value?: string; directoryOrgId?: string | null },
+): Promise<string[]> {
+  const requestOrg = requestOrgId ? String(requestOrgId) : '';
+  if (!requestOrg || userIds.length === 0) return userIds;
+
+  let members: any[] = [];
+  try {
+    members = await deps.engine.find('sys_member', {
+      filter: { organization_id: requestOrg, user_id: { $in: userIds } },
+      fields: ['user_id'],
+      limit: 10000,
+      context: SYSTEM_CTX,
+    } as any);
+  } catch {
+    // Membership unreadable — do NOT drop everyone on an infrastructure
+    // hiccup. Routing to someone who may not see the request is recoverable
+    // (an admin can grant the membership); silently emptying a live approval
+    // slate is not.
+    return userIds;
+  }
+
+  const canRead = new Set(
+    (members ?? []).map((m: any) => String(m?.user_id ?? '')).filter(Boolean),
+  );
+  const dropped = userIds.filter((u) => !canRead.has(u));
+  if (dropped.length === 0) return userIds;
+
+  deps.logger?.warn?.(
+    `[approvals] ADR-0105 D9: ${dropped.length} cross-organization approver(s) dropped — `
+    + `they hold '${context.value ?? context.approverType}' in organization `
+    + `'${context.directoryOrgId}' but no membership in the request's organization `
+    + `'${requestOrg}', so the D2 union wall would hide the request from them. `
+    + `Grant those users a membership in the request's organization, or retarget the approver.`,
+    { dropped, requestOrganizationId: requestOrg, directoryOrganizationId: context.directoryOrgId },
+  );
+  return userIds.filter((u) => canRead.has(u));
+}

package/src/index.ts

@@ -20,6 +20,9 @@ export {
   type ApprovalClock,
   type ApprovalServiceOptions,
   type ApprovalResumeSurface,
+  // #3447 P2 — expression approvers + empty-slate auto-approve outcome.
+  type ApproverExpressionContext,
+  type ApprovalNodeAutoOutcome,
 } from './approval-service.js';
 export {
   ApprovalsServicePlugin,

package/src/lifecycle-hooks.ts

@@ -93,6 +93,28 @@ export function bindApprovalLockHook(engine: MinimalEngine, logger?: MinimalLogg
     const pending = await pendingRequestFor(engine, object, id);
     if (!pending) return;
 
+    // The run that OPENED this approval may still write its own target record
+    // (#3456). Without this the lock cannot tell "the run that owns this pending
+    // request" from "an unrelated user edit", so a flow that touches the record
+    // between opening the approval and the decision — or a manual `resume` with
+    // no decision — dies on its own `RECORD_LOCKED` and leaves the record locked
+    // behind it.
+    //
+    // Keyed on run identity, NOT on elevation: a `runAs:'user'` run must stay
+    // RLS-scoped, so widening it to `isSystem` would be the wrong tool. The
+    // automation engine stamps `flowRunId` into the server-built ExecutionContext
+    // (never client-supplied, like `isSystem`) and it grants nothing by itself —
+    // the only write it permits is to the one record this very run already holds
+    // a pending request against.
+    //
+    // Read off `provenance`, not `session`: provenance says WHAT produced the
+    // write, and a run can own its writes while resolving no principal at all.
+    // A schedule-triggered run is exactly that — it reaches here with NO
+    // session, and that shape is the one that used to die on its own lock
+    // (#3712).
+    const writerRun = (ctx?.provenance as any)?.flowRunId;
+    if (writerRun && pending.flow_run_id && String(writerRun) === String(pending.flow_run_id)) return;
+
     const config = parseJson<any>(pending.node_config_json, {});
     if (config?.lockRecord === false) return;
 

package/src/record-lock-schedule-run.integration.test.ts

@@ -0,0 +1,206 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #3703 / #3712 / #3760 — the run that opened a pending approval may write its
+ * own locked record.
+ *
+ * #3703 exempted "the run that opened the pending request" from the approvals
+ * record lock, keyed on `flowRunId`. #3712 extended that to the run that
+ * resolved no identity — an effective `runAs:'user'` run with no trigger user —
+ * by giving it a provenance-only ObjectQL context carrying just the run id.
+ *
+ * #3760 then closed the fail-open that path depended on: a run with no trigger
+ * user may no longer perform a data operation at all, because presenting no
+ * principal is precisely what made the write UNSCOPED. So the user-less variant
+ * is now REFUSED rather than exempted, and a schedule reaches its own record the
+ * explicit way — `runAs:'system'`, which the hook exempts on its own
+ * `isSystem` branch. The `flowRunId` exemption remains live and load-bearing for
+ * what it was built for: a `runAs:'user'` run that DOES have a user.
+ *
+ * The original miss was a HAND-OFF gap, not a logic gap: every hop worked in
+ * isolation. So this test still refuses to stub any hop. It runs the real
+ * `resolveRunDataContext` from the automation runtime, feeds its output to a
+ * real {@link ObjectQL} engine, and lets the real lock hook decide — the same
+ * three layers, in the same order, as a live deployment.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { ObjectQL } from '@objectstack/objectql';
+import { resolveRunDataContext } from '@objectstack/service-automation';
+import { bindApprovalLockHook } from './lifecycle-hooks.js';
+
+const opportunity = {
+  name: 'opportunity',
+  label: 'Opportunity',
+  fields: {
+    id: { name: 'id', type: 'text' as const, primaryKey: true },
+    name: { name: 'name', type: 'text' as const },
+    amount: { name: 'amount', type: 'number' as const },
+  },
+};
+
+/** The lock hook reads pending requests off this object. */
+const approvalRequest = {
+  name: 'sys_approval_request',
+  label: 'Approval Request',
+  fields: {
+    id: { name: 'id', type: 'text' as const, primaryKey: true },
+    object_name: { name: 'object_name', type: 'text' as const },
+    record_id: { name: 'record_id', type: 'text' as const },
+    status: { name: 'status', type: 'text' as const },
+    flow_run_id: { name: 'flow_run_id', type: 'text' as const },
+    node_config_json: { name: 'node_config_json', type: 'text' as const },
+  },
+};
+
+function makeMemoryDriver() {
+  const stores = new Map<string, Map<string, Record<string, unknown>>>();
+  const storeFor = (o: string) => {
+    let s = stores.get(o);
+    if (!s) { s = new Map(); stores.set(o, s); }
+    return s;
+  };
+  let nextId = 0;
+  const matches = (row: Record<string, unknown>, where: any): boolean => {
+    if (!where || typeof where !== 'object') return true;
+    for (const [k, v] of Object.entries(where)) {
+      if (k.startsWith('$')) continue;
+      const exp = (v && typeof v === 'object' && '$eq' in (v as any)) ? (v as any).$eq : v;
+      if ((row[k] ?? null) !== (exp ?? null)) return false;
+    }
+    return true;
+  };
+  const driver: any = {
+    name: 'memory', version: '0.0.0', supports: {},
+    async connect() {}, async disconnect() {}, async checkHealth() { return true; }, async execute() { return null; },
+    async find(o: string, ast: any) { return Array.from(storeFor(o).values()).filter((r) => matches(r, ast?.where)); },
+    findStream() { throw new Error('ns'); },
+    async findOne(o: string, ast: any) { for (const r of storeFor(o).values()) if (matches(r, ast?.where)) return r; return null; },
+    async create(o: string, data: Record<string, unknown>) {
+      nextId += 1;
+      const id = (data.id as string) ?? `r_${nextId}`;
+      const row = { ...data, id };
+      storeFor(o).set(id, row);
+      return row;
+    },
+    async update(o: string, id: string, data: Record<string, unknown>) {
+      const s = storeFor(o);
+      const cur = s.get(id);
+      if (!cur) throw new Error(`nf ${o}/${id}`);
+      const up = { ...cur, ...data, id };
+      s.set(id, up);
+      return up;
+    },
+    async upsert(o: string, data: Record<string, unknown>) {
+      const id = data.id as string | undefined;
+      return id && storeFor(o).has(id) ? this.update(o, id, data) : this.create(o, data);
+    },
+    async delete(o: string, id: string) { return storeFor(o).delete(id); },
+    async count(o: string, ast: any) { return (await this.find(o, ast)).length; },
+    async bulkCreate(o: string, rows: Record<string, unknown>[]) { return Promise.all(rows.map((r) => this.create(o, r))); },
+    async bulkUpdate() { return []; },
+    async bulkDelete() {},
+    async beginTransaction() { return { commit: async () => {}, rollback: async () => {} }; },
+    async commit() {}, async rollback() {},
+  };
+  return driver;
+}
+
+/**
+ * A `runAs:'user'` run that HAS a trigger user — the live consumer of the
+ * `flowRunId` exemption, and the shape #3703 built it for (a record-change or
+ * screen flow that opened the approval and now writes its own target record).
+ */
+const OWNING_RUN = (flowRunId: string) => ({ runAs: 'user' as const, userId: 'u1', flowRunId });
+
+/** What a schedule trigger produces: an event, and NO user. Refused since #3760. */
+const USER_LESS_RUN = (flowRunId: string) => ({ runAs: 'user' as const, flowRunId });
+
+/** The supported shape for a schedule that must write records (ADR-0049). */
+const SYSTEM_RUN = (flowRunId: string) => ({ runAs: 'system' as const, flowRunId });
+
+describe('an owning run and the approvals record lock (#3703 / #3712 / #3760)', () => {
+  let engine: ObjectQL;
+  let oppId: string;
+
+  beforeEach(async () => {
+    engine = new ObjectQL();
+    engine.registerDriver(makeMemoryDriver(), true);
+    await engine.init();
+    for (const o of [opportunity, approvalRequest]) engine.registry.registerObject(o as any);
+
+    const opp = await engine.insert('opportunity', { name: 'Deal', amount: 100 });
+    oppId = String(opp.id);
+    await engine.insert('sys_approval_request', {
+      object_name: 'opportunity',
+      record_id: oppId,
+      status: 'pending',
+      flow_run_id: 'run_1',
+      node_config_json: JSON.stringify({ lockRecord: true }),
+    });
+
+    bindApprovalLockHook(engine as any);
+  });
+
+  const writeAs = (context: unknown) =>
+    engine.update('opportunity', { id: oppId, amount: 200 }, { context } as any);
+
+  it('lets the OWNING run write its own target record', async () => {
+    // The full hand-off, unstubbed: the automation runtime resolves the run's
+    // ObjectQL context, the engine turns it into hook provenance, the lock hook
+    // matches it against the pending request it opened.
+    const dataCtx = resolveRunDataContext(OWNING_RUN('run_1'));
+    expect(dataCtx, 'nothing could carry the run id').toMatchObject({ flowRunId: 'run_1' });
+
+    await expect(writeAs(dataCtx)).resolves.toBeDefined();
+    const row = await engine.findOne('opportunity', { where: { id: oppId } });
+    expect(row.amount).toBe(200);
+  });
+
+  it('still blocks a DIFFERENT run', async () => {
+    await expect(writeAs(resolveRunDataContext(OWNING_RUN('run_other'))))
+      .rejects.toThrow(/RECORD_LOCKED/);
+  });
+
+  it('still blocks an ordinary user edit', async () => {
+    await expect(writeAs({ isSystem: false, userId: 'u1', positions: [], permissions: [] }))
+      .rejects.toThrow(/RECORD_LOCKED/);
+  });
+
+  it('still blocks a context-less write', async () => {
+    await expect(writeAs(undefined)).rejects.toThrow(/RECORD_LOCKED/);
+  });
+
+  it('the exemption is PROVENANCE, not privilege — the exempted write is not elevated', async () => {
+    // The exemption must not have been bought with elevation: the run that
+    // writes its own locked record is still a plain `runAs:'user'` principal,
+    // subject to the same RLS as the user who triggered it. Only `flowRunId`
+    // distinguishes it, and `flowRunId` grants nothing on its own.
+    const dataCtx = resolveRunDataContext(OWNING_RUN('run_1')) as Record<string, unknown>;
+    expect(dataCtx.isSystem, 'the exemption rode in on isSystem').toBe(false);
+    expect(dataCtx.flowRunId).toBe('run_1');
+    expect(dataCtx.userId).toBe('u1');
+  });
+
+  // #3760 — the case #3712 solved by handing the lock a provenance-only context
+  // is gone at the root: such a run may not perform a data operation at all,
+  // because presenting no principal is exactly what made the write unscoped. It
+  // is refused BEFORE the lock is ever consulted.
+  it('a USER-LESS run never reaches the lock — it cannot perform a data op at all', async () => {
+    expect(() => resolveRunDataContext(USER_LESS_RUN('run_1')))
+      .toThrow(/no trigger user could be resolved/);
+  });
+
+  // ...and the capability itself survives, via the explicit route: a schedule
+  // that must write records declares `runAs:'system'`, which the lock hook
+  // exempts on its own isSystem branch. Elevation is now declared rather than
+  // acquired by having no identity.
+  it("a schedule that declares runAs:'system' still writes its own target record", async () => {
+    const dataCtx = resolveRunDataContext(SYSTEM_RUN('run_1'));
+    expect(dataCtx).toMatchObject({ isSystem: true, flowRunId: 'run_1' });
+
+    await expect(writeAs(dataCtx)).resolves.toBeDefined();
+    const row = await engine.findOne('opportunity', { where: { id: oppId } });
+    expect(row.amount).toBe(200);
+  });
+});