@objectstack/rest 12.6.0 → 14.3.0

package/dist/index.d.cts

@@ -251,6 +251,10 @@ declare class RestServer {
     private i18nServiceProvider?;
     private analyticsServiceProvider?;
     private settingsServiceProvider?;
+    /** [ADR-0090] `security` service resolver — used by the
+     *  /security/suggested-bindings (D5/D9) and /security/explain (D6)
+     *  routes (plugin-security). */
+    private securityServiceProvider?;
     /** Sync probe: is a kernel service registered? Single-env path for nav
      *  capability gates (ADR-0057 D10) — resolveExecCtx sets no kernel in
      *  single-kernel deployments, so this prevents the gate failing open. */
@@ -262,7 +266,7 @@ declare class RestServer {
      * the durable source of truth a restarted/other node reads.
      */
     private readonly cancelledImportJobs;
-    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>, analyticsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, settingsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, serviceExistsProvider?: (name: string) => boolean);
+    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig, kernelManager?: RestKernelManager, envRegistry?: RestEnvRegistry, defaultEnvironmentIdProvider?: () => string | undefined, authServiceProvider?: (environmentId?: string) => Promise<any | undefined>, objectQLProvider?: (environmentId?: string) => Promise<any | undefined>, emailServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingServiceProvider?: (environmentId?: string) => Promise<any | undefined>, reportsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, approvalsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, sharingRulesServiceProvider?: (environmentId?: string) => Promise<any | undefined>, i18nServiceProvider?: (environmentId?: string) => Promise<any | undefined>, analyticsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, settingsServiceProvider?: (environmentId?: string) => Promise<any | undefined>, serviceExistsProvider?: (name: string) => boolean, securityServiceProvider?: (environmentId?: string) => Promise<any | undefined>);
     /**
      * Resolve the protocol for a given request. When `environmentId` is present
      * and a KernelManager is wired, fetch the per-project kernel's
@@ -350,6 +354,24 @@ declare class RestServer {
      * to the protocol layer (the SecurityPlugin treats undefined as anon).
      */
     private resolveExecCtx;
+    /**
+     * [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.
+     */
+    private resolveAudienceCaller;
+    /** Whether any of these books carries a `{ permissionSet }` audience. */
+    private static anyPermissionSetAudience;
+    /** Coerce a getMetaItems result (array | {items}) into an array. */
+    private static metaItemsArray;
+    /** Fetch every book of the environment, shaped for the audience resolver. */
+    private fetchAudienceBooks;
     /** Heavy path behind `resolveExecCtx` — resolve identity + RBAC/RLS + localization. */
     private computeExecCtx;
     /**
@@ -593,6 +615,26 @@ declare class RestServer {
      * `@objectstack/service-analytics` fails cleanly.
      */
     private registerAnalyticsEndpoints;
+    /**
+     * [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`).
+     */
+    private registerSecurityExplainEndpoints;
     private registerSharingEndpoints;
     /**
      * Register sharing-rule endpoints (M10.17). Mirrors the existing
@@ -607,6 +649,25 @@ declare class RestServer {
      * Returns 501 when no sharing-rule service is configured.
      */
     private registerSharingRuleEndpoints;
+    /**
+     * 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).
+     */
+    private registerSecurityEndpoints;
     /**
      * Register saved-report + scheduled-digest endpoints (M11.C16).
      *
@@ -682,4 +743,324 @@ interface RestApiPluginConfig {
  */
 declare function createRestApiPlugin(config?: RestApiPluginConfig): Plugin;
 
-export { type RestApiPluginConfig, RestServer, type RouteEntry, RouteGroupBuilder, RouteManager, createRestApiPlugin };
+/**
+ * Type-aware value formatting for the streaming data export route
+ * (`GET /data/:object/export`).
+ *
+ * The raw rows returned by `findData` carry *storage* values: lookup / user
+ * fields hold ids (or, when `$expand`-ed, nested records), select fields hold
+ * option codes, booleans hold true/false, dates hold ISO strings. None of those
+ * read well in a spreadsheet. These helpers turn each value into a human
+ * readable cell using the object's field metadata.
+ *
+ * Contract: when no field metadata is available (schema lookup failed or carried
+ * no fields) every helper is a pass-through, so the export stays byte-for-byte
+ * identical to the un-formatted behaviour.
+ */
+interface ExportFieldMeta {
+    name: string;
+    type?: string;
+    label?: string;
+    options?: Array<{
+        label?: string;
+        value?: unknown;
+        color?: string;
+    }>;
+    /** Target object for lookup / master_detail / user fields. */
+    reference?: string;
+    /** Field on the referenced record to show as its label. */
+    displayField?: string;
+}
+/**
+ * Build a field-name → metadata map from an object schema (best-effort).
+ *
+ * Accepts both shapes `fields` appears in across the stack: the runtime
+ * `ObjectSchema.fields` is a `Record<fieldName, FieldDefinition>` object map
+ * (the form served by the engine registry / `getMetaItem`), while some callers
+ * and fixtures hand back a plain `FieldDefinition[]` array. A field's name is
+ * taken from its own `name`, falling back to the map key.
+ */
+declare function buildFieldMetaMap(schema: unknown): Map<string, ExportFieldMeta>;
+
+/**
+ * Bulk-import request parsing — extracted verbatim from rest-server.ts
+ * (#2766 V2) so consumers outside the generic `/data/:object/import` routes
+ * (the identity import endpoint in plugin-auth) can accept byte-identical
+ * payloads (rows[]/csv/xlsxBase64, mapping in either shape, writeMode +
+ * matchFields) without re-implementing the parsers.
+ */
+
+/**
+ * Detect the `getMetaItem` response envelope (`{ type, name, item, lock, … }`)
+ * whose translatable metadata document is nested at `.item`. The cached read
+ * path and `getMetaItems` element shape hand back the already-unwrapped
+ * document instead, so translation helpers must distinguish the two: an
+ * envelope carries a nested `item` object alongside its own `type`/`name`,
+ * which a bare metadata document never does.
+ */
+declare function isMetaEnvelope(value: any): boolean;
+/**
+ * Minimal RFC-4180-style CSV parser used by the bulk-import endpoint
+ * (M10.9). Handles quoted fields (including embedded quotes via "" and
+ * embedded commas/newlines) and both CRLF and LF line endings.
+ *
+ * The first non-empty line is treated as the header row. Header names
+ * can be re-mapped to canonical field names via the optional `mapping`
+ * argument (e.g. `{ "First Name": "first_name" }`); unmapped headers
+ * pass through unchanged. Empty cells become empty strings.
+ *
+ * Kept dependency-free so REST stays runtime-portable (Hono / Express
+ * adapters both consume this without pulling a CSV lib transitively).
+ */
+declare function parseCsvToRows(csv: string, mapping?: Record<string, string>): Array<Record<string, any>>;
+/**
+ * Parse an .xlsx workbook (raw bytes) into row objects, mirroring
+ * {@link parseCsvToRows}: first non-empty row is the header, each subsequent row
+ * becomes `{ header→cell }` with the optional `mapping` renaming columns. Reads
+ * the named/indexed `sheet` when given, else the first worksheet. Dynamically
+ * imports ExcelJS (already a dependency of the export path) so CSV/JSON imports
+ * don't pay for it.
+ */
+declare function parseXlsxToRows(buffer: Buffer | ArrayBuffer, mapping?: Record<string, string>, sheet?: string | number): Promise<Array<Record<string, any>>>;
+/** Everything the import runner needs, parsed & validated from a request body. */
+interface PreparedImport {
+    rows: Array<Record<string, any>>;
+    metaMap: Map<string, ExportFieldMeta>;
+    writeMode: 'insert' | 'update' | 'upsert';
+    matchFields: string[];
+    dryRun: boolean;
+    runAutomations: boolean;
+    trimWhitespace: boolean;
+    nullValues?: string[];
+    createMissingOptions: boolean;
+    skipBlankMatchKey: boolean;
+}
+type PrepareImportResult = {
+    ok: true;
+    prepared: PreparedImport;
+} | {
+    ok: false;
+    status: number;
+    code: string;
+    error: string;
+};
+/**
+ * Parse & validate a bulk-import request body into a {@link PreparedImport}.
+ *
+ * Shared by the synchronous `POST /data/:object/import` route and the async
+ * import-job create route so both accept byte-identical payloads (writeMode +
+ * matchFields, mapping in either shape, rows[]/csv/xlsxBase64) and resolve the
+ * same field metadata. The only knob that differs is `maxRows` (5k sync vs
+ * 50k async). Returns a discriminated result; the caller maps `!ok` to an HTTP
+ * error using the returned status/code/error.
+ */
+declare function prepareImportRequest(body: any, opts: {
+    p: any;
+    objectName: string;
+    environmentId?: string;
+    maxRows: number;
+}): Promise<PrepareImportResult>;
+
+/**
+ * import-runner — the shared row-processing core for bulk import.
+ *
+ * Both the synchronous `POST /data/:object/import` route and the asynchronous
+ * import-job worker feed rows through {@link runImport}. Extracting the loop
+ * keeps the two paths byte-for-byte identical in coercion, upsert matching, and
+ * per-row reporting — the async worker only adds progress persistence and
+ * cancellation on top.
+ *
+ * Rows resolved to a CREATE are batched through `p.createManyData` (the
+ * engine's array-form `insert()` — one round-trip per batch, with transient
+ * retry and per-row degradation on a logical/validation failure) instead of
+ * one `p.createData` call per row — see framework#2678. A protocol that
+ * doesn't implement `createManyData` falls back to the original per-row
+ * `createData` path unchanged.
+ */
+type ImportAction = 'created' | 'updated' | 'skipped' | 'failed';
+interface ImportRowResult {
+    row: number;
+    ok: boolean;
+    action: ImportAction;
+    id?: string;
+    field?: string;
+    error?: string;
+    code?: string;
+}
+/** Running tallies handed to {@link RunImportOptions.onProgress}. */
+interface ImportProgress {
+    processed: number;
+    total: number;
+    created: number;
+    updated: number;
+    skipped: number;
+    errors: number;
+}
+/**
+ * Records exactly what a non-dry-run import changed, so the job can be undone:
+ * created records are deleted, and updated records have the touched fields
+ * restored to their pre-import values. Only the fields the import wrote are
+ * captured (keyed to `before`), keeping the log precise and bounded.
+ */
+interface ImportUndoLog {
+    /** Ids of records this import created (delete to undo). */
+    created: string[];
+    /** Per updated record: the touched fields' values *before* the import. */
+    updated: Array<{
+        id: string;
+        before: Record<string, any>;
+    }>;
+}
+interface ImportRunSummary extends ImportProgress {
+    ok: number;
+    results: ImportRowResult[];
+    cancelled: boolean;
+    /** Present only when `captureUndo` was set — the reversal instructions. */
+    undoLog?: ImportUndoLog;
+}
+/** Minimal protocol surface the runner needs (find / create / update). */
+interface ImportProtocolLike {
+    findData(args: any): Promise<any>;
+    createData(args: any): Promise<any>;
+    updateData(args: any): Promise<any>;
+    /**
+     * Optional bulk-create primitive. When present, `runImport` batches
+     * CREATE-resolved rows through it instead of one `createData` call per
+     * row — see framework#2678. Must resolve to `{ records: any[] }` with one
+     * record per input row, in the same order.
+     */
+    createManyData?(args: {
+        object: string;
+        records: any[];
+        context?: any;
+        environmentId?: string;
+    }): Promise<{
+        records: any[];
+    }>;
+}
+interface RunImportOptions {
+    /** Protocol/engine to read & write through. */
+    p: ImportProtocolLike;
+    objectName: string;
+    environmentId?: string;
+    /** Exec context threaded onto reads and (with automation toggle) writes. */
+    context?: any;
+    /** Already-mapped rows (source columns renamed to target fields). */
+    rows: Array<Record<string, any>>;
+    /** Field metadata for value coercion (name→id lookups, select codes, …). */
+    metaMap: Map<string, ExportFieldMeta>;
+    writeMode: 'insert' | 'update' | 'upsert';
+    matchFields: string[];
+    dryRun: boolean;
+    runAutomations: boolean;
+    trimWhitespace: boolean;
+    nullValues?: string[];
+    createMissingOptions: boolean;
+    skipBlankMatchKey: boolean;
+    /**
+     * Progress callback, invoked every {@link RunImportOptions.progressEvery}
+     * processed rows and once at the end. May be async; the runner awaits it so a
+     * DB write of progress completes before the next chunk.
+     */
+    onProgress?: (p: ImportProgress) => void | Promise<void>;
+    /**
+     * Rows between onProgress calls (default 200). Also the flush boundary for
+     * buffered creates — a batch never grows past this before being written,
+     * so progress numbers stay accurate at every reported checkpoint.
+     */
+    progressEvery?: number;
+    /**
+     * Cooperative cancellation. Checked at each progress boundary; when it returns
+     * truthy the runner stops and returns `cancelled: true` with partial results.
+     */
+    shouldCancel?: () => boolean | Promise<boolean>;
+    /**
+     * When true (and not a dry run), accumulate an {@link ImportUndoLog} so the
+     * import can be reverted later. Callers gate this on row count to bound the
+     * stored snapshot size.
+     */
+    captureUndo?: boolean;
+}
+declare function runImport(opts: RunImportOptions): Promise<ImportRunSummary>;
+
+/**
+ * Type-aware value *coercion* for the bulk-import route
+ * (`POST /data/:object/import`).
+ *
+ * This is the inverse of `export-format.ts`. A spreadsheet / CSV cell arrives as
+ * a raw string (or, for JSON payloads, an arbitrary primitive); the storage
+ * layer, on the other hand, expects *storage* values — booleans as real
+ * booleans, numbers as numbers, dates as ISO strings, select fields as their
+ * option **code** (not the human label), and lookup / user fields as the
+ * referenced record **id** (not its name). The engine deliberately does not
+ * coerce for storage (see `record-validator.ts`, which coerces only to *check*
+ * a value and then discards the coerced form), so import has to do it here.
+ *
+ * The accepted storage shapes below are dictated by what
+ * `validateFieldValue` in `packages/objectql` will accept:
+ *   - number / currency / percent / rating / slider → a finite `number`
+ *   - boolean / toggle                              → a real `boolean`
+ *   - date / datetime                               → an ISO-8601 string
+ *   - time                                          → `HH:MM` / `HH:MM:SS`
+ *   - select / radio                                → an option *value*
+ *   - multiselect / checkboxes / tags               → an array of option values
+ *   - lookup / master_detail / user / reference     → a record id (resolved async)
+ *
+ * Contract: when a field carries no usable metadata the value passes through
+ * untouched, so an import stays byte-identical to the pre-coercion behaviour.
+ */
+
+/**
+ * Structured outcome of a reference lookup. `id` set → a single record matched.
+ * `ambiguous` → the display value matched more than one record, so linking any
+ * one of them would be a guess the importer refuses to make. `matchedField`
+ * names the field the match came from (for diagnostics). An empty object means
+ * nothing matched. A bare `string | undefined` is still accepted from legacy
+ * resolvers and normalised to this shape.
+ */
+interface RefMatch {
+    id?: string;
+    ambiguous?: boolean;
+    matchedField?: string;
+}
+/**
+ * Resolve a reference field's display value (a name / email / id typed by the
+ * user) to the referenced record's id. Return `undefined` / `{}` when nothing
+ * matches (caller surfaces "not found"), a bare id string / `{ id }` on a unique
+ * hit, or `{ ambiguous: true }` when several records share the value. Legacy
+ * resolvers that return `string | undefined` keep working. Implementations are
+ * expected to cache — the same name shows up on many rows.
+ */
+type RefResolver = (referenceObject: string, displayValue: string, meta: ExportFieldMeta) => Promise<string | undefined | RefMatch>;
+interface CoerceContext {
+    /** Trim leading/trailing whitespace from string-ish cells (default true). */
+    trimWhitespace?: boolean;
+    /** Extra strings (besides `''`) treated as null, e.g. `['N/A', 'null']`. */
+    nullValues?: string[];
+    /**
+     * When a select/multiselect cell matches no known option, keep the raw value
+     * instead of failing. Note: the engine still validates option membership, so
+     * this only helps when the option is (or will be) present in the schema.
+     */
+    createMissingOptions?: boolean;
+    /** Async reference resolver (name/email/id → record id). Optional. */
+    resolveRef?: RefResolver;
+}
+/** A per-field coercion failure, shaped like the engine's validation errors. */
+interface FieldCoerceError {
+    field: string;
+    code: string;
+    message: string;
+}
+/**
+ * Coerce a whole raw row into a storage-ready record. Unknown columns (no
+ * matching field metadata) pass through untouched so ad-hoc / schemaless
+ * objects still import. Collects every field error rather than stopping at the
+ * first, so a UI can show all problems in a row at once.
+ */
+declare function coerceRow(rawRow: Record<string, unknown>, metaMap: Map<string, ExportFieldMeta>, ctx: CoerceContext): Promise<{
+    data: Record<string, unknown>;
+    errors: FieldCoerceError[];
+}>;
+
+export { type CoerceContext, type ExportFieldMeta, type ImportAction, type ImportProgress, type ImportProtocolLike, type ImportRowResult, type ImportRunSummary, type ImportUndoLog, type PrepareImportResult, type PreparedImport, type RefResolver, type RestApiPluginConfig, RestServer, type RouteEntry, RouteGroupBuilder, RouteManager, type RunImportOptions, buildFieldMetaMap, coerceRow, createRestApiPlugin, isMetaEnvelope, parseCsvToRows, parseXlsxToRows, prepareImportRequest, runImport };