fix(plugin-sharing): a missing required capability is a hard stop the owner and Modify-All mint alternatives do not pass

canMintWithoutVisibility answers false when the ADR-0066 D3 capability
AND-gate refuses the caller a read, read from the declared
required_permissions layer of ISecurityService.explain; createLink then
re-throws the capability refusal as it came. Positive evidence is needed to
admit; a probe without explain, a throw or a report without the layer stop.

Claude-Session: https://claude.ai/code/session_01DiCSbmJrkzNhuEAier4VoJ
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

packages/plugins/plugin-sharing/src/share-link-service.test.ts

@@ -1193,6 +1193,8 @@ describe('[ADR-0111 D8 rule 1 / ruling A′] mint authority: visibility, or the
   const ADMIN = 'u_admin';
   const MANAGER = 'u_manager';
   const READER = 'u_reader';
+  /** Owns a record on the capability-gated object AND holds the capability. */
+  const CAPABLE_OWNER = 'u_capable_owner';
 
   const SCHEMAS = {
     sys_share_link: { name: 'sys_share_link', fields: {} },
@@ -1211,18 +1213,52 @@ describe('[ADR-0111 D8 rule 1 / ruling A′] mint authority: visibility, or the
     },
     // Never opted in.
     notes: { name: 'notes', access: { default: 'private' }, fields: { id: {}, owner_id: {} } },
+    // Owner-private AND capability-gated (ADR-0066 D3): a read needs `view_vault`.
+    vault: {
+      name: 'vault',
+      access: { default: 'private' },
+      requiredPermissions: ['view_vault'],
+      publicSharing: { enabled: true, allowedAudiences: ['link_only'], allowedPermissions: ['view'] },
+      fields: { id: {}, owner_id: {} },
+    },
   };
-  const PRIVATE_OBJECTS = new Set(['conversations', 'briefs', 'notes']);
+  const PRIVATE_OBJECTS = new Set(['conversations', 'briefs', 'notes', 'vault']);
+  /** The capabilities each principal holds; the doubles below read only this. */
+  const HELD_CAPABILITIES: Record<string, string[]> = { [CAPABLE_OWNER]: ['view_vault'] };
+  const requiredOf = (object: string): string[] =>
+    ((SCHEMAS as Record<string, any>)[object]?.requiredPermissions as string[] | undefined) ?? [];
+  const lacksCapability = (object: string, userId: unknown): boolean =>
+    requiredOf(object).some((c) => !(HELD_CAPABILITIES[String(userId)] ?? []).includes(c));
 
   const denial = () =>
     Object.assign(new Error('You do not have permission to perform this action.'), {
       code: 'PERMISSION_DENIED',
       statusCode: 403,
     });
+  /** The capability AND-gate's refusal: the same class, carrying what was missing. */
+  const capabilityDenial = (object: string) =>
+    Object.assign(new Error('You do not have permission to perform this action.'), {
+      code: 'PERMISSION_DENIED',
+      statusCode: 403,
+      details: { object, requiredPermissions: requiredOf(object), missingPermissions: requiredOf(object) },
+    });
+  /**
+   * The explain report's `required_permissions` layer, computed from the same
+   * `HELD_CAPABILITIES` the read double refuses with — so the two agree by
+   * construction, as the real engine and middleware do.
+   */
+  const explainDouble = async (request: { object: string }, ctx: any) => {
+    explainCalls += 1;
+    const verdict = requiredOf(request.object).length === 0
+      ? 'not_applicable'
+      : lacksCapability(request.object, ctx?.userId) ? 'denies' : 'neutral';
+    return { layers: [{ layer: 'required_permissions', verdict, detail: 'double' }] } as any;
+  };
 
   let engine: ReturnType<typeof makeFakeEngine>;
   let posture: string | undefined;
   let writeScopeCalls: number;
+  let explainCalls: number;
   let sharing: SharingService;
   let service: ShareLinkService;
   let mintProbeCalls: Array<[string, string, string | undefined]>;
@@ -1241,15 +1277,24 @@ describe('[ADR-0111 D8 rule 1 / ruling A′] mint authority: visibility, or the
       { id: 'b_pub', title: 'Published', status: 'published', owner_id: OWNER },
     ];
     engine._tables.notes = [{ id: 'n1', owner_id: OWNER }];
+    engine._tables.vault = [
+      { id: 'v_owner', owner_id: OWNER },
+      { id: 'v_capable', owner_id: CAPABLE_OWNER },
+    ];
     const plainFind = engine.find.bind(engine);
     engine.find = async (object: string, options?: any) => {
       const ctx = options?.context ?? {};
-      if (PRIVATE_OBJECTS.has(object) && ctx.isSystem !== true && ctx.userId !== READER) throw denial();
+      if (PRIVATE_OBJECTS.has(object) && ctx.isSystem !== true) {
+        // The capability AND-gate runs BEFORE the CRUD grant (ADR-0066 D3).
+        if (lacksCapability(object, ctx.userId)) throw capabilityDenial(object);
+        if (ctx.userId !== READER) throw denial();
+      }
       return plainFind(object, options);
     };
 
     posture = 'single';
     writeScopeCalls = 0;
+    explainCalls = 0;
     mintProbeCalls = [];
     sharing = new SharingService({
       engine: engine as any,
@@ -1259,6 +1304,7 @@ describe('[ADR-0111 D8 rule 1 / ruling A′] mint authority: visibility, or the
           writeScopeCalls += 1;
           return ctx?.userId === MANAGER ? 'unit' : 'own';
         },
+        explain: explainDouble,
       }),
       // The enterprise seam: the manager's `unit` covers the owner.
       hierarchyResolver: () =>
@@ -1340,6 +1386,65 @@ describe('[ADR-0111 D8 rule 1 / ruling A′] mint authority: visibility, or the
     await expect(service.createLink(conversation(), as(OWNER))).resolves.toMatchObject({ created_by: OWNER });
   });
 
+  describe('the capability hard stop (ADR-0066 D3): no alternative applies past a missing required capability', () => {
+    it('an owner lacking the capability is refused with the capability refusal itself, and nothing lands', async () => {
+      const refusal = await service.createLink(mintIn('vault', 'v_owner'), as(OWNER)).then(
+        () => { throw new Error('the owner minted past the capability gate'); },
+        (err) => err,
+      );
+      expect(refusal).toMatchObject({
+        code: 'PERMISSION_DENIED',
+        statusCode: 403,
+        details: { missingPermissions: ['view_vault'] },
+      });
+      expect(minted()).toEqual([]);
+      // The owner alternative itself was admitted; the stop is what refused.
+      expect(await sharing.canManageShares('vault', 'v_owner', as(OWNER))).toBe(true);
+    });
+
+    it('a Modify-All holder lacking the capability is refused the same way', async () => {
+      await expect(service.createLink(mintIn('vault', 'v_owner'), as(ADMIN)))
+        .rejects.toMatchObject({ code: 'PERMISSION_DENIED', details: { missingPermissions: ['view_vault'] } });
+      expect(minted()).toEqual([]);
+    });
+
+    it('control: an owner who HOLDS the capability mints on the same object (refused only by the CRUD grant)', async () => {
+      await expect(engine.find('vault', { where: { id: 'v_capable' }, context: as(CAPABLE_OWNER) }))
+        .rejects.toMatchObject({ code: 'PERMISSION_DENIED' });
+      await expect(service.createLink(mintIn('vault', 'v_capable'), as(CAPABLE_OWNER)))
+        .resolves.toMatchObject({ record_id: 'v_capable', created_by: CAPABLE_OWNER });
+    });
+
+    it('control: the owner of an object that requires no capability still mints', async () => {
+      await expect(service.createLink(conversation(), as(OWNER))).resolves.toMatchObject({ created_by: OWNER });
+    });
+
+    it('a refused stranger never pays for the explain walk', async () => {
+      await expect(service.createLink(mintIn('vault', 'v_owner'), as(STRANGER))).rejects.toMatchObject({ code: 'PERMISSION_DENIED' });
+      await expect(service.createLink(conversation(), as(STRANGER))).rejects.toMatchObject({ code: 'PERMISSION_DENIED' });
+      expect(explainCalls).toBe(0);
+    });
+
+    it.each([
+      ['a security service without explain', { hasWriteBypass: async () => false }],
+      ['an explain that throws', { explain: async () => { throw new Error('explain down'); } }],
+      ['a report without the layer', { explain: async () => ({ layers: [] }) }],
+      ['a verdict outside admits', { explain: async () => ({ layers: [{ layer: 'required_permissions', verdict: 'narrows', detail: 'x' }] }) }],
+    ])('fails closed: %s refuses the owner', async (_name, probe) => {
+      const closed = new SharingService({
+        engine: engine as any,
+        securityService: () => probe as any,
+        tenancy: () => ({ posture: 'single' }),
+      });
+      expect(await closed.canMintWithoutVisibility('conversations', 'c1', as(OWNER))).toBe(false);
+    });
+
+    it('a deployment with no security service at all enforces no capability gate, so the owner alternative stands', async () => {
+      const open = new SharingService({ engine: engine as any, tenancy: () => ({ posture: 'single' }) });
+      expect(await open.canMintWithoutVisibility('conversations', 'c1', as(OWNER))).toBe(true);
+    });
+  });
+
   describe('the order: opt-in, then authority, then eligibility', () => {
     it('the opt-in comes first — the owner of a record on an object that never opted in is refused 422', async () => {
       await expect(service.createLink(mintIn('notes', 'n1'), as(OWNER)))

packages/plugins/plugin-sharing/src/share-link-service.ts

@@ -437,8 +437,10 @@ export interface ShareLinkServiceOptions {
    * mint on a record their visibility read refused, because they are its
    * OWNER or hold the explicit Modify-All bypass? `createLink` asks it only
    * after that read refused. It answers with `canManageShares`' own owner and
-   * bypass branches and never with its hierarchy-depth branch, and it is
-   * withheld where an organization wall is in force.
+   * bypass branches and never with its hierarchy-depth branch. It is withheld
+   * where an organization wall is in force, and it answers `false` when the
+   * refusal was the object's capability AND-gate (`requiredPermissions`,
+   * ADR-0066 D3), which is a hard stop the alternatives do not pass.
    *
    * Absent → visibility alone admits (the pre-A′ rule), so a deployment
    * without the sharing service never widens who may mint. A throwing probe
@@ -606,10 +608,13 @@ export class ShareLinkService implements IShareLinkService {
     // once visibility has refused. The probe is the sharing service's
     // `canMintWithoutVisibility`: `canManageShares`' owner and bypass branches
     // WITHOUT its hierarchy-depth branch — a hierarchy manager still needs
-    // visibility to mint — and withheld under an organization wall. Admitted,
-    // the record is read under the system context: the caller's authority is
-    // established, and the eligibility gate below must judge the row the
-    // anonymous holder will be served (`resolveToken` reads it the same way).
+    // visibility to mint — withheld under an organization wall, and never past
+    // a capability the object requires (ADR-0066 D3): when the read was refused
+    // for a missing `requiredPermissions` capability, the probe answers `false`
+    // and that refusal is re-thrown as it came. Admitted, the record is read
+    // under the system context: the caller's authority is established, and the
+    // eligibility gate below must judge the row the anonymous holder will be
+    // served (`resolveToken` reads it the same way).
     //
     // A system caller reaches the probe only when its own system-context read
     // found nothing or failed, and the probe grants it nothing it lacks: it

packages/plugins/plugin-sharing/src/sharing-service.ts

@@ -3,6 +3,7 @@
 import type {
   AuthoredRowWriteOperation,
   AuthoredRowWriteVerdict,
+  ExplainAccessRequest,
   ISharingService,
   IHierarchyScopeResolver,
   RecordShare,
@@ -13,6 +14,7 @@ import type {
 import {
   normalizeTenancyPosture,
   postureEnforcesWall,
+  type ExplainDecision,
   type TenancyPosture,
 } from '@objectstack/spec/security';
 // [#7136] Every enforcement method below takes the FULL `resolveAuthzContext`
@@ -287,6 +289,20 @@ export interface SharingSecurityProbe {
     object: string,
     context: unknown,
   ): Promise<'own' | 'own_and_reports' | 'unit' | 'unit_and_below' | 'org'>;
+  /**
+   * [ADR-0111 D8 rule 1 — the capability hard stop] `ISecurityService.explain`,
+   * a declared (not optional) contract method, read here for ONE layer of its
+   * declared report: `required_permissions`, the ADR-0066 D3 capability
+   * AND-gate. The explain engine computes that layer with the middleware's own
+   * capability fold, so its `denies` is the refusal the read gate throws.
+   * Used by {@link SharingService.canMintWithoutVisibility} only. Absent while
+   * the service is present, a throw, or a report that does not carry the layer
+   * answers as a refusal.
+   */
+  explain?(
+    request: ExplainAccessRequest,
+    callerContext?: unknown,
+  ): Promise<Pick<ExplainDecision, 'layers'>>;
 }
 
 /** [#5103] The table whose orphans this service owns. */
@@ -1026,6 +1042,16 @@ export class SharingService implements ISharingService {
    * {@link organizationScopeRequired} reads, fail-closed: an unresolvable
    * posture counts as walled.
    *
+   * **A capability the object requires.** When the caller lacks a capability
+   * the object's `requiredPermissions` demands for a read (ADR-0066 D3), the
+   * visibility read was refused by that AND-gate, and the gate is a hard stop:
+   * neither alternative applies past it. The owner exception is about the
+   * record ROW (the owner's own record is the thing shared), not about a
+   * capability an administrator withheld from the caller for the whole object;
+   * and a Modify-All holder who lacks it does not "already read everything".
+   * The verdict is the declared `required_permissions` layer of
+   * `ISecurityService.explain` (`capabilityGateRefusesRead`).
+   *
    * Everything else fails CLOSED to `false`: a missing record, a
    * principal-less context, a failed read or probe.
    */
@@ -1035,7 +1061,53 @@ export class SharingService implements ISharingService {
     context: ExecutionContext,
   ): Promise<boolean> {
     if (this.organizationScopeRequired()) return false;
-    return (await this.ownerOrBypass(object, recordId, context)).kind === 'admit';
+    if ((await this.ownerOrBypass(object, recordId, context)).kind !== 'admit') return false;
+    // Asked last, and only of a principal an alternative admitted, so a
+    // refused stranger never pays for the explain walk.
+    return !(await this.capabilityGateRefusesRead(object, context));
+  }
+
+  /**
+   * [ADR-0111 D8 rule 1 — the capability hard stop] Does the ADR-0066 D3
+   * capability AND-gate refuse `context` a READ of `object`?
+   *
+   * Answered by `ISecurityService.explain`, a declared contract method, from
+   * the one layer of its declared report that IS that gate:
+   * `required_permissions`. The explain engine computes the layer with the
+   * read middleware's own capability fold (the same `requiredPermissions`
+   * normalisation, the same held-capability union, the same ADR-0090 D10
+   * delegator intersection), so `denies` there is the refusal the visibility
+   * read threw. It is NOT the owner-private CRUD refusal, which the same report
+   * attributes to `object_crud` with this layer `not_applicable` — which is
+   * what lets the hard stop leave the owner alternative standing on an object
+   * that requires no capability.
+   *
+   * `false` (the gate admits) needs POSITIVE evidence: the layer present with
+   * `neutral` (capabilities held) or `not_applicable` (none required). A
+   * security service without `explain`, a throw, a report missing the layer or
+   * carrying any other verdict answers `true` — a stop. The one exception is a
+   * deployment with NO security service at all: nothing there enforces a
+   * capability gate, so no read was refused by one.
+   */
+  private async capabilityGateRefusesRead(
+    object: string,
+    context: ExecutionContext,
+  ): Promise<boolean> {
+    let probe: SharingSecurityProbe | null | undefined;
+    try {
+      probe = this.securityService?.();
+    } catch {
+      return true;
+    }
+    if (!probe) return false;
+    if (typeof probe.explain !== 'function') return true;
+    try {
+      const decision = await probe.explain({ object, operation: 'read' }, context);
+      const gate = decision?.layers?.find((layer) => layer?.layer === 'required_permissions');
+      return !(gate && (gate.verdict === 'neutral' || gate.verdict === 'not_applicable'));
+    } catch {
+      return true;
+    }
   }
 
   /**