@objectstack/plugin-sharing 4.0.1

package/src/sharing-service.test.ts

@@ -0,0 +1,355 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { SharingService } from './sharing-service.js';
+import { buildSharingMiddleware } from './sharing-plugin.js';
+
+// ─────────────────────────────────────────────────────────────────────
+// In-memory fake engine
+// ─────────────────────────────────────────────────────────────────────
+
+interface FakeRow {
+  [k: string]: any;
+}
+
+function makeFakeEngine(schemas: Record<string, any>) {
+  const tables: Record<string, FakeRow[]> = {};
+  const ensure = (name: string) => (tables[name] ??= []);
+
+  function matches(row: FakeRow, filter: any): boolean {
+    if (!filter || typeof filter !== 'object') return true;
+    if (filter.$or && Array.isArray(filter.$or)) {
+      return filter.$or.some((f: any) => matches(row, f));
+    }
+    if (filter.$and && Array.isArray(filter.$and)) {
+      return filter.$and.every((f: any) => matches(row, f));
+    }
+    for (const [k, v] of Object.entries(filter)) {
+      if (k === '$or' || k === '$and') continue;
+      const rv = row[k];
+      if (v != null && typeof v === 'object' && '$in' in (v as any)) {
+        if (!(v as any).$in.includes(rv)) return false;
+        continue;
+      }
+      if (rv !== v) return false;
+    }
+    return true;
+  }
+
+  return {
+    _tables: tables,
+    getSchema(name: string) { return schemas[name]; },
+    async find(object: string, options?: any) {
+      const table = ensure(object);
+      const filter = options?.filter ?? options?.where;
+      return table.filter(r => matches(r, filter)).slice(0, options?.limit ?? 1000);
+    },
+    async insert(object: string, data: any) {
+      const row = { ...data };
+      ensure(object).push(row);
+      return row;
+    },
+    async update(object: string, idOrData: any, dataOrOptions?: any) {
+      // Engine signature is overloaded — handle the (data, options)
+      // shape used by SharingService.grant() where id lives on data.
+      const data = typeof idOrData === 'object' ? idOrData : dataOrOptions;
+      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 id = options?.where?.id ?? options?.id;
+      const i = table.findIndex(r => r.id === id);
+      if (i >= 0) table.splice(i, 1);
+      return { id };
+    },
+  };
+}
+
+const ACCOUNT_SCHEMA = {
+  name: 'account',
+  sharingModel: 'private',
+  fields: { id: {}, name: {}, owner_id: {} },
+};
+
+const LEAD_SCHEMA = {
+  name: 'lead',
+  sharingModel: 'read',
+  fields: { id: {}, name: {}, owner_id: {} },
+};
+
+const PUBLIC_SCHEMA = {
+  name: 'task',
+  // no sharingModel — treated as public
+  fields: { id: {}, name: {}, owner_id: {} },
+};
+
+const ORPHAN_SCHEMA = {
+  name: 'note',
+  sharingModel: 'private',
+  // no owner_id — sharing skipped
+  fields: { id: {}, body: {} },
+};
+
+// ─────────────────────────────────────────────────────────────────────
+
+describe('SharingService.buildReadFilter', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: SharingService;
+  beforeEach(() => {
+    engine = makeFakeEngine({
+      account: ACCOUNT_SCHEMA,
+      lead: LEAD_SCHEMA,
+      task: PUBLIC_SCHEMA,
+      note: ORPHAN_SCHEMA,
+      sys_record_share: { name: 'sys_record_share' },
+    });
+    svc = new SharingService({ engine });
+  });
+
+  it('returns null for system context', async () => {
+    expect(await svc.buildReadFilter('account', { isSystem: true })).toBeNull();
+  });
+
+  it('returns null for objects in the bypass list', async () => {
+    expect(await svc.buildReadFilter('sys_user', { userId: 'u1' })).toBeNull();
+  });
+
+  it('returns null for public objects', async () => {
+    expect(await svc.buildReadFilter('task', { userId: 'u1' })).toBeNull();
+  });
+
+  it('returns null for read-only-sharing objects (writes are gated, reads are not)', async () => {
+    expect(await svc.buildReadFilter('lead', { userId: 'u1' })).toBeNull();
+  });
+
+  it('returns null for objects without owner_id even when private', async () => {
+    expect(await svc.buildReadFilter('note', { userId: 'u1' })).toBeNull();
+  });
+
+  it('returns deny-all for private object with no userId', async () => {
+    const f = await svc.buildReadFilter('account', {});
+    expect(f).toEqual({ id: '__deny_all__' });
+  });
+
+  it('returns owner-only filter when user has no explicit shares', async () => {
+    const f = await svc.buildReadFilter('account', { userId: 'alice' });
+    expect(f).toEqual({ owner_id: 'alice' });
+  });
+
+  it('returns owner OR shared-record filter when grants exist', async () => {
+    await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'alice' }, { userId: 'admin' });
+    await svc.grant({ object: 'account', recordId: 'a2', recipientId: 'alice', accessLevel: 'edit' }, { userId: 'admin' });
+    const f: any = await svc.buildReadFilter('account', { userId: 'alice' });
+    expect(f.$or).toBeDefined();
+    expect(f.$or[0]).toEqual({ owner_id: 'alice' });
+    expect(f.$or[1].id.$in.sort()).toEqual(['a1', 'a2']);
+  });
+});
+
+describe('SharingService.canEdit', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: SharingService;
+  beforeEach(() => {
+    engine = makeFakeEngine({
+      account: ACCOUNT_SCHEMA,
+      lead: LEAD_SCHEMA,
+      task: PUBLIC_SCHEMA,
+      sys_record_share: { name: 'sys_record_share' },
+    });
+    svc = new SharingService({ engine });
+    engine._tables.account = [
+      { id: 'a1', name: 'Acme', owner_id: 'alice' },
+      { id: 'a2', name: 'Beta', owner_id: 'bob' },
+    ];
+    engine._tables.lead = [
+      { id: 'l1', name: 'Lead1', owner_id: 'alice' },
+    ];
+  });
+
+  it('returns true for system context', async () => {
+    expect(await svc.canEdit('account', 'a1', { isSystem: true })).toBe(true);
+  });
+
+  it('returns true for public objects', async () => {
+    expect(await svc.canEdit('task', 'anything', { userId: 'bob' })).toBe(true);
+  });
+
+  it('returns true for record owner', async () => {
+    expect(await svc.canEdit('account', 'a1', { userId: 'alice' })).toBe(true);
+  });
+
+  it('returns false for non-owner without share', async () => {
+    expect(await svc.canEdit('account', 'a1', { userId: 'bob' })).toBe(false);
+  });
+
+  it('returns false for read-only share', async () => {
+    await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'bob', accessLevel: 'read' }, { userId: 'admin' });
+    expect(await svc.canEdit('account', 'a1', { userId: 'bob' })).toBe(false);
+  });
+
+  it('returns true for edit share', async () => {
+    await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'bob', accessLevel: 'edit' }, { userId: 'admin' });
+    expect(await svc.canEdit('account', 'a1', { userId: 'bob' })).toBe(true);
+  });
+
+  it('enforces canEdit for sharingModel=read', async () => {
+    expect(await svc.canEdit('lead', 'l1', { userId: 'alice' })).toBe(true);
+    expect(await svc.canEdit('lead', 'l1', { userId: 'bob' })).toBe(false);
+  });
+});
+
+describe('SharingService.grant / listShares / revoke', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: SharingService;
+  beforeEach(() => {
+    engine = makeFakeEngine({ account: ACCOUNT_SCHEMA, sys_record_share: {} });
+    svc = new SharingService({ engine });
+  });
+
+  it('creates a new grant on first call', async () => {
+    const r = await svc.grant(
+      { object: 'account', recordId: 'a1', recipientId: 'bob', accessLevel: 'edit' },
+      { userId: 'admin' },
+    );
+    expect(r.id).toMatch(/^shr_/);
+    expect(r.access_level).toBe('edit');
+    expect(r.granted_by).toBe('admin');
+    expect(engine._tables.sys_record_share.length).toBe(1);
+  });
+
+  it('upserts on second call with same (object, record, recipient)', async () => {
+    const a = await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'bob' }, { userId: 'admin' });
+    const b = await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'bob', accessLevel: 'full' }, { userId: 'admin' });
+    expect(engine._tables.sys_record_share.length).toBe(1);
+    expect(b.id).toBe(a.id);
+    expect(b.access_level).toBe('full');
+  });
+
+  it('listShares returns all grants on a record', async () => {
+    await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'bob' }, { userId: 'admin' });
+    await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'carol', accessLevel: 'edit' }, { userId: 'admin' });
+    const rows = await svc.listShares('account', 'a1', { userId: 'admin' });
+    expect(rows.length).toBe(2);
+  });
+
+  it('revoke removes the row', async () => {
+    const r = await svc.grant({ object: 'account', recordId: 'a1', recipientId: 'bob' }, { userId: 'admin' });
+    await svc.revoke(r.id, { userId: 'admin' });
+    expect(engine._tables.sys_record_share.length).toBe(0);
+  });
+
+  it('rejects grant input missing required fields', async () => {
+    await expect(svc.grant({} as any, {})).rejects.toThrow(/VALIDATION_FAILED/);
+    await expect(svc.grant({ object: 'account' } as any, {})).rejects.toThrow(/VALIDATION_FAILED/);
+    await expect(svc.grant({ object: 'account', recordId: 'a1' } as any, {})).rejects.toThrow(/VALIDATION_FAILED/);
+  });
+});
+
+describe('buildSharingMiddleware (engine integration)', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: SharingService;
+  beforeEach(() => {
+    engine = makeFakeEngine({
+      account: ACCOUNT_SCHEMA,
+      lead: LEAD_SCHEMA,
+      task: PUBLIC_SCHEMA,
+      sys_record_share: {},
+    });
+    svc = new SharingService({ engine });
+    engine._tables.account = [
+      { id: 'a1', name: 'Acme', owner_id: 'alice' },
+      { id: 'a2', name: 'Beta', owner_id: 'bob' },
+    ];
+  });
+
+  it('adds visibility filter on find', async () => {
+    const mw = buildSharingMiddleware(svc);
+    const ctx: any = {
+      object: 'account',
+      operation: 'find',
+      ast: {},
+      context: { userId: 'alice' },
+    };
+    await mw(ctx, async () => {});
+    expect(ctx.ast.where).toEqual({ owner_id: 'alice' });
+  });
+
+  it('skips read filter for system context', async () => {
+    const mw = buildSharingMiddleware(svc);
+    const ctx: any = {
+      object: 'account',
+      operation: 'find',
+      ast: {},
+      context: { isSystem: true },
+    };
+    await mw(ctx, async () => {});
+    expect(ctx.ast.where).toBeUndefined();
+  });
+
+  it('throws FORBIDDEN on update by non-owner', async () => {
+    const mw = buildSharingMiddleware(svc);
+    const ctx: any = {
+      object: 'account',
+      operation: 'update',
+      data: { id: 'a1', name: 'X' },
+      context: { userId: 'bob' },
+    };
+    await expect(mw(ctx, async () => {})).rejects.toMatchObject({ code: 'FORBIDDEN', status: 403 });
+  });
+
+  it('allows update by owner', async () => {
+    const mw = buildSharingMiddleware(svc);
+    const ctx: any = {
+      object: 'account',
+      operation: 'update',
+      data: { id: 'a1', name: 'X' },
+      context: { userId: 'alice' },
+    };
+    let nextCalled = false;
+    await mw(ctx, async () => { nextCalled = true; });
+    expect(nextCalled).toBe(true);
+  });
+
+  it('allows delete after explicit edit grant', async () => {
+    await svc.grant({ object: 'account', recordId: 'a2', recipientId: 'alice', accessLevel: 'edit' }, { userId: 'admin' });
+    const mw = buildSharingMiddleware(svc);
+    const ctx: any = {
+      object: 'account',
+      operation: 'delete',
+      options: { where: { id: 'a2' } },
+      context: { userId: 'alice' },
+    };
+    let nextCalled = false;
+    await mw(ctx, async () => { nextCalled = true; });
+    expect(nextCalled).toBe(true);
+  });
+
+  it('does not block insert', async () => {
+    const mw = buildSharingMiddleware(svc);
+    const ctx: any = {
+      object: 'account',
+      operation: 'insert',
+      data: { id: 'a3', owner_id: 'eve' },
+      context: { userId: 'eve' },
+    };
+    let nextCalled = false;
+    await mw(ctx, async () => { nextCalled = true; });
+    expect(nextCalled).toBe(true);
+  });
+
+  it('preserves caller-provided filter via $and', async () => {
+    const mw = buildSharingMiddleware(svc);
+    const ctx: any = {
+      object: 'account',
+      operation: 'find',
+      ast: { where: { name: 'Acme' } },
+      context: { userId: 'alice' },
+    };
+    await mw(ctx, async () => {});
+    expect(ctx.ast.where).toEqual({ $and: [{ name: 'Acme' }, { owner_id: 'alice' }] });
+  });
+});

package/src/sharing-service.ts

@@ -0,0 +1,283 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type {
+  ISharingService,
+  RecordShare,
+  GrantShareInput,
+  SharingExecutionContext,
+  ShareAccessLevel,
+} from '@objectstack/spec/contracts';
+
+/**
+ * Shape of the data engine the service actually needs. Kept narrow so
+ * unit tests can pass an in-memory fake without depending on the full
+ * ObjectQL engine class.
+ */
+export interface SharingEngine {
+  find(object: string, options?: any): Promise<any[]>;
+  findOne?(object: string, options?: any): Promise<any>;
+  insert(object: string, data: any, options?: any): Promise<any>;
+  update(object: string, idOrData: any, dataOrOptions?: any, options?: any): Promise<any>;
+  delete(object: string, options?: any): Promise<any>;
+  getSchema?(object: string): any | undefined;
+}
+
+/**
+ * Random share id. Keeps the plugin self-contained (no `crypto.randomUUID`
+ * dependency in environments that don't expose it on `globalThis`).
+ */
+function makeShareId(): string {
+  const g: any = globalThis as any;
+  if (g.crypto?.randomUUID) return `shr_${g.crypto.randomUUID()}`;
+  return `shr_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** System-elevated context for the plugin's own queries / mutations. */
+const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+
+/**
+ * Owner field convention. Hard-coded to `owner_id` for MVP — the
+ * sharing model in Salesforce / ServiceNow / Dynamics all assume a
+ * single owner field, and customising it is a follow-up. Objects
+ * without `owner_id` are treated as "unowned" and read filters are
+ * suppressed (they fall back to OWD-public behaviour).
+ */
+const OWNER_FIELD = 'owner_id';
+
+/**
+ * Effective sharing model. Anything other than `private` / `read` is
+ * treated as public — that includes objects that don't declare
+ * `sharingModel` at all, so existing CRM behaviour is preserved
+ * until an admin opts an object in.
+ */
+function effectiveSharingModel(schema: any): 'private' | 'read' | 'public' {
+  const m = schema?.sharingModel ?? schema?.security?.sharingModel;
+  if (m === 'private') return 'private';
+  if (m === 'read') return 'read';
+  return 'public';
+}
+
+function hasOwnerField(schema: any): boolean {
+  return Boolean(schema?.fields && OWNER_FIELD in schema.fields);
+}
+
+export interface SharingServiceOptions {
+  engine: SharingEngine;
+  /** Object names that bypass sharing — typically platform internals. */
+  bypassObjects?: string[];
+}
+
+/**
+ * Default `ISharingService` implementation.
+ *
+ * Stores every grant in `sys_record_share`. The plugin layer registers
+ * an engine middleware that calls `buildReadFilter` / `canEdit` so that
+ * neither this class nor its callers need to know about middleware
+ * plumbing.
+ */
+export class SharingService implements ISharingService {
+  private readonly engine: SharingEngine;
+  private readonly bypassObjects: Set<string>;
+
+  constructor(options: SharingServiceOptions) {
+    this.engine = options.engine;
+    this.bypassObjects = new Set([
+      'sys_record_share',
+      'sys_user',
+      'sys_organization',
+      'sys_member',
+      'sys_role',
+      'sys_permission_set',
+      'sys_user_permission_set',
+      'sys_role_permission_set',
+      ...(options.bypassObjects ?? []),
+    ]);
+  }
+
+  /**
+   * Build a `FilterCondition` restricting `find` to records the caller
+   * may see. Returns `null` when no filter should be applied.
+   */
+  async buildReadFilter(
+    object: string,
+    context: SharingExecutionContext,
+  ): Promise<unknown | null> {
+    if (this.shouldBypass(object, context)) return null;
+
+    const schema = this.engine.getSchema?.(object);
+    if (!schema) return null;
+    if (effectiveSharingModel(schema) !== 'private') return null;
+    if (!hasOwnerField(schema)) return null;
+    if (!context.userId) {
+      // Authenticated context with no user id is a degenerate case
+      // (e.g. anonymous API key). Restrict to nothing rather than
+      // accidentally leaking owner-only data.
+      return { id: '__deny_all__' };
+    }
+
+    const grants = await this.engine.find('sys_record_share', {
+      filter: {
+        object_name: object,
+        recipient_type: 'user',
+        recipient_id: context.userId,
+      },
+      fields: ['record_id', 'access_level'],
+      limit: 5000,
+      context: SYSTEM_CTX,
+    });
+
+    const grantedIds: string[] = Array.isArray(grants)
+      ? grants.map((g: any) => String(g.record_id)).filter(Boolean)
+      : [];
+
+    if (grantedIds.length === 0) {
+      return { [OWNER_FIELD]: context.userId };
+    }
+
+    return {
+      $or: [
+        { [OWNER_FIELD]: context.userId },
+        { id: { $in: grantedIds } },
+      ],
+    };
+  }
+
+  /**
+   * Return `true` if the caller may edit `(object, recordId)`. Always
+   * `true` for system context, public objects, and objects without an
+   * owner field.
+   */
+  async canEdit(
+    object: string,
+    recordId: string,
+    context: SharingExecutionContext,
+  ): Promise<boolean> {
+    if (this.shouldBypass(object, context)) return true;
+
+    const schema = this.engine.getSchema?.(object);
+    if (!schema) return true;
+    const model = effectiveSharingModel(schema);
+    if (model === 'public') return true;
+    if (!hasOwnerField(schema)) return true;
+    if (!context.userId) return false;
+
+    // 1) Ownership — fast path.
+    const own = await this.engine.find(object, {
+      filter: { id: recordId },
+      fields: ['id', OWNER_FIELD],
+      limit: 1,
+      context: SYSTEM_CTX,
+    });
+    const owner = Array.isArray(own) && own[0] ? (own[0] as any)[OWNER_FIELD] : undefined;
+    if (owner && String(owner) === String(context.userId)) return true;
+
+    // 2) Explicit edit / full share.
+    const editGrants = await this.engine.find('sys_record_share', {
+      filter: {
+        object_name: object,
+        record_id: recordId,
+        recipient_type: 'user',
+        recipient_id: context.userId,
+        access_level: { $in: ['edit', 'full'] },
+      },
+      fields: ['id'],
+      limit: 1,
+      context: SYSTEM_CTX,
+    });
+    return Array.isArray(editGrants) && editGrants.length > 0;
+  }
+
+  /**
+   * Upsert a share row. Returning the existing row when an identical
+   * grant already exists keeps the REST endpoint idempotent.
+   */
+  async grant(
+    input: GrantShareInput,
+    context: SharingExecutionContext,
+  ): Promise<RecordShare> {
+    if (!input.object) throw new Error('VALIDATION_FAILED: object is required');
+    if (!input.recordId) throw new Error('VALIDATION_FAILED: recordId is required');
+    if (!input.recipientId) throw new Error('VALIDATION_FAILED: recipientId is required');
+
+    const recipientType = input.recipientType ?? 'user';
+    const accessLevel: ShareAccessLevel = input.accessLevel ?? 'read';
+    const source = input.source ?? 'manual';
+
+    // Upsert: if a row with same (object, record, recipient) exists,
+    // update its access level / reason; otherwise insert a new one.
+    const existing = await this.engine.find('sys_record_share', {
+      filter: {
+        object_name: input.object,
+        record_id: input.recordId,
+        recipient_type: recipientType,
+        recipient_id: input.recipientId,
+      },
+      limit: 1,
+      context: SYSTEM_CTX,
+    });
+    const now = new Date().toISOString();
+    if (Array.isArray(existing) && existing[0]) {
+      const row: any = existing[0];
+      const patch: any = {
+        id: row.id,
+        access_level: accessLevel,
+        source,
+        source_id: input.sourceId ?? row.source_id ?? null,
+        reason: input.reason ?? row.reason ?? null,
+        updated_at: now,
+      };
+      await this.engine.update('sys_record_share', patch, { context: SYSTEM_CTX });
+      return { ...row, ...patch } as RecordShare;
+    }
+
+    const id = makeShareId();
+    const row: any = {
+      id,
+      object_name: input.object,
+      record_id: input.recordId,
+      recipient_type: recipientType,
+      recipient_id: input.recipientId,
+      access_level: accessLevel,
+      source,
+      source_id: input.sourceId ?? null,
+      granted_by: context.userId ?? null,
+      reason: input.reason ?? null,
+      created_at: now,
+      updated_at: now,
+    };
+    await this.engine.insert('sys_record_share', row, { context: SYSTEM_CTX });
+    return row as RecordShare;
+  }
+
+  /** Delete a share row by id. No-op when not found. */
+  async revoke(shareId: string, _context: SharingExecutionContext): Promise<void> {
+    if (!shareId) throw new Error('VALIDATION_FAILED: shareId is required');
+    await this.engine.delete('sys_record_share', {
+      where: { id: shareId },
+      context: SYSTEM_CTX,
+    });
+  }
+
+  /** List share rows for `(object, recordId)`. */
+  async listShares(
+    object: string,
+    recordId: string,
+    _context: SharingExecutionContext,
+  ): Promise<RecordShare[]> {
+    const rows = await this.engine.find('sys_record_share', {
+      filter: { object_name: object, record_id: recordId },
+      orderBy: [{ field: 'created_at', direction: 'desc' }],
+      limit: 500,
+      context: SYSTEM_CTX,
+    });
+    return Array.isArray(rows) ? (rows as RecordShare[]) : [];
+  }
+
+  // ── helpers ──────────────────────────────────────────────────────
+
+  private shouldBypass(object: string, context: SharingExecutionContext): boolean {
+    if (context?.isSystem) return true;
+    if (this.bypassObjects.has(object)) return true;
+    return false;
+  }
+}