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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-reports",
-  "version": "16.1.0",
+  "version": "17.0.0-rc.0",
   "license": "Apache-2.0",
   "description": "Saved reports + scheduled email digests for ObjectStack — sys_saved_report + sys_report_schedule + IReportService.",
   "main": "dist/index.js",
@@ -14,9 +14,9 @@
   },
   "dependencies": {
     "croner": "^10.0.1",
-    "@objectstack/core": "16.1.0",
-    "@objectstack/platform-objects": "16.1.0",
-    "@objectstack/spec": "16.1.0"
+    "@objectstack/core": "17.0.0-rc.0",
+    "@objectstack/platform-objects": "17.0.0-rc.0",
+    "@objectstack/spec": "17.0.0-rc.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.1",

package/src/report-export-axis.test.ts

@@ -0,0 +1,220 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #3710 — the reports side door around the user-level export axis (#3544).
+ *
+ * `GET /data/:object/export` answers 403 for a caller without the export grant.
+ * A report over the SAME object rendered as CSV is the same bulk copy of the
+ * same rows, so before this gate a refused caller could simply save a report,
+ * run it as CSV — or schedule one to their own inbox — and get the data anyway.
+ *
+ * The gate lives in `executeReport`, which every path funnels through (run,
+ * ad-hoc, and the scheduled dispatch), so these exercise all three rather than
+ * trusting one call site.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { ReportService, type ReportEmail } from './report-service.js';
+
+function makeFakeEngine() {
+  const tables: Record<string, any[]> = {};
+  const ensure = (n: string) => (tables[n] ??= []);
+  const matches = (row: any, filter: any): boolean => {
+    if (!filter || typeof filter !== 'object') return true;
+    for (const [k, v] of Object.entries(filter)) if (row[k] !== v) return false;
+    return true;
+  };
+  return {
+    _tables: tables,
+    async find(object: string, options?: any) {
+      return ensure(object)
+        .filter((r) => matches(r, options?.filter ?? options?.where))
+        .slice(0, options?.limit ?? 1000);
+    },
+    async insert(object: string, data: any) { ensure(object).push({ ...data }); return { ...data }; },
+    async update(object: string, idOrData: any, _opts?: any) {
+      const data = typeof idOrData === 'object' ? idOrData : _opts;
+      const id = typeof idOrData === 'object' ? idOrData.id : idOrData;
+      const table = ensure(object);
+      const i = table.findIndex((r) => r.id === id);
+      if (i >= 0) table[i] = { ...table[i], ...data };
+      return table[i];
+    },
+    async delete(object: string, options?: any) {
+      const table = ensure(object);
+      const i = table.findIndex((r) => r.id === (options?.where?.id ?? options?.id));
+      if (i >= 0) table.splice(i, 1);
+      return {};
+    },
+  };
+}
+
+function makeFakeEmail() {
+  const sent: any[] = [];
+  const email: ReportEmail & { _sent: any[] } = {
+    _sent: sent,
+    async send(input) { sent.push(input); return { status: 'sent' }; },
+  };
+  return email;
+}
+
+const CTX = { userId: 'u1', tenantId: 't1', positions: [], permissions: [] };
+const now = new Date('2026-01-15T10:00:00Z');
+
+describe('reports × the user-level export axis (#3710)', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let email: ReturnType<typeof makeFakeEmail>;
+  let canExport: ReturnType<typeof vi.fn>;
+
+  const build = (opts: { canExport?: any } = {}) =>
+    new ReportService({
+      engine: engine as any,
+      email,
+      clock: { now: () => now },
+      maxRows: 5000,
+      resolveOwnerContext: async (ownerId: string) =>
+        ownerId ? { userId: ownerId, tenantId: 't1', positions: [], permissions: [] } : null,
+      ...('canExport' in opts ? { canExport: opts.canExport } : { canExport }),
+    });
+
+  beforeEach(() => {
+    engine = makeFakeEngine();
+    email = makeFakeEmail();
+    canExport = vi.fn().mockResolvedValue(true);
+    engine._tables['lead'] = [
+      { id: 'l1', name: 'Acme', status: 'open' },
+      { id: 'l2', name: 'Globex', status: 'won' },
+    ];
+  });
+
+  const saveReport = async (svc: ReportService, format: 'csv' | 'json' | 'html_table') =>
+    svc.saveReport(
+      { name: 'leads', object: 'lead', query: { fields: ['id', 'name'] }, format },
+      CTX,
+    );
+
+  describe('interactive run', () => {
+    it('denies a CSV report run when the caller may not export the object', async () => {
+      const svc = build({ canExport: vi.fn().mockResolvedValue(false) });
+      const report = await saveReport(svc, 'csv');
+      await expect(svc.run(report.id, CTX)).rejects.toThrow(/EXPORT_NOT_PERMITTED/);
+    });
+
+    it('denies a JSON report run too — json is a bulk machine-readable copy', async () => {
+      const svc = build({ canExport: vi.fn().mockResolvedValue(false) });
+      const report = await saveReport(svc, 'json');
+      await expect(svc.run(report.id, CTX)).rejects.toThrow(/EXPORT_NOT_PERMITTED/);
+    });
+
+    it('ALLOWS html_table — a rendered view is reading, not exporting', async () => {
+      // The axis must not become a second read permission: a caller holding
+      // allowRead may already see these rows on screen.
+      const svc = build({ canExport: vi.fn().mockResolvedValue(false) });
+      const report = await saveReport(svc, 'html_table');
+      const result = await svc.run(report.id, CTX);
+      expect(result.rowCount).toBe(2);
+    });
+
+    it('allows CSV when the grant is held, and asks about the REPORT object', async () => {
+      const svc = build();
+      const report = await saveReport(svc, 'csv');
+      const result = await svc.run(report.id, CTX);
+      expect(result.rowCount).toBe(2);
+      expect(canExport).toHaveBeenCalledWith('lead', expect.objectContaining({ userId: 'u1' }));
+    });
+
+    it('refuses BEFORE reading any row', async () => {
+      const svc = build({ canExport: vi.fn().mockResolvedValue(false) });
+      const report = await saveReport(svc, 'csv');
+      const findSpy = vi.spyOn(engine, 'find');
+      await expect(svc.run(report.id, CTX)).rejects.toThrow(/EXPORT_NOT_PERMITTED/);
+      // `sys_saved_report` lookups are fine; the OBJECT must never be queried.
+      expect(findSpy.mock.calls.some(([obj]) => obj === 'lead')).toBe(false);
+    });
+
+    it('a throwing canExport denies (fail closed, ADR-0049)', async () => {
+      const svc = build({ canExport: vi.fn().mockRejectedValue(new Error('resolution failed')) });
+      const report = await saveReport(svc, 'csv');
+      await expect(svc.run(report.id, CTX)).rejects.toThrow(/EXPORT_NOT_PERMITTED/);
+    });
+
+    it('no canExport wired → axis does not apply (no plugin-security deployment)', async () => {
+      const svc = build({ canExport: undefined });
+      const report = await saveReport(svc, 'csv');
+      const result = await svc.run(report.id, CTX);
+      expect(result.rowCount).toBe(2);
+    });
+  });
+
+  describe('scheduling', () => {
+    it('refuses to CREATE a csv schedule the author could not run', async () => {
+      const svc = build({ canExport: vi.fn().mockResolvedValue(false) });
+      const report = await saveReport(svc, 'html_table');
+      await expect(
+        svc.scheduleReport({ reportId: report.id, recipients: ['a@b.c'], format: 'csv' }, CTX),
+      ).rejects.toThrow(/EXPORT_NOT_PERMITTED/);
+    });
+
+    it('allows an html_table schedule for the same caller', async () => {
+      const svc = build({ canExport: vi.fn().mockResolvedValue(false) });
+      const report = await saveReport(svc, 'html_table');
+      const sched = await svc.scheduleReport(
+        { reportId: report.id, recipients: ['a@b.c'], format: 'html_table' },
+        CTX,
+      );
+      expect(sched.id).toBeTruthy();
+    });
+  });
+
+  describe('scheduled dispatch — the original side door', () => {
+    it('a csv schedule created while granted STOPS delivering once the grant is revoked', async () => {
+      // The reason the dispatch re-checks instead of trusting the create-time
+      // check: permissions change after a schedule exists.
+      const gate = vi.fn().mockResolvedValue(true);
+      const svc = build({ canExport: gate });
+      const report = await saveReport(svc, 'html_table');
+      await svc.scheduleReport(
+        { reportId: report.id, recipients: ['a@b.c'], format: 'csv', intervalMinutes: 1 },
+        CTX,
+      );
+
+      gate.mockResolvedValue(false); // grant revoked
+      // Force the schedule due (mirrors the existing dispatch suite).
+      engine._tables['sys_report_schedule'][0].next_run_at = new Date(now.getTime() - 1000).toISOString();
+      const out = await svc.dispatchDue();
+
+      expect(out.failed).toBe(1);
+      expect(email._sent).toHaveLength(0);
+      const sched = engine._tables['sys_report_schedule'][0];
+      expect(String(sched.last_error)).toMatch(/EXPORT_NOT_PERMITTED/);
+    });
+
+    it('an html_table schedule still delivers for a caller without the grant', async () => {
+      const svc = build({ canExport: vi.fn().mockResolvedValue(false) });
+      const report = await saveReport(svc, 'html_table');
+      await svc.scheduleReport(
+        { reportId: report.id, recipients: ['a@b.c'], format: 'html_table', intervalMinutes: 1 },
+        CTX,
+      );
+      // Force the schedule due (mirrors the existing dispatch suite).
+      engine._tables['sys_report_schedule'][0].next_run_at = new Date(now.getTime() - 1000).toISOString();
+      const out = await svc.dispatchDue();
+      expect(out.fired).toBe(1);
+      expect(email._sent).toHaveLength(1);
+    });
+
+    it('a csv schedule delivers when the owner holds the grant', async () => {
+      const svc = build();
+      const report = await saveReport(svc, 'html_table');
+      await svc.scheduleReport(
+        { reportId: report.id, recipients: ['a@b.c'], format: 'csv', intervalMinutes: 1 },
+        CTX,
+      );
+      // Force the schedule due (mirrors the existing dispatch suite).
+      engine._tables['sys_report_schedule'][0].next_run_at = new Date(now.getTime() - 1000).toISOString();
+      const out = await svc.dispatchDue();
+      expect(out.fired).toBe(1);
+      expect(email._sent[0].attachments?.[0]?.contentType).toBe('text/csv');
+    });
+  });
+});

package/src/report-service.ts

@@ -197,8 +197,35 @@ export interface ReportServiceOptions {
    * closed instead of running with RLS bypassed (#2980).
    */
   resolveOwnerContext?: OwnerContextResolver;
+  /**
+   * [#3544 / #3710] The user-level export axis —
+   * `ISecurityService.canExport(object, context)`, wired by the reports plugin
+   * from `getService('security')`.
+   *
+   * A report rendered as `csv`/`json` IS a bulk machine-readable copy of the
+   * object, so it is the same privilege `GET /data/:object/export` gates.
+   * Without this the axis had a side door: a caller refused at that route could
+   * save a report on the same object, run it as CSV — or schedule one to their
+   * own inbox — and receive the identical rows.
+   *
+   * Omitted (no `plugin-security`, so no permission sets exist anywhere) → the
+   * axis does not apply, matching the REST export route's own fail-open.
+   */
+  canExport?: (object: string, context: unknown) => Promise<boolean>;
 }
 
+/**
+ * [#3544 / #3710] Report formats that constitute a BULK EXPORT rather than a
+ * rendering.
+ *
+ * `csv`/`json` are machine-readable copies — re-importable elsewhere, and
+ * exactly what `GET /data/:object/export` serves. `html_table` is a PRESENTED
+ * view: the report equivalent of reading rows on screen, which any caller
+ * holding `allowRead` may already do. Gating it would restrict reading rather
+ * than exporting and would take the axis past what it is for.
+ */
+const BULK_EXPORT_FORMATS: ReadonlySet<string> = new Set(['csv', 'json']);
+
 export class ReportService implements IReportService {
   private readonly engine: ReportEngine;
   private readonly email?: ReportEmail;
@@ -206,6 +233,7 @@ export class ReportService implements IReportService {
   private readonly logger: NonNullable<ReportServiceOptions['logger']>;
   private readonly maxRows: number;
   private readonly resolveOwnerContext?: OwnerContextResolver;
+  private readonly canExportFn?: (object: string, context: unknown) => Promise<boolean>;
 
   constructor(opts: ReportServiceOptions) {
     this.engine = opts.engine;
@@ -214,6 +242,48 @@ export class ReportService implements IReportService {
     this.logger = opts.logger ?? {};
     this.maxRows = Math.max(1, opts.maxRows ?? 5000);
     this.resolveOwnerContext = opts.resolveOwnerContext;
+    this.canExportFn = opts.canExport;
+  }
+
+  /**
+   * [#3544 / #3710] Gate a report rendering on the user-level export axis.
+   *
+   * Throws `EXPORT_NOT_PERMITTED` when the principal behind `context` may not
+   * take a bulk copy of `object`. A no-op for non-bulk formats (`html_table`),
+   * for a system context, and when no `canExport` is wired.
+   *
+   * Deliberately checked HERE — one place — rather than at each of the three
+   * callers (`runReport`, the ad-hoc run, and the scheduled dispatch): a gate
+   * per call site is how a fourth call site later ships ungated. `dispatchDue`
+   * routes through `executeReport` too, so the scheduled CSV is covered by the
+   * same line. (`scheduleReport` additionally pre-checks, so an author is
+   * refused when they create the schedule rather than silently at 3am — but
+   * that is UX, and THIS is the enforcement: a grant revoked after the schedule
+   * was created must still stop the delivery.)
+   *
+   * Fails CLOSED on a throw — it resolves permission sets to decide, and a
+   * resolution failure must never read as a grant (ADR-0049).
+   */
+  private async assertExportAllowed(
+    object: string,
+    format: string,
+    context: SharingExecutionContext | undefined,
+  ): Promise<void> {
+    if (!BULK_EXPORT_FORMATS.has(format)) return;
+    if (context?.isSystem) return;
+    if (!this.canExportFn) return;
+    let allowed: boolean;
+    try {
+      allowed = await this.canExportFn(object, context);
+    } catch (err) {
+      this.logger.warn?.('ReportService: canExport check failed — denying export', err);
+      allowed = false;
+    }
+    if (!allowed) {
+      throw new Error(
+        `EXPORT_NOT_PERMITTED: exporting '${object}' as ${format} is not permitted for this user`,
+      );
+    }
   }
 
   // ── Access control ─────────────────────────────────────────────
@@ -361,6 +431,9 @@ export class ReportService implements IReportService {
     context: SharingExecutionContext,
     stamp = true,
   ): Promise<ReportRunResult> {
+    // [#3544 / #3710] The export axis, BEFORE any row is read — a refusal must
+    // not be reachable after the data has already been pulled.
+    await this.assertExportAllowed(report.object_name, report.format, context);
     const q = report.query ?? {};
     const limit = Math.min(q.limit ?? DEFAULT_LIMIT, this.maxRows);
     const rows = await this.engine.find(report.object_name, {
@@ -416,6 +489,12 @@ export class ReportService implements IReportService {
     const report = await this.getReport(input.reportId, context);
     if (!report) throw new Error(`REPORT_NOT_FOUND: ${input.reportId}`);
 
+    // [#3544 / #3710] Refuse a bulk-format schedule the author could not run
+    // themselves, at CREATE time — otherwise the refusal only surfaces on the
+    // first silent 3am sweep. Advisory only: `executeReport` re-checks on every
+    // dispatch, which is what catches a grant revoked after this point.
+    await this.assertExportAllowed(report.object_name, input.format ?? 'html_table', context);
+
     const now = this.clock.now();
     const interval = input.intervalMinutes ?? DEFAULT_INTERVAL_MIN;
     const cron = input.cronExpression?.trim() || null;

package/src/reports-plugin.ts

@@ -82,11 +82,28 @@ export class ReportsServicePlugin implements Plugin {
         ctx.logger.warn('ReportsServicePlugin: no email service — schedules will fire without delivery');
       }
 
+      // [#3544 / #3710] The user-level export axis. A `csv`/`json` report is a
+      // bulk machine-readable copy of its object — the same privilege
+      // `GET /data/:object/export` gates — so the reports surface must ask the
+      // SAME question of the SAME authority, or it is a side door around the
+      // axis. Resolved lazily per call rather than captured here: `security` is
+      // registered by plugin-security's own `kernel:ready` hook and may not
+      // exist yet at construction time. Absent service (no plugin-security ⇒ no
+      // permission sets anywhere) → the axis does not apply, matching the REST
+      // export route's fail-open.
+      const canExport = async (object: string, context: unknown): Promise<boolean> => {
+        let security: any;
+        try { security = ctx.getService<any>('security'); } catch { return true; }
+        if (!security || typeof security.canExport !== 'function') return true;
+        return await security.canExport(object, context);
+      };
+
       this.service = new ReportService({
         engine: engine as ReportEngine,
         email,
         logger: ctx.logger,
         maxRows: this.options.maxRows,
+        canExport,
         // Scheduled reports run under the owner's resolved RLS context, not a
         // system bypass (#2980). No owner-context resolver is wired yet — that
         // is the reports-surface consumer of ADR-0073's user-less identity