@objectstack/plugin-approvals 17.0.0 → 17.1.0

package/dist/index.mjs

@@ -1384,10 +1384,45 @@ var SysApprovalRequest = ObjectSchema.create({
   },
   fields: {
     id: Field.text({ label: "Request ID", required: true, readonly: true, group: "System" }),
+    // ⚠️ MEASURED DEFECT, cloud#1395 — read this before trusting the column.
+    //
+    // An approval request DOES belong to an organization: it is read through the
+    // organization wall by the approvals inbox, and on a shared-database
+    // deployment a row carrying no organization is not filtered BY that wall —
+    // it is either invisible to everyone or visible to everyone, decided by
+    // whatever filter each surface happens to apply rather than by the data.
+    //
+    // The value is resolved from the ACTING CONTEXT only (`openNodeRequest`'s
+    // `ctxOrg`), so it is NULL whenever the flow that opened the request ran
+    // without one — every schedule / time-relative / api triggered run, none of
+    // which sets a tenant. On a walled single-database HotCRM SaaS boot this
+    // measured 27 of 27 rows org-less, each naming an `object_name` /
+    // `record_id` owned by a specific customer.
+    //
+    // ⛔ Do NOT read that as "platform tables do not carry an organization".
+    // `sys_audit_log` (1669 rows) was correctly attributed on the SAME boot,
+    // because its writer takes the organization from the RECORD the row is
+    // about, with the session only as fallback (plugin-audit
+    // `resolveRecordOrganizationField`, #8707 honouring #8287's ruling). Two
+    // writers read the actor; a third reads the subject. That disagreement is
+    // the defect.
+    //
+    // Which of the two a side-table row should follow is an open contract
+    // question on cloud#1395 — the audit resolver is scope-pinned to audit
+    // stamping by the #8778 ruling, so this writer needs its own. The same
+    // `ctxOrg` also stamps `sys_approval_action` and `sys_approval_approver`,
+    // so all three move together.
     organization_id: Field.lookup("sys_organization", {
       label: "Organization",
       required: false,
       group: "System",
+      // ⛔ String unchanged on purpose: it is extracted into the generated i18n
+      // bundles (`translations/*.objects.generated.ts`, as `help`), so rewording
+      // it is a translation-regeneration change and not a comment. The
+      // correction it needs — it claims a propagation that measurably does not
+      // happen, and says "Tenant" where ADR-0120 §Terminology requires
+      // "organization" — rides the cloud#1395 write-side fix, which rewrites the
+      // sentence and regenerates the four locales in one pass.
       description: "Tenant that owns this approval request (propagated from submitter context)"
     }),
     process_name: Field.text({
@@ -1531,6 +1566,28 @@ var SysApprovalRequest = ObjectSchema.create({
   // approving, rejecting, or reassigning it to a real approver. `viewer` is
   // attached by getRequest/listRequests; where it is absent the predicate fails
   // closed.
+  //
+  // Every predicate below is guarded for the SPARSE action face (#8990). This
+  // binding is a list row or a record read carrying only what the caller
+  // projected, and CEL aborts the whole expression at key resolution — so the
+  // unguarded `record.viewer.can_act` faulted (`No such key: viewer`) on any
+  // row without the block, and the button silently vanished, indistinguishable
+  // from "the gate said no". `materializeDeclaredFields`'s doc comment in
+  // `@objectstack/objectql` is the canonical statement of the guard rule; this
+  // file follows it and does not restate it.
+  //
+  // `viewer` is a NESTED block, which needs one measurement the canonical rule
+  // does not spell out. Measured against the `@objectstack/formula` CEL engine:
+  // `has(record.viewer) && record.viewer != null && record.viewer.can_act`
+  // still FAULTS on `{viewer: {}}` (`No such key: can_act`) and on
+  // `{viewer: {can_act: null}}` (`Logical operator requires bool operands`).
+  // Guarding the LEAF instead — `has(record.viewer) &&
+  // has(record.viewer.can_act) && record.viewer.can_act == true` — is total
+  // over every binding AND subsumes the parent `!= null` half, because `has()`
+  // on a path whose parent is null answers `false` rather than faulting. So the
+  // leaf `has()` plus the `== true` comparison is the MINIMAL safe form here,
+  // not a longer one: `== true` is load-bearing (a bare truthy read of a null
+  // leaf faults the logical operator), the parent `!= null` is not.
   actions: [
     {
       name: "approval_approve",
@@ -1550,7 +1607,7 @@ var SysApprovalRequest = ObjectSchema.create({
         // string[]`; the decision route persists them on `sys_approval_action`.
         { name: "attachments", label: "Attachments", type: "file", multiple: true, required: false }
       ],
-      visible: "record.viewer.can_act || record.viewer.can_override",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true || has(record.viewer) && has(record.viewer.can_override) && record.viewer.can_override == true",
       locations: ["record_section", "list_item"],
       successMessage: "Approved.",
       refreshAfter: true
@@ -1578,7 +1635,7 @@ var SysApprovalRequest = ObjectSchema.create({
         { name: "comment", label: "Comment", type: "textarea", required: false },
         { name: "attachments", label: "Attachments", type: "file", multiple: true, required: false }
       ],
-      visible: "record.viewer.can_act || record.viewer.can_override",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true || has(record.viewer) && has(record.viewer.can_override) && record.viewer.can_override == true",
       locations: ["record_section", "list_item"],
       successMessage: "Rejected.",
       refreshAfter: true
@@ -1599,7 +1656,7 @@ var SysApprovalRequest = ObjectSchema.create({
         { field: "submitter_id", name: "to", label: "New approver", required: true, helpText: "User to hand this step to" },
         { name: "comment", label: "Comment", type: "textarea", required: false }
       ],
-      visible: "record.viewer.can_act || record.viewer.can_override",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true || has(record.viewer) && has(record.viewer.can_override) && record.viewer.can_override == true",
       locations: ["record_section"],
       successMessage: "Reassigned.",
       refreshAfter: true
@@ -1618,7 +1675,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "Reason", type: "textarea", required: false }
       ],
-      visible: "record.viewer.can_act",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true",
       locations: ["record_section"],
       successMessage: "Sent back for revision.",
       refreshAfter: true
@@ -1633,7 +1690,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "What do you need?", type: "textarea", required: true }
       ],
-      visible: "record.viewer.can_act",
+      visible: "has(record.viewer) && has(record.viewer.can_act) && record.viewer.can_act == true",
       locations: ["record_section"],
       successMessage: "Information requested.",
       refreshAfter: true
@@ -1654,7 +1711,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "Note", type: "textarea", required: false }
       ],
-      visible: 'record.status == "pending" && record.viewer.is_submitter',
+      visible: 'has(record.status) && record.status == "pending" && has(record.viewer) && has(record.viewer.is_submitter) && record.viewer.is_submitter == true',
       locations: ["record_section"],
       successMessage: "Reminder sent.",
       refreshAfter: true
@@ -1674,7 +1731,7 @@ var SysApprovalRequest = ObjectSchema.create({
       ],
       // Recall applies while the request is live for the submitter — pending
       // (withdraw) or returned (abandon the revision instead of resubmitting).
-      visible: '(record.status == "pending" || record.status == "returned") && record.viewer.is_submitter',
+      visible: 'has(record.status) && (record.status == "pending" || record.status == "returned") && has(record.viewer) && has(record.viewer.is_submitter) && record.viewer.is_submitter == true',
       locations: ["record_section"],
       successMessage: "Recalled.",
       refreshAfter: true
@@ -1689,7 +1746,7 @@ var SysApprovalRequest = ObjectSchema.create({
       params: [
         { name: "comment", label: "What changed?", type: "textarea", required: false }
       ],
-      visible: 'record.status == "returned" && record.viewer.is_submitter',
+      visible: 'has(record.status) && record.status == "returned" && has(record.viewer) && has(record.viewer.is_submitter) && record.viewer.is_submitter == true',
       locations: ["record_section"],
       successMessage: "Resubmitted.",
       refreshAfter: true
@@ -2335,6 +2392,9 @@ var _ApprovalService = class _ApprovalService {
     this.messaging = opts.messaging;
     this.publicBaseUrl = (opts.publicBaseUrl ?? "").replace(/\/$/, "");
     this.tenancyPosture = opts.tenancyPosture;
+    this.recordReaderVisibleObjects = new Set(
+      (Array.isArray(opts.recordReaderVisibleObjects) ? opts.recordReaderVisibleObjects : []).map((n) => String(n ?? "").trim()).filter(Boolean)
+    );
   }
   /** Attach (or replace) the ADR-0105 D9 posture provider. */
   attachTenancyPosture(provider) {
@@ -2836,9 +2896,48 @@ var _ApprovalService = class _ApprovalService {
    * Position holders (ADR-0090 D3): `sys_user_position` is the platform-owned
    * assignment table, keyed by the position's machine name (ADR-0057 D4),
    * unioned with the better-auth membership string (`sys_member.role`) as a
-   * transition source — the same semantics as `PositionGraphService` in
-   * `plugin-sharing`, so an approval routes to exactly the users the sharing
-   * engine would expand for the same position.
+   * transition source.
+   *
+   * ⚠️ This is a ROUTING read (approver slates and escalation targets), and it
+   * is deliberately NOT the same read as `PositionGraphService` in
+   * `plugin-sharing`, whatever the shared method name suggests. Both answer
+   * "who holds position P"; this one reads the directory RAW — neither the
+   * ADR-0091 D2 validity window nor the `sys_position.active` catalogue flag is
+   * applied. Maintainer ruling, 2026-08-15 (#8710, inheriting #8613), verbatim:
+   *
+   * > Access-conferring paths filter deactivated positions; addressing paths
+   * > do not.
+   *
+   * Routing is an addressing path, so dropping a holder here is fail-OPEN, not
+   * fail-closed: an expansion that comes back empty does not narrow the slate,
+   * it falls through to the literal `position:` slot no user can ever act on —
+   * the permanently stuck request of #3807 / #3424. A step routing to nobody is
+   * worse than one routing to a lapsed holder, so the lapsed holder stays.
+   *
+   * Where the two implementations actually stand, per source. Both limbs are
+   * listed because a statement about one of them is not a statement about this
+   * method:
+   *
+   *  1. `sys_user_position` — sharing projects `valid_from` / `valid_until` and
+   *     drops rows on `isGrantActive` inside its own helper; we project
+   *     `user_id` alone, so an assignment that expired last month still routes.
+   *     This is the one real divergence, and it is the intended one.
+   *  2. `sys_member.role` — raw on BOTH sides (`TeamGraphService.expandRoleUsers`
+   *     projects `user_id` too). The table carries no window columns at all and
+   *     `isGrantActive` reads an absent bound as unbounded, so there is nothing
+   *     a filter could do here; membership tier names have no `sys_position`
+   *     row either (#8710's "a name with no row is untouched" fallback), so no
+   *     catalogue flag either. This limb cannot be brought into parity by
+   *     adding a filter — see {@link expandMembershipTierUsers}.
+   *  3. `sys_position.active` — the sharing engine's gate for it lives at the
+   *     RULE EVALUATOR's call site (`positionConfersAccess` in
+   *     `sharing-rule-service.ts`), not inside `PositionGraphService`; the same
+   *     ruling gives it no counterpart on this path.
+   *
+   * The omission is per-READ, not a missing dependency: `isGrantActive` is
+   * imported in this file and IS applied to `sys_approval_delegation` in
+   * {@link lookupActiveDelegation}. ⛔ So do not "fix" this by adding the window
+   * filter here — that is the option #8710 rejected, on the reasoning above.
    */
   async expandPositionUsers(positionName, organizationId) {
     if (!positionName) return [];
@@ -2866,6 +2965,13 @@ var _ApprovalService = class _ApprovalService {
    * NOT positions. Named for the projection (`org_membership_level`, ADR-0057
    * D7 / ADR-0090 D3), not for better-auth's column: the column name is theirs
    * and stays, the platform-facing word does not.
+   *
+   * Read RAW, like every routing read here, and with nothing available to
+   * filter even if it were not: `sys_member` carries no ADR-0091 D2 window
+   * columns, and a tier name has no `sys_position` row to read `active` off.
+   * {@link expandPositionUsers} carries the ruling both reads inherit
+   * (#8613 / #8710) — this method is also the second limb of that union, so a
+   * change here changes position routing too.
    */
   async expandMembershipTierUsers(tier, organizationId) {
     if (!tier) return [];
@@ -5095,7 +5201,7 @@ var _ApprovalService = class _ApprovalService {
    * is a plain membership test over the resolved ids). So this cannot hide a
    * request from someone who could actually act on it.
    */
-  async visibleRequestIds(context, tenantOrg) {
+  async visibleRequestIds(context, tenantOrg, target) {
     if (this.isOverrideActor(context, tenantOrg)) return null;
     const uid2 = context?.userId != null ? String(context.userId) : "";
     if (!uid2) return /* @__PURE__ */ new Set();
@@ -5137,8 +5243,90 @@ var _ApprovalService = class _ApprovalService {
         error: err instanceof Error ? err.message : String(err)
       });
     }
+    await this.addRecordReaderVisibleIds(ids, context, tenantOrg, target);
     return ids;
   }
+  /**
+   * [#8652] Read-only approval visibility derived from READ ACCESS TO THE
+   * TARGET BUSINESS RECORD.
+   *
+   * Maintainer ruling 2026-08-15: a user who can read the target record may
+   * view that record's approval requests and full action history, read-only,
+   * behind a switch that is default OFF, anchored on the EXISTING record-read
+   * permission. The rejected alternative was a host-injected visibility hook —
+   * a security predicate the platform could neither constrain nor audit.
+   *
+   * ## How the anchor is evaluated
+   *
+   * By asking the engine to read the record AS THE CALLER. That is the whole
+   * check: `engine.find(object, { where: { id }, context })` runs the ordinary
+   * ObjectQL middleware — object CRUD read, then RLS — so a denial throws and a
+   * row the caller may not see comes back empty. Both mean "no". No new
+   * permission, role or grant type is invented, and no second copy of the
+   * access rule exists to drift from the first.
+   *
+   * ⚠️ The caller's context is load-bearing. Probing with {@link SYSTEM_CTX} —
+   * the context every other read in this service uses — would read exactly like
+   * a permission check while admitting every authenticated user in the tenant.
+   *
+   * ## Why it needs a NAMED TARGET, and what that deliberately excludes
+   *
+   * The rule is anchored on one record, so it can only be evaluated where a
+   * record is named: a list filtered by `object` + `recordId` (what a record
+   * page's approval tab sends), or a request loaded by id (whose own row names
+   * its target). An UNTARGETED list — the inbox — is left exactly as it was:
+   * answering it under this tier would mean probing every request in the tenant
+   * for read access, which is unbounded, and would turn a work queue into a
+   * browse surface. The confirmed consumer is the record page; the inbox is not
+   * part of the ruling and is not widened here.
+   *
+   * ## What becomes visible (stated plainly, because the switch is an opt-in)
+   *
+   * The request row — including its `payload` snapshot of the record at
+   * submission time — plus the full action history: actor, decision, timestamp,
+   * the action's COMMENT text, and (through the same gate, via
+   * {@link ApprovalService.authorizeFileRead}) any decision attachments. The
+   * comment text is the ruling's "full action history" read literally; it is
+   * flagged on the card as the one granularity edge worth a second look.
+   *
+   * Read-only is not enforced here and must not be: the decision paths
+   * (`decideNode` / `reassign` / `recall` / `comment`) authorize on the pending
+   * approver slate, the submitter, or {@link ApprovalService.isOverrideActor},
+   * none of which this tier touches. Seeing a request confers nothing.
+   */
+  async addRecordReaderVisibleIds(ids, context, tenantOrg, target) {
+    if (this.recordReaderVisibleObjects.size === 0) return;
+    const object = String(target?.object ?? "").trim();
+    const recordId = String(target?.recordId ?? "").trim();
+    if (!object || !recordId) return;
+    if (!this.recordReaderVisibleObjects.has(object)) return;
+    const uid2 = context?.userId != null ? String(context.userId) : "";
+    if (!uid2) return;
+    try {
+      const readable = await this.engine.find(object, {
+        where: { id: recordId },
+        fields: ["id"],
+        limit: 1,
+        context
+      });
+      if (!Array.isArray(readable) || readable.length === 0) return;
+      const orgWhere = tenantOrg ? { organization_id: tenantOrg } : {};
+      const rows = await this.engine.find("sys_approval_request", {
+        where: { object_name: object, record_id: recordId, ...orgWhere },
+        fields: ["id"],
+        limit: _ApprovalService.APPROVER_INDEX_CAP,
+        context: SYSTEM_CTX2
+      });
+      for (const r of Array.isArray(rows) ? rows : []) {
+        if (r?.id != null) ids.add(String(r.id));
+      }
+    } catch (err) {
+      this.logger?.debug?.("[approvals] record-reader visibility probe declined", {
+        object,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
   /** Intersect an existing `where.id` constraint with the participant set. */
   applyVisibility(where, visible) {
     if (!visible) return true;
@@ -5162,7 +5350,10 @@ var _ApprovalService = class _ApprovalService {
       if (ids.length === 0) return [];
       where.id = ids.length === 1 ? ids[0] : { $in: ids };
     }
-    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg))) return [];
+    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg, {
+      object: filter?.object,
+      recordId: filter?.recordId
+    }))) return [];
     const findOpts = {
       where,
       orderBy: [{ field: "created_at", order: "desc" }],
@@ -5188,7 +5379,10 @@ var _ApprovalService = class _ApprovalService {
       if (ids.length === 0) return 0;
       where.id = ids.length === 1 ? ids[0] : { $in: ids };
     }
-    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg))) return 0;
+    if (!this.applyVisibility(where, await this.visibleRequestIds(context, tenantOrg, {
+      object: filter?.object,
+      recordId: filter?.recordId
+    }))) return 0;
     const countFn = this.engine.count;
     if (typeof countFn === "function") {
       try {
@@ -5234,7 +5428,10 @@ var _ApprovalService = class _ApprovalService {
     });
     if (!Array.isArray(rows) || !rows[0]) return null;
     if (enforceVisibility) {
-      const visible = await this.visibleRequestIds(context, tenantOrg ?? null);
+      const visible = await this.visibleRequestIds(context, tenantOrg ?? null, {
+        object: rows[0].object_name,
+        recordId: rows[0].record_id
+      });
       if (visible && !visible.has(String(rows[0].id))) return null;
     }
     const row = rowFromRequest(rows[0]);
@@ -5994,6 +6191,9 @@ var ApprovalsServicePlugin = class {
       engine,
       logger: ctx.logger,
       publicBaseUrl: this.options.publicBaseUrl,
+      // [#8652] Read-only record-reader visibility. Default OFF — an absent
+      // declaration reaches the service as an empty set and changes nothing.
+      recordReaderVisibleObjects: this.options.recordReaderVisibleObjects,
       // [ADR-0105 D9] Cross-organization approver targeting is a `group`-posture
       // capability. Read LAZILY (not captured at start) because the tenancy
       // service resolves its posture during its own start, which may not have