feat(spec): ADR-0066 D2/D3 — object access posture + requiredPermissions

- access: { default: 'public' | 'private' } — secure-by-default object posture
  (ObjectAccessConfigSchema), a data-model posture like tenancy. private opts the
  object out of wildcard '*' grants and (via the engine) out of wildcard RLS.
- requiredPermissions: string[] on Object — capability contract (mirrors
  App.requiredPermissions), enforced by the engine as an AND-gate.
- Both optional; absent ⇒ public / no gate (no migration for existing objects).
- Tests + full-DTS build green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

packages/spec/src/data/object.test.ts

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { ObjectSchema, ObjectCapabilities, IndexSchema, ObjectFieldGroupSchema, ObjectExternalBindingSchema, type ServiceObject } from './object.zod';
+import { ObjectSchema, ObjectCapabilities, IndexSchema, ObjectFieldGroupSchema, ObjectExternalBindingSchema, ObjectAccessConfigSchema, type ServiceObject } from './object.zod';
 
 describe('ObjectCapabilities', () => {
   it('should apply default values correctly', () => {
@@ -953,3 +953,39 @@ describe('ObjectSchema.fieldGroups', () => {
     });
   });
 });
+
+
+describe('ADR-0066 — object access posture (D2) + requiredPermissions (D3)', () => {
+  it('ObjectAccessConfigSchema defaults to public', () => {
+    expect(ObjectAccessConfigSchema.parse({}).default).toBe('public');
+  });
+
+  it('accepts an explicit private posture', () => {
+    expect(ObjectAccessConfigSchema.parse({ default: 'private' }).default).toBe('private');
+  });
+
+  it('rejects an unknown posture value', () => {
+    expect(() => ObjectAccessConfigSchema.parse({ default: 'secret' })).toThrow();
+  });
+
+  it('round-trips access + requiredPermissions on an object', () => {
+    const obj = ObjectSchema.create({
+      name: 'sys_license',
+      tenancy: { enabled: false, strategy: 'shared' },
+      access: { default: 'private' },
+      requiredPermissions: ['manage_licenses'],
+      fields: { signed_token: { type: 'text' } },
+    });
+    expect(obj.access?.default).toBe('private');
+    expect(obj.requiredPermissions).toEqual(['manage_licenses']);
+  });
+
+  it('leaves access undefined (public by convention) when omitted', () => {
+    const obj = ObjectSchema.create({
+      name: 'crm_account',
+      fields: { name: { type: 'text' } },
+    });
+    expect(obj.access).toBeUndefined();
+    expect(obj.requiredPermissions).toBeUndefined();
+  });
+});

packages/spec/src/data/object.zod.ts

@@ -135,6 +135,32 @@ export const TenancyConfigSchema = lazySchema(() => z.object({
   crossTenantAccess: z.boolean().default(false).describe('Allow cross-tenant data access (with explicit permission)'),
 }));
 
+/**
+ * [ADR-0066 D2] Secure-by-default object posture.
+ *
+ * Declares whether the object participates in blanket wildcard permission
+ * grants — a data-model posture like {@link TenancyConfigSchema}, NOT an
+ * assignment (it names no principal).
+ *
+ * - `public` (default) — covered by a permission set's `'*'` wildcard object
+ *   grant; today's allow-by-default behaviour.
+ * - `private` — NOT covered by the `'*'` wildcard grant; access requires an
+ *   EXPLICIT per-object grant (Salesforce "new object = no access until
+ *   granted"). A `private` object is ALSO exempt from wildcard RLS
+ *   (`tenant_isolation`, owner scoping): the posture-gated superuser bypass
+ *   (`viewAllRecords`/`modifyAllRecords`) short-circuits RLS, so a platform
+ *   admin — incl. one who is also an org admin whose `tenant_isolation` would
+ *   otherwise narrow the result — sees all rows, while non-admins without an
+ *   explicit grant see none.
+ *
+ * Pair with the object's `requiredPermissions` (D3) to additionally gate access
+ * on holding a capability.
+ */
+export const ObjectAccessConfigSchema = lazySchema(() => z.object({
+  default: z.enum(['public', 'private']).default('public')
+    .describe('Default exposure posture: public (covered by wildcard grants) | private (needs explicit grant; exempt from wildcard RLS).'),
+}));
+
 /**
  * Soft Delete Configuration Schema
  * Implements recycle bin / trash functionality
@@ -487,6 +513,25 @@ const ObjectSchemaBase = z.object({
 
   // Multi-tenancy configuration
   tenancy: TenancyConfigSchema.optional().describe('Multi-tenancy configuration for SaaS applications'),
+
+  /**
+   * [ADR-0066 D2] Secure-by-default object posture. `access.default: 'private'`
+   * opts the object OUT of blanket wildcard (`'*'`) permission grants (access
+   * then needs an explicit per-object grant) and exempts it from wildcard RLS
+   * via the posture-gated superuser bypass. Absent ⇒ `public` (today's
+   * allow-by-default behaviour; no migration for existing objects).
+   */
+  access: ObjectAccessConfigSchema.optional().describe('[ADR-0066 D2] Object exposure posture (public-by-default vs private secure-by-default).'),
+
+  /**
+   * [ADR-0066 D3] Capability contract — capability name(s) (permission-set
+   * `systemPermissions`; D1 records) a caller MUST hold to access this object at
+   * all. Mirrors `App.requiredPermissions`. Enforced by plugin-security as an
+   * AND-gate: checked IN ADDITION to permission-set CRUD grants — a caller
+   * missing any listed capability is denied regardless of grants. Absent/empty
+   * ⇒ no capability gate.
+   */
+  requiredPermissions: z.array(z.string()).optional().describe('[ADR-0066 D3] Capabilities required to access this object (AND-gate, checked alongside CRUD grants).'),
 
   // Soft delete configuration
   softDelete: SoftDeleteConfigSchema.optional().describe('Soft delete (trash/recycle bin) configuration'),
@@ -867,6 +912,7 @@ export type ServiceObjectInput = z.input<typeof ObjectSchemaBase>;
 export type ObjectCapabilities = z.infer<typeof ObjectCapabilities>;
 export type ObjectIndex = z.infer<typeof IndexSchema>;
 export type TenancyConfig = z.infer<typeof TenancyConfigSchema>;
+export type ObjectAccessConfig = z.infer<typeof ObjectAccessConfigSchema>;
 export type SoftDeleteConfig = z.infer<typeof SoftDeleteConfigSchema>;
 export type VersioningConfig = z.infer<typeof VersioningConfigSchema>;
 export type PartitioningConfig = z.infer<typeof PartitioningConfigSchema>;