@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": minor
+---
+
+feat(spec): declare `metadata.maskObjectFields` and `getMetadataReadableFields` (#6622)
+
+ADR-0106's metadata-plane field-level security shipped in #6612 with two members
+**honoured but undeclared** — deliberately, because `packages/spec` is the spec
+seat's surface and the implementing PR did not touch it. Both now have a
+declared seat. This is the declaration half only: no runtime behaviour changes,
+in either direction, in any deployment.
+
+**`MetadataEndpointsConfigSchema.maskObjectFields`** — `z.boolean().default(true)`
+(ADR-0106 D8). The per-server switch for masking served object schemas to the
+calling user's readable fields. It was already read by `@objectstack/rest`'s
+`normalizeConfig` through a cast, following the `api.enableOpenApi` /
+`api.enableSearch` precedent, so a deployment that sets it has always been
+honoured. What the declaration adds is that the key is now **type-safe in
+`objectstack.config.ts`**, carries its documentation with it, appears in the
+generated config schema and reference docs, and — the part that was a real gap —
+**survives a parse**. `MetadataEndpointsConfigSchema` strips keys it does not
+declare, so an author who ran their config through the schema before handing it
+to the server lost the opt-out silently; that hole is closed. The default is
+`true`, matching the shipped behaviour, so no deployment moves.
+
+**`ISecurityService.getMetadataReadableFields?`** (ADR-0106 D7). The
+metadata-plane sibling of `getReadableFields`: identical except that a caller
+resolving to **zero** permission sets goes through the same fallback-set
+resolution `/auth/me/permissions` uses instead of falling open to the full field
+set — so a guest-facing deployment's schema exposure is a deliberate
+permission-set decision rather than an accidental everything-default.
+`@objectstack/plugin-security` has implemented it since #6612 and
+`@objectstack/metadata-core` already feature-detects it, falling back to
+`getReadableFields`.
+
+The member is **optional**, following the precedent #6841 set on this same
+contract: absence is a defined, handled state (a security service that predates
+ADR-0106 keeps its pre-ADR behaviour), so a required declaration would assert
+something the codebase deliberately declines to rely on — `packages/rest` types
+the whole service as `Partial<ISecurityService>`, and this contract's own header
+instructs consumers to feature-detect. Optional also prevents the mistake
+structurally: the unguarded call does not compile, so a consumer cannot skip the
+fallback by accident.
@@ -133,6 +133,7 @@ const result = BatchEndpointsConfigSchema.parse(data);
 | **prefix** | `string` | ✅ | URL prefix for metadata endpoints |
 | **enableCache** | `boolean` | ✅ | Enable HTTP cache headers (ETag, Last-Modified) |
 | **cacheTtl** | `integer` | ✅ | Cache TTL in seconds |
+| **maskObjectFields** | `boolean` | ✅ | [ADR-0106 D8] Mask served object schemas to the caller's readable fields |
 | **endpoints** | `{ types: boolean; items: boolean; item: boolean; schema: boolean }` | optional | Enable/disable specific endpoints |
 
 
@@ -170,7 +171,7 @@ const result = BatchEndpointsConfigSchema.parse(data);
 | :--- | :--- | :--- | :--- |
 | **api** | `{ version: string; basePath: string; apiPath?: string; enableCrud: boolean; … }` | optional | REST API configuration |
 | **crud** | `{ operations?: object; patterns?: Record<string, object>; dataPrefix: string; objectParamStyle: Enum<'path' \| 'query'> }` | optional | CRUD endpoints configuration |
-| **metadata** | `{ prefix: string; enableCache: boolean; cacheTtl: integer; endpoints?: object }` | optional | Metadata endpoints configuration |
+| **metadata** | `{ prefix: string; enableCache: boolean; cacheTtl: integer; maskObjectFields: boolean; … }` | optional | Metadata endpoints configuration |
 | **batch** | `{ maxBatchSize: integer; enableBatchEndpoint: boolean; operations?: object; defaultAtomic: boolean }` | optional | Batch endpoints configuration |
 | **routes** | `{ includeObjects?: string[]; excludeObjects?: string[]; nameTransform: Enum<'none' \| 'plural' \| 'kebab-case' \| 'camelCase'>; overrides?: Record<string, object> }` | optional | Route generation configuration |
 | **openApi31** | `never` | optional | [REMOVED] `RestServerConfig.openApi31` was removed in @objectstack/spec 17 (#4579, ADR-0049) — no runtime ever read it: the REST server forwards only `api`/`crud`/`metadata`/`batch`/`routes`, and the served /openapi.json is the pre-generated contract enriched with the live server URL and the registered objects, so webhook/callback definitions declared here never appeared in it. Delete the key. Config-driven OpenAPI 3.1 webhooks/callbacks documentation is a new capability and must arrive via the enforce route of ADR-0049 (a new ADR), not by re-declaring the key; for a real outbound webhook use `Webhook` from `@objectstack/spec/automation`. |
 
@@ -103,6 +103,7 @@
     "api/MetadataCacheResponse:notModified = false",
     "api/MetadataEndpointsConfig:cacheTtl = 3600",
     "api/MetadataEndpointsConfig:enableCache = true",
+    "api/MetadataEndpointsConfig:maskObjectFields = true",
     "api/MetadataEndpointsConfig:prefix = \"/meta\"",
     "api/MetadataExportRequest:format = \"json\"",
     "api/MetadataImportRequest:conflictResolution = \"skip\"",
 
@@ -1026,6 +1026,7 @@
     "api/MetadataEndpointsConfig:cacheTtl",
     "api/MetadataEndpointsConfig:enableCache",
     "api/MetadataEndpointsConfig:endpoints",
+    "api/MetadataEndpointsConfig:maskObjectFields",
     "api/MetadataEndpointsConfig:prefix",
     "api/MetadataEvent:definition",
     "api/MetadataEvent:id",
 
@@ -14,6 +14,7 @@ import {
   RestServerConfig,
   type RestApiConfig as RestApiConfigType,
   type RestServerConfig as RestServerConfigType,
+  type MetadataEndpointsConfig,
 } from './rest-server.zod';
 
 describe('RestApiConfigSchema', () => {
@@ -269,6 +270,55 @@ describe('MetadataEndpointsConfigSchema', () => {
 
     expect(config.endpoints?.schema).toBe(false);
   });
+
+  it('[ADR-0106 D8] maskObjectFields defaults to true — the mask is ON unless opted out', () => {
+    // The default is the whole security posture of the key: a deployment that
+    // never mentions `maskObjectFields` must still mask served object schemas.
+    // Pinning the MATERIALIZED default (not just the declaration) is what makes
+    // a later `.optional()` — which would hand `undefined` to the REST layer —
+    // fail here rather than silently unmask every metadata read.
+    const config = MetadataEndpointsConfigSchema.parse({});
+
+    expect(config.maskObjectFields).toBe(true);
+  });
+
+  it('[ADR-0106 D8] maskObjectFields: false is the declared per-server opt-out', () => {
+    // The opt-out has to SURVIVE the parse. Before this key had a declared seat,
+    // the schema stripped it (zod's default posture for an undeclared key) and
+    // the REST layer only saw it because it reads its config object raw, through
+    // a cast. An author who parses their config first now keeps the opt-out.
+    const optedOut = MetadataEndpointsConfigSchema.parse({ maskObjectFields: false });
+
+    expect(optedOut.maskObjectFields).toBe(false);
+
+    // Explicit `true` is a real answer too, not a no-op the parse discards.
+    expect(MetadataEndpointsConfigSchema.parse({ maskObjectFields: true }).maskObjectFields).toBe(true);
+  });
+
+  it('[ADR-0106 D8] maskObjectFields is authorable without a cast, and is a boolean (compile-time)', () => {
+    // The declaration's REASON for existing: `objectstack.config.ts` authors the
+    // key by name and `packages/rest`'s `normalizeConfig` reads it. Both of them
+    // go through this input type, so this is the pin that says the key no longer
+    // needs `(metadata as any)` to be reachable.
+    const authored: MetadataEndpointsConfig = { maskObjectFields: false };
+    const readAsBoolean: boolean | undefined = authored.maskObjectFields;
+    expect(readAsBoolean).toBe(false);
+
+    // Optional on the INPUT side — omitting it is how a deployment takes the
+    // default, and it must stay legal.
+    const omitted: MetadataEndpointsConfig = { prefix: '/meta' };
+    expect(omitted.maskObjectFields).toBeUndefined();
+
+    // …and it is a boolean switch, not a string one. Never invoked: its only job
+    // is to make the compiler prove the seat is typed rather than `any`, which
+    // is exactly what the cast it replaces could not do.
+    const mustNotCompile = () => {
+      // @ts-expect-error `maskObjectFields` is a boolean — a truthy string is not the opt-out
+      const wrongType: MetadataEndpointsConfig = { maskObjectFields: 'false' };
+      return wrongType;
+    };
+    expect(typeof mustNotCompile).toBe('function');
+  });
 });
 
 describe('BatchEndpointsConfigSchema', () => {
 
@@ -290,7 +290,30 @@ export const MetadataEndpointsConfigSchema = lazySchema(() => z.object({
    * Cache TTL in seconds
    */
   cacheTtl: z.number().int().default(3600).describe('Cache TTL in seconds'),
-  
+
+  /**
+   * [ADR-0106 D8] Per-caller field-level masking of the OBJECT SCHEMAS this
+   * server serves from `/meta` and `/metadata`.
+   *
+   * Default **on**: an object schema is projected onto the fields the CALLING
+   * user may read, so a field they cannot read does not appear at all — not its
+   * name, label, type, picklist options, formula, `visibleWhen` predicate,
+   * `defaultValue`, nor the `requiredPermissions` capability guarding it.
+   *
+   * `false` opts this server out and serves the full schema to every
+   * authenticated caller, as releases before ADR-0106 did. The change is
+   * **disclosure only**: the data plane masks values and refuses forbidden
+   * writes either way, and the console reads field affordances from
+   * `/auth/me/permissions`, so toggling it never changes UI correctness.
+   *
+   * Deployment-wide counterpart: `OS_ALLOW_UNMASKED_OBJECT_METADATA=1`, which
+   * also covers the runtime `/metadata` dispatcher (that path has no per-server
+   * REST config to read). Either opt-out disables the mask; neither is needed
+   * to keep it on.
+   */
+  maskObjectFields: z.boolean().default(true)
+    .describe('[ADR-0106 D8] Mask served object schemas to the caller\'s readable fields'),
+
   /**
    * Enable specific metadata endpoints
    */
 
@@ -98,6 +98,63 @@ describe('Security Service Contract', () => {
       .resolves.toEqual(['id', 'name']);
   });
 
+  it('[ADR-0106 D7] getMetadataReadableFields is OPTIONAL — absence degrades to getReadableFields', async () => {
+    // THE structural pin behind "a deployment whose security service predates
+    // ADR-0106 keeps its pre-ADR behaviour". Optional is what makes that a
+    // property of the TYPE: such a service still satisfies the contract, and a
+    // consumer cannot reach the metadata-plane answer without first handling
+    // the absent case.
+    const withoutIt: ISecurityService = makeService({ getReadableFields: async () => ['id', 'name'] });
+    expect(typeof withoutIt.getMetadataReadableFields).toBe('undefined');
+
+    // The unguarded call does not compile. Never invoked — its only job is to
+    // make the COMPILER prove the point (invoking it would merely prove that
+    // JavaScript throws on `undefined()`, which is the runtime symptom this
+    // declaration exists to prevent).
+    const mustNotCompileWithoutAGuard = () =>
+      // @ts-expect-error possibly undefined — a consumer must feature-detect first
+      withoutIt.getMetadataReadableFields('deal', { userId: 'u1' });
+    expect(typeof mustNotCompileWithoutAGuard).toBe('function');
+
+    // The shape consumers actually write (`metadata-core`'s object-schema mask
+    // resolver): prefer the metadata-plane answer, fall back to the data-plane
+    // one. The fallback is never NARROWER than the metadata-plane answer, which
+    // is why degrading here cannot hide columns a caller may see.
+    const ask = typeof withoutIt.getMetadataReadableFields === 'function'
+      ? withoutIt.getMetadataReadableFields.bind(withoutIt)
+      : withoutIt.getReadableFields.bind(withoutIt);
+    await expect(ask('deal', { userId: 'u1' })).resolves.toEqual(['id', 'name']);
+  });
+
+  it('[ADR-0106 D7] the metadata plane narrows where the data plane falls open', async () => {
+    // The one respect in which the two methods differ, and the reason a second
+    // method exists at all: a caller resolving to ZERO permission sets falls
+    // OPEN on the data plane (mirroring the middleware, which skips its field
+    // gate entirely) and resolves the fallback set on the metadata plane, so a
+    // guest deployment's schema exposure is a deliberate permission-set
+    // decision rather than an accidental everything-default.
+    const service = makeService({
+      getReadableFields: async () => ['id', 'name', 'secret'],
+      getMetadataReadableFields: async (_object, context) =>
+        context?.isSystem ? ['id', 'name', 'secret'] : ['id'],
+    });
+
+    await expect(service.getReadableFields('deal', {})).resolves.toEqual(['id', 'name', 'secret']);
+    await expect(service.getMetadataReadableFields?.('deal', {})).resolves.toEqual(['id']);
+
+    // A system context bypasses on BOTH planes.
+    await expect(service.getMetadataReadableFields?.('deal', { isSystem: true }))
+      .resolves.toEqual(['id', 'name', 'secret']);
+
+    // …and it inherits getReadableFields' two distinct empty answers, unchanged:
+    // `undefined` = no answer (fall back to your own projection), `[]` = the real
+    // answer that no field may be disclosed.
+    const noAnswer = makeService({ getMetadataReadableFields: async () => undefined });
+    await expect(noAnswer.getMetadataReadableFields?.('deal', { userId: 'u1' })).resolves.toBeUndefined();
+    const nothingDisclosable = makeService({ getMetadataReadableFields: async () => [] });
+    await expect(nothingDisclosable.getMetadataReadableFields?.('deal', { userId: 'u1' })).resolves.toEqual([]);
+  });
+
   it('a partial implementation is feature-detectable rather than wrong', () => {
     // Consumers probe (`typeof svc.getReadableFields === 'function'`) so an
     // implementation may omit a method it cannot honour and still be usable.
 
@@ -33,7 +33,9 @@
  *   answers "which columns may this caller see" for presentation purposes; when
  *   the object schema cannot be resolved it returns `undefined`, meaning
  *   "no answer — use your own fallback", NOT "no fields are readable". An empty
- *   array is a real answer and means the opposite: nothing is readable.
+ *   array is a real answer and means the opposite: nothing is readable. Its
+ *   metadata-plane sibling {@link ISecurityService.getMetadataReadableFields}
+ *   (ADR-0106 D7) reads the same two empty answers the same way.
  * - **Verdicts fail to ABSTENTION.** {@link ISecurityService.checkAuthoredRowWrite}
  *   answers a question a composing caller may use to WIDEN, so its failure mode
  *   is the one that changes nothing: `abstain`. It never reports `admit` for a
@@ -231,6 +233,49 @@ export interface ISecurityService {
    */
   getReadableFields(object: string, context?: SecurityContext): Promise<string[] | undefined>;
 
+  /**
+   * [ADR-0106 D7] The METADATA-PLANE variant of {@link getReadableFields}:
+   * which field names may be DISCLOSED to `context` when an object SCHEMA is
+   * served, as opposed to which columns of a row it may read.
+   *
+   * Identical to {@link getReadableFields} in every respect but one — a caller
+   * that resolves to **zero** permission sets goes through the same fallback-set
+   * resolution `/auth/me/permissions` uses (`security.fallbackPermissionSet`,
+   * default `member_default`) instead of falling open to the full field set.
+   *
+   * **Why the two differ rather than converge.** `getReadableFields` mirrors the
+   * engine middleware, which skips its whole field gate for a caller with no
+   * permission sets; on the DATA plane, reporting a narrowing the enforcement
+   * path would not apply is its own kind of drift, so falling open is the
+   * correct, drift-free answer there. The metadata plane has no such symmetry to
+   * preserve — the question is disclosure, and D7 rules that a public/guest
+   * deployment's schema exposure must be a deliberate permission-set decision
+   * rather than an accidental everything-default. It still falls open when the
+   * fallback set itself resolves to nothing (no `member_default` in the
+   * deployment at all): that is the "no FLS posture here" tier, not a restricted
+   * caller.
+   *
+   * **Fails SOFT, with the same two distinct empty answers as
+   * {@link getReadableFields}:** `undefined` is "no answer — use your own
+   * fallback" (e.g. the object schema could not be resolved); `[]` is the real
+   * answer that this caller may see NO field. A system context bypasses and
+   * yields the full field set.
+   *
+   * **OPTIONAL, and absence is a defined state — not a bug.** A security service
+   * that predates ADR-0106, or one that cannot honour the fallback resolution,
+   * omits it; consumers feature-detect
+   * (`typeof svc.getMetadataReadableFields === 'function'`) and fall back to
+   * {@link getReadableFields}, which is the pre-ADR-0106 behaviour and never a
+   * *narrower* answer. Declaring it optional is what makes that degradation a
+   * property of the type rather than a promise in prose: the unguarded call does
+   * not compile, so a consumer cannot skip the fallback by accident.
+   *
+   * The masking itself is gated separately by the deployment's D8 opt-outs
+   * (`metadata.maskObjectFields: false`, `OS_ALLOW_UNMASKED_OBJECT_METADATA`);
+   * this method only answers the projection question when a mask applies.
+   */
+  getMetadataReadableFields?(object: string, context?: SecurityContext): Promise<string[] | undefined>;
+
   /**
    * The effective permission-set NAMES for `context` — positions expanded and
    * the additive baseline applied, i.e. the same set the middleware enforces