@objectstack/plugin-approvals 17.1.0 → 17.2.0

package/dist/index.d.ts

@@ -364,11 +364,18 @@ declare const SysApprovalRequest: Omit<{
             maxAge: string;
             onlyWhen?: Record<string, string | number | boolean | {
                 $in: (string | number)[];
+            } | {
+                $null: boolean;
             }> | undefined;
         } | undefined;
         ttl?: {
             field: string;
             expireAfter: string;
+            onlyWhen?: Record<string, string | number | boolean | {
+                $in: (string | number)[];
+            } | {
+                $null: boolean;
+            }> | undefined;
         } | undefined;
         storage?: {
             strategy: "rotation";
@@ -4566,11 +4573,18 @@ declare const SysApprovalAction: Omit<{
             maxAge: string;
             onlyWhen?: Record<string, string | number | boolean | {
                 $in: (string | number)[];
+            } | {
+                $null: boolean;
             }> | undefined;
         } | undefined;
         ttl?: {
             field: string;
             expireAfter: string;
+            onlyWhen?: Record<string, string | number | boolean | {
+                $in: (string | number)[];
+            } | {
+                $null: boolean;
+            }> | undefined;
         } | undefined;
         storage?: {
             strategy: "rotation";
@@ -7129,11 +7143,18 @@ declare const SysApprovalApprover: Omit<{
             maxAge: string;
             onlyWhen?: Record<string, string | number | boolean | {
                 $in: (string | number)[];
+            } | {
+                $null: boolean;
             }> | undefined;
         } | undefined;
         ttl?: {
             field: string;
             expireAfter: string;
+            onlyWhen?: Record<string, string | number | boolean | {
+                $in: (string | number)[];
+            } | {
+                $null: boolean;
+            }> | undefined;
         } | undefined;
         storage?: {
             strategy: "rotation";
@@ -8671,11 +8692,18 @@ declare const SysApprovalDelegation: Omit<{
             maxAge: string;
             onlyWhen?: Record<string, string | number | boolean | {
                 $in: (string | number)[];
+            } | {
+                $null: boolean;
             }> | undefined;
         } | undefined;
         ttl?: {
             field: string;
             expireAfter: string;
+            onlyWhen?: Record<string, string | number | boolean | {
+                $in: (string | number)[];
+            } | {
+                $null: boolean;
+            }> | undefined;
         } | undefined;
         storage?: {
             strategy: "rotation";
@@ -10443,6 +10471,64 @@ declare const SysApprovalDelegation: Omit<{
     };
 }, "fields">;
 
+/**
+ * Read-time redaction of the approval payload snapshot (#10749).
+ *
+ * ## The defect this closes
+ *
+ * `sys_approval_request.payload_json` stores the submitted record's raw row,
+ * captured from the flow's `$record` variable — which the automation layer
+ * hands over with **the record's own FLS never applying**. The column is a
+ * `textarea` on `sys_approval_request`, so to every read door it is an opaque
+ * string: the field-visibility machinery governs *columns of objects* and
+ * cannot see inside a JSON column. Every field-level read control an app
+ * author declared on the SUBJECT object — `requiredPermissions` (ADR-0066 D3),
+ * a permission set marking a field non-readable, a `maskingRule` — is
+ * therefore unenforceable on the approval path, for every app.
+ *
+ * ## The shape of the fix (maintainer ruling 2026-08-22, Option B)
+ *
+ * The full snapshot **stays at rest**: the approval record remains audit
+ * evidence of what was actually submitted. Redaction is applied at SERVE time,
+ * keyed on the reading caller, so the same row answers an admin with the whole
+ * snapshot and a restricted approver with only the fields they may read.
+ *
+ * The readable set is not recomputed here. It comes from the security
+ * service's `getReadableFields(object, context)` — documented as the same
+ * field mask the read middleware applies, so this seam cannot drift from
+ * data-plane FLS, and the CSV/XLSX export path already derives its columns
+ * from it.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * - **It does not gate on OBJECT-level access.** An approver routinely has no
+ *   read grant on the object under approval at all — that is the normal shape
+ *   of an approval, and the snapshot is how they see what they are approving.
+ *   `getReadableFields` answers with the full field set for a caller who has
+ *   no field-permission entries for the object, which is exactly the behaviour
+ *   this seam wants: FIELD-level declarations are enforced, object-level
+ *   access is untouched, and every approval drawer shipping today keeps
+ *   rendering.
+ * - **It does not act on `hidden: true`.** `hidden` is a UI contract ("Hidden
+ *   from default UI") and, in the spec's own words, "has never governed
+ *   serialization" — measurably: no read path in the repo strips a value on
+ *   it. Making it govern serialization here alone would make the approval path
+ *   stricter than a direct read of the very same row (so it would close no
+ *   leak — the approver can just read the record), while breaking every drawer
+ *   that renders a `hidden` business column. That is a `packages/spec`
+ *   semantics question, and it is left open rather than decided here.
+ */
+/** The slice of the security service this seam consumes. */
+interface FieldVisibilitySource {
+    /**
+     * Fields of `object` this context may read — the same mask the ObjectQL read
+     * middleware applies. `undefined` when the object schema cannot be resolved;
+     * `[]` is the security plugin's own fail-closed tier (unresolvable posture,
+     * dangling on-behalf-of delegator).
+     */
+    getReadableFields(object: string, context?: unknown): Promise<string[] | undefined>;
+}
+
 /**
  * Node-era approval runtime (ADR-0019).
  *
@@ -10608,7 +10694,7 @@ interface ApprovalServiceOptions {
     clock?: ApprovalClock;
     logger?: {
         info?: (msg: any, ...rest: any[]) => void;
-        warn?: (msg: any, ...rest: any[]) => void;
+        warn: (msg: any, ...rest: any[]) => void;
         error?: (msg: any, ...rest: any[]) => void;
         debug?: (msg: any, ...rest: any[]) => void;
     };
@@ -10635,6 +10721,14 @@ interface ApprovalServiceOptions {
      * guard stands down.
      */
     tenancyPosture?: () => string | undefined;
+    /**
+     * [#10749] Field-visibility authority used to redact the payload snapshot at
+     * serve time. Usually attached after construction via
+     * {@link ApprovalService.attachFieldVisibility}, because the security plugin
+     * may register after this one. Absent ⇒ snapshots are served unredacted,
+     * exactly as before this seam landed.
+     */
+    fieldVisibility?: FieldVisibilitySource;
     /**
      * [#8652] Objects on which a user holding READ access to the target business
      * record may also see that record's approval requests and action history —
@@ -10652,6 +10746,7 @@ declare class ApprovalService implements IApprovalService {
     private messaging?;
     private publicBaseUrl;
     private tenancyPosture?;
+    private fieldVisibility?;
     /**
      * [#8652] The enabled object set for the record-reader visibility tier.
      * EMPTY means the tier is off — the default, and the shape every existing
@@ -10661,6 +10756,29 @@ declare class ApprovalService implements IApprovalService {
     constructor(opts: ApprovalServiceOptions);
     /** Attach (or replace) the ADR-0105 D9 posture provider. */
     attachTenancyPosture(provider: () => string | undefined): void;
+    /**
+     * [#10749] Attach (or replace) the field-visibility authority the payload
+     * redaction seam reads. Late-bound: plugin load order does not guarantee the
+     * security service exists when this one is constructed.
+     */
+    attachFieldVisibility(source: FieldVisibilitySource | undefined): void;
+    /**
+     * [#10749] Redact each row's payload snapshot down to the fields the READING
+     * caller may see on that row's subject object.
+     *
+     * Runs BEFORE {@link ApprovalService.enrichRows}, and that ordering is
+     * load-bearing rather than incidental: `enrichRows` derives `payload_display`
+     * (lookup foreign keys inside the snapshot resolved to referenced record
+     * titles) and `payload_labels` (a label per snapshot key) by WALKING THE
+     * SNAPSHOT'S OWN KEYS. Redact first and both derived maps are clean for free;
+     * redact after and a restricted field's name, its authored label and the
+     * title of the record it points at all still ship — the value would be gone
+     * and the disclosure would not.
+     *
+     * Rows are grouped by subject object so one `getReadableFields` call covers a
+     * whole page of same-object requests.
+     */
+    private redactPayloads;
     /** Deps bundle for the ADR-0105 D9 org-scope helpers. */
     private get orgScopeDeps();
     /**
@@ -10789,8 +10907,110 @@ declare class ApprovalService implements IApprovalService {
      * expression's own values, pre-expansion) for the `__resolvedFrom` audit.
      */
     private resolveExpressionApprovers;
-    /** Flat team — `sys_team` is better-auth's collaboration grouping (no hierarchy). */
+    /**
+     * Flat team — `sys_team` is better-auth's collaboration grouping (no hierarchy).
+     *
+     * Takes an organization for the reason every sibling expansion does
+     * ({@link expandBusinessUnitUsers}, {@link expandPositionUsers},
+     * {@link expandMembershipTierUsers}): an approver expansion answers "who, in
+     * THIS organization". Before #10230 this one did not ask, and it was the last
+     * expansion that did not — a `team` approver naming ANOTHER organization's
+     * team routed that organization's people an approval over a record they are
+     * not a tenant of.
+     *
+     * TWO screens run here, and they assert different things (#10230, #10547):
+     *
+     *   1. the TEAM must not provably belong to another organization
+     *      ({@link teamIsProvablyOutsideOrg}) — `sys_team` carries
+     *      `organization_id` outright
+     *      (`packages/platform-objects/src/identity/sys-team.object.ts`), so a
+     *      team id transitively names exactly one organization and ONE row
+     *      answers the question;
+     *   2. each expanded MEMBER must not provably hold membership only in other
+     *      organizations ({@link dropMembersProvablyOutsideOrg}) —
+     *      `sys_team_member` carries `team_id` and `user_id` and NO tenancy
+     *      column at all, so passing (1) says nothing whatever about the people
+     *      it lists.
+     *
+     * #10230 landed (1) alone and deferred (2) on purpose. What closed the
+     * deferral is that (1) does not imply (2) even a little: a member removed
+     * from the organization but left on the team, a team re-parented across
+     * organizations (`/organization/update-team` accepts `organizationId` in its
+     * partial body), or a `sys_team_member` row written by a seed rather than
+     * through better-auth all produce a team that passes (1) carrying a user who
+     * is provably a tenant of somewhere else. Measured on this tree, not read off
+     * the schema — the probe is quoted in `team-member-org-screen.test.ts`.
+     *
+     * (2) is the SAME assertion as {@link managerIsProvablyOutsideOrg}, one hop
+     * further out, and it is asserted the same way: `sys_user` carries no tenancy
+     * fact, so `sys_member` rows are the only evidence that a person is placed
+     * anywhere. Like that screen, this one grants no reads and applies no read
+     * screen to any approver type that lacks one today, so it decides nothing
+     * #7497 (does approver routing imply record read visibility?) asks.
+     */
     private expandTeamUsers;
+    /**
+     * Is `teamId` PROVABLY a team of a DIFFERENT organization? (#10230)
+     *
+     * "Provably" carries the same posture the sibling screen states at length in
+     * {@link managerIsProvablyOutsideOrg}, for the same reasons:
+     *
+     *   - the team row carries an `organization_id` and it is not the request's
+     *       ⇒ the tenancy fact is present and NEGATIVE ⇒ screen it out;
+     *   - the row carries no `organization_id`, does not exist, or the read failed
+     *       ⇒ the tenancy fact is ABSENT ⇒ leave routing exactly as it was.
+     *
+     * The `organization_id = null` limb is not timidity — it is the reading
+     * {@link businessUnitOrgScope} settled on one screen below, for the identical
+     * shape: null on a platform object means "owned by no organization", which is
+     * what a seed writes because a seed cannot know the organization id the
+     * runtime mints at boot. Treating null as "not mine" would delete every
+     * seeded team approver at once — a larger behaviour change than the hole
+     * being closed. Measured, and not hypothetically: this package's own
+     * `team_ok` expansion fixture is exactly such a stack (it has
+     * `sys_team_member` rows, a request carrying an organization, and no
+     * `sys_team` row at all).
+     *
+     * Screening the TEAM before reading its members is also what keeps the cost
+     * at one row: a team that fails the screen never fans out.
+     */
+    private teamIsProvablyOutsideOrg;
+    /**
+     * Drop the expanded team members who are PROVABLY tenants of other
+     * organizations and not of `organizationId`. (#10547)
+     *
+     * Returns the survivors, in the order they were expanded.
+     *
+     * Posture — identical to {@link managerIsProvablyOutsideOrg} and
+     * {@link teamIsProvablyOutsideOrg}, deliberately, because it is the same
+     * assertion about the same table:
+     *
+     *   - membership rows exist for this user, none in `organizationId`
+     *       ⇒ the tenancy fact is present and NEGATIVE ⇒ drop him;
+     *   - no membership rows at all for him, the read failed, or the request
+     *     carries no organization
+     *       ⇒ the tenancy fact is ABSENT ⇒ leave routing exactly as it was.
+     *
+     * The absent limb is load-bearing rather than timid, and #3807 is the recorded
+     * cost of getting it wrong: a stack that stamps an organization on requests
+     * but never materializes `sys_member` rows would otherwise lose EVERY team
+     * approver at once. This package's own `team_ok` expansion fixture and
+     * #10230's T2/T3 fixtures are exactly such stacks — they carry team rows and
+     * a request organization and no `sys_member` table at all — so the absent
+     * limb is exercised by neighbours on every run of this suite.
+     *
+     * ONE read for the whole slate, never one per person: the expansion is capped
+     * at 10000 members and a per-user query would turn a single team approver
+     * into 10000 round trips.
+     *
+     * ⚠️ A TRUNCATED read fails open, and that is the subtle half. This read is
+     * the only evidence that a member IS a tenant here, so a result cut off at
+     * the limit could be missing the very row that keeps a legitimate approver on
+     * the slate — screening him out on missing evidence, which inverts the
+     * posture into fail-CLOSED precisely where it must not. When the read comes
+     * back at the cap it is treated as no evidence at all.
+     */
+    private dropMembersProvablyOutsideOrg;
     /**
      * Tenant scope for a `sys_business_unit` read that may legitimately be
      * env-wide (#3807).
@@ -10876,7 +11096,64 @@ declare class ApprovalService implements IApprovalService {
      * change here changes position routing too.
      */
     private expandMembershipTierUsers;
+    /**
+     * `sys_user.manager_id`, screened to the request's organization (#10153).
+     *
+     * Takes an organization argument for the same reason its siblings do
+     * ({@link expandPositionUsers}, {@link expandMembershipTierUsers}): an
+     * approver expansion answers "who, in THIS organization". Before #10153 this
+     * one did not ask, and it was the only expansion that did not — a
+     * `manager_id` pointing at a person in another organization routed that
+     * person an approval over a record they are not a tenant of.
+     *
+     * ⚠️ The screen reads `sys_member`, which LOOKS like the D2 read-visibility
+     * filter next to it ({@link filterApproversWhoCanRead}). It is not, and this
+     * comment exists so the next reader does not conclude that #7497 (does
+     * approver routing imply record read visibility?) was settled here. It was
+     * not. Two facts make this the SIBLING treatment rather than a
+     * read-visibility ruling:
+     *
+     *   1. Two of the three org-scoped expansions already screen on exactly this
+     *      column — `expandMembershipTierUsers` filters `sys_member.organization_id`
+     *      outright, and it is also the second limb of `expandPositionUsers`. So
+     *      `sys_member.organization_id` is already this file's answer to "which
+     *      organization is this person in", independent of what they may read.
+     *   2. `sys_user` carries no `organization_id` at all. It is a GLOBAL identity
+     *      table, so a membership row is the only tenancy fact that exists for a
+     *      user — there is no other read this screen could have been written with.
+     *
+     * This change grants no reads and applies no read screen to any type that
+     * lacks one today, so it decides nothing #7497 asks.
+     */
     private lookupManager;
+    /**
+     * Is `managerId` PROVABLY a member of other organizations and not of
+     * `organizationId`? (#10153)
+     *
+     * "Provably" is the whole shape of this screen, and it is deliberate rather
+     * than a weaker version of "must prove membership":
+     *
+     *   - membership rows exist for this user, none in the request's org
+     *       ⇒ the tenancy fact is present and NEGATIVE ⇒ screen him out;
+     *   - no membership rows at all, or the read failed
+     *       ⇒ the tenancy fact is ABSENT ⇒ leave routing exactly as it was.
+     *
+     * The fail-open half is not timidity, it is this file's ruled posture on
+     * addressing paths, stated twice already: {@link filterApproversWhoCanRead}
+     * refuses to empty a live slate on an infrastructure hiccup, and
+     * {@link expandPositionUsers} carries "a step routing to nobody is worse than
+     * one routing to a lapsed holder". It is also load-bearing in practice — a
+     * stack that stamps an organization on its requests but does not materialize
+     * `sys_member` rows would otherwise lose every manager approver at once,
+     * which is a bigger behaviour change than the hole being closed. Measured:
+     * this repo's own `type:manager` out-of-office fixture is such a stack.
+     *
+     * Screening the MANAGER only, before OOO delegation, is deliberate too: the
+     * delegate arrives from `sys_approval_delegation`, whose rows already carry
+     * (and are already filtered by) an `organization_id` in
+     * {@link lookupActiveDelegation}. This card is about `sys_user.manager_id`.
+     */
+    private managerIsProvablyOutsideOrg;
     /**
      * Out-of-office auto-skip (#1322 M1). Given an individually-routed approver
      * id, follow any active `sys_approval_delegation` chain and return the id the
@@ -11408,6 +11685,56 @@ declare class ApprovalService implements IApprovalService {
         inserted: number;
         deleted: number;
     }>;
+    /**
+     * [#11040] May the free-text pushdown carry an arm on the SNAPSHOT column,
+     * for THIS caller over THIS query's scope?
+     *
+     * `payload_json` is the one searched column whose contents the serve path
+     * masks per reader (`redactPayloads`, #10749). A predicate over it is
+     * evaluated by the driver against the column AT REST — unmasked, before
+     * anything is served — so for a caller whose view of the snapshot is masked,
+     * row membership answers questions about contents that caller may not read.
+     * The other four arms are columns of `sys_approval_request` itself, which
+     * every caller who can see the row reads whole; they are untouched.
+     *
+     * ## The invariant this method exists to hold
+     *
+     * "This caller's view is masked" is read from **the same authority and the
+     * same per-caller call as the serve path** — `resolveReadableSnapshotFields`,
+     * asked as the CALLER (never `SYSTEM_CTX`). A second, independently derived
+     * notion of "redacted" — comparing the readable set against the object's
+     * schema, say — would be a fresh source of drift, and drift between the
+     * serve rule and the filter rule IS the defect this closes, reconstituted one
+     * layer down. So the only "not masked" answer accepted here is the one serve
+     * itself acts on: `undefined`, the seam's documented do-not-narrow branch.
+     * When the seam holds a concrete list the mask is IN FORCE, whether or not it
+     * happens to remove a key from any particular row — a row-dependent question
+     * no predicate can answer before rows exist.
+     *
+     * ## The two predicate-time cases
+     *
+     * Redaction is decided per ROW (each row names its own subject object, hence
+     * its own readable set), but a filter is built before any row exists:
+     *
+     *  - **authority absent** — `resolveReadableSnapshotFields` answers
+     *    `undefined` for EVERY object, so serve hands over every snapshot whole.
+     *    Keeping the arm leaks nothing serve does not already hand over, and this
+     *    is the shape every deployment that has not wired the security plugin
+     *    gets: search is byte-for-byte unchanged. Checked first, and that order
+     *    is load-bearing — see the object-scope note below.
+     *  - **authority wired** — the readable set is per object, so the arm is
+     *    admissible only for a scope of exactly one KNOWN object. With
+     *    `filter.object` present that object is known at predicate time and the
+     *    seam is asked about it directly. Absent, the query spans every object
+     *    and there is nothing sound to ask, so the arm is dropped.
+     *
+     * Dropping an arm is strictly NARROWING: it never refuses a query and never
+     * widens what comes back, so the fail-closed direction is cheap here and is
+     * taken rather than reaching for a per-object predicate machine to avoid it.
+     * Refusing the query outright would be the louder behaviour change, and is
+     * deliberately not what this does.
+     */
+    private freeTextMayMatchSnapshot;
     /** Filter type accepted by {@link listRequests} / {@link countRequests}. */
     private buildRequestWhere;
     /** Window the approver-index probe — pending queues live far below this. */
@@ -11641,10 +11968,45 @@ declare class ApprovalsServicePlugin implements Plugin {
     private service?;
     private engine?;
     private escalationJobScheduled;
+    /**
+     * Captured where the job is scheduled, not resolved at teardown: `destroy()`
+     * — the hook the kernel actually calls — takes NO `PluginContext`
+     * (`Plugin.destroy?(): Promise<void> | void`, core `types.ts`). Holding the
+     * very service the schedule was placed with also means the cancel cannot miss
+     * it because the registry has already been torn down around us.
+     */
+    private jobService?;
     constructor(options?: ApprovalsPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
-    stop(ctx: PluginContext): Promise<void>;
+    /**
+     * The kernel's teardown hook (`Plugin.destroy?()`, core `types.ts`) — the
+     * ONLY teardown entry point `ObjectKernel.performShutdown()` and
+     * `LiteKernel.destroy()` invoke.
+     *
+     * [#10371] IT USED TO BE `stop()`, WHICH NOTHING CALLED. `Plugin` declares
+     * `init()`, `start?()` and `destroy?()` and no `stop()`, so the kernel walked
+     * past this plugin at shutdown: the SLA escalation job stayed scheduled and
+     * this plugin's ObjectQL hooks stayed bound to an engine the kernel had
+     * finished with. `start()` IS on the interface, so the pair read as symmetric
+     * in review — that asymmetry is what let the same shape survive in six
+     * packages at once.
+     *
+     * This member owns no timer of its own (the escalation clock belongs to
+     * `service-job`), so it never cost a merge-queue eviction the way the
+     * `plugin-reports` / `service-messaging` members did (#9371). The class is
+     * the same one either way: a teardown the kernel does not reach.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Retained alias for {@link destroy}. Kept because it is public API of an
+     * exported class, and removing it would break an embedder who learned to call
+     * it directly precisely BECAUSE the kernel never did. The parameter is now
+     * optional and ignored: `destroy()` takes no context, so teardown uses the
+     * job service captured when the escalation clock was wired. Prefer kernel
+     * shutdown; direct callers keep working unchanged.
+     */
+    stop(_ctx?: PluginContext): Promise<void>;
 }
 
 /** Minimal surface of the automation engine this provider depends on. */