@objectstack/plugin-sharing 9.9.1 → 9.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/plugin-sharing",
-  "version": "9.9.1",
+  "version": "9.11.0",
   "license": "Apache-2.0",
   "description": "Record-level sharing for ObjectStack — sys_record_share + middleware that enforces sharingModel + ISharingService.",
   "main": "dist/index.js",
@@ -13,10 +13,10 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "9.9.1",
-    "@objectstack/objectql": "9.9.1",
-    "@objectstack/platform-objects": "9.9.1",
-    "@objectstack/spec": "9.9.1"
+    "@objectstack/core": "9.11.0",
+    "@objectstack/objectql": "9.11.0",
+    "@objectstack/platform-objects": "9.11.0",
+    "@objectstack/spec": "9.11.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.3",

package/src/objects/sys-sharing-rule.object.ts

@@ -131,12 +131,12 @@ export const SysSharingRule = ObjectSchema.create({
     }),
 
     recipient_type: Field.select(
-      ['user', 'team', 'department', 'role', 'queue'],
+      ['user', 'team', 'department', 'role', 'role_and_subordinates', 'queue'],
       {
         label: 'Recipient Type',
         required: true,
         defaultValue: 'department',
-        description: 'Kind of principal that receives access — expanded to user grants at evaluation time. `department` walks the parent_department_id tree; `team` is flat (better-auth).',
+        description: 'Kind of principal that receives access — expanded to user grants at evaluation time. `department` walks the parent_department_id tree; `team` is flat (better-auth); `role` is the role\'s direct members; `role_and_subordinates` walks the sys_role.parent hierarchy to also include every subordinate role (ADR-0056 D6).',
         group: 'Recipient',
       },
     ),

package/src/role-graph.test.ts

@@ -0,0 +1,60 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+// ADR-0056 D6 — role-hierarchy graph powering the `role_and_subordinates` recipient.
+
+import { describe, it, expect } from 'vitest';
+import { RoleGraphService } from './role-graph.js';
+
+// Minimal engine: resolves find('sys_role', {parent}) and find('sys_member', {role}).
+function makeEngine(roles: Array<{ name: string; parent?: string | null }>, members: Array<{ role: string; user_id: string }>) {
+  return {
+    async find(object: string, options: any) {
+      const f = options?.filter ?? options?.where ?? {};
+      if (object === 'sys_role') return roles.filter(r => (f.parent === undefined || r.parent === f.parent));
+      if (object === 'sys_member') return members.filter(m => (f.role === undefined || m.role === f.role));
+      return [];
+    },
+  } as any;
+}
+
+const ROLES = [
+  { name: 'ceo', parent: null },
+  { name: 'vp', parent: 'ceo' },
+  { name: 'rep', parent: 'vp' },
+  { name: 'rep2', parent: 'vp' },
+];
+const MEMBERS = [
+  { role: 'ceo', user_id: 'u_ceo' },
+  { role: 'vp', user_id: 'u_vp' },
+  { role: 'rep', user_id: 'u_rep' },
+  { role: 'rep2', user_id: 'u_rep2' },
+];
+
+describe('RoleGraphService (ADR-0056 D6)', () => {
+  it('descendantRoles walks the hierarchy downward (incl. self)', async () => {
+    const g = new RoleGraphService({ engine: makeEngine(ROLES, MEMBERS) });
+    expect((await g.descendantRoles('ceo')).sort()).toEqual(['ceo', 'rep', 'rep2', 'vp']);
+    expect((await g.descendantRoles('vp')).sort()).toEqual(['rep', 'rep2', 'vp']);
+    expect(await g.descendantRoles('rep')).toEqual(['rep']);
+  });
+
+  it('expandRoleAndSubordinates returns the role + all subordinate users', async () => {
+    const g = new RoleGraphService({ engine: makeEngine(ROLES, MEMBERS) });
+    expect((await g.expandRoleAndSubordinates('ceo')).sort()).toEqual(['u_ceo', 'u_rep', 'u_rep2', 'u_vp']);
+    expect((await g.expandRoleAndSubordinates('vp')).sort()).toEqual(['u_rep', 'u_rep2', 'u_vp']);
+    expect(await g.expandRoleAndSubordinates('rep')).toEqual(['u_rep']);
+  });
+
+  it('is cycle-safe (A↔B parent loop terminates)', async () => {
+    const cyclic = [{ name: 'a', parent: 'b' }, { name: 'b', parent: 'a' }];
+    const g = new RoleGraphService({ engine: makeEngine(cyclic, [{ role: 'a', user_id: 'ua' }, { role: 'b', user_id: 'ub' }]) });
+    const d = (await g.descendantRoles('a')).sort();
+    expect(d).toEqual(['a', 'b']);
+    expect((await g.expandRoleAndSubordinates('a')).sort()).toEqual(['ua', 'ub']);
+  });
+
+  it('unknown role → empty', async () => {
+    const g = new RoleGraphService({ engine: makeEngine(ROLES, MEMBERS) });
+    expect(await g.expandRoleAndSubordinates('nope')).toEqual([]);
+    expect(await g.expandRoleAndSubordinates('')).toEqual([]);
+  });
+});

package/src/role-graph.ts

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import type { SharingEngine } from './sharing-service.js';
+import { TeamGraphService } from './team-graph.js';
+
+const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
+
+type RoleCache = {
+  descendants?: Map<string, string[]>;
+  expand?: Map<string, string[]>;
+};
+
+export interface RoleGraphOptions {
+  engine: SharingEngine;
+  /** Optional tenant scope; null means cross-tenant lookups. */
+  organizationId?: string | null;
+  /** Optional shared cache across one evaluator pass. */
+  cache?: RoleCache;
+  /** Reused for role → direct-member-user expansion (sys_member.role). */
+  teamGraph?: TeamGraphService;
+}
+
+/**
+ * Role hierarchy graph (ADR-0056 D6).
+ *
+ * Walks `sys_role.parent` to resolve a role's SUBORDINATE roles, powering the
+ * declarative `role_and_subordinates` sharing-rule recipient — Salesforce-style
+ * "grant access using the role hierarchy", expressed per sharing rule rather
+ * than hardcoded. A role's `parent` is its manager role, so the subordinates of
+ * `R` are every role whose ancestor chain passes through `R`.
+ *
+ * All lookups elevate to a system context (the hierarchy is platform metadata);
+ * callers own their own authorization. Cycles are guarded by a visited set.
+ */
+export class RoleGraphService {
+  private readonly engine: SharingEngine;
+  private readonly organizationId: string | null;
+  private readonly cache: RoleCache;
+  private readonly teamGraph: TeamGraphService;
+
+  constructor(opts: RoleGraphOptions) {
+    this.engine = opts.engine;
+    this.organizationId = opts.organizationId ?? null;
+    this.cache = opts.cache ?? {};
+    this.cache.descendants ??= new Map();
+    this.cache.expand ??= new Map();
+    this.teamGraph =
+      opts.teamGraph ?? new TeamGraphService({ engine: this.engine, organizationId: this.organizationId });
+  }
+
+  /** Direct child roles of `roleName` (`sys_role.parent === roleName`). */
+  private async childRoles(roleName: string): Promise<string[]> {
+    const filter: Record<string, unknown> = { parent: roleName };
+    if (this.organizationId) filter.organization_id = this.organizationId;
+    let rows: any[] = [];
+    try {
+      rows = await this.engine.find('sys_role', {
+        filter,
+        fields: ['name'],
+        limit: 5000,
+        context: SYSTEM_CTX,
+      });
+    } catch {
+      rows = [];
+    }
+    return Array.from(new Set((rows ?? []).map((r: any) => String(r.name ?? '')).filter(Boolean)));
+  }
+
+  /** `roleName` plus every role beneath it in the hierarchy (BFS, cycle-safe). */
+  async descendantRoles(roleName: string): Promise<string[]> {
+    if (!roleName) return [];
+    const cached = this.cache.descendants!.get(roleName);
+    if (cached) return cached;
+    const out: string[] = [];
+    const seen = new Set<string>();
+    const queue: string[] = [roleName];
+    while (queue.length) {
+      const r = queue.shift()!;
+      if (seen.has(r)) continue;
+      seen.add(r);
+      out.push(r);
+      for (const child of await this.childRoles(r)) {
+        if (!seen.has(child)) queue.push(child);
+      }
+    }
+    this.cache.descendants!.set(roleName, out);
+    return out;
+  }
+
+  /** Users holding `roleName` OR any subordinate role (the `role_and_subordinates` set). */
+  async expandRoleAndSubordinates(roleName: string, organizationId?: string): Promise<string[]> {
+    if (!roleName) return [];
+    const org = organizationId ?? this.organizationId ?? '*';
+    const key = `${org}::${roleName}`;
+    const cached = this.cache.expand!.get(key);
+    if (cached) return cached;
+    const roles = await this.descendantRoles(roleName);
+    const users = new Set<string>();
+    for (const role of roles) {
+      for (const uid of await this.teamGraph.expandRoleUsers(role, organizationId ?? this.organizationId ?? undefined)) {
+        users.add(uid);
+      }
+    }
+    const result = Array.from(users);
+    this.cache.expand!.set(key, result);
+    return result;
+  }
+}

package/src/sharing-rule-service.ts

@@ -12,6 +12,7 @@ import type {
 import type { SharingEngine } from './sharing-service.js';
 import type { SharingService } from './sharing-service.js';
 import { TeamGraphService } from './team-graph.js';
+import { RoleGraphService } from './role-graph.js';
 import { DepartmentGraphService } from './department-graph.js';
 
 const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
@@ -266,6 +267,16 @@ export class SharingRuleService implements ISharingRuleService {
       return dept.expandUsers(rule.recipient_id);
     }
     if (rule.recipient_type === 'role') return team.expandRoleUsers(rule.recipient_id, rule.organization_id ?? undefined);
+    if (rule.recipient_type === 'role_and_subordinates') {
+      // ADR-0056 D6 — declarative role-hierarchy widening: this role + every
+      // subordinate role's users (configured per sharing rule, not hardcoded).
+      const roleGraph = new RoleGraphService({
+        engine: this.engine,
+        organizationId: rule.organization_id ?? null,
+        teamGraph: team,
+      });
+      return roleGraph.expandRoleAndSubordinates(rule.recipient_id, rule.organization_id ?? undefined);
+    }
     // queue — v1 stores literal; treat as no-op until queue impl lands.
     return [];
   }

package/src/sharing-service.test.ts

@@ -100,6 +100,18 @@ const PUBLIC_SCHEMA = {
   fields: { id: {}, name: {}, owner_id: {} },
 };
 
+// ADR-0056 D1 — canonical OWD vocabulary maps onto the same enforced behaviours.
+const CANON_PUBLIC_READ_SCHEMA = {
+  name: 'kbarticle',
+  sharingModel: 'public_read', // canonical alias of legacy `read`
+  fields: { id: {}, name: {}, owner_id: {} },
+};
+const CANON_PUBLIC_RW_SCHEMA = {
+  name: 'whiteboard',
+  sharingModel: 'public_read_write', // canonical alias of "public" (no record filter)
+  fields: { id: {}, name: {}, owner_id: {} },
+};
+
 const ORPHAN_SCHEMA = {
   name: 'note',
   sharingModel: 'private',
@@ -118,6 +130,8 @@ describe('SharingService.buildReadFilter', () => {
       lead: LEAD_SCHEMA,
       task: PUBLIC_SCHEMA,
       note: ORPHAN_SCHEMA,
+      kbarticle: CANON_PUBLIC_READ_SCHEMA,
+      whiteboard: CANON_PUBLIC_RW_SCHEMA,
       sys_record_share: { name: 'sys_record_share' },
     });
     svc = new SharingService({ engine });
@@ -139,6 +153,14 @@ describe('SharingService.buildReadFilter', () => {
     expect(await svc.buildReadFilter('lead', { userId: 'u1' })).toBeNull();
   });
 
+  it('canonical public_read reads like `read` (everyone reads → no filter) [ADR-0056 D1]', async () => {
+    expect(await svc.buildReadFilter('kbarticle', { userId: 'u1' })).toBeNull();
+  });
+
+  it('canonical public_read_write is unscoped on read [ADR-0056 D1]', async () => {
+    expect(await svc.buildReadFilter('whiteboard', { userId: 'u1' })).toBeNull();
+  });
+
   it('returns null for objects without owner_id even when private', async () => {
     expect(await svc.buildReadFilter('note', { userId: 'u1' })).toBeNull();
   });
@@ -171,6 +193,8 @@ describe('SharingService.canEdit', () => {
       account: ACCOUNT_SCHEMA,
       lead: LEAD_SCHEMA,
       task: PUBLIC_SCHEMA,
+      kbarticle: CANON_PUBLIC_READ_SCHEMA,
+      whiteboard: CANON_PUBLIC_RW_SCHEMA,
       sys_record_share: { name: 'sys_record_share' },
     });
     svc = new SharingService({ engine });
@@ -181,6 +205,9 @@ describe('SharingService.canEdit', () => {
     engine._tables.lead = [
       { id: 'l1', name: 'Lead1', owner_id: 'alice' },
     ];
+    engine._tables.kbarticle = [
+      { id: 'k1', name: 'KB1', owner_id: 'alice' },
+    ];
   });
 
   it('returns true for system context', async () => {
@@ -213,6 +240,15 @@ describe('SharingService.canEdit', () => {
     expect(await svc.canEdit('lead', 'l1', { userId: 'alice' })).toBe(true);
     expect(await svc.canEdit('lead', 'l1', { userId: 'bob' })).toBe(false);
   });
+
+  it('canonical public_read gates writes to the owner [ADR-0056 D1]', async () => {
+    expect(await svc.canEdit('kbarticle', 'k1', { userId: 'alice' })).toBe(true);
+    expect(await svc.canEdit('kbarticle', 'k1', { userId: 'bob' })).toBe(false);
+  });
+
+  it('canonical public_read_write lets anyone write [ADR-0056 D1]', async () => {
+    expect(await svc.canEdit('whiteboard', 'anything', { userId: 'bob' })).toBe(true);
+  });
 });
 
 describe('SharingService.grant / listShares / revoke', () => {

package/src/sharing-service.ts

@@ -45,15 +45,21 @@ const SYSTEM_CTX = { isSystem: true, roles: [], permissions: [] } as const;
 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.
+ * Effective sharing model — collapses the authorable OWD vocabulary onto the
+ * three behaviours this service enforces (ADR-0056 D1):
+ *   - `private`                         → owner-only read + write
+ *   - `public_read` / legacy `read`     → everyone reads, owner writes
+ *   - everything else                   → public (no record-level filter)
+ *
+ * "Everything else" covers the canonical `public_read_write`, the legacy
+ * `read_write` / `full` aliases, `controlled_by_parent` (scoped separately by
+ * the security plugin), and objects that declare no `sharingModel` at all — so
+ * existing 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';
+  if (m === 'read' || m === 'public_read') return 'read';
   return 'public';
 }