fix(analytics): scope dimension-label lookup to the referenced object's RLS (#3602)

A dataset that groups by a lookup/master_detail dimension resolves the
grouped FK ids to the related record's display name via a per-record read
(`group by id`) dressed as an aggregate. That read carried no read scope,
so it revealed related-record display names whenever the referenced
object's RLS is stricter than the base object whose rows carry the id — a
user could read a name the referenced object's own RLS would hide.
(Same-object and looser-referenced cases were already safe: the ids come
from the post-#3597 scoped aggregate. This closes the stricter-referenced
case, the one residual flagged in #3602.)

The label lookup now applies the REFERENCED object's own read scope, bound
to the request via the same getReadScope provider the aggregate path uses,
composed with `$and` (never key-merge) so the id predicate can't displace
it. Fail-closed: if that object's scope can't be resolved, the dimension's
labels are skipped (raw id renders) instead of fetched unscoped. No change
when no read-scope provider is configured.

`DimensionLabelDeps.fetchRecordLabels` gains an optional `scope` arg and
`resolveDimensionLabels` an optional `resolveScope` resolver — both
service-analytics-internal, no spec/contract change.

Tests: dimension-labels unit cases prove the referenced-object scope is
threaded and that resolution failure fails closed; a query-dataset
integration case proves AnalyticsService.queryDataset binds the referenced
object's scope (not the base object's) — reverting the wiring turns it red.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: os-zhuang

.changeset/analytics-label-read-scope.md

@@ -0,0 +1,25 @@
+---
+"@objectstack/service-analytics": patch
+---
+
+fix(analytics): scope the dimension-label lookup to the referenced object's RLS (#3602)
+
+When a dataset groups by a `lookup`/`master_detail` dimension, analytics resolves
+the grouped FK ids to the related record's display name via a per-record read
+(`group by id`) dressed as an aggregate. That read carried **no read scope**, so
+it revealed related-record display names whenever the referenced object's RLS is
+stricter than the base object whose rows carry the id — a user could see a name
+the referenced object's own RLS would hide. (Same-object and looser-referenced
+cases were already safe because the ids come from the post-#3597 scoped
+aggregate; this closes the stricter-referenced case.)
+
+The label lookup now applies the **referenced object's own** read scope — bound
+to the request via the same `getReadScope` provider the aggregate path uses,
+composed with `$and` (never key-merge) so it can't be displaced by the id
+predicate. Fail-closed: if that object's scope can't be resolved, the dimension's
+labels are skipped (the raw id renders) rather than fetched unscoped. No behaviour
+change when no read-scope provider is configured.
+
+Internal `DimensionLabelDeps.fetchRecordLabels` gains an optional `scope` argument
+and `resolveDimensionLabels` an optional `resolveScope` resolver; both are
+service-analytics-internal (no spec/contract change).

packages/services/service-analytics/src/__tests__/dimension-labels.test.ts

@@ -117,6 +117,71 @@ describe('resolveDimensionLabels', () => {
     expect(calls).toBe(1);
     expect(rows.map((r) => r.account)).toEqual(['Acme Corp', 'Acme Corp', 'Globex']);
   });
+
+  // ── #3602 — the label lookup must carry the REFERENCED object's read scope ──
+  describe('lookup label read scope (#3602)', () => {
+    it('passes the referenced object scope through to fetchRecordLabels', async () => {
+      let seenScope: unknown = 'UNSET';
+      let seenTarget: string | undefined;
+      const d = deps({
+        fetchRecordLabels: async (target, ids, scope) => {
+          seenTarget = target;
+          seenScope = scope;
+          return new Map<unknown, string>(ids.map((id) => [id, `name-${String(id)}`]));
+        },
+      });
+      const rows = [{ account: 'acc1', n: 1 }];
+      // resolveScope returns the referenced object's own RLS predicate.
+      await resolveDimensionLabels('task', [{ name: 'account', field: 'account' }], rows, d, (target) => {
+        expect(target).toBe('crm_account'); // the REFERENCED object, not the base
+        return { organization_id: 'org_A' };
+      });
+      expect(seenTarget).toBe('crm_account');
+      expect(seenScope).toEqual({ organization_id: 'org_A' });
+    });
+
+    it('fails CLOSED: when the scope cannot be resolved, the id is left raw (no unscoped fetch)', async () => {
+      let fetched = false;
+      const d = deps({
+        fetchRecordLabels: async (_t, ids) => {
+          fetched = true;
+          return new Map<unknown, string>(ids.map((id) => [id, 'LEAKED NAME']));
+        },
+      });
+      const rows = [{ account: 'acc1', n: 1 }];
+      await resolveDimensionLabels('task', [{ name: 'account', field: 'account' }], rows, d, () => {
+        throw new Error('security service unavailable');
+      });
+      // The label fetch must NOT have run, and the raw id must survive.
+      expect(fetched).toBe(false);
+      expect(rows).toEqual([{ account: 'acc1', n: 1 }]);
+    });
+
+    it('a select dimension is unaffected by scope resolution (no referenced object)', async () => {
+      let scopeCalls = 0;
+      const rows = [{ status: 'backlog', n: 1 }];
+      await resolveDimensionLabels('task', [{ name: 'status', field: 'status' }], rows, deps(), () => {
+        scopeCalls++;
+        return undefined;
+      });
+      expect(scopeCalls).toBe(0); // scope is only resolved for lookup/master_detail dims
+      expect(rows).toEqual([{ status: 'Backlog', n: 1 }]);
+    });
+
+    it('no resolver (no security configured) → unscoped fetch, unchanged behaviour', async () => {
+      let seenScope: unknown = 'UNSET';
+      const d = deps({
+        fetchRecordLabels: async (_t, ids, scope) => {
+          seenScope = scope;
+          return new Map<unknown, string>(ids.map((id) => [id, 'Acme Corp']));
+        },
+      });
+      const rows = [{ account: 'acc1', n: 1 }];
+      await resolveDimensionLabels('task', [{ name: 'account', field: 'account' }], rows, d /* no resolveScope */);
+      expect(seenScope).toBeUndefined();
+      expect(rows).toEqual([{ account: 'Acme Corp', n: 1 }]);
+    });
+  });
 });
 
 describe('formatDateBucket', () => {

packages/services/service-analytics/src/__tests__/query-dataset.test.ts

@@ -393,4 +393,52 @@ describe('AnalyticsService.queryDataset', () => {
     expect(result.totals[1].dimensions).toEqual([]);
     expect(result.drillRawTotals[1]).toEqual([{}]);
   });
+
+  // ── #3602 — the lookup label read is scoped to the REFERENCED object's RLS ──
+  it('threads the referenced object read scope (not the base object) into the label fetch', async () => {
+    const byAccount = DatasetSchema.parse({
+      name: 'sales_acct_scoped', label: 'Sales', object: 'opportunity', include: [],
+      dimensions: [{ name: 'account', field: 'account', type: 'lookup', label: 'Account' }],
+      measures: [{ name: 'revenue', aggregate: 'sum', field: 'amount' }],
+    });
+    const labelScopes: Array<{ target: string; scope: unknown }> = [];
+    const svc = new AnalyticsService({
+      queryCapabilities: () => ({ nativeSql: true, objectqlAggregate: false, inMemory: false }),
+      executeRawSql: async () => [{ account: 'acc1', revenue: 1000 }],
+      // Per-object scope: opportunity and crm_account get DIFFERENT predicates, so
+      // the assertion proves the label fetch used the referenced object's scope,
+      // not the base object's.
+      getReadScope: (object, ctx?: ExecutionContext) => {
+        if (!ctx?.tenantId) return undefined;
+        return object === 'crm_account'
+          ? { organization_id: ctx.tenantId, is_public: true }
+          : { organization_id: ctx.tenantId };
+      },
+      labelResolver: {
+        getObjectFields: (obj) => ({
+          opportunity: { account: { type: 'lookup', reference: 'crm_account' } },
+          crm_account: { name: { type: 'text' } },
+        } as Record<string, Record<string, { type?: string; reference?: string }>>)[obj],
+        fetchRecordLabels: async (target, ids, scope) => {
+          labelScopes.push({ target, scope });
+          const m = new Map<unknown, string>();
+          for (const id of ids) m.set(id, `name-${String(id)}`);
+          return m;
+        },
+      },
+    });
+
+    const result = await svc.queryDataset(
+      byAccount,
+      { dimensions: ['account'], measures: ['revenue'] },
+      { tenantId: 'org_A' } as ExecutionContext,
+    ) as any;
+
+    // The label fetch ran against the referenced object, carrying ITS scope.
+    expect(labelScopes).toEqual([
+      { target: 'crm_account', scope: { organization_id: 'org_A', is_public: true } },
+    ]);
+    // And the label actually resolved (end-to-end sanity).
+    expect(result.rows).toEqual([{ account: 'name-acc1', revenue: 1000 }]);
+  });
 });

packages/services/service-analytics/src/analytics-service.ts

@@ -604,14 +604,23 @@ export class AnalyticsService implements IAnalyticsService {
         .filter((d) => !!d.field)
         .map((d) => ({ name: d.name, field: d.field, type: d.type, dateGranularity: d.dateGranularity }));
       if (dims.length) {
+        // #3602 — bind the referenced object's read scope to THIS request so the
+        // label lookup (a per-record read of the related object) cannot surface a
+        // record the referenced object's RLS would hide. Same provider the
+        // aggregate path uses; `undefined` when no provider is configured, in
+        // which case labels fetch unscoped exactly as before.
+        const provider = this.readScopeProvider;
+        const resolveScope = provider
+          ? (targetObject: string) => provider(targetObject, context)
+          : undefined;
         try {
-          await resolveDimensionLabels(dataset.object, dims, result.rows, this.labelResolver);
+          await resolveDimensionLabels(dataset.object, dims, result.rows, this.labelResolver, resolveScope);
           // Totals rows (#1753) carry dimension values too (a row subtotal is
           // keyed by its row bucket) — resolve each grouping's own subset.
           for (const total of result.totals ?? []) {
             const subset = dims.filter((d) => total.dimensions.includes(d.name));
             if (subset.length) {
-              await resolveDimensionLabels(dataset.object, subset, total.rows, this.labelResolver);
+              await resolveDimensionLabels(dataset.object, subset, total.rows, this.labelResolver, resolveScope);
             }
           }
         } catch (e) {

packages/services/service-analytics/src/dimension-labels.ts

@@ -39,10 +39,34 @@ export interface DimensionLabelDeps {
    * Fetch a map of `id → display label` for the given ids of a target object.
    * The implementation chooses the target's display field. Returning an empty
    * map (e.g. no display field, no data access) leaves the ids unresolved.
+   *
+   * `scope` (ADR-0021 D-C, #3602) is the TARGET object's own read scope — the
+   * RLS/tenant `FilterCondition` the implementation must AND into the label
+   * lookup so this never reveals a related record the target object's RLS would
+   * hide. The label lookup is a per-record read (`group by id`) dressed as an
+   * aggregate; without the scope it leaks display names whenever the referenced
+   * object is more restricted than the base object whose rows carry the id.
+   * `undefined` means "no scope for this object" (global table / unrestricted
+   * caller) — the same contract as the read-scope provider.
    */
-  fetchRecordLabels(targetObject: string, ids: unknown[]): Promise<Map<unknown, string>>;
+  fetchRecordLabels(
+    targetObject: string,
+    ids: unknown[],
+    scope?: Record<string, unknown>,
+  ): Promise<Map<unknown, string>>;
 }
 
+/**
+ * Resolve the TARGET object's read scope for a label lookup (#3602). Returns the
+ * object's RLS/tenant `FilterCondition`, `null`/`undefined` when the object is
+ * unscoped, or a rejected promise when the scope cannot be resolved — in which
+ * case the resolver fails CLOSED (skips that dimension's labels) rather than
+ * fetching unscoped names.
+ */
+export type LabelScopeResolver = (
+  targetObject: string,
+) => Promise<Record<string, unknown> | null | undefined> | Record<string, unknown> | null | undefined;
+
 const LOOKUP_TYPES = new Set(['lookup', 'master_detail']);
 
 /** Date-dimension granularity (mirrors the dataset `dateGranularity` enum). */
@@ -100,12 +124,18 @@ export function formatDateBucket(value: unknown, granularity?: DateGranularity |
  *   (row key = `name`)
  * @param rows - result rows, mutated in place
  * @param deps - injected runtime capabilities
+ * @param resolveScope - (ADR-0021 D-C, #3602) resolves the referenced object's
+ *   own read scope for a lookup/master_detail dimension's label fetch. When it
+ *   throws, that dimension's labels are SKIPPED (fail-closed — the raw id renders
+ *   instead) rather than fetched unscoped. Omit when no read-scope provider is
+ *   configured (labels then fetch unscoped, as before — no security in play).
  */
 export async function resolveDimensionLabels(
   baseObject: string,
   dims: Array<{ name: string; field: string; type?: string; dateGranularity?: DateGranularity | string }>,
   rows: Record<string, unknown>[],
   deps: DimensionLabelDeps,
+  resolveScope?: LabelScopeResolver,
 ): Promise<void> {
   if (!rows.length || !dims.length) return;
   const fields = deps.getObjectFields(baseObject);
@@ -148,7 +178,20 @@ export async function resolveDimensionLabels(
         new Set(rows.map((r) => r[dim.name]).filter((v) => v != null)),
       );
       if (ids.length === 0) continue;
-      const labelById = await deps.fetchRecordLabels(meta.reference, ids);
+      // #3602 — the label lookup reads the REFERENCED object by id. Scope it to
+      // that object's own RLS so it never surfaces a related record the target's
+      // RLS would hide (leak fires when the referenced object is stricter than
+      // the base). Fail closed: if the scope can't be resolved, skip this
+      // dimension's labels (raw id renders) rather than fetch unscoped.
+      let scope: Record<string, unknown> | null | undefined;
+      if (resolveScope) {
+        try {
+          scope = await resolveScope(meta.reference);
+        } catch {
+          continue;
+        }
+      }
+      const labelById = await deps.fetchRecordLabels(meta.reference, ids, scope ?? undefined);
       if (!labelById || labelById.size === 0) continue;
       for (const row of rows) {
         const label = labelById.get(row[dim.name]);

packages/services/service-analytics/src/plugin.ts

@@ -353,17 +353,24 @@ export class AnalyticsServicePlugin implements Plugin {
     };
     const labelResolver: DimensionLabelDeps = {
       getObjectFields: (objectName) => dataEngine()?.getObject?.(objectName)?.fields,
-      fetchRecordLabels: async (targetObject, ids) => {
+      fetchRecordLabels: async (targetObject, ids, scope) => {
         const map = new Map<unknown, string>();
         const displayField = pickDisplayField(dataEngine()?.getObject?.(targetObject)?.fields);
         if (!displayField || !executeAggregate || ids.length === 0) return map;
+        // #3602 — AND the referenced object's own read scope into the id filter,
+        // with `$and` (never key-merge) so it cannot be displaced by the id
+        // predicate — the same composition the strategy uses for the aggregate.
+        // Without it this per-record read leaks display names the target's RLS
+        // would hide (fires when the referenced object is stricter than the base).
+        const idFilter: Record<string, unknown> = { id: { $in: ids } };
+        const filter = scope ? { $and: [idFilter, scope] } : idFilter;
         // Group by (id, displayField) — one row per record — reusing the aggregate
         // bridge rather than adding a record-fetch capability. A count keeps engines
         // that require ≥1 aggregation happy; the count itself is unused.
         const rows = await executeAggregate(targetObject, {
           groupBy: ['id', displayField],
           aggregations: [{ field: 'id', method: 'count', alias: '_c' }],
-          filter: { id: { $in: ids } },
+          filter,
         });
         for (const r of rows) {
           if (r.id != null && r[displayField] != null) map.set(r.id, String(r[displayField]));