@open-mercato/core 0.6.7-develop.6593.1.0ecf630f1e → 0.6.7-develop.6594.1.5581f765f4

package/dist/modules/entities/migrations/Migration20260716120000.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/modules/entities/migrations/Migration20260716120000.ts"],
+  "sourcesContent": ["import { Migration } from '@mikro-orm/migrations';\n\nexport class Migration20260716120000 extends Migration {\n\n  override async up(): Promise<void> {\n    this.addSql(`alter table \"custom_entities\" add column \"access_restricted\" boolean not null default false;`);\n  }\n\n  override async down(): Promise<void> {\n    this.addSql(`alter table \"custom_entities\" drop column \"access_restricted\";`);\n  }\n\n}\n"],
+  "mappings": "AAAA,SAAS,iBAAiB;AAEnB,MAAM,gCAAgC,UAAU;AAAA,EAErD,MAAe,KAAoB;AACjC,SAAK,OAAO,8FAA8F;AAAA,EAC5G;AAAA,EAEA,MAAe,OAAsB;AACnC,SAAK,OAAO,gEAAgE;AAAA,EAC9E;AAEF;",
+  "names": []
+}

package/generated/entities/custom_entity/index.ts

@@ -5,6 +5,7 @@ export const description = "description";
 export const label_field = "label_field";
 export const default_editor = "default_editor";
 export const show_in_sidebar = "show_in_sidebar";
+export const access_restricted = "access_restricted";
 export const organization_id = "organization_id";
 export const tenant_id = "tenant_id";
 export const is_active = "is_active";

package/generated/entity-fields-registry.ts

@@ -503,6 +503,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "label_field": "label_field",
       "default_editor": "default_editor",
       "show_in_sidebar": "show_in_sidebar",
+      "access_restricted": "access_restricted",
       "organization_id": "organization_id",
       "tenant_id": "tenant_id",
       "is_active": "is_active",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.6.7-develop.6593.1.0ecf630f1e",
+  "version": "0.6.7-develop.6594.1.5581f765f4",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -254,16 +254,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.6.7-develop.6593.1.0ecf630f1e",
-    "@open-mercato/shared": "0.6.7-develop.6593.1.0ecf630f1e",
-    "@open-mercato/ui": "0.6.7-develop.6593.1.0ecf630f1e",
+    "@open-mercato/ai-assistant": "0.6.7-develop.6594.1.5581f765f4",
+    "@open-mercato/shared": "0.6.7-develop.6594.1.5581f765f4",
+    "@open-mercato/ui": "0.6.7-develop.6594.1.5581f765f4",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.6.7-develop.6593.1.0ecf630f1e",
-    "@open-mercato/shared": "0.6.7-develop.6593.1.0ecf630f1e",
-    "@open-mercato/ui": "0.6.7-develop.6593.1.0ecf630f1e",
+    "@open-mercato/ai-assistant": "0.6.7-develop.6594.1.5581f765f4",
+    "@open-mercato/shared": "0.6.7-develop.6594.1.5581f765f4",
+    "@open-mercato/ui": "0.6.7-develop.6594.1.5581f765f4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/modules/auth/api/features.ts

@@ -3,6 +3,8 @@ import { z } from 'zod'
 import type { OpenApiMethodDoc, OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { getModules } from '@open-mercato/shared/lib/i18n/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { synthesizeRestrictedEntityFeatures } from '@open-mercato/core/modules/entities/lib/restrictedEntityFeatures'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['auth.acl.manage'] },
@@ -44,6 +46,21 @@ export async function GET(req: Request) {
       return base
     })
   )
+  // Append synthesized per-entity features for the tenant's restricted custom
+  // entities so they can be granted in the ACL editor. Tenant-scoped; never
+  // throws (falls back to the static catalog on any failure).
+  try {
+    const { resolve } = await createRequestContainer()
+    const em = resolve('em') as any
+    const synthesized = await synthesizeRestrictedEntityFeatures(em, auth.tenantId ?? null)
+    for (const item of synthesized) {
+      const deps = normalizeDependsOn(item.dependsOn)
+      const base: FeatureItem = { id: item.id, title: item.title, module: item.module }
+      if (deps) base.dependsOn = deps
+      items.push(base)
+    }
+  } catch {}
+
   // Deduplicate by id (keep first occurrence)
   const byId = new Map<string, FeatureItem>()
   for (const it of items) if (!byId.has(it.id)) byId.set(it.id, it)

package/src/modules/entities/api/entities.ts

@@ -68,6 +68,7 @@ export async function GET(req: Request) {
       labelField: (c as any).labelField ?? undefined,
       defaultEditor: (c as any).defaultEditor ?? undefined,
       showInSidebar: (c as any).showInSidebar ?? false,
+      accessRestricted: (c as any).accessRestricted ?? false,
       updatedAt: c.updatedAt instanceof Date ? c.updatedAt.toISOString() : (c.updatedAt ?? undefined),
     }))
 
@@ -113,6 +114,10 @@ export async function POST(req: Request) {
     return NextResponse.json({ error: 'Validation failed', details: parsed.error.flatten() }, { status: 400 })
   }
   const input = parsed.data
+  // Distinguish "caller did not send the field" (apply tenant default-restricted
+  // policy on create) from "caller explicitly chose false".
+  const accessRestrictedExplicit = body != null && typeof body === 'object'
+    && Object.prototype.hasOwnProperty.call(body, 'accessRestricted')
 
   const container = await createRequestContainer()
   const { resolve } = container
@@ -157,6 +162,7 @@ export async function POST(req: Request) {
   })
   if (guard.blockedResponse) return guard.blockedResponse
 
+  const isCreate = !ent
   if (!ent) ent = em.create(CustomEntity, { ...where, createdAt: new Date() })
   ent.label = input.label
   ent.description = input.description ?? null
@@ -164,6 +170,27 @@ export async function POST(req: Request) {
   ent.labelField = input.labelField ?? ent.labelField ?? null
   ent.defaultEditor = input.defaultEditor ?? ent.defaultEditor ?? null
   ent.showInSidebar = input.showInSidebar ?? ent.showInSidebar ?? false
+  // Never silently flip a security control on a partial upsert. `access_restricted`
+  // changes ONLY when the caller explicitly sends the field. On create without it,
+  // fall back to the tenant default-restricted policy; on update without it, keep
+  // the entity's current value (a metadata-only update must not un-restrict).
+  if (accessRestrictedExplicit) {
+    ent.accessRestricted = input.accessRestricted === true
+  } else if (isCreate) {
+    let policyDefault = false
+    try {
+      const moduleConfigService = resolve('moduleConfigService') as {
+        getValue: (m: string, n: string, o?: { defaultValue?: unknown; scope?: { tenantId?: string | null } }) => Promise<unknown>
+      }
+      policyDefault = (await moduleConfigService.getValue('entities', 'newEntitiesRestrictedByDefault', {
+        defaultValue: false,
+        scope: { tenantId: auth.tenantId ?? null },
+      })) === true
+    } catch {}
+    ent.accessRestricted = policyDefault
+  } else {
+    ent.accessRestricted = ent.accessRestricted ?? false
+  }
   ent.updatedAt = new Date()
   em.persist(ent)
   await em.flush()
@@ -229,6 +256,7 @@ const entitySummarySchema = z.object({
   labelField: z.string().optional(),
   defaultEditor: z.string().optional(),
   showInSidebar: z.boolean().optional(),
+  accessRestricted: z.boolean().optional(),
   updatedAt: z.string().optional(),
   count: z.number(),
 })

package/src/modules/entities/api/entity-settings.ts

@@ -0,0 +1,103 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
+import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+
+// Tenant-scoped policy: when true, new custom entities are created with
+// `access_restricted = true` unless the create request explicitly sets the flag.
+const CONFIG_MODULE = 'entities'
+const NEW_ENTITIES_RESTRICTED_KEY = 'newEntitiesRestrictedByDefault'
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['entities.definitions.view'] },
+  PUT: { requireAuth: true, requireFeatures: ['entities.definitions.manage'] },
+}
+
+type ModuleConfigServiceLike = {
+  getValue: (
+    moduleId: string,
+    name: string,
+    options?: { defaultValue?: unknown; scope?: { tenantId?: string | null } },
+  ) => Promise<unknown>
+  setValue: (
+    moduleId: string,
+    name: string,
+    value: unknown,
+    scope?: { tenantId?: string | null },
+  ) => Promise<unknown>
+}
+
+async function readPolicy(tenantId: string | null): Promise<boolean> {
+  try {
+    const { resolve } = await createRequestContainer()
+    const moduleConfigService = resolve('moduleConfigService') as ModuleConfigServiceLike
+    const value = await moduleConfigService.getValue(CONFIG_MODULE, NEW_ENTITIES_RESTRICTED_KEY, {
+      defaultValue: false,
+      scope: { tenantId },
+    })
+    return value === true
+  } catch {
+    return false
+  }
+}
+
+export async function GET(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  const newEntitiesRestrictedByDefault = await readPolicy(auth.tenantId ?? null)
+  return NextResponse.json({ newEntitiesRestrictedByDefault })
+}
+
+const putBodySchema = z.object({
+  newEntitiesRestrictedByDefault: z.boolean(),
+})
+
+export async function PUT(req: Request) {
+  const auth = await getAuthFromRequest(req)
+  if (!auth || !auth.tenantId) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+  let body: unknown
+  try { body = await req.json() } catch { return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 }) }
+  const parsed = putBodySchema.safeParse(body)
+  if (!parsed.success) {
+    return NextResponse.json({ error: 'Validation failed', details: parsed.error.flatten() }, { status: 400 })
+  }
+  const { resolve } = await createRequestContainer()
+  const moduleConfigService = resolve('moduleConfigService') as ModuleConfigServiceLike
+  await moduleConfigService.setValue(
+    CONFIG_MODULE,
+    NEW_ENTITIES_RESTRICTED_KEY,
+    parsed.data.newEntitiesRestrictedByDefault,
+    { tenantId: auth.tenantId ?? null },
+  )
+  return NextResponse.json({ ok: true, newEntitiesRestrictedByDefault: parsed.data.newEntitiesRestrictedByDefault })
+}
+
+const settingsResponseSchema = z.object({
+  newEntitiesRestrictedByDefault: z.boolean(),
+})
+
+export const openApi: OpenApiRouteDoc = {
+  tag: 'Entities',
+  summary: 'Custom entity workspace settings',
+  methods: {
+    GET: {
+      summary: 'Get custom entity settings',
+      description: 'Returns the tenant-scoped default-restricted policy for new custom entities.',
+      responses: [
+        { status: 200, description: 'Current settings', schema: settingsResponseSchema },
+        { status: 401, description: 'Missing authentication', schema: z.object({ error: z.string() }) },
+      ],
+    },
+    PUT: {
+      summary: 'Update custom entity settings',
+      description: 'Sets the tenant-scoped default-restricted policy for new custom entities.',
+      requestBody: { schema: putBodySchema },
+      responses: [
+        { status: 200, description: 'Updated settings', schema: z.object({ ok: z.boolean(), newEntitiesRestrictedByDefault: z.boolean() }) },
+        { status: 400, description: 'Invalid payload', schema: z.object({ error: z.string() }) },
+        { status: 401, description: 'Missing authentication', schema: z.object({ error: z.string() }) },
+      ],
+    },
+  },
+}

package/src/modules/entities/api/records.ts

@@ -20,29 +20,63 @@ import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('entities').child({ component: 'records' })
 
-let declaredCustomEntityIds: Set<string> | null = null
-function isDeclaredCustomEntity(entityId: string): boolean {
-  if (declaredCustomEntityIds === null) {
+let declaredCustomEntityRestricted: Map<string, boolean> | null = null
+function loadDeclaredCustomEntities(): Map<string, boolean> {
+  if (declaredCustomEntityRestricted === null) {
     try {
-      const mods = getModules() as Array<{ customEntities?: Array<{ id?: string }> }>
-      if (Array.isArray(mods) && mods.length) {
-        const ids = new Set<string>()
-        for (const mod of mods) {
-          for (const spec of mod?.customEntities ?? []) {
-            if (spec?.id) ids.add(spec.id)
-          }
+      const mods = getModules() as Array<{ customEntities?: Array<{ id?: string; accessRestricted?: boolean }> }>
+      const map = new Map<string, boolean>()
+      for (const mod of mods ?? []) {
+        for (const spec of mod?.customEntities ?? []) {
+          if (spec?.id) map.set(spec.id, spec.accessRestricted === true)
         }
-        declaredCustomEntityIds = ids
       }
+      // Cache even when empty so we don't rebuild on every request (and fall back
+      // to the DB lookup unnecessarily). Only a thrown getModules() leaves it null
+      // so a genuinely-uninitialized registry is retried.
+      declaredCustomEntityRestricted = map
     } catch {}
   }
-  return declaredCustomEntityIds?.has(entityId) ?? false
+  return declaredCustomEntityRestricted ?? new Map<string, boolean>()
+}
+function isDeclaredCustomEntity(entityId: string): boolean {
+  return loadDeclaredCustomEntities().has(entityId)
+}
+
+type RecordsEntityScope = { tenantId: string | null; organizationId: string | null }
+
+// Resolve the CustomEntity registration that applies to THIS caller, most-specific
+// first (org+tenant → tenant-global → instance-global), mirroring the overlay
+// precedence used by the entity-definitions list. Scoping matters because the
+// row's `access_restricted` flag is a security control: an unscoped lookup could
+// read another tenant's row for a colliding entityId (e.g. `user:vendors`) and
+// mis-decide the restriction. Returns null when the caller's scope has no row.
+async function findScopedCustomEntity(em: any, CustomEntity: any, entityId: string, scope: RecordsEntityScope) {
+  const { tenantId, organizationId } = scope
+  const candidates: Array<Record<string, unknown>> = [
+    { entityId, organizationId, tenantId },
+    { entityId, organizationId: null, tenantId },
+    { entityId, organizationId: null, tenantId: null },
+  ]
+  const seen = new Set<string>()
+  for (const where of candidates) {
+    const key = JSON.stringify(where)
+    if (seen.has(key)) continue
+    seen.add(key)
+    const row = await em.findOne(CustomEntity as any, where)
+    if (row) return row
+  }
+  return null
 }
 
 const CUSTOM_ENTITY_RECORD_RESOURCE_KIND = 'entities.record'
 
 type RecordsEntityKind = 'system' | 'custom' | 'unknown'
 
+// `restricted` is meaningful only when `kind === 'custom'`; it drives the
+// per-entity ACL gate in `assertEntityAclForRequest`.
+type RecordsEntityClassification = { kind: RecordsEntityKind; restricted: boolean }
+
 // This surface manages doc-storage records, which exist for CUSTOM entities only.
 // Module-declared ids backed by a registered ORM table are system entities — their
 // records live in their own module tables/APIs, and stray doc rows for them poisoned
@@ -50,18 +84,25 @@ type RecordsEntityKind = 'system' | 'custom' | 'unknown'
 // previous fallback that classified an entity by the mere presence of
 // `custom_entities_storage` rows is gone: within the allowed set, declaration (ce.ts)
 // or an active `custom_entities` registration is authoritative.
-async function classifyRecordsEntity(em: any, entityId: string): Promise<RecordsEntityKind> {
-  if (isOrmBackedSystemEntityId(em, entityId)) return 'system'
-  if (isDeclaredCustomEntity(entityId)) return 'custom'
+async function classifyRecordsEntity(em: any, entityId: string, scope: RecordsEntityScope): Promise<RecordsEntityClassification> {
+  if (isOrmBackedSystemEntityId(em, entityId)) return { kind: 'system', restricted: false }
+  const declared = loadDeclaredCustomEntities()
+  if (declared.has(entityId)) return { kind: 'custom', restricted: declared.get(entityId) === true }
   try {
     const { CustomEntity } = await import('../data/entities')
-    // Any registration row — active or soft-deleted — proves the id is a custom
-    // entity. Records persist beyond the definition's soft delete (TC-ENTITIES-006)
-    // and must stay readable/deletable, e.g. for the restore flow and cleanup.
-    const found = await em.findOne(CustomEntity as any, { entityId })
-    if (found) return 'custom'
+    // Restriction is decided from the row that applies to THIS caller's scope so
+    // a colliding entityId in another tenant can't flip the flag.
+    const scoped = await findScopedCustomEntity(em, CustomEntity, entityId, scope)
+    if (scoped) return { kind: 'custom', restricted: (scoped as any).accessRestricted === true }
+    // No in-scope registration: preserve the historical custom-vs-unknown
+    // classification (any registration row — active or soft-deleted — proves the
+    // id is custom; records persist beyond soft delete, TC-ENTITIES-006). A row
+    // outside the caller's scope never marks the entity restricted for them, and
+    // the record query is itself tenant/org-scoped, so this cannot leak data.
+    const anyRow = await em.findOne(CustomEntity as any, { entityId })
+    if (anyRow) return { kind: 'custom', restricted: false }
   } catch {}
-  return 'unknown'
+  return { kind: 'unknown', restricted: false }
 }
 
 function systemEntityRecordsRejection(entityId: string) {
@@ -171,10 +212,10 @@ export async function GET(req: Request) {
     // registered in `custom_entities`, so classification checks the declared registry plus
     // active registrations. System (table-backed) ids are rejected above; for the allowed
     // set `isCustomEntity` drives mapRow's cf_ stripping so the edit form reads back values.
-    const entityKind = await classifyRecordsEntity(em, entityId)
+    const { kind: entityKind, restricted: isRestricted } = await classifyRecordsEntity(em, entityId, { tenantId: auth.tenantId ?? null, organizationId: scope.selectedId ?? auth.orgId ?? null })
     if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
     const isCustomEntity = entityKind === 'custom'
-    await assertEntityAclForRequest({ auth, entityId, action: 'view', isCustomEntity, rbac })
+    await assertEntityAclForRequest({ auth, entityId, action: 'view', isCustomEntity, isRestricted, rbac })
     if (organizationIds && organizationIds.length === 0) {
       return NextResponse.json({ items: [], total: 0, page, pageSize, totalPages: 0 })
     }
@@ -395,10 +436,10 @@ export async function POST(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const entityKind = await classifyRecordsEntity(em, entityId)
+    const { kind: entityKind, restricted: isRestricted } = await classifyRecordsEntity(em, entityId, { tenantId: auth.tenantId ?? null, organizationId: scope.selectedId ?? auth.orgId ?? null })
     if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
     const isCustomEntity = entityKind === 'custom'
-    await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
+    await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, isRestricted, rbac })
     // Strip reserved record/system columns the edit form echoes back from the loaded record
     // (`id`, plus `updated_at`/`updatedAt` used for optimistic locking). They are not custom
     // fields; without this they validate as cf_id / cf_updated_at / cf_updatedAt and are
@@ -469,10 +510,10 @@ export async function PUT(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const entityKind = await classifyRecordsEntity(em, entityId)
+    const { kind: entityKind, restricted: isRestricted } = await classifyRecordsEntity(em, entityId, { tenantId: auth.tenantId ?? null, organizationId: scope.selectedId ?? auth.orgId ?? null })
     if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
     const isCustomEntity = entityKind === 'custom'
-    await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
+    await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, isRestricted, rbac })
     // Strip reserved record/system columns the edit form echoes back from the loaded record
     // (`id`, plus `updated_at`/`updatedAt` used for optimistic locking). They are not custom
     // fields; without this they validate as cf_id / cf_updated_at / cf_updatedAt and are
@@ -568,10 +609,10 @@ export async function DELETE(req: Request) {
     const scope = await resolveOrganizationScope({ em, rbac, auth, selectedId: getSelectedOrganizationFromRequest(req) })
     const targetOrgId = scope.selectedId ?? auth.orgId
     if (!targetOrgId) return NextResponse.json({ error: 'Organization context is required' }, { status: 400 })
-    const entityKind = await classifyRecordsEntity(em, entityId)
+    const { kind: entityKind, restricted: isRestricted } = await classifyRecordsEntity(em, entityId, { tenantId: auth.tenantId ?? null, organizationId: scope.selectedId ?? auth.orgId ?? null })
     if (entityKind === 'system') return systemEntityRecordsRejection(entityId)
     const isCustomEntity = entityKind === 'custom'
-    await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, rbac })
+    await assertEntityAclForRequest({ auth, entityId, action: 'manage', isCustomEntity, isRestricted, rbac })
 
     try {
       const currentUpdatedAt = await readCustomEntityRecordUpdatedAt(em, {

package/src/modules/entities/backend/entities/user/[entityId]/page.tsx

@@ -53,7 +53,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
   const [label, setLabel] = useState('')
   const [entitySource, setEntitySource] = useState<EntitySource>('custom')
   const [entityFormLoading, setEntityFormLoading] = useState(true)
-  const [entityInitial, setEntityInitial] = useState<{ label?: string; description?: string; labelField?: string; defaultEditor?: string; showInSidebar?: boolean; updatedAt?: string }>({})
+  const [entityInitial, setEntityInitial] = useState<{ label?: string; description?: string; labelField?: string; defaultEditor?: string; showInSidebar?: boolean; accessRestricted?: boolean; updatedAt?: string }>({})
   const [defs, setDefs] = useState<Def[]>([])
   const [defsVersion, setDefsVersion] = useState<string | null>(null)
   const [orderDirty, setOrderDirty] = useState(false)
@@ -180,6 +180,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
           const defaultEditorValue =
             typeof record?.defaultEditor === 'string' ? record.defaultEditor : ''
           const showInSidebarValue = record?.showInSidebar === true
+          const accessRestrictedValue = record?.accessRestricted === true
           const updatedAtValue =
             typeof record?.updatedAt === 'string' && record.updatedAt.length > 0 ? record.updatedAt : undefined
           setLabel(labelValue)
@@ -190,6 +191,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
             labelField: labelFieldValue,
             defaultEditor: defaultEditorValue,
             showInSidebar: showInSidebarValue,
+            accessRestricted: accessRestrictedValue,
             updatedAt: updatedAtValue,
           })
           setEntityFormLoading(false)
@@ -419,6 +421,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
       defaultEditor: z.union([z.enum(['markdown','simpleMarkdown','htmlRichText']).optional(), z.literal('')]).optional(),
       // Include showInSidebar so CrudForm doesn't strip it on submit
       showInSidebar: z.boolean().optional(),
+      accessRestricted: z.boolean().optional(),
     }) as z.ZodType<Record<string, unknown>>
 
   const metadataFieldsReadOnly = entitySource === 'code'
@@ -438,6 +441,12 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
       ],
     } as any,
     ...(entitySource === 'custom' ? [{ id: 'showInSidebar', label: t('entities.userEntities.form.showInSidebar.label', 'Show in sidebar'), type: 'checkbox' }] : []),
+    ...(entitySource === 'custom' ? [{
+      id: 'accessRestricted',
+      label: t('entities.userEntities.form.accessRestricted.label', 'Restrict record access'),
+      type: 'checkbox',
+      description: t('entities.userEntities.form.accessRestricted.help', 'Require an explicit per-entity permission to view or manage this entity’s records. Leave off to allow anyone with the general records permission.'),
+    }] : []),
   ]
   const renderFieldDefinitions = React.useCallback(() => (
       <FieldDefinitionsEditor
@@ -496,7 +505,7 @@ export default function EditDefinitionsPage({ params }: { params?: { entityId?:
   const definitionsGroup: CrudFormGroup = { id: 'definitions', title: t('entities.userEntities.edit.groups.definitions', 'Field Definitions'), column: 1, component: renderFieldDefinitions }
 
   const groups: CrudFormGroup[] = [
-    { id: 'settings', title: t('entities.userEntities.edit.groups.settings', 'Entity Settings'), column: 1, fields: entitySource === 'custom' ? ['label','description','defaultEditor','showInSidebar'] : ['label','description','defaultEditor'] },
+    { id: 'settings', title: t('entities.userEntities.edit.groups.settings', 'Entity Settings'), column: 1, fields: entitySource === 'custom' ? ['label','description','defaultEditor','showInSidebar','accessRestricted'] : ['label','description','defaultEditor'] },
     definitionsGroup,
   ]
 
@@ -673,7 +682,7 @@ export function buildEntityMetadataPayload(
   const partial = entitySource === 'custom'
     ? upsertCustomEntitySchema
         .pick({ label: true, description: true, labelField: true as any, defaultEditor: true as any })
-        .extend({ showInSidebar: z.boolean().optional() }) as unknown as z.ZodTypeAny
+        .extend({ showInSidebar: z.boolean().optional(), accessRestricted: z.boolean().optional() }) as unknown as z.ZodTypeAny
     : upsertCustomEntitySchema
         .pick({ label: true, description: true, defaultEditor: true as any }) as unknown as z.ZodTypeAny
   const normalized = {

package/src/modules/entities/backend/entities/user/create/page.tsx

@@ -9,6 +9,7 @@ import { upsertCustomEntitySchema } from '@open-mercato/core/modules/entities/da
 import { useRouter } from 'next/navigation'
 import { pushWithFlash } from '@open-mercato/ui/backend/utils/flash'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { LoadingMessage } from '@open-mercato/ui/backend/detail'
 
 const schema = upsertCustomEntitySchema
 
@@ -17,6 +18,21 @@ import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 export default function CreateEntityPage() {
   const t = useT()
   const router = useRouter()
+  // Pre-fill the restriction toggle from the tenant default-restricted policy so
+  // the form reflects the workspace posture; null while loading.
+  const [defaultRestricted, setDefaultRestricted] = React.useState<boolean | null>(null)
+  React.useEffect(() => {
+    let active = true
+    ;(async () => {
+      const data = await readApiResultOrThrow<{ newEntitiesRestrictedByDefault?: boolean }>(
+        '/api/entities/entity-settings',
+        undefined,
+        { errorMessage: '[internal] Failed to load entity settings', fallback: { newEntitiesRestrictedByDefault: false } },
+      ).catch(() => ({ newEntitiesRestrictedByDefault: false }))
+      if (active) setDefaultRestricted(data?.newEntitiesRestrictedByDefault === true)
+    })()
+    return () => { active = false }
+  }, [])
   const fields = React.useMemo<CrudField[]>(() => ([
     {
       id: 'entityId',
@@ -39,8 +55,24 @@ export default function CreateEntityPage() {
       ],
     } as unknown as CrudField,
     { id: 'showInSidebar', label: t('entities.userEntities.form.showInSidebar.label', 'Show in sidebar'), type: 'checkbox' } as CrudField,
+    {
+      id: 'accessRestricted',
+      label: t('entities.userEntities.form.accessRestricted.label', 'Restrict record access'),
+      type: 'checkbox',
+      description: t('entities.userEntities.form.accessRestricted.help', 'Require an explicit per-entity permission to view or manage this entity’s records. Leave off to allow anyone with the general records permission.'),
+    } as CrudField,
   ]), [t])
 
+  if (defaultRestricted === null) {
+    return (
+      <Page>
+        <PageBody>
+          <LoadingMessage label={t('entities.userEntities.form.loading', 'Loading…')} />
+        </PageBody>
+      </Page>
+    )
+  }
+
   return (
     <Page>
       <PageBody>
@@ -49,7 +81,7 @@ export default function CreateEntityPage() {
           backHref="/backend/entities/user"
           schema={schema}
           fields={fields}
-          initialValues={{ entityId: 'user:your_entity', label: '', showInSidebar: false }}
+          initialValues={{ entityId: 'user:your_entity', label: '', showInSidebar: false, accessRestricted: defaultRestricted }}
           submitLabel={t('entities.userEntities.form.submit', 'Create')}
           cancelHref="/backend/entities/user"
           onSubmit={async (vals) => {

package/src/modules/entities/data/entities.ts

@@ -136,6 +136,12 @@ export class CustomEntity {
   @Property({ name: 'show_in_sidebar', type: 'boolean', default: false })
   showInSidebar: boolean = false
 
+  // When true, records require an explicit per-entity ACL grant
+  // (entities.records.<entity_id>.view/.manage) beyond the coarse
+  // entities.records.* feature. Defaults to unrestricted for backward compat.
+  @Property({ name: 'access_restricted', type: 'boolean', default: false })
+  accessRestricted: boolean = false
+
   // Note: Per-field UI preferences (list visibility, filter visibility, form editability)
   // are stored in CustomFieldDef.configJson, not at entity level.
 

package/src/modules/entities/i18n/de.json

@@ -221,6 +221,8 @@
   "entities.userEntities.errors.entityIdRequired": "Entitäts-ID ist erforderlich",
   "entities.userEntities.errors.loadFailed": "Entitäten konnten nicht geladen werden",
   "entities.userEntities.flash.created": "Entität erstellt",
+  "entities.userEntities.form.accessRestricted.help": "Erfordert eine explizite entitätsspezifische Berechtigung zum Anzeigen oder Verwalten der Datensätze dieser Entität. Deaktiviert lassen, um allen Benutzern mit der allgemeinen Datensatzberechtigung Zugriff zu gewähren.",
+  "entities.userEntities.form.accessRestricted.label": "Datensatzzugriff einschränken",
   "entities.userEntities.form.defaultEditor.label": "Standardeditor (mehrzeilig)",
   "entities.userEntities.form.defaultEditor.options.default": "Standard (Markdown)",
   "entities.userEntities.form.defaultEditor.options.htmlRichText": "HTML-Rich-Text",
@@ -230,6 +232,7 @@
   "entities.userEntities.form.entityId.label": "Entitäts-ID",
   "entities.userEntities.form.entityId.placeholder": "module_name:entity_id",
   "entities.userEntities.form.label.label": "Bezeichnung",
+  "entities.userEntities.form.loading": "Wird geladen…",
   "entities.userEntities.form.showInSidebar.label": "In der Seitenleiste anzeigen",
   "entities.userEntities.form.submit": "Erstellen",
   "entities.userEntities.form.title": "Entität erstellen",

package/src/modules/entities/i18n/en.json

@@ -221,6 +221,8 @@
   "entities.userEntities.errors.entityIdRequired": "Entity ID is required",
   "entities.userEntities.errors.loadFailed": "Failed to load entities",
   "entities.userEntities.flash.created": "Entity created",
+  "entities.userEntities.form.accessRestricted.help": "Require an explicit per-entity permission to view or manage this entity’s records. Leave off to allow anyone with the general records permission.",
+  "entities.userEntities.form.accessRestricted.label": "Restrict record access",
   "entities.userEntities.form.defaultEditor.label": "Default Editor (multiline)",
   "entities.userEntities.form.defaultEditor.options.default": "Default (Markdown)",
   "entities.userEntities.form.defaultEditor.options.htmlRichText": "HTML Rich Text",
@@ -230,6 +232,7 @@
   "entities.userEntities.form.entityId.label": "Entity ID",
   "entities.userEntities.form.entityId.placeholder": "module_name:entity_id",
   "entities.userEntities.form.label.label": "Label",
+  "entities.userEntities.form.loading": "Loading…",
   "entities.userEntities.form.showInSidebar.label": "Show in sidebar",
   "entities.userEntities.form.submit": "Create",
   "entities.userEntities.form.title": "Create Entity",

package/src/modules/entities/i18n/es.json

@@ -221,6 +221,8 @@
   "entities.userEntities.errors.entityIdRequired": "El ID de la entidad es obligatorio",
   "entities.userEntities.errors.loadFailed": "No se pudieron cargar las entidades",
   "entities.userEntities.flash.created": "Entidad creada",
+  "entities.userEntities.form.accessRestricted.help": "Requiere un permiso explícito por entidad para ver o gestionar los registros de esta entidad. Déjalo desactivado para permitir el acceso a cualquiera con el permiso general de registros.",
+  "entities.userEntities.form.accessRestricted.label": "Restringir acceso a registros",
   "entities.userEntities.form.defaultEditor.label": "Editor predeterminado (multilínea)",
   "entities.userEntities.form.defaultEditor.options.default": "Predeterminado (Markdown)",
   "entities.userEntities.form.defaultEditor.options.htmlRichText": "HTML enriquecido",
@@ -230,6 +232,7 @@
   "entities.userEntities.form.entityId.label": "ID de la entidad",
   "entities.userEntities.form.entityId.placeholder": "nombre_modulo:id_entidad",
   "entities.userEntities.form.label.label": "Etiqueta",
+  "entities.userEntities.form.loading": "Cargando…",
   "entities.userEntities.form.showInSidebar.label": "Mostrar en la barra lateral",
   "entities.userEntities.form.submit": "Crear",
   "entities.userEntities.form.title": "Crear entidad",

package/src/modules/entities/i18n/pl.json

@@ -221,6 +221,8 @@
   "entities.userEntities.errors.entityIdRequired": "Identyfikator encji jest wymagany",
   "entities.userEntities.errors.loadFailed": "Nie udało się wczytać encji",
   "entities.userEntities.flash.created": "Encja została utworzona",
+  "entities.userEntities.form.accessRestricted.help": "Wymaga jawnego uprawnienia dla tej encji, aby przeglądać lub zarządzać jej rekordami. Pozostaw wyłączone, aby zezwolić na dostęp każdemu z ogólnym uprawnieniem do rekordów.",
+  "entities.userEntities.form.accessRestricted.label": "Ogranicz dostęp do rekordów",
   "entities.userEntities.form.defaultEditor.label": "Domyślny edytor (wiele linii)",
   "entities.userEntities.form.defaultEditor.options.default": "Domyślne (Markdown)",
   "entities.userEntities.form.defaultEditor.options.htmlRichText": "HTML Rich Text",
@@ -230,6 +232,7 @@
   "entities.userEntities.form.entityId.label": "Identyfikator encji",
   "entities.userEntities.form.entityId.placeholder": "module_name:entity_id",
   "entities.userEntities.form.label.label": "Etykieta",
+  "entities.userEntities.form.loading": "Ładowanie…",
   "entities.userEntities.form.showInSidebar.label": "Pokaż w panelu bocznym",
   "entities.userEntities.form.submit": "Utwórz",
   "entities.userEntities.form.title": "Utwórz encję",