feat(security/metadata-protocol): enforce OWD posture on the runtime write path (#3050)

Implements the ADR-0094-addendum registerAuthoringGate seam — an awaited,
THROWING pre-persistence hook in saveMetaItem (draft + publish-mode saves,
environment writes only; control-plane bootstrap bypasses like the ADR-0005
gate) — and registers plugin-security's object posture gate on it:

- R1 env-tighten-only (ADR-0086 D1, ADR-0049): an environment overlay of a
  packaged object may not widen sharingModel/externalSharingModel beyond the
  packaged declaration. Closes the OS_METADATA_WRITABLE=object hole where the
  escape hatch admitted unvalidated OWD widening (private ->
  public_read_write) with zero checks.
- R2 external<=internal (ADR-0090 D11): previously .describe() prose + CLI
  lint only; now rejected at save time on every runtime authoring surface.

Write-path only: no zod refine, stored/grandfathered metadata keeps loading
(the ADR-0090 D1 lesson). controlled_by_parent excluded from ordering on
either side, mirroring lint's OWD_WIDTH. publishMetaItem promotes an
already-gated draft body, so no second gate. Protocols predating the seam
keep legacy behavior (feature-detected wiring).

Tests: authoring-gate seam contract (metadata-protocol, 6 new) + posture gate
unit suite (plugin-security, 18).

Author: claude

.changeset/owd-posture-authoring-gate.md

@@ -0,0 +1,6 @@
+---
+'@objectstack/metadata-protocol': minor
+'@objectstack/plugin-security': minor
+---
+
+OWD posture is now enforced on the runtime write path (#3050). `metadata-protocol` gains the ADR-0094-addendum `registerAuthoringGate(type, gate)` seam — an awaited, throwing pre-persistence hook inside `saveMetaItem` (draft and publish-mode saves; environment writes only). `plugin-security` registers the `object` posture gate on it: an environment overlay of a packaged object may only TIGHTEN `sharingModel`/`externalSharingModel` (ADR-0086 D1 — closes the `OS_METADATA_WRITABLE=object` unvalidated-widening hole), and `externalSharingModel ≤ sharingModel` (ADR-0090 D11) is now rejected at save time instead of only by CLI lint. Write-path only — stored metadata keeps loading unchanged.

packages/metadata-protocol/src/index.ts

@@ -3,6 +3,7 @@
 export { ObjectStackProtocolImplementation, ConcurrentUpdateError, normalizeViewMetadata } from './protocol.js';
 export type { UninstallCleanup, UninstallCleanupOutcome } from './protocol.js';
 export type { MetadataMutationEvent, MetadataMutationProjector, MutationProjectionOutcome } from './protocol.js';
+export type { MetadataAuthoringGate, MetadataAuthoringGateContext } from './protocol.js';
 
 export { SysMetadataRepository, resetEnvWritableMetadataTypes } from './sys-metadata-repository.js';
 export type {

packages/metadata-protocol/src/mutation-listeners.test.ts

@@ -116,3 +116,73 @@ describe('ObjectStackProtocolImplementation.registerMutationProjector (ADR-0094)
     expect(out).toEqual({ success: false, error: 'projection boom' });
   });
 });
+
+// #3050 — the pre-persistence AUTHORING GATE seam (ADR-0094 addendum). The
+// inverse contract of the projector: it runs BEFORE persistence and a throw
+// PROPAGATES (rejecting the write) instead of being swallowed. saveMetaItem
+// invokes it for env writes only, both draft and publish-mode saves; the
+// domain-gate behavior itself (OWD posture) is pinned in plugin-security's
+// object-posture-gate suite.
+describe('ObjectStackProtocolImplementation.registerAuthoringGate (#3050)', () => {
+  const save = (over: Record<string, unknown> = {}) => ({
+    type: 'object', name: 'crm_account', state: 'active' as const, body: { sharingModel: 'private' }, ...over,
+  });
+
+  it('dispatches the registered gate with the body and state', async () => {
+    const p = makeProtocol();
+    const seen: any[] = [];
+    p.registerAuthoringGate('object', (ctx) => { seen.push(ctx); });
+    await (p as any).runAuthoringGate(save({ state: 'draft' }));
+    expect(seen).toHaveLength(1);
+    expect(seen[0]).toMatchObject({
+      type: 'object', name: 'crm_account', state: 'draft',
+      body: { sharingModel: 'private' }, isArtifactBacked: false,
+    });
+  });
+
+  it('normalizes plural registrations to the singular type', async () => {
+    const p = makeProtocol();
+    const gate = vi.fn();
+    p.registerAuthoringGate('objects', gate);
+    await (p as any).runAuthoringGate(save());
+    expect(gate).toHaveBeenCalledTimes(1);
+  });
+
+  it('a gate throw PROPAGATES with its status/code (the write is rejected)', async () => {
+    const p = makeProtocol();
+    p.registerAuthoringGate('object', () => {
+      const err: any = new Error('[owd_widening_forbidden] no widening');
+      err.code = 'owd_widening_forbidden'; err.status = 403;
+      throw err;
+    });
+    await expect((p as any).runAuthoringGate(save())).rejects.toMatchObject({
+      code: 'owd_widening_forbidden', status: 403,
+    });
+  });
+
+  it('is a no-op for types with no registered gate', async () => {
+    const p = makeProtocol();
+    await expect((p as any).runAuthoringGate(save({ type: 'view' }))).resolves.toBeUndefined();
+  });
+
+  it('resolves isArtifactBacked + declaredBody from the artifact registry', async () => {
+    const declared = { name: 'crm_account', sharingModel: 'private', _packageId: 'crm' };
+    const engine = { registry: { getItem: (_t: string, n: string) => (n === 'crm_account' ? declared : undefined) } };
+    const p = new ObjectStackProtocolImplementation(engine as any);
+    const seen: any[] = [];
+    p.registerAuthoringGate('object', (ctx) => { seen.push(ctx); });
+    await (p as any).runAuthoringGate(save());
+    expect(seen[0].isArtifactBacked).toBe(true);
+    expect(seen[0].declaredBody).toBe(declared);
+  });
+
+  it('a second registration replaces the first (idempotent re-init)', async () => {
+    const p = makeProtocol();
+    const first = vi.fn(); const second = vi.fn();
+    p.registerAuthoringGate('object', first);
+    p.registerAuthoringGate('object', second);
+    await (p as any).runAuthoringGate(save());
+    expect(first).not.toHaveBeenCalled();
+    expect(second).toHaveBeenCalledTimes(1);
+  });
+});

packages/metadata-protocol/src/protocol.ts

@@ -799,6 +799,40 @@ export interface MutationProjectionOutcome {
     error?: string;
 }
 
+/**
+ * Pre-persistence authoring gate (ADR-0094 addendum seam; #3050).
+ *
+ * Unlike the post-persist {@link MetadataMutationProjector} (best-effort,
+ * never thrown), an authoring gate runs BEFORE persistence and REJECTS the
+ * write by throwing — it is the seam for domain invariants that must hold on
+ * every runtime-authored body regardless of which HTTP surface produced it
+ * (e.g. plugin-security's OWD posture gate: an environment may only TIGHTEN
+ * a packaged object's `sharingModel`, and `externalSharingModel ≤
+ * sharingModel` per ADR-0090 D11).
+ *
+ * Invoked inside `saveMetaItem` for BOTH draft and publish-mode saves, after
+ * the ADR-0005 overlay/runtime-create authorization and the per-type spec
+ * validation — so `publishMetaItem` promotes an already-gated body and needs
+ * no second gate. Environment writes only: control-plane bootstrap writes
+ * (`environmentId === undefined`) are the package author's own channel and
+ * bypass the gate, mirroring the ADR-0005 gate above.
+ */
+export interface MetadataAuthoringGateContext {
+    /** Singular type name (e.g. `object`). */
+    type: string;
+    name: string;
+    /** Lifecycle the body is being saved into. */
+    state: 'draft' | 'active';
+    organizationId?: string;
+    /** The body being persisted. */
+    body: unknown;
+    /** True when a packaged artifact backs this name — the write is an env overlay of shipped metadata. */
+    isArtifactBacked: boolean;
+    /** The packaged (code-layer) baseline body when {@link isArtifactBacked}; the declaration an overlay customizes. */
+    declaredBody?: unknown;
+}
+export type MetadataAuthoringGate = (ctx: MetadataAuthoringGateContext) => void | Promise<void>;
+
 export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     private engine: MetadataHostEngine;
     private getServicesRegistry?: () => Map<string, any>;
@@ -847,6 +881,14 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
      */
     private mutationProjectors = new Map<string, MetadataMutationProjector>();
 
+    /**
+     * Pre-persistence authoring gates (#3050). One per type; a second
+     * registration replaces the first (idempotent re-init). Unlike
+     * projectors these THROW to reject the write — see
+     * {@link MetadataAuthoringGate}.
+     */
+    private authoringGates = new Map<string, MetadataAuthoringGate>();
+
     constructor(
         engine: IDataEngine,
         getServicesRegistry?: () => Map<string, any>,
@@ -894,6 +936,49 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         this.mutationProjectors.set(singular, projector);
     }
 
+    /**
+     * Register the pre-persistence authoring gate for a metadata type
+     * (ADR-0094 addendum seam; #3050). Called by domain plugins at init —
+     * e.g. plugin-security registers the `object` OWD posture gate. The gate
+     * THROWS to reject the write. Singular or plural type names both resolve;
+     * one gate per type, a second registration replaces the first.
+     */
+    registerAuthoringGate(type: string, gate: MetadataAuthoringGate): void {
+        const singular = PLURAL_TO_SINGULAR[type] ?? type;
+        this.authoringGates.set(singular, gate);
+    }
+
+    /**
+     * Run the registered authoring gate for an about-to-persist body (#3050).
+     * No-op when no gate is registered for the type. A gate throw PROPAGATES
+     * (with its status/code) — that is the contract: the write is rejected
+     * before persistence. Resolves the artifact-backed flag and the packaged
+     * declaration body (the baseline an overlay customizes) for the gate.
+     */
+    private async runAuthoringGate(evt: {
+        type: string; name: string; state: 'draft' | 'active'; organizationId?: string; body: unknown;
+    }): Promise<void> {
+        const singular = PLURAL_TO_SINGULAR[evt.type] ?? evt.type;
+        const gate = this.authoringGates.get(singular);
+        if (!gate) return;
+        const artifactBacked = this.isArtifactBacked(evt.type, evt.name);
+        let declaredBody: unknown;
+        if (artifactBacked && typeof this.engine.registry?.getItem === 'function') {
+            const alt = PLURAL_TO_SINGULAR[evt.type] ?? SINGULAR_TO_PLURAL[evt.type];
+            declaredBody = this.engine.registry.getItem(evt.type, evt.name)
+                ?? (alt ? this.engine.registry.getItem(alt, evt.name) : undefined);
+        }
+        await gate({
+            type: singular,
+            name: evt.name,
+            state: evt.state,
+            ...(evt.organizationId ? { organizationId: evt.organizationId } : {}),
+            body: evt.body,
+            isArtifactBacked: artifactBacked,
+            ...(declaredBody !== undefined ? { declaredBody } : {}),
+        });
+    }
+
     /**
      * Run the registered projector for a just-persisted mutation (ADR-0094).
      * Returns `undefined` when no projector is registered for the type;
@@ -4010,6 +4095,22 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
             }
         }
 
+        // Pre-persistence authoring gate (#3050): a domain plugin may veto the
+        // body before it persists (throws propagate to the caller with their
+        // status/code). Runs for BOTH draft and publish-mode saves, so a later
+        // publishMetaItem promotes an already-gated body. Environment writes
+        // only — control-plane bootstrap writes (environmentId undefined) are
+        // the package author's own channel, mirroring the ADR-0005 gate above.
+        if (this.environmentId !== undefined) {
+            await this.runAuthoringGate({
+                type: request.type,
+                name: request.name,
+                state: mode === 'draft' ? 'draft' : 'active',
+                ...(request.organizationId ? { organizationId: request.organizationId } : {}),
+                body: request.item,
+            });
+        }
+
         // 1. Update the in-memory registry (runtime cache) ONLY for the
         //    `object` type — schema definitions feed engine.syncSchema and
         //    must be reflected immediately for CRUD to work. For all other

packages/plugins/plugin-security/src/index.ts

@@ -44,6 +44,8 @@ export type {
 } from './permission-set-projection.js';
 export { cleanupPackagePermissions } from './cleanup-package-permissions.js';
 export type { PackagePermissionCleanupOutcome } from './cleanup-package-permissions.js';
+export { objectPostureGate, registerObjectPostureGate } from './object-posture-gate.js';
+export type { ObjectPostureGateContext } from './object-posture-gate.js';
 export { claimSeedOwnership } from './claim-seed-ownership.js';
 export { normalizeManagedByVocab } from './normalize-managed-by.js';
 export { appDefaultPermissionSetName } from './app-default-permission-set.js';

packages/plugins/plugin-security/src/object-posture-gate.test.ts

@@ -0,0 +1,158 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+// #3050 — OWD posture authoring gate: env-tighten-only over packaged
+// declarations (ADR-0086 D1) + external ≤ internal (ADR-0090 D11), enforced
+// on the runtime write path (previously CLI-lint-only).
+
+import { describe, it, expect } from 'vitest';
+import { objectPostureGate, registerObjectPostureGate } from './object-posture-gate.js';
+
+const base = (over: Partial<Parameters<typeof objectPostureGate>[0]> = {}) => ({
+  type: 'object',
+  name: 'crm_account',
+  body: {},
+  isArtifactBacked: false,
+  ...over,
+});
+
+describe('R2 — external ≤ internal (ADR-0090 D11)', () => {
+  it('rejects external wider than internal', () => {
+    expect(() => objectPostureGate(base({
+      body: { sharingModel: 'public_read', externalSharingModel: 'public_read_write' },
+    }))).toThrowError(/owd_external_wider/);
+  });
+
+  it('rejects explicit external on an OWD-less body (internal defaults to private, ADR-0090 D1)', () => {
+    expect(() => objectPostureGate(base({
+      body: { externalSharingModel: 'public_read' },
+    }))).toThrowError(/owd_external_wider/);
+  });
+
+  it('accepts external equal to internal', () => {
+    expect(() => objectPostureGate(base({
+      body: { sharingModel: 'public_read', externalSharingModel: 'public_read' },
+    }))).not.toThrow();
+  });
+
+  it('accepts external tighter than internal', () => {
+    expect(() => objectPostureGate(base({
+      body: { sharingModel: 'public_read_write', externalSharingModel: 'private' },
+    }))).not.toThrow();
+  });
+
+  it('skips ordering when either side is controlled_by_parent (inherits master pair)', () => {
+    expect(() => objectPostureGate(base({
+      body: { sharingModel: 'controlled_by_parent', externalSharingModel: 'public_read' },
+    }))).not.toThrow();
+    expect(() => objectPostureGate(base({
+      body: { sharingModel: 'public_read', externalSharingModel: 'controlled_by_parent' },
+    }))).not.toThrow();
+  });
+
+  it('accepts a body with no posture fields at all', () => {
+    expect(() => objectPostureGate(base({ body: { name: 'crm_account', fields: {} } }))).not.toThrow();
+  });
+
+  it('carries 403 + code on the error', () => {
+    try {
+      objectPostureGate(base({ body: { sharingModel: 'private', externalSharingModel: 'public_read' } }));
+      expect.unreachable('should have thrown');
+    } catch (e: any) {
+      expect(e.status).toBe(403);
+      expect(e.code).toBe('owd_external_wider');
+    }
+  });
+});
+
+describe('R1 — env-tighten-only over a packaged declaration (ADR-0086 D1)', () => {
+  it('rejects widening internal beyond the declared baseline', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      declaredBody: { sharingModel: 'private' },
+      body: { sharingModel: 'public_read_write' },
+    }))).toThrowError(/owd_widening_forbidden/);
+  });
+
+  it('rejects widening when the declaration is OWD-less (baseline = private per ADR-0090 D1)', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      declaredBody: { name: 'crm_account' },
+      body: { sharingModel: 'public_read' },
+    }))).toThrowError(/owd_widening_forbidden/);
+  });
+
+  it('rejects widening external beyond the declared external (default private, D11)', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      declaredBody: { sharingModel: 'public_read' },
+      body: { sharingModel: 'public_read', externalSharingModel: 'public_read' },
+    }))).toThrowError(/owd_widening_forbidden/);
+  });
+
+  it('accepts tightening the packaged posture', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      declaredBody: { sharingModel: 'public_read_write', externalSharingModel: 'public_read' },
+      body: { sharingModel: 'private', externalSharingModel: 'private' },
+    }))).not.toThrow();
+  });
+
+  it('accepts an overlay that leaves posture unchanged', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      declaredBody: { sharingModel: 'public_read' },
+      body: { sharingModel: 'public_read', label: 'Renamed' },
+    }))).not.toThrow();
+  });
+
+  it('accepts an overlay that omits posture fields entirely', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      declaredBody: { sharingModel: 'private' },
+      body: { label: 'Renamed' },
+    }))).not.toThrow();
+  });
+
+  it('skips tighten comparison when declared side is controlled_by_parent', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      declaredBody: { sharingModel: 'controlled_by_parent' },
+      body: { sharingModel: 'public_read' },
+    }))).not.toThrow();
+  });
+
+  it('does not apply R1 to runtime-created (non-artifact) objects — env owns them', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: false,
+      body: { sharingModel: 'public_read_write' },
+    }))).not.toThrow();
+  });
+
+  it('does not apply R1 when the declared baseline is unavailable', () => {
+    expect(() => objectPostureGate(base({
+      isArtifactBacked: true,
+      body: { sharingModel: 'public_read_write' },
+    }))).not.toThrow();
+  });
+});
+
+describe('registerObjectPostureGate wiring', () => {
+  it('registers on a protocol exposing registerAuthoringGate and rejects through it', async () => {
+    const gates = new Map<string, (ctx: any) => void | Promise<void>>();
+    const protocol = {
+      registerAuthoringGate: (type: string, gate: (ctx: any) => void) => gates.set(type, gate),
+    };
+    expect(registerObjectPostureGate(protocol)).toBe(true);
+    const gate = gates.get('object')!;
+    expect(gate).toBeTypeOf('function');
+    await expect(async () => gate({
+      type: 'object', name: 'crm_account', body: { sharingModel: 'private', externalSharingModel: 'public_read' },
+      isArtifactBacked: false,
+    })).rejects.toThrowError(/owd_external_wider/);
+  });
+
+  it('feature-detects: returns false on a protocol without the seam', () => {
+    expect(registerObjectPostureGate({})).toBe(false);
+    expect(registerObjectPostureGate(undefined)).toBe(false);
+  });
+});