@objectstack/plugin-security 8.0.0 → 9.0.0

package/dist/index.d.mts

@@ -82,10 +82,58 @@ declare class SecurityPlugin implements Plugin {
      * zero rows.
      */
     private readonly tenancyDisabledCache;
+    /**
+     * Service handles captured in `start()` so the request-time RLS resolution
+     * (used by BOTH the engine middleware and the public {@link getReadFilter}
+     * service method) shares one code path. `null` until `start()` wires them.
+     */
+    private metadata;
+    private ql;
+    private dbLoader?;
+    private logger;
     constructor(options?: SecurityPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
     destroy(): Promise<void>;
+    /**
+     * ADR-0021 D-C — resolve the per-request READ scope (tenant + RLS predicate)
+     * for one object as a canonical `FilterCondition`, WITHOUT touching the
+     * ObjectQL engine. This is the seam the analytics raw-SQL path bridges to so
+     * it enforces the SAME row scoping the engine middleware applies on `find`.
+     *
+     * Returns:
+     *   - `undefined` → no scope applies (system context, or an unauthenticated
+     *     request with no userId/roles/permissions — authn is gated elsewhere).
+     *   - a `FilterCondition` → AND it into the object's scan (the join's `ON`/
+     *     `WHERE` for analytics; the where clause for a plain find).
+     *   - the `RLS_DENY_FILTER` sentinel → policies applied but none compiled, or
+     *     resolution failed — fail-closed to zero rows. NEVER returns "allow all"
+     *     on error, so a degraded permission subsystem cannot leak cross-tenant
+     *     rows through analytics.
+     *
+     * Async because permission-set resolution can hit the database; the analytics
+     * service pre-resolves these per request (base + every joined object) before
+     * the synchronous SQL builder runs.
+     */
+    getReadFilter(object: string, context?: any): Promise<Record<string, unknown> | null | undefined>;
+    /**
+     * Resolve the effective permission sets for an execution context — roles +
+     * explicit permission sets, with the configured baseline applied both as an
+     * implicit request (when none were named) and as a post-resolution fallback
+     * (when named ones resolved to nothing). Shared by the engine middleware and
+     * {@link getReadFilter} so both enforce identical RLS. May throw if the
+     * underlying metadata/db resolution fails (callers fail-closed).
+     */
+    private resolvePermissionSetsForContext;
+    /**
+     * Compile the applicable RLS policies for (object, operation) into a single
+     * `FilterCondition`, applying the field-existence safety net (wildcard
+     * policies targeting a column the object lacks fail-closed to the deny
+     * sentinel, unless the object explicitly opted out of tenancy). Shared by the
+     * engine middleware and {@link getReadFilter}. Returns `null` when no policy
+     * applies (caller adds no filter).
+     */
+    private computeRlsFilter;
     /**
      * Collect all RLS policies from permission sets applicable to the given object/operation.
      */
@@ -774,10 +822,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {
@@ -3612,10 +3659,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {
@@ -7044,10 +7090,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {
@@ -9293,10 +9338,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {

package/dist/index.d.ts

@@ -82,10 +82,58 @@ declare class SecurityPlugin implements Plugin {
      * zero rows.
      */
     private readonly tenancyDisabledCache;
+    /**
+     * Service handles captured in `start()` so the request-time RLS resolution
+     * (used by BOTH the engine middleware and the public {@link getReadFilter}
+     * service method) shares one code path. `null` until `start()` wires them.
+     */
+    private metadata;
+    private ql;
+    private dbLoader?;
+    private logger;
     constructor(options?: SecurityPluginOptions);
     init(ctx: PluginContext): Promise<void>;
     start(ctx: PluginContext): Promise<void>;
     destroy(): Promise<void>;
+    /**
+     * ADR-0021 D-C — resolve the per-request READ scope (tenant + RLS predicate)
+     * for one object as a canonical `FilterCondition`, WITHOUT touching the
+     * ObjectQL engine. This is the seam the analytics raw-SQL path bridges to so
+     * it enforces the SAME row scoping the engine middleware applies on `find`.
+     *
+     * Returns:
+     *   - `undefined` → no scope applies (system context, or an unauthenticated
+     *     request with no userId/roles/permissions — authn is gated elsewhere).
+     *   - a `FilterCondition` → AND it into the object's scan (the join's `ON`/
+     *     `WHERE` for analytics; the where clause for a plain find).
+     *   - the `RLS_DENY_FILTER` sentinel → policies applied but none compiled, or
+     *     resolution failed — fail-closed to zero rows. NEVER returns "allow all"
+     *     on error, so a degraded permission subsystem cannot leak cross-tenant
+     *     rows through analytics.
+     *
+     * Async because permission-set resolution can hit the database; the analytics
+     * service pre-resolves these per request (base + every joined object) before
+     * the synchronous SQL builder runs.
+     */
+    getReadFilter(object: string, context?: any): Promise<Record<string, unknown> | null | undefined>;
+    /**
+     * Resolve the effective permission sets for an execution context — roles +
+     * explicit permission sets, with the configured baseline applied both as an
+     * implicit request (when none were named) and as a post-resolution fallback
+     * (when named ones resolved to nothing). Shared by the engine middleware and
+     * {@link getReadFilter} so both enforce identical RLS. May throw if the
+     * underlying metadata/db resolution fails (callers fail-closed).
+     */
+    private resolvePermissionSetsForContext;
+    /**
+     * Compile the applicable RLS policies for (object, operation) into a single
+     * `FilterCondition`, applying the field-existence safety net (wildcard
+     * policies targeting a column the object lacks fail-closed to the deny
+     * sentinel, unless the object explicitly opted out of tenancy). Shared by the
+     * engine middleware and {@link getReadFilter}. Returns `null` when no policy
+     * applies (caller adds no filter).
+     */
+    private computeRlsFilter;
     /**
      * Collect all RLS policies from permission sets applicable to the given object/operation.
      */
@@ -774,10 +822,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {
@@ -3612,10 +3659,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {
@@ -7044,10 +7090,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {
@@ -9293,10 +9338,9 @@ declare const securityObjects: ((Omit<{
         } | undefined;
         chart?: {
             chartType: "bar" | "line" | "pie" | "area" | "scatter";
-            xAxisField: string;
-            yAxisFields: string[];
-            aggregation?: "count" | "min" | "max" | "sum" | "avg" | undefined;
-            groupByField?: string | undefined;
+            dataset: string;
+            values: string[];
+            dimensions?: string[] | undefined;
         } | undefined;
         description?: string | undefined;
         sharing?: {

package/dist/index.js

@@ -2572,6 +2572,14 @@ var SecurityPlugin = class {
      * zero rows.
      */
     this.tenancyDisabledCache = /* @__PURE__ */ new Map();
+    /**
+     * Service handles captured in `start()` so the request-time RLS resolution
+     * (used by BOTH the engine middleware and the public {@link getReadFilter}
+     * service method) shares one code path. `null` until `start()` wires them.
+     */
+    this.metadata = null;
+    this.ql = null;
+    this.logger = {};
     this.bootstrapPermissionSets = options.defaultPermissionSets ?? securityDefaultPermissionSets;
     this.fallbackPermissionSet = options.fallbackPermissionSet === void 0 ? "member_default" : options.fallbackPermissionSet;
   }
@@ -2637,6 +2645,9 @@ var SecurityPlugin = class {
       ctx.logger.warn("ObjectQL engine does not support middleware, security middleware not registered");
       return;
     }
+    this.metadata = metadata;
+    this.ql = ql;
+    this.logger = ctx.logger;
     try {
       const orgScoping = ctx.getService("org-scoping");
       this.orgScopingEnabled = !!orgScoping;
@@ -2671,6 +2682,17 @@ var SecurityPlugin = class {
         fields: typeof r.field_permissions === "string" ? JSON.parse(r.field_permissions || "{}") : r.field_permissions ?? {}
       }));
     } : void 0;
+    this.dbLoader = dbLoader;
+    try {
+      ctx.registerService("security", {
+        getReadFilter: (object, context) => this.getReadFilter(object, context)
+      });
+      ctx.logger.info('[security] registered "security" service (getReadFilter) for raw-SQL RLS bridging');
+    } catch (e) {
+      ctx.logger.warn?.('[security] failed to register "security" service', {
+        error: e.message
+      });
+    }
     ql.registerMiddleware(async (opCtx, next) => {
       if (opCtx.context?.isSystem) {
         return next();
@@ -2682,25 +2704,7 @@ var SecurityPlugin = class {
       }
       let permissionSets = [];
       try {
-        const requested = [...roles, ...explicitPermissionSets];
-        if (requested.length === 0 && opCtx.context?.userId && this.fallbackPermissionSet) {
-          requested.push(this.fallbackPermissionSet);
-        }
-        permissionSets = await this.permissionEvaluator.resolvePermissionSets(
-          requested,
-          metadata,
-          this.bootstrapPermissionSets,
-          dbLoader
-        );
-        if (permissionSets.length === 0 && opCtx.context?.userId && this.fallbackPermissionSet) {
-          const fallback = await this.permissionEvaluator.resolvePermissionSets(
-            [this.fallbackPermissionSet],
-            metadata,
-            this.bootstrapPermissionSets,
-            dbLoader
-          );
-          permissionSets = fallback;
-        }
+        permissionSets = await this.resolvePermissionSetsForContext(opCtx.context);
       } catch (e) {
         ctx.logger.error(
           `[security] permission resolution failed for operation '${opCtx.operation}' on object '${opCtx.object}' (user ${opCtx.context?.userId ?? "unknown"}) \u2014 denying request (fail-closed)`,
@@ -2756,25 +2760,13 @@ var SecurityPlugin = class {
           }
         }
       }
-      const allRlsPolicies = this.collectRLSPolicies(permissionSets, opCtx.object, opCtx.operation);
-      if (allRlsPolicies.length > 0 && opCtx.ast) {
-        const objectFields = await this.getObjectFieldNames(metadata, opCtx.object, ql);
-        const tenancyDisabled = this.tenancyDisabledCache.get(opCtx.object) === true;
-        let dropped = 0;
-        const compilable = objectFields ? allRlsPolicies.filter((p) => {
-          const targetField = this.extractTargetField(p.using);
-          if (!targetField) return true;
-          if (objectFields.has(targetField)) return true;
-          if (tenancyDisabled && targetField === "organization_id") {
-            return false;
-          }
-          dropped++;
-          return false;
-        }) : allRlsPolicies;
-        let rlsFilter = this.rlsCompiler.compileFilter(compilable, opCtx.context);
-        if (rlsFilter == null && dropped > 0) {
-          rlsFilter = { ...RLS_DENY_FILTER };
-        }
+      if (opCtx.ast) {
+        const rlsFilter = await this.computeRlsFilter(
+          permissionSets,
+          opCtx.object,
+          opCtx.operation,
+          opCtx.context
+        );
         if (rlsFilter) {
           if (opCtx.ast.where) {
             opCtx.ast.where = { $and: [opCtx.ast.where, rlsFilter] };
@@ -2856,6 +2848,106 @@ var SecurityPlugin = class {
   }
   async destroy() {
   }
+  /**
+   * ADR-0021 D-C — resolve the per-request READ scope (tenant + RLS predicate)
+   * for one object as a canonical `FilterCondition`, WITHOUT touching the
+   * ObjectQL engine. This is the seam the analytics raw-SQL path bridges to so
+   * it enforces the SAME row scoping the engine middleware applies on `find`.
+   *
+   * Returns:
+   *   - `undefined` → no scope applies (system context, or an unauthenticated
+   *     request with no userId/roles/permissions — authn is gated elsewhere).
+   *   - a `FilterCondition` → AND it into the object's scan (the join's `ON`/
+   *     `WHERE` for analytics; the where clause for a plain find).
+   *   - the `RLS_DENY_FILTER` sentinel → policies applied but none compiled, or
+   *     resolution failed — fail-closed to zero rows. NEVER returns "allow all"
+   *     on error, so a degraded permission subsystem cannot leak cross-tenant
+   *     rows through analytics.
+   *
+   * Async because permission-set resolution can hit the database; the analytics
+   * service pre-resolves these per request (base + every joined object) before
+   * the synchronous SQL builder runs.
+   */
+  async getReadFilter(object, context) {
+    if (context?.isSystem) return void 0;
+    const roles = context?.roles ?? [];
+    const explicit = context?.permissions ?? [];
+    if (roles.length === 0 && explicit.length === 0 && !context?.userId) {
+      return void 0;
+    }
+    try {
+      const permissionSets = await this.resolvePermissionSetsForContext(context);
+      const filter = await this.computeRlsFilter(permissionSets, object, "find", context);
+      return filter ?? void 0;
+    } catch (e) {
+      this.logger.error?.(
+        `[security] getReadFilter failed for object '${object}' (user ${context?.userId ?? "unknown"}) \u2014 denying (fail-closed)`,
+        e instanceof Error ? e : new Error(String(e))
+      );
+      return { ...RLS_DENY_FILTER };
+    }
+  }
+  /**
+   * Resolve the effective permission sets for an execution context — roles +
+   * explicit permission sets, with the configured baseline applied both as an
+   * implicit request (when none were named) and as a post-resolution fallback
+   * (when named ones resolved to nothing). Shared by the engine middleware and
+   * {@link getReadFilter} so both enforce identical RLS. May throw if the
+   * underlying metadata/db resolution fails (callers fail-closed).
+   */
+  async resolvePermissionSetsForContext(context) {
+    const roles = context?.roles ?? [];
+    const explicitPermissionSets = context?.permissions ?? [];
+    const requested = [...roles, ...explicitPermissionSets];
+    if (requested.length === 0 && context?.userId && this.fallbackPermissionSet) {
+      requested.push(this.fallbackPermissionSet);
+    }
+    let permissionSets = await this.permissionEvaluator.resolvePermissionSets(
+      requested,
+      this.metadata,
+      this.bootstrapPermissionSets,
+      this.dbLoader
+    );
+    if (permissionSets.length === 0 && context?.userId && this.fallbackPermissionSet) {
+      permissionSets = await this.permissionEvaluator.resolvePermissionSets(
+        [this.fallbackPermissionSet],
+        this.metadata,
+        this.bootstrapPermissionSets,
+        this.dbLoader
+      );
+    }
+    return permissionSets;
+  }
+  /**
+   * Compile the applicable RLS policies for (object, operation) into a single
+   * `FilterCondition`, applying the field-existence safety net (wildcard
+   * policies targeting a column the object lacks fail-closed to the deny
+   * sentinel, unless the object explicitly opted out of tenancy). Shared by the
+   * engine middleware and {@link getReadFilter}. Returns `null` when no policy
+   * applies (caller adds no filter).
+   */
+  async computeRlsFilter(permissionSets, object, operation, context) {
+    const allRlsPolicies = this.collectRLSPolicies(permissionSets, object, operation);
+    if (allRlsPolicies.length === 0) return null;
+    const objectFields = await this.getObjectFieldNames(this.metadata, object, this.ql);
+    const tenancyDisabled = this.tenancyDisabledCache.get(object) === true;
+    let dropped = 0;
+    const compilable = objectFields ? allRlsPolicies.filter((p) => {
+      const targetField = this.extractTargetField(p.using);
+      if (!targetField) return true;
+      if (objectFields.has(targetField)) return true;
+      if (tenancyDisabled && targetField === "organization_id") {
+        return false;
+      }
+      dropped++;
+      return false;
+    }) : allRlsPolicies;
+    let rlsFilter = this.rlsCompiler.compileFilter(compilable, context);
+    if (rlsFilter == null && dropped > 0) {
+      rlsFilter = { ...RLS_DENY_FILTER };
+    }
+    return rlsFilter;
+  }
   /**
    * Collect all RLS policies from permission sets applicable to the given object/operation.
    */