@objectstack/rest 13.0.0 → 14.5.0

package/dist/index.cjs

@@ -33,7 +33,14 @@ __export(index_exports, {
   RestServer: () => RestServer,
   RouteGroupBuilder: () => RouteGroupBuilder,
   RouteManager: () => RouteManager,
-  createRestApiPlugin: () => createRestApiPlugin
+  buildFieldMetaMap: () => buildFieldMetaMap,
+  coerceRow: () => coerceRow,
+  createRestApiPlugin: () => createRestApiPlugin,
+  isMetaEnvelope: () => isMetaEnvelope,
+  parseCsvToRows: () => parseCsvToRows,
+  parseXlsxToRows: () => parseXlsxToRows,
+  prepareImportRequest: () => prepareImportRequest,
+  runImport: () => runImport
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -289,7 +296,14 @@ function buildFieldMetaMap(schema) {
       label: typeof f.label === "string" ? f.label : void 0,
       options: Array.isArray(f.options) ? f.options : void 0,
       reference: typeof f.reference === "string" ? f.reference : void 0,
-      displayField: typeof f.displayField === "string" ? f.displayField : void 0
+      displayField: typeof f.displayField === "string" ? f.displayField : void 0,
+      required: f.required === true,
+      system: f.system === true,
+      readonly: f.readonly === true,
+      // Mirror the engine's `applyFieldDefaults` gate (`f.defaultValue == null`
+      // ⇒ no default): any non-null default — literal, expression object, or the
+      // `current_user` token — counts as satisfying a required field.
+      hasDefault: f.defaultValue != null
     });
   }
   return map;
@@ -327,6 +341,22 @@ function optionLabel(value, options) {
   const hit = options.find((o) => o && o.value === value);
   return hit?.label ?? value;
 }
+function toArgb(color) {
+  if (typeof color !== "string") return void 0;
+  const hex = color.trim().replace(/^#/, "");
+  if (/^[0-9a-fA-F]{3}$/.test(hex)) {
+    const [r, g, b] = hex;
+    return `FF${r}${r}${g}${g}${b}${b}`.toUpperCase();
+  }
+  if (/^[0-9a-fA-F]{6}$/.test(hex)) return `FF${hex}`.toUpperCase();
+  return void 0;
+}
+function cellFontColor(value, meta) {
+  if (value === null || value === void 0) return void 0;
+  if (!meta || !meta.type || !OPTION_TYPES.has(meta.type) || !meta.options) return void 0;
+  const hit = meta.options.find((o) => o && o.value === value);
+  return toArgb(hit?.color);
+}
 function displayFromRecord(rec, displayField) {
   if (displayField && rec[displayField] != null) return String(rec[displayField]);
   for (const k of NAME_KEY_FALLBACKS) {
@@ -543,6 +573,27 @@ async function coerceFieldValue(raw, meta, ctx) {
   }
   return { value: trim && typeof raw === "string" ? raw.trim() : raw };
 }
+var REQUIRED_CHECK_SKIP = /* @__PURE__ */ new Set([
+  "id",
+  "created_at",
+  "created_by",
+  "updated_at",
+  "updated_by"
+]);
+function isBlankValue(v) {
+  return v === void 0 || v === null || typeof v === "string" && v.trim() === "";
+}
+function firstMissingRequiredField(data, metaMap) {
+  for (const meta of metaMap.values()) {
+    if (!meta.required) continue;
+    if (meta.system || meta.readonly) continue;
+    if (meta.hasDefault) continue;
+    if (meta.type === "autonumber") continue;
+    if (REQUIRED_CHECK_SKIP.has(meta.name)) continue;
+    if (isBlankValue(data[meta.name])) return meta.name;
+  }
+  return null;
+}
 async function coerceRow(rawRow, metaMap, ctx) {
   const data = {};
   const errors = [];
@@ -741,7 +792,11 @@ function runImport(opts) {
           if (!handled) {
             const willUpdate = existing && typeof existing === "object";
             const willCreate = !willUpdate && (writeMode === "insert" || writeMode === "upsert");
-            if (!willUpdate && !willCreate) {
+            const requiredMiss = willCreate && !runAutomations ? firstMissingRequiredField(data, metaMap) : null;
+            if (requiredMiss) {
+              errCount++;
+              results[i] = { row: rowNo, ok: false, action: "failed", field: requiredMiss, code: "required", error: `${requiredMiss} is required` };
+            } else if (!willUpdate && !willCreate) {
               skipped++;
               results[i] = { row: rowNo, ok: true, action: "skipped", code: "NO_MATCH" };
             } else if (dryRun) {
@@ -913,155 +968,10 @@ function applyMappingToRows(rows, artifact) {
   return { ok: true, rows: out };
 }
 
-// src/rest-server.ts
-var import_meta = {};
-var logError = (...args) => globalThis.console?.error(...args);
-var TRANSLATABLE_META_TYPES = /* @__PURE__ */ new Set(["view", "action", "object", "app", "dashboard"]);
+// src/import-prepare.ts
 function isMetaEnvelope(value) {
   return !!value && typeof value === "object" && typeof value.type === "string" && typeof value.name === "string" && value.item != null && typeof value.item === "object" && !Array.isArray(value.item);
 }
-function mapDataError(error, object) {
-  if (error?.code === "DELETE_RESTRICTED") {
-    return {
-      status: 409,
-      body: {
-        error: error?.message ?? "Cannot delete: dependent records exist",
-        code: "DELETE_RESTRICTED",
-        ...error?.dependentObject ? { dependentObject: error.dependentObject } : {},
-        ...typeof error?.dependentCount === "number" ? { dependentCount: error.dependentCount } : {},
-        ...object ? { object } : {}
-      }
-    };
-  }
-  if (error?.code === "CONCURRENT_UPDATE" || error?.name === "ConcurrentUpdateError") {
-    return {
-      status: 409,
-      body: {
-        error: error?.message ?? "Record was modified by another user",
-        code: "CONCURRENT_UPDATE",
-        ...error?.currentVersion ? { currentVersion: error.currentVersion } : {},
-        ...error?.currentRecord ? { currentRecord: error.currentRecord } : {},
-        ...object ? { object } : {}
-      }
-    };
-  }
-  if (error?.code === "VALIDATION_FAILED" || error?.name === "ValidationError") {
-    return {
-      status: 400,
-      body: {
-        error: error?.message ?? "Validation failed",
-        code: "VALIDATION_FAILED",
-        fields: Array.isArray(error?.fields) ? error.fields : [],
-        ...object ? { object } : {}
-      }
-    };
-  }
-  if (error?.code === "PERMISSION_DENIED" || error?.name === "PermissionDeniedError" || typeof error?.message === "string" && error.message.startsWith("[Security] Access denied")) {
-    return {
-      status: 403,
-      body: {
-        error: error?.message ?? "Permission denied",
-        code: "PERMISSION_DENIED",
-        ...object ? { object } : {}
-      }
-    };
-  }
-  const raw = String(error?.message ?? error ?? "");
-  const lower = raw.toLowerCase();
-  if (raw.includes("[EnvironmentKernelFactory]") && (lower.includes("missing database_url") || lower.includes("not found"))) {
-    const isProvisioning = lower.includes("status='provisioning'") || lower.includes("status='pending'");
-    const isFailed = lower.includes("status='failed'");
-    return {
-      status: isProvisioning ? 503 : isFailed ? 502 : 404,
-      body: {
-        error: raw,
-        code: isProvisioning ? "PROJECT_PROVISIONING" : isFailed ? "PROJECT_PROVISIONING_FAILED" : "PROJECT_NOT_FOUND"
-      }
-    };
-  }
-  if (error?.code === "RECORD_NOT_FOUND" || /^Record\s+\S+\s+not found in\s+\S+/i.test(raw)) {
-    return {
-      status: 404,
-      body: {
-        error: raw,
-        code: "RECORD_NOT_FOUND",
-        ...object ? { object } : {}
-      }
-    };
-  }
-  const unknownColumn = /has no column named\s+["'`]?([a-z0-9_]+)/i.exec(raw) || /no such column:\s*["'`]?([a-z0-9_.]+)/i.exec(raw) || /unknown column\s+["'`]([a-z0-9_]+)["'`]/i.exec(raw) || /column\s+["'`]([a-z0-9_]+)["'`]\s+of relation\s+\S+\s+does not exist/i.exec(raw);
-  if (unknownColumn) {
-    const field = unknownColumn[1]?.split(".").pop();
-    return {
-      status: 400,
-      body: {
-        error: field ? `Unknown field '${field}'${object ? ` on object '${object}'` : ""}` : "Request references a field that does not exist",
-        code: "INVALID_FIELD",
-        ...field ? { field } : {},
-        ...object ? { object } : {}
-      }
-    };
-  }
-  const notNull = /not null constraint failed:\s*\S*?\.([a-z0-9_]+)/i.exec(raw) || /null value in column\s+["'`]([a-z0-9_]+)["'`]/i.exec(raw) || /column\s+["'`]([a-z0-9_]+)["'`]\s+cannot be null/i.exec(raw);
-  if (notNull) {
-    const field = notNull[1];
-    return {
-      status: 400,
-      body: {
-        error: `${field} is required`,
-        code: "VALIDATION_FAILED",
-        fields: [{ field, code: "required", message: `${field} is required` }],
-        hint: `If '${field}' is optional in your object metadata, the database column is still NOT NULL \u2014 the physical schema has drifted from metadata. Run 'os migrate' to reconcile (or reset the dev database).`,
-        ...object ? { object } : {}
-      }
-    };
-  }
-  const looksLikeUnknownObject = lower.includes("no such table") || lower.includes("relation") && lower.includes("does not exist") || lower.includes("table not found") || lower.includes("unknown object") || lower.includes("object not found") || lower.includes("no driver available") || object !== void 0 && lower.includes(`'${object.toLowerCase()}'`) && lower.includes("not");
-  if (looksLikeUnknownObject) {
-    return {
-      status: 404,
-      body: {
-        error: object ? `Object '${object}' is not registered` : "Object not found",
-        code: "object_not_found",
-        object
-      }
-    };
-  }
-  const looksLikeSqlLeak = lower.includes("sqlite_") || lower.includes("sqlstate") || lower.startsWith("insert into ") || lower.startsWith("update ") || lower.startsWith("select ") || lower.startsWith("delete from ") || lower.includes("constraint failed") || lower.includes("unique constraint") || lower.includes("foreign key");
-  if (looksLikeSqlLeak) {
-    if (lower.includes("unique constraint") || lower.includes("unique violation")) {
-      return {
-        status: 409,
-        body: {
-          error: "A record with this value already exists",
-          code: "UNIQUE_VIOLATION",
-          ...object ? { object } : {}
-        }
-      };
-    }
-    return {
-      status: 500,
-      body: { error: "Internal data error", code: "DATABASE_ERROR" }
-    };
-  }
-  return { status: 400, body: { error: raw || "Bad request" } };
-}
-function sendError(res, error, object) {
-  if (typeof error?.status === "number" && error.status >= 400 && error.status < 600) {
-    const safeMsg = typeof error.message === "string" && error.message.length < 500 ? error.message : "Request failed";
-    res.status(error.status).json({
-      error: safeMsg,
-      ...error.code ? { code: error.code } : {},
-      ...Array.isArray(error.issues) ? { issues: error.issues } : {}
-    });
-    return;
-  }
-  const mapped = mapDataError(error, object);
-  res.status(mapped.status).json(mapped.body);
-}
-function isExpectedDataStatus(status) {
-  return status === 403 || status === 404 || status === 409 || status === 502 || status === 503;
-}
 function parseCsvToRows(csv, mapping = {}) {
   const text = csv.replace(/^\uFEFF/, "");
   const cells = [];
@@ -1280,6 +1190,163 @@ async function prepareImportRequest(body, opts) {
     }
   };
 }
+
+// src/rest-server.ts
+var import_meta = {};
+var logError = (...args) => globalThis.console?.error(...args);
+var TRANSLATABLE_META_TYPES = /* @__PURE__ */ new Set(["view", "action", "object", "app", "dashboard"]);
+function mapDataError(error, object) {
+  if (error?.code === "DELETE_RESTRICTED") {
+    return {
+      status: 409,
+      body: {
+        error: error?.message ?? "Cannot delete: dependent records exist",
+        code: "DELETE_RESTRICTED",
+        ...error?.dependentObject ? { dependentObject: error.dependentObject } : {},
+        ...typeof error?.dependentCount === "number" ? { dependentCount: error.dependentCount } : {},
+        ...object ? { object } : {}
+      }
+    };
+  }
+  if (error?.code === "CONCURRENT_UPDATE" || error?.name === "ConcurrentUpdateError") {
+    return {
+      status: 409,
+      body: {
+        error: error?.message ?? "Record was modified by another user",
+        code: "CONCURRENT_UPDATE",
+        ...error?.currentVersion ? { currentVersion: error.currentVersion } : {},
+        ...error?.currentRecord ? { currentRecord: error.currentRecord } : {},
+        ...object ? { object } : {}
+      }
+    };
+  }
+  if (error?.code === "VALIDATION_FAILED" || error?.name === "ValidationError") {
+    return {
+      status: 400,
+      body: {
+        error: error?.message ?? "Validation failed",
+        code: "VALIDATION_FAILED",
+        fields: Array.isArray(error?.fields) ? error.fields : [],
+        ...object ? { object } : {}
+      }
+    };
+  }
+  if (error?.code === "FEEDS_DISABLED" || error?.code === "FILES_DISABLED") {
+    return {
+      status: 403,
+      body: {
+        error: error?.message ?? "This capability is disabled for the target object",
+        code: error.code,
+        ...error?.object || object ? { object: error?.object ?? object } : {}
+      }
+    };
+  }
+  if (error?.code === "PERMISSION_DENIED" || error?.name === "PermissionDeniedError" || typeof error?.message === "string" && error.message.startsWith("[Security] Access denied")) {
+    return {
+      status: 403,
+      body: {
+        error: error?.message ?? "Permission denied",
+        code: "PERMISSION_DENIED",
+        ...object ? { object } : {}
+      }
+    };
+  }
+  const raw = String(error?.message ?? error ?? "");
+  const lower = raw.toLowerCase();
+  if (raw.includes("[EnvironmentKernelFactory]") && (lower.includes("missing database_url") || lower.includes("not found"))) {
+    const isProvisioning = lower.includes("status='provisioning'") || lower.includes("status='pending'");
+    const isFailed = lower.includes("status='failed'");
+    return {
+      status: isProvisioning ? 503 : isFailed ? 502 : 404,
+      body: {
+        error: raw,
+        code: isProvisioning ? "PROJECT_PROVISIONING" : isFailed ? "PROJECT_PROVISIONING_FAILED" : "PROJECT_NOT_FOUND"
+      }
+    };
+  }
+  if (error?.code === "RECORD_NOT_FOUND" || /^Record\s+\S+\s+not found in\s+\S+/i.test(raw)) {
+    return {
+      status: 404,
+      body: {
+        error: raw,
+        code: "RECORD_NOT_FOUND",
+        ...object ? { object } : {}
+      }
+    };
+  }
+  const unknownColumn = /has no column named\s+["'`]?([a-z0-9_]+)/i.exec(raw) || /no such column:\s*["'`]?([a-z0-9_.]+)/i.exec(raw) || /unknown column\s+["'`]([a-z0-9_]+)["'`]/i.exec(raw) || /column\s+["'`]([a-z0-9_]+)["'`]\s+of relation\s+\S+\s+does not exist/i.exec(raw);
+  if (unknownColumn) {
+    const field = unknownColumn[1]?.split(".").pop();
+    return {
+      status: 400,
+      body: {
+        error: field ? `Unknown field '${field}'${object ? ` on object '${object}'` : ""}` : "Request references a field that does not exist",
+        code: "INVALID_FIELD",
+        ...field ? { field } : {},
+        ...object ? { object } : {}
+      }
+    };
+  }
+  const notNull = /not null constraint failed:\s*\S*?\.([a-z0-9_]+)/i.exec(raw) || /null value in column\s+["'`]([a-z0-9_]+)["'`]/i.exec(raw) || /column\s+["'`]([a-z0-9_]+)["'`]\s+cannot be null/i.exec(raw);
+  if (notNull) {
+    const field = notNull[1];
+    return {
+      status: 400,
+      body: {
+        error: `${field} is required`,
+        code: "VALIDATION_FAILED",
+        fields: [{ field, code: "required", message: `${field} is required` }],
+        hint: `If '${field}' is optional in your object metadata, the database column is still NOT NULL \u2014 the physical schema has drifted from metadata. Run 'os migrate' to reconcile (or reset the dev database).`,
+        ...object ? { object } : {}
+      }
+    };
+  }
+  const looksLikeUnknownObject = lower.includes("no such table") || lower.includes("relation") && lower.includes("does not exist") || lower.includes("table not found") || lower.includes("unknown object") || lower.includes("object not found") || lower.includes("no driver available") || object !== void 0 && lower.includes(`'${object.toLowerCase()}'`) && lower.includes("not");
+  if (looksLikeUnknownObject) {
+    return {
+      status: 404,
+      body: {
+        error: object ? `Object '${object}' is not registered` : "Object not found",
+        code: "object_not_found",
+        object
+      }
+    };
+  }
+  const looksLikeSqlLeak = lower.includes("sqlite_") || lower.includes("sqlstate") || lower.startsWith("insert into ") || lower.startsWith("update ") || lower.startsWith("select ") || lower.startsWith("delete from ") || lower.includes("constraint failed") || lower.includes("unique constraint") || lower.includes("foreign key");
+  if (looksLikeSqlLeak) {
+    if (lower.includes("unique constraint") || lower.includes("unique violation")) {
+      return {
+        status: 409,
+        body: {
+          error: "A record with this value already exists",
+          code: "UNIQUE_VIOLATION",
+          ...object ? { object } : {}
+        }
+      };
+    }
+    return {
+      status: 500,
+      body: { error: "Internal data error", code: "DATABASE_ERROR" }
+    };
+  }
+  return { status: 400, body: { error: raw || "Bad request" } };
+}
+function sendError(res, error, object) {
+  if (typeof error?.status === "number" && error.status >= 400 && error.status < 600) {
+    const safeMsg = typeof error.message === "string" && error.message.length < 500 ? error.message : "Request failed";
+    res.status(error.status).json({
+      error: safeMsg,
+      ...error.code ? { code: error.code } : {},
+      ...Array.isArray(error.issues) ? { issues: error.issues } : {}
+    });
+    return;
+  }
+  const mapped = mapDataError(error, object);
+  res.status(mapped.status).json(mapped.body);
+}
+function isExpectedDataStatus(status) {
+  return status === 403 || status === 404 || status === 409 || status === 502 || status === 503;
+}
 var IMPORT_JOB_OBJECT = "sys_import_job";
 var IMPORT_JOB_MAX_ROWS = 5e4;
 var IMPORT_JOB_RESULTS_CAP = 500;
@@ -1384,7 +1451,7 @@ function rowsToCsv(fields, rows, includeHeader, metaMap) {
   }
   return lines.join("\r\n") + (lines.length > 0 ? "\r\n" : "");
 }
-async function createXlsxStream(res) {
+async function createXlsxStream(res, useStyles = false) {
   const { PassThrough } = await import("stream");
   const ExcelJS = (await import("exceljs")).default ?? await import("exceljs");
   const passthrough = new PassThrough();
@@ -1401,7 +1468,7 @@ async function createXlsxStream(res) {
     });
     passthrough.on("error", reject);
   });
-  const wb = new ExcelJS.stream.xlsx.WorkbookWriter({ stream: passthrough, useStyles: false });
+  const wb = new ExcelJS.stream.xlsx.WorkbookWriter({ stream: passthrough, useStyles });
   const ws = wb.addWorksheet("Export");
   return {
     ws,
@@ -1412,8 +1479,8 @@ async function createXlsxStream(res) {
     }
   };
 }
-var RestServer = class {
-  constructor(server, protocol, config = {}, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider, analyticsServiceProvider, settingsServiceProvider, serviceExistsProvider) {
+var RestServer = class _RestServer {
+  constructor(server, protocol, config = {}, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider, analyticsServiceProvider, settingsServiceProvider, serviceExistsProvider, securityServiceProvider) {
     /**
      * Short-TTL cache for `hostname → environmentId` (P1-4). `resolveByHostname`
      * is a control-plane lookup (typically a DB query) that otherwise runs on
@@ -1466,6 +1533,7 @@ var RestServer = class {
     this.analyticsServiceProvider = analyticsServiceProvider;
     this.settingsServiceProvider = settingsServiceProvider;
     this.serviceExistsProvider = serviceExistsProvider;
+    this.securityServiceProvider = securityServiceProvider;
   }
   /**
    * Resolve the protocol for a given request. When `environmentId` is present
@@ -1704,6 +1772,54 @@ var RestServer = class {
     perReq.set(key, pending);
     return pending;
   }
+  /**
+   * [ADR-0046 §6.7] The audience-evaluation view of the caller for book/doc
+   * gating. `permissionSets` resolves through the security service's
+   * `resolvePermissionSetNames` — the SAME resolution as data-plane
+   * enforcement (positions expanded, additive baseline), so the docs gate
+   * can never drift from it. `permissionSets` stays undefined when the
+   * service is absent or resolution fails; `audienceAllows` then DENIES
+   * permission-set-gated audiences (fail closed, ADR-0049). Resolution is
+   * skipped unless `needPermissionSets` — callers pass true only when a
+   * `{ permissionSet }` audience is actually in play.
+   */
+  async resolveAudienceCaller(environmentId, req, opts) {
+    const ctx = await this.resolveExecCtx(environmentId, req).catch(() => void 0);
+    const authenticated = !!ctx?.userId;
+    if (!authenticated || !opts.needPermissionSets || !this.securityServiceProvider) {
+      return { authenticated };
+    }
+    try {
+      const svc = await this.securityServiceProvider(environmentId);
+      if (!svc || typeof svc.resolvePermissionSetNames !== "function") return { authenticated };
+      const names = await svc.resolvePermissionSetNames(ctx);
+      return { authenticated, permissionSets: Array.isArray(names) ? names : [] };
+    } catch {
+      return { authenticated };
+    }
+  }
+  /** Whether any of these books carries a `{ permissionSet }` audience. */
+  static anyPermissionSetAudience(books) {
+    return books.some(
+      (b) => b && typeof b === "object" && b.audience && typeof b.audience === "object" && typeof b.audience.permissionSet === "string"
+    );
+  }
+  /** Coerce a getMetaItems result (array | {items}) into an array. */
+  static metaItemsArray(raw) {
+    if (Array.isArray(raw)) return raw;
+    if (raw && typeof raw === "object" && Array.isArray(raw.items)) return raw.items;
+    return [];
+  }
+  /** Fetch every book of the environment, shaped for the audience resolver. */
+  async fetchAudienceBooks(p, environmentId) {
+    const raw = await p.getMetaItems({
+      type: "book",
+      ...environmentId ? { environmentId } : {}
+    }).catch(() => []);
+    return _RestServer.metaItemsArray(raw).map(
+      (b) => b && typeof b === "object" ? { ...b, packageId: b._packageId } : b
+    );
+  }
   /** Heavy path behind `resolveExecCtx` — resolve identity + RBAC/RLS + localization. */
   async computeExecCtx(environmentId, req) {
     try {
@@ -2212,6 +2328,8 @@ var RestServer = class {
       this.registerReportsEndpoints(bp);
       this.registerApprovalsEndpoints(bp);
       this.registerAnalyticsEndpoints(bp);
+      this.registerSecurityEndpoints(bp);
+      this.registerSecurityExplainEndpoints(bp);
       this.registerDataActionEndpoints(bp);
       if (this.config.api.enableCrud) {
         this.registerCrudEndpoints(bp);
@@ -2424,9 +2542,49 @@ var RestServer = class {
     }
   }
   /**
-   * Register metadata endpoints
+   * Register the metadata routes behind the SAME `requireAuth` gate the
+   * `/data` routes use.
+   *
+   * `registerMetadataEndpoints` builds ~17 `/meta/*` routes but — unlike the
+   * `/data` handlers — never calls {@link enforceAuth}: its handlers assumed
+   * the `requireAuth` gate rejected anonymous callers "upstream", yet nothing
+   * upstream covers `/meta`, so on a `requireAuth` deployment an anonymous
+   * caller could read object / field schemas. On a tenant-less runtime host
+   * those are SYSTEM-object schemas and the host is publicly reachable — a
+   * real leak.
+   *
+   * Rather than add the gate to every handler (and have the next new route
+   * forget it — the exact failure mode that caused this), wrap the route
+   * registrar for the duration of registration so every meta route, present
+   * and future, inherits it. The check is a no-op when `requireAuth` is off
+   * (demo / single-tenant), so the previously-public metadata surface there
+   * is unchanged; an authenticated user passes exactly as on `/data`.
    */
   registerMetadataEndpoints(basePath) {
+    const realRouteManager = this.routeManager;
+    const guardedRouteManager = {
+      register: (entry) => {
+        const inner = entry.handler;
+        if (typeof inner !== "function") return realRouteManager.register(entry);
+        return realRouteManager.register({
+          ...entry,
+          handler: async (req, res) => {
+            const environmentId = req?.params?.environmentId;
+            const context = await this.resolveExecCtx(environmentId, req).catch(() => void 0);
+            if (this.enforceAuth(req, res, context)) return;
+            return inner(req, res);
+          }
+        });
+      }
+    };
+    this.routeManager = guardedRouteManager;
+    try {
+      this.registerMetadataEndpointsInner(basePath);
+    } finally {
+      this.routeManager = realRouteManager;
+    }
+  }
+  registerMetadataEndpointsInner(basePath) {
     const { metadata } = this.config;
     const metaPath = `${basePath}${metadata.prefix}`;
     const isScoped = basePath.includes("/environments/:environmentId");
@@ -2573,6 +2731,48 @@ var RestServer = class {
                 visible = Array.isArray(raw) ? filtered : { ...raw, items: filtered };
               }
             }
+            if (req.params.type === "book") {
+              const raw = visible;
+              const list = _RestServer.metaItemsArray(raw);
+              if (list.length > 0) {
+                const { audienceAllows } = await import("@objectstack/spec/system");
+                const caller = await this.resolveAudienceCaller(environmentId, req, {
+                  needPermissionSets: _RestServer.anyPermissionSetAudience(list)
+                });
+                const filtered = list.filter((b) => b && typeof b === "object" && audienceAllows(b.audience, caller));
+                visible = Array.isArray(raw) ? filtered : { ...raw, items: filtered };
+              }
+            }
+            if (req.params.type === "doc") {
+              const raw = visible;
+              const list = _RestServer.metaItemsArray(raw);
+              if (list.length > 0) {
+                const { audienceAllows, docAudienceAllows, resolveDocAudiences } = await import("@objectstack/spec/system");
+                const books = await this.fetchAudienceBooks(p, environmentId);
+                const caller = await this.resolveAudienceCaller(environmentId, req, {
+                  needPermissionSets: _RestServer.anyPermissionSetAudience(books)
+                });
+                let filtered;
+                if (caller.authenticated && !_RestServer.anyPermissionSetAudience(books)) {
+                  filtered = list;
+                } else {
+                  const corpus = list.filter((d) => d && typeof d === "object").map((d) => ({
+                    name: d.name,
+                    group: d.group,
+                    tags: d.tags,
+                    order: d.order,
+                    packageId: d._packageId
+                  }));
+                  const audiences = resolveDocAudiences(books, corpus);
+                  filtered = list.filter((d) => {
+                    if (!d || typeof d !== "object") return false;
+                    const eff = audiences.get(d.name);
+                    return eff ? docAudienceAllows(eff, caller) : audienceAllows("org", caller);
+                  });
+                }
+                visible = Array.isArray(raw) ? filtered : { ...raw, items: filtered };
+              }
+            }
             if (req.params.type === "doc") {
               const locale = this.extractLocale(req);
               const { resolveDocLocale } = await import("@objectstack/spec/system");
@@ -2646,7 +2846,7 @@ var RestServer = class {
             const prot = await this.resolveProtocol(environmentId, req);
             const locale = this.extractLocale(req);
             const packageId = req.query?.package || void 0;
-            const { resolveBookTree, deriveImplicitPackageBook, isPublicAudience, resolveDocLocale } = await import("@objectstack/spec/system");
+            const { resolveBookTree, deriveImplicitPackageBook, audienceAllows, resolveDocAudiences, docAudienceAllows, resolveDocLocale } = await import("@objectstack/spec/system");
             const norm = (raw) => Array.isArray(raw) ? raw : raw && Array.isArray(raw.items) ? raw.items : [];
             const books = norm(await prot.getMetaItems({
               type: "book",
@@ -2657,9 +2857,16 @@ var RestServer = class {
             if (!book) {
               book = deriveImplicitPackageBook(req.params.name, req.params.name);
             }
-            const ctx = await this.resolveExecCtx(environmentId, req).catch(() => void 0);
-            if (!ctx?.userId && !isPublicAudience(book.audience)) {
-              sendError(res, { code: "unauthorized", message: "This documentation requires sign-in", status: 401 });
+            const audienceBooks = books.map((b) => b && typeof b === "object" ? { ...b, packageId: b._packageId } : b);
+            const caller = await this.resolveAudienceCaller(environmentId, req, {
+              needPermissionSets: _RestServer.anyPermissionSetAudience([book, ...audienceBooks])
+            });
+            if (!audienceAllows(book.audience, caller)) {
+              if (!caller.authenticated) {
+                sendError(res, { code: "unauthorized", message: "This documentation requires sign-in", status: 401 });
+              } else {
+                sendError(res, { code: "PERMISSION_DENIED", message: "This documentation is limited to holders of a permission set you do not have", status: 403 });
+              }
               return;
             }
             const docs = norm(await prot.getMetaItems({
@@ -2676,6 +2883,14 @@ var RestServer = class {
               packageId: d._packageId
             }));
             const tree = resolveBookTree(book, docs, book._packageId);
+            const gatedTreePossible = !caller.authenticated || _RestServer.anyPermissionSetAudience(audienceBooks);
+            if (gatedTreePossible) {
+              const audiences = resolveDocAudiences(audienceBooks, docs);
+              tree.groups = tree.groups.map((g) => ({
+                ...g,
+                entries: g.entries.filter((e) => !e.doc || docAudienceAllows(audiences.get(e.doc), caller))
+              })).filter((g) => g.entries.some((e) => e.doc || e.href));
+            }
             res.json(tree);
           } catch (error) {
             logError("[REST] Unhandled error:", error);
@@ -2710,7 +2925,7 @@ var RestServer = class {
             const isDraftRead = typeof req.query?.state === "string" && req.query.state.toLowerCase() === "draft";
             const previewDrafts = typeof req.query?.preview === "string" && req.query.preview.toLowerCase() === "draft";
             const packageScoped = typeof req.query?.package === "string" && req.query.package.length > 0;
-            if (metadata.enableCache && p.getMetaItemCached && !isAppType && !isDraftRead && !previewDrafts && !packageScoped && req.params.type !== "doc") {
+            if (metadata.enableCache && p.getMetaItemCached && !isAppType && !isDraftRead && !previewDrafts && !packageScoped && req.params.type !== "doc" && req.params.type !== "book") {
               const cacheRequest = {
                 ifNoneMatch: req.headers["if-none-match"],
                 ifModifiedSince: req.headers["if-modified-since"]
@@ -2779,6 +2994,47 @@ var RestServer = class {
                 const serviceGate = registered ? (n) => registered.has(n) : void 0;
                 if (serviceGate) visible = this.filterDashboardForUser(visible, serviceGate);
               }
+              if ((req.params.type === "book" || req.params.type === "doc") && visible) {
+                const { audienceAllows, docAudienceAllows, resolveDocAudiences } = await import("@objectstack/spec/system");
+                const target = isMetaEnvelope(visible) ? visible.item : visible;
+                let caller;
+                let allowed;
+                if (req.params.type === "book") {
+                  caller = await this.resolveAudienceCaller(environmentId, req, {
+                    needPermissionSets: _RestServer.anyPermissionSetAudience([target])
+                  });
+                  allowed = audienceAllows(target?.audience, caller);
+                } else {
+                  const books = await this.fetchAudienceBooks(p, environmentId);
+                  caller = await this.resolveAudienceCaller(environmentId, req, {
+                    needPermissionSets: _RestServer.anyPermissionSetAudience(books)
+                  });
+                  if (caller.authenticated && !_RestServer.anyPermissionSetAudience(books)) {
+                    allowed = true;
+                  } else {
+                    const corpus = _RestServer.metaItemsArray(await p.getMetaItems({
+                      type: "doc",
+                      ...environmentId ? { environmentId } : {}
+                    }).catch(() => [])).filter((d) => d && typeof d === "object").map((d) => ({
+                      name: d.name,
+                      group: d.group,
+                      tags: d.tags,
+                      order: d.order,
+                      packageId: d._packageId
+                    }));
+                    const audiences = resolveDocAudiences(books, corpus);
+                    allowed = docAudienceAllows(audiences.get(target?.name), caller);
+                  }
+                }
+                if (!allowed) {
+                  if (!caller.authenticated) {
+                    sendError(res, { code: "unauthorized", message: "This documentation requires sign-in", status: 401 });
+                  } else {
+                    sendError(res, { code: "PERMISSION_DENIED", message: "This documentation is limited to holders of a permission set you do not have", status: 403 });
+                  }
+                  return;
+                }
+              }
               if (req.params.type === "doc" && visible) {
                 const locale = this.extractLocale(req);
                 const { resolveDocLocale } = await import("@objectstack/spec/system");
@@ -3779,9 +4035,11 @@ var RestServer = class {
           const includeHeader = String(q.header ?? "true").toLowerCase() !== "false";
           const HARD_CAP = 5e4;
           const MAX_CHUNK = 5e3;
+          const STYLE_ROW_CAP = 1e4;
           const requestedLimit = q.limit != null ? Math.max(1, Number(q.limit) || 0) : 1e4;
           const limit = Math.min(requestedLimit, HARD_CAP);
           const chunkSize = Math.min(MAX_CHUNK, Math.max(50, q.page != null ? Number(q.page) || 500 : 500));
+          const styled = format === "xlsx" && limit <= STYLE_ROW_CAP;
           let filter = void 0;
           if (typeof q.filter === "string" && q.filter.length > 0) {
             try {
@@ -3848,12 +4106,13 @@ var RestServer = class {
           }
           res.header("X-Export-Format", format);
           res.header("X-Export-Limit", String(limit));
+          if (format === "xlsx") res.header("X-Export-Styles", styled ? "applied" : "dropped");
           res.header("Cache-Control", "no-store");
           let exported = 0;
           let firstChunk = true;
           let skip = 0;
           if (format === "json") res.write("[");
-          const xlsx = format === "xlsx" ? await createXlsxStream(res) : null;
+          const xlsx = format === "xlsx" ? await createXlsxStream(res, styled) : null;
           while (exported < limit) {
             const take = Math.min(chunkSize, limit - exported);
             const findArgs = {
@@ -3881,8 +4140,16 @@ var RestServer = class {
               if (firstChunk && includeHeader) {
                 xlsx.ws.addRow((fields ?? []).map((f) => headerLabel(f, metaMap))).commit();
               }
+              const cols = fields ?? [];
               for (const row of rows) {
-                xlsx.ws.addRow(formatRowCells(row, fields ?? [], metaMap)).commit();
+                const r = xlsx.ws.addRow(formatRowCells(row, cols, metaMap));
+                if (styled) {
+                  cols.forEach((f, i) => {
+                    const argb = cellFontColor(row?.[f], metaMap.get(f));
+                    if (argb) r.getCell(i + 1).font = { color: { argb } };
+                  });
+                }
+                r.commit();
               }
             } else {
               for (let i = 0; i < rows.length; i++) {
@@ -4511,6 +4778,100 @@ var RestServer = class {
       metadata: { summary: "Run a semantic-layer dataset (preview/query)", tags: ["analytics"] }
     });
   }
+  /**
+   * [ADR-0090 D6] Access-explanation endpoint — the REST face of the
+   * explain engine (framework#2696).
+   *
+   *   GET  {basePath}/security/explain?object=…&operation=…&userId=…
+   *   POST {basePath}/security/explain   body: { object, operation, userId? }
+   *
+   * Delegates to the security service's `explain(request, callerContext)`
+   * (`SecurityPlugin.explainAccessForCaller`) — the same code paths the
+   * enforcement middleware runs, so the report is explained by
+   * construction. Caller authorization lives in the SERVICE, not here:
+   * explaining ANOTHER user requires `manage_users` or a delegated
+   * `adminScope` covering that user (D12); the service's
+   * `PermissionDeniedError` maps to 403. The route itself only insists on
+   * an authenticated caller (an access report is sensitive even about
+   * oneself, and the anonymous `guest` posture is not this endpoint's
+   * business) and returns 501 when no security service exposing `explain`
+   * is mounted (a deployment without `@objectstack/plugin-security`).
+   */
+  registerSecurityExplainEndpoints(basePath) {
+    const isScoped = basePath.includes("/environments/:environmentId");
+    const resolveService = async (environmentId, req) => {
+      try {
+        const envId = await this.resolveRequestEnvironmentId(environmentId, req);
+        if (envId && envId !== "platform" && this.kernelManager) {
+          const kernel = await this.kernelManager.getOrCreate(envId);
+          const svc = await kernel.getServiceAsync("security").catch(() => void 0);
+          if (svc) return svc;
+        }
+      } catch {
+      }
+      if (!this.securityServiceProvider) return void 0;
+      try {
+        return await this.securityServiceProvider(environmentId);
+      } catch {
+        return void 0;
+      }
+    };
+    const handler = async (req, res) => {
+      try {
+        const environmentId = isScoped ? req.params?.environmentId : void 0;
+        const context = await this.resolveExecCtx(environmentId, req);
+        if (this.enforceAuth(req, res, context)) return;
+        if (!context?.userId) {
+          return res.status(401).json({
+            code: "UNAUTHORIZED",
+            message: "The access-explanation endpoint requires an authenticated caller."
+          });
+        }
+        const svc = await resolveService(environmentId, req);
+        if (!svc || typeof svc.explain !== "function") {
+          return res.status(501).json({
+            code: "NOT_IMPLEMENTED",
+            message: "Access explanation is not available on this deployment (no security service with explain)."
+          });
+        }
+        const src = req.method === "GET" ? req.query ?? {} : req.body ?? {};
+        const { ExplainRequestSchema } = await import("@objectstack/spec/security");
+        const parsed = ExplainRequestSchema.safeParse({
+          object: src.object,
+          operation: src.operation ?? "read",
+          ...src.userId != null && src.userId !== "" ? { userId: src.userId } : {}
+        });
+        if (!parsed.success) {
+          return res.status(400).json({
+            code: "VALIDATION_FAILED",
+            message: "Invalid explain request \u2014 expected { object: string, operation: read|create|update|delete|transfer|restore|purge, userId?: string }.",
+            detail: String(parsed.error?.message ?? "").slice(0, 1e3)
+          });
+        }
+        const decision = await svc.explain(parsed.data, context);
+        res.json(decision);
+      } catch (error) {
+        const msg = String(error?.message ?? error ?? "");
+        if (error?.code === "PERMISSION_DENIED" || error?.name === "PermissionDeniedError" || msg.startsWith("[Security] Access denied")) {
+          return res.status(403).json({ code: "PERMISSION_DENIED", message: msg.slice(0, 1e3) });
+        }
+        logError("[REST] Security explain error:", error);
+        res.status(500).json({ code: "EXPLAIN_FAILED", error: msg.slice(0, 500) });
+      }
+    };
+    this.routeManager.register({
+      method: "GET",
+      path: `${basePath}/security/explain`,
+      handler,
+      metadata: { summary: "Explain why a principal can (or cannot) perform an operation on an object (ADR-0090 D6)", tags: ["security"] }
+    });
+    this.routeManager.register({
+      method: "POST",
+      path: `${basePath}/security/explain`,
+      handler,
+      metadata: { summary: "Explain why a principal can (or cannot) perform an operation on an object (ADR-0090 D6)", tags: ["security"] }
+    });
+  }
   registerSharingEndpoints(basePath) {
     const { crud } = this.config;
     const dataPath = `${basePath}${crud.dataPrefix}`;
@@ -4753,6 +5114,106 @@ var RestServer = class {
       metadata: { summary: "Re-evaluate a sharing rule and reconcile grants", tags: ["sharing"] }
     });
   }
+  /**
+   * Register the security admin endpoints (ADR-0090 D5/D9) — suggested
+   * audience bindings. A package permission set declaring `isDefault: true`
+   * is an install-time SUGGESTION to bind it to the `everyone` position;
+   * these routes surface pending suggestions and let a tenant admin resolve
+   * them. The `security` service (plugin-security) does the real gating:
+   * tenant-admin pre-check on all three, and confirm writes the binding
+   * with the caller's execution context so the audience-anchor and
+   * delegated-admin gates enforce it — never auto-bound, never system.
+   *
+   *   GET  {basePath}/security/suggested-bindings?status=&packageId=
+   *   POST {basePath}/security/suggested-bindings/:id/confirm
+   *   POST {basePath}/security/suggested-bindings/:id/dismiss
+   *
+   * Routes return 501 when the `security` service is not registered
+   * (deployment without plugin-security). Typed service errors carry their
+   * HTTP status (403 permission / 404 not found / 409 state).
+   */
+  registerSecurityEndpoints(basePath) {
+    const dataPath = basePath;
+    const isScoped = basePath.includes("/environments/:environmentId");
+    const resolveService = async (environmentId) => {
+      if (!this.securityServiceProvider) return void 0;
+      try {
+        const svc = await this.securityServiceProvider(environmentId);
+        return svc && typeof svc.listAudienceBindingSuggestions === "function" ? svc : void 0;
+      } catch {
+        return void 0;
+      }
+    };
+    const respond501 = (res) => res.status(501).json({
+      code: "NOT_IMPLEMENTED",
+      message: "Security service is not configured on this deployment"
+    });
+    const handleError = (err, res, defaultCode) => {
+      const status = typeof err?.statusCode === "number" ? err.statusCode : 500;
+      if (status !== 500) {
+        return res.status(status).json({ code: err?.code ?? defaultCode, error: String(err?.message ?? err) });
+      }
+      logError(`[REST] suggested-bindings ${defaultCode}:`, err);
+      return res.status(500).json({ code: defaultCode, error: String(err?.message ?? err).slice(0, 500) });
+    };
+    this.routeManager.register({
+      method: "GET",
+      path: `${dataPath}/security/suggested-bindings`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const svc = await resolveService(environmentId);
+          if (!svc) return respond501(res);
+          const result = await svc.listAudienceBindingSuggestions(context ?? {}, {
+            status: req.query?.status ? String(req.query.status) : void 0,
+            packageId: req.query?.packageId ? String(req.query.packageId) : void 0
+          });
+          res.json({ data: result });
+        } catch (err) {
+          handleError(err, res, "SUGGESTION_LIST_FAILED");
+        }
+      },
+      metadata: { summary: "List suggested audience bindings (ADR-0090 D5/D9)", tags: ["security"] }
+    });
+    this.routeManager.register({
+      method: "POST",
+      path: `${dataPath}/security/suggested-bindings/:id/confirm`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const svc = await resolveService(environmentId);
+          if (!svc) return respond501(res);
+          const result = await svc.confirmAudienceBindingSuggestion(context ?? {}, String(req.params.id));
+          res.json({ data: result });
+        } catch (err) {
+          handleError(err, res, "SUGGESTION_CONFIRM_FAILED");
+        }
+      },
+      metadata: { summary: "Confirm a suggested audience binding (creates the everyone/guest binding)", tags: ["security"] }
+    });
+    this.routeManager.register({
+      method: "POST",
+      path: `${dataPath}/security/suggested-bindings/:id/dismiss`,
+      handler: async (req, res) => {
+        try {
+          const environmentId = isScoped ? req.params?.environmentId : void 0;
+          const context = await this.resolveExecCtx(environmentId, req);
+          if (this.enforceAuth(req, res, context)) return;
+          const svc = await resolveService(environmentId);
+          if (!svc) return respond501(res);
+          const result = await svc.dismissAudienceBindingSuggestion(context ?? {}, String(req.params.id));
+          res.json({ data: result });
+        } catch (err) {
+          handleError(err, res, "SUGGESTION_DISMISS_FAILED");
+        }
+      },
+      metadata: { summary: "Dismiss a suggested audience binding", tags: ["security"] }
+    });
+  }
   /**
    * Register saved-report + scheduled-digest endpoints (M11.C16).
    *
@@ -5550,6 +6011,20 @@ function registerPackageRoutes(server, packageService, basePath = "/api/v1", opt
     try {
       const packageId = req.params.id;
       const version = req.query?.version;
+      if (!version && typeof options.protocol?.deletePackage === "function") {
+        const result2 = await options.protocol.deletePackage({ packageId });
+        if (result2.failedCount === 0) {
+          res.json({
+            success: true,
+            message: `Deleted ${packageId}`,
+            deletedCount: result2.deletedCount,
+            cleanups: result2.cleanups
+          });
+          return;
+        }
+        res.status(400).json({ success: false, failed: result2.failed, cleanups: result2.cleanups });
+        return;
+      }
       const result = await packageService.delete(packageId, version);
       if (result.success) {
         res.json({
@@ -5749,6 +6224,13 @@ function createRestApiPlugin(config = {}) {
           return void 0;
         }
       };
+      const securityServiceProvider = async (_environmentId) => {
+        try {
+          return ctx.getService("security");
+        } catch {
+          return void 0;
+        }
+      };
       if (!server) {
         ctx.logger.warn(`RestApiPlugin: HTTP Server service '${serverService}' not found. REST routes skipped.`);
         return;
@@ -5766,7 +6248,7 @@ function createRestApiPlugin(config = {}) {
         }
       };
       try {
-        const restServer = new RestServer(server, protocol, config.api, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider, analyticsServiceProvider, settingsServiceProvider, serviceExistsProvider);
+        const restServer = new RestServer(server, protocol, config.api, kernelManager, envRegistry, defaultEnvironmentIdProvider, authServiceProvider, objectQLProvider, emailServiceProvider, sharingServiceProvider, reportsServiceProvider, approvalsServiceProvider, sharingRulesServiceProvider, i18nServiceProvider, analyticsServiceProvider, settingsServiceProvider, serviceExistsProvider, securityServiceProvider);
         restServer.registerRoutes();
         ctx.logger.info("REST API successfully registered");
         if (config.api?.api?.requireAuth === false) {
@@ -5822,6 +6304,13 @@ function createRestApiPlugin(config = {}) {
   RestServer,
   RouteGroupBuilder,
   RouteManager,
-  createRestApiPlugin
+  buildFieldMetaMap,
+  coerceRow,
+  createRestApiPlugin,
+  isMetaEnvelope,
+  parseCsvToRows,
+  parseXlsxToRows,
+  prepareImportRequest,
+  runImport
 });
 //# sourceMappingURL=index.cjs.map