@rebasepro/server 0.22.0 → 0.24.0

package/dist/api/logs-routes.d.ts

@@ -44,6 +44,15 @@ declare class LogRingBuffer {
     getLatest(count?: number): LogEntry[];
 }
 export declare const logBuffer: LogRingBuffer;
+/**
+ * Which process this log belongs to.
+ *
+ * The ring is this process's memory, and nothing gathers the rings of a
+ * deployment's other replicas or of its split runtime roles. So a reader is
+ * told whose log it is: `HOSTNAME` is the pod name on Kubernetes and the
+ * container id under Docker; the pid tells two local processes apart.
+ */
+export declare function logInstanceName(): string;
 /** Add a log entry */
 export declare function addLog(level: LogEntry["level"], source: LogEntry["source"], message: string, metadata?: Record<string, unknown>): void;
 export interface LogMiddlewareOptions {
@@ -55,7 +64,25 @@ export interface LogMiddlewareOptions {
      * server it is also the thing evicting real entries out of the ring.
      */
     ignorePaths?: string[];
+    /**
+     * Where the API is mounted (`/api`). The segment after it names the
+     * subsystem a request is filed under — see {@link sourceForRequestPath}.
+     * Unset, the first segment of the path is read.
+     */
+    basePath?: string;
 }
+/**
+ * The `source` of a request entry: the subsystem its path addresses.
+ *
+ * `/api/auth/*` and the MCP authorization server under `/api/oauth/*` are
+ * `auth`, `/api/storage/*` is `storage`, and everything else is `api`. The
+ * Logs Explorer's Source filter matches this field, so a sign-in filed as
+ * `api` was invisible under Auth. The realtime socket is not an HTTP request
+ * and is not recorded here.
+ *
+ * Exported for its test.
+ */
+export declare function sourceForRequestPath(path: string, basePath?: string): LogEntry["source"];
 /** Hono middleware to log API requests */
 export declare function logMiddleware(options?: LogMiddlewareOptions): MiddlewareHandler<HonoEnv>;
 /**
@@ -79,6 +106,17 @@ export interface LogStreamTiming {
     heartbeatMs?: number;
     maxPending?: number;
 }
-export declare function createLogsRoutes(timing?: LogStreamTiming): Hono<HonoEnv>;
+/** What ends the stream from the server's side. */
+export interface LogsRoutesOptions {
+    /**
+     * Aborted when the backend shuts down. Every open stream ends then, rather
+     * than when its client happens to leave: `server.close()` waits on every
+     * open connection, so one Studio → Logs tab held a SIGTERM for the whole
+     * force timeout — longer than Cloud Run's or `docker stop`'s grace period,
+     * which killed the process before the pool was closed.
+     */
+    closeSignal?: AbortSignal;
+}
+export declare function createLogsRoutes(timing?: LogStreamTiming, options?: LogsRoutesOptions): Hono<HonoEnv>;
 declare const _default: Hono<HonoEnv, import("hono/types").BlankSchema, "/">;
 export default _default;

package/dist/api/openapi-generator.d.ts

@@ -28,3 +28,20 @@ export interface OpenApiGeneratorOptions {
     };
 }
 export declare function generateOpenApiSpec(collections: CollectionConfig[], options?: OpenApiGeneratorOptions): Record<string, unknown>;
+/**
+ * Build the component schema for a collection (output / read shape).
+ *
+ * Every declared property except the ones {@link isDocumentedProperty} rules
+ * out, plus the foreign keys and relations {@link emitRelationProperties} adds.
+ */
+export declare function buildCollectionSchema(collection: CollectionConfig, registeredSchemas: ReadonlySet<string>): Record<string, unknown>;
+/**
+ * Build an input schema (for POST/PUT) — excludes auto-generated fields.
+ *
+ * `excludeFromApi` columns are left out too, and the server now agrees: a write
+ * naming one is refused (`write-validation.ts`), which is what the flag's name
+ * and the generated SDK's own documentation always said. This comment used to
+ * record that such a write was "still accepted" — the document was right and
+ * the server was the thing that had not caught up.
+ */
+export declare function buildCollectionInputSchema(collection: CollectionConfig): Record<string, unknown>;

package/dist/api/rest/api-generator.d.ts

@@ -1,7 +1,32 @@
 import { Hono } from "hono";
 import { AuthAdapter, DataDriver, CollectionConfig } from "@rebasepro/types";
-import { HonoEnv } from "../types.js";
+import { QueryOptions, HonoEnv } from "../types.js";
 import { type ListLimitOptions } from "./query-parser.js";
+/**
+ * The row a single-row write addresses, as its route found it.
+ *
+ * `/comments/7` and `/posts/1/comments/7` address the same kind of row — a row
+ * of `comments` — two ways, and a write to it is one operation whichever way
+ * it arrived: the same body checks, the same `If-Match`, the same
+ * `Idempotency-Key`, the same answer. It was two pipelines, and the nested one
+ * re-listed two of the root's checks by hand and skipped the rest.
+ */
+export interface RowAddress {
+    /** The collection the row belongs to: what a body is checked against and an `ETag` computed for. */
+    collection: CollectionConfig;
+    /**
+     * The path the driver reads and writes at: the collection's own, or a
+     * nested one, which the driver resolves and scopes to its parent row.
+     */
+    path: string;
+    /**
+     * Handed to the driver beside `path`. Unset for a nested path, whose
+     * collection the driver resolves from the path itself.
+     */
+    driverCollection?: CollectionConfig;
+    /** What a 404 calls the address. */
+    name: string;
+}
 /**
  * Lightweight REST API generator that leverages existing Rebase DataDriver.
  * Supports `include` query parameter for eager-loading relations via Drizzle.
@@ -113,34 +138,64 @@ export declare class RestApiGenerator {
      */
     private createUnmatchedRoute;
     /**
-     * Check API key permissions for a collection operation.
-     * Throws 403 if the key doesn't have the required permission.
-     * No-ops if the request is not authenticated via an API key.
+     * Check a narrowed credential's data scope for a collection operation:
+     * `data:<operation>` on the collection, or unqualified.
+     *
+     * Throws 403 when it is missing. A person's own session holds the whole
+     * data plane — their rows are RLS's to decide — so this only ever refuses
+     * an API key or a token.
      */
     private enforceApiKeyPermission;
     /**
-     * API key permission check for nested paths. The operation targets the
-     * LAST collection in the path (e.g. "posts" for /authors/1/posts), so
-     * that is the slug the key must hold permission for — checking the
-     * parent instead would let a key scoped to "authors" write "posts".
-     * `parseSubPath` always yields a collectionPath ending in a collection
-     * slug, never an id.
+     * Data-scope check for nested paths.
+     *
+     * The operation lands on the collection the path addresses — the target
+     * of its last relation — so that is the collection the key must hold the
+     * route's operation for; checking only the parent would let a key scoped
+     * to `authors` write `posts`. The *collection*, not the path segment: a
+     * relation's name is not its target's slug, and a key for `notes` read
+     * `internal_notes` through `projects/1/notes` because the check read the
+     * name off the URL.
+     *
+     * Every collection the path passes through is addressed as well — "the
+     * posts of author 1" goes through a row of `authors` — so the key must be
+     * able to read each of them.
      */
     private enforceSubcollectionApiKeyPermission;
     /**
-     * The collection a nested path writes into — the target of the relation its
-     * last segment names.
+     * The collection a path's first segment names.
+     *
+     * By the rule the driver's registry applies (`CollectionRegistry.get`),
+     * because the driver is what a nested path is forwarded to: the slug, then
+     * the slug written in kebab case — URLs are — then the table name. Matching
+     * the slug alone left the other two spellings resolving in the driver and
+     * in nothing here, so a nested request spelled either way was checked
+     * against no collection at all.
+     */
+    private collectionNamed;
+    /**
+     * Walk a nested path to the collection it addresses — the target of the
+     * relation its last segment names.
      *
-     * Needed so a nested write can be checked against a schema at all. Without
-     * it these routes skipped `assertKnownWriteFields` entirely, which is why a
-     * typo `POST /posts` rejected with a 400 while the same typo on
-     * `POST /authors/1/posts` was dropped from the statement and answered 201.
+     * Needed so a nested request can be checked against a schema at all: the
+     * fields a body may write and a query may read are the target's. A path
+     * that names nothing is a 404 here, before anything else happens. This
+     * used to return `undefined` instead and leave the refusal to the driver,
+     * and every check on these routes was written `if (target) …` — so a path
+     * the driver could resolve and this walk could not was a request with no
+     * checks on it, rather than a refused one.
      *
-     * Returns `undefined` rather than throwing when the path cannot be walked:
-     * the driver raises the authoritative error a moment later, and duplicating
-     * it here would report a resolution failure as a validation failure.
+     * The path handed back is spelled with the root's slug, which is what
+     * makes the two agree: whatever spelling arrived, the driver is asked about
+     * the collection this route checked the request against.
      */
-    private resolveNestedWriteCollection;
+    private resolveNestedPath;
+    /**
+     * Refuse a write through `nested` that sets a relation this caller may not
+     * write — the parent's relation, or the parent's key on the child. See
+     * {@link assertNestedWriteAllowed}; the socket asks it the same question.
+     */
+    private assertNestedRelationWritable;
     /**
      * `PATCH <collection>/<id>/<relation>/<targetId>` with a `_pivot` body: set
      * the columns that one many-to-many link carries.
@@ -160,15 +215,30 @@ export declare class RestApiGenerator {
      */
     private updateRelationPivotFromBody;
     /**
-     * The synthetic collection standing in for the junction a nested path's last
-     * hop reaches through, or `undefined` when that hop is not a `manyToMany`
-     * carrying `through.properties`.
+     * Updates to rows of the auth collection, checked and put in stored form
+     * by the auth adapter — `AuthAdapter.prepareUserUpdates`. Those rows are
+     * the users, so an update is user administration and holds to what
+     * `/admin/users` holds to: the last administrator stays one, an email is
+     * stored the way sign-in looks it up. Any other collection's values, and
+     * an adapter with no such step, pass through unchanged.
+     */
+    private prepareUserUpdates;
+    /**
+     * Delete rows of the auth collection as user administration: the adapter's
+     * checks and `beforeUserDelete` before (either may refuse), its session
+     * cleanup and `afterUserDelete` after. See {@link prepareUserUpdates}.
+     */
+    private deletingUsers;
+    /**
+     * `POST /users/bulk`: every row a user creation, the rows written as one
+     * transaction, the invitations sent once it has committed.
      *
-     * Built from the relation rather than by walking every collection: the same
-     * `getJunctionConfigForRelation` the schema planner and the driver use, so
-     * the shape validated here is the shape the columns were emitted from.
+     * Answered in full whatever `Prefer` says, and never replayed from the
+     * idempotency store, as `POST /users` is: the answer can carry temporary
+     * passwords, which are shown once. Dropped from a minimal answer they are
+     * gone, and handed out again on a replayed key they are disclosed.
      */
-    private resolveJunctionCollection;
+    private createUsers;
     /**
      * Get the request-scoped driver. Throws if none is set — never falls
      * back to the unscoped `this.driver` to avoid bypassing RLS/auth.
@@ -199,16 +269,41 @@ export declare class RestApiGenerator {
      */
     private runIdempotent;
     /**
-     * The row as the read routes serve it, for hashing into an `ETag`.
+     * The row an `ETag` is hashed from: the REST read of it, with no
+     * `?fields=` projection and no `?include=`.
+     *
+     * The read routes and the write routes both take their tag from here, so a
+     * tag a `GET` handed out and the tag a write compares it against are
+     * hashes of one rendering of the row. The write routes' own existence read
+     * is not that rendering, not even for its version column: `driver.fetchOne`
+     * returns the admin view model, where a date is a `{ __type: "date" }`
+     * envelope rather than the ISO string the REST row carries. Hashing it
+     * matched no tag any read ever handed out, so every conditional write to a
+     * collection with an `on_update` date was a 412.
+     *
+     * A driver without a REST read serves `GET /:id` from `fetchOne` too, so
+     * there the row already read is the rendering to hash.
+     *
+     * @param withDeleted how the row was read — a purge reads a trashed row,
+     *   and a tag compared against a read that hides it compares against
+     *   nothing.
+     */
+    static rowForETag(driver: DataDriver, address: RowAddress, id: string, alreadyRead: Record<string, unknown> | undefined, withDeleted?: QueryOptions["withDeleted"]): Promise<Record<string, unknown> | undefined>;
+    /**
+     * `GET /:id`, at a row's own address or through a parent: the row as the
+     * query asked for it, and the `ETag` naming its version.
      *
-     * A tag derived from a version column is the same whichever read produced
-     * the row, so nothing extra is fetched for it. The fallback hashes the row
-     * itself, and there the *shape* matters: `GET /:id` serves the REST walk
-     * while the write routes read through `driver.fetchOne` (the admin view
-     * model), so hashing whichever one happened to be in hand would give the
-     * same row two different tags and make every `If-Match` a coin toss.
+     * The tag names the row, not the read. `?fields=` and `?include=` change
+     * what the response carries, and hashing what they produced gave one row a
+     * different tag for every way of reading it — none of them the tag a write
+     * computes, so the `If-Match` of any caller that read a projection or a
+     * relation was a 412. A narrowed read therefore takes its tag from
+     * {@link rowForETag}, the read the write routes make.
      */
-    private rowForETag;
+    static readRow(driver: DataDriver, address: RowAddress, id: string, queryOptions: QueryOptions): Promise<{
+        row: Record<string, unknown>;
+        etag: string | undefined;
+    } | undefined>;
     /**
      * Answer a bulk write, honouring `Prefer: return=minimal`.
      *
@@ -218,6 +313,28 @@ export declare class RestApiGenerator {
      * the count never has to ask for the rows.
      */
     private respondBulk;
+    /**
+     * Create one row: `POST /<collection>`, and the same create reached through
+     * a parent, `POST /<parent>/<id>/<relation>`.
+     *
+     * Errors from here are deliberately not re-classified. This layer cannot
+     * tell a constraint violation from an unreachable database, and it used to
+     * call both `BAD_REQUEST` — a claim that the caller sent something wrong and
+     * should not retry. The driver holds the SQLSTATE and raises an `ApiError`
+     * for what is genuinely the request's fault; anything still unclassified
+     * here is ours, and that is a 500.
+     */
+    private createRow;
+    /**
+     * Update one row: `PATCH /<collection>/<id>`, and the same row reached
+     * through a parent. Errors are not re-classified; see {@link createRow}.
+     */
+    private updateRow;
+    /**
+     * Delete one row: `DELETE /<collection>/<id>`, and the same row reached
+     * through a parent.
+     */
+    private deleteRow;
     /**
      * Create REST routes for a collection using existing Rebase patterns
      */
@@ -258,17 +375,16 @@ export declare class RestApiGenerator {
      * @param collectionPath the path to read — a nested listing passes its own
      *   `parent/:id/child` path, which the driver resolves.
      */
-    private readPage;
+    static readPage(driver: DataDriver, collection: CollectionConfig, queryOptions: QueryOptions, searchString?: string, searchExplain?: boolean, collectionPath?: string): Promise<{
+        rows: Record<string, unknown>[];
+        meta: Record<string, unknown>;
+    }>;
     /**
      * Fetch raw collection data without Entity wrapper (fallback for non-Postgres)
      */
-    private fetchRawCollection;
+    static fetchRawCollection(driver: DataDriver, collection: CollectionConfig, queryOptions: QueryOptions, searchString?: string, searchExplain?: boolean, collectionPath?: string, startAfter?: Record<string, unknown>): Promise<Record<string, unknown>[]>;
     /**
      * Count raw entities for a collection
      */
-    private countRawEntities;
-    /**
-     * Fetch single entity raw data without Entity wrapper (fallback)
-     */
-    private fetchRawEntity;
+    static countRawEntities(driver: DataDriver, collection: CollectionConfig, queryOptions: QueryOptions, searchString?: string, collectionPath?: string): Promise<number>;
 }

package/dist/api/rest/auth-collection-writes.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A write to the auth collection is user administration.
+ *
+ * The auth collection's rows are the users. `/admin/users` holds a change to
+ * one to the auth adapter's rules: a create goes through the adapter's user
+ * creation (the password hashed, the email normalized, the collection's
+ * `onCreateUser`, the invitation), an update may not leave the project without
+ * an administrator and stores an email the way sign-in looks it up, and a
+ * deletion runs `beforeUserDelete` (a veto), ends the sessions and runs
+ * `afterUserDelete`. The data doors that write the same rows — the REST routes
+ * and MCP's write tools — call these, so that no door writes a user by rules
+ * of its own. (The Postgres socket calls the adapter's methods directly.)
+ *
+ * Every function here leaves any other collection, and an adapter without the
+ * step, exactly as it was: the rows are then written as any table's.
+ */
+import type { AuthAdapter, CollectionConfig, UserCreationFinalizeResult, UserCreationPrepareResult } from "@rebasepro/types";
+import type { FieldViewer } from "@rebasepro/common";
+/** Whether `collection` is the auth collection — its rows are the users. */
+export declare function isAuthCollection(collection: CollectionConfig): boolean;
+/** An adapter that performs user creation (`prepareUserCreation`). */
+export type UserCreatingAdapter = AuthAdapter & Required<Pick<AuthAdapter, "prepareUserCreation">>;
+/**
+ * Whether a create on `collection` is a user creation `adapter` performs: the
+ * collection is the auth collection and the adapter has the step. When not,
+ * the door writes the row as any other.
+ */
+export declare function createsUsers(adapter: AuthAdapter | undefined, collection: CollectionConfig): adapter is UserCreatingAdapter;
+/**
+ * Check a create body for the auth collection against what the adapter says a
+ * create consumes (`describeUserCreationContract`).
+ *
+ * Signups carry credential fields (`password`) the collection does not declare
+ * as columns, so the body is checked for everything else. A custom
+ * `onCreateUser` owns the body's shape, and then the adapter asks for no check:
+ * the collection's fields do not describe what arrived.
+ *
+ * `rowIndex` names the row in a bulk write's message.
+ */
+export declare function assertUserCreationBodyValid(adapter: AuthAdapter | undefined, collection: CollectionConfig, body: Record<string, unknown>, viewer: FieldViewer, rowIndex?: number): void;
+/**
+ * The first half of creating users, before anything is written: each body
+ * through the adapter's `prepareUserCreation` (the password hashed or
+ * generated, the email normalized, the collection's `onCreateUser`), in order.
+ * The `values` of each result are what the door writes.
+ */
+export declare function prepareUserCreations(adapter: UserCreatingAdapter, collection: CollectionConfig, bodies: readonly Record<string, unknown>[]): Promise<UserCreationPrepareResult[]>;
+/**
+ * The second half, once the rows are written — and only then, so a write that
+ * fails invites nobody: the credentials' delivery through
+ * {@link completeUserCreation}, which is also what `POST /admin/users` calls.
+ *
+ * @returns For each row, the delivery fields a create response carries
+ * (`invitationSent`, and `temporaryPassword` when nobody was sent one).
+ */
+export declare function completeUserCreations(adapter: UserCreatingAdapter, prepared: readonly UserCreationPrepareResult[], rows: readonly Record<string, unknown>[]): Promise<UserCreationFinalizeResult[]>;
+/**
+ * Create one user through the auth collection: {@link prepareUserCreations},
+ * then `save` (the door's own driver write), then
+ * {@link completeUserCreations}.
+ *
+ * `undefined` when the create is not a user creation ({@link createsUsers}) —
+ * the door then writes the row as any other.
+ */
+export declare function createUserThroughAuthCollection(adapter: AuthAdapter | undefined, collection: CollectionConfig, body: Record<string, unknown>, save: (values: Record<string, unknown>) => Promise<Record<string, unknown>>): Promise<{
+    row: Record<string, unknown>;
+    delivery: UserCreationFinalizeResult;
+} | undefined>;
+/**
+ * Updates to rows of the auth collection, checked and put in stored form by
+ * the adapter's `prepareUserUpdates`: judged together, so a bulk demotion of
+ * every administrator is refused although each row alone would pass.
+ *
+ * @returns Each update's values, as they should be written, in order.
+ */
+export declare function prepareAuthCollectionUpdates(adapter: AuthAdapter | undefined, collection: CollectionConfig, updates: {
+    uid: string;
+    values: Record<string, unknown>;
+}[]): Promise<Record<string, unknown>[]>;
+/**
+ * Delete rows of the auth collection as user administration: the adapter's
+ * checks and `beforeUserDelete` before `remove` runs (either may refuse), its
+ * session cleanup and `afterUserDelete` after.
+ */
+export declare function deletingAuthCollectionUsers<T>(adapter: AuthAdapter | undefined, collection: CollectionConfig | undefined, uids: string[], remove: () => Promise<T>): Promise<T>;

package/dist/api/rest/field-access-query.d.ts

@@ -1,4 +1,4 @@
-import type { CollectionConfig } from "@rebasepro/types";
+import type { CollectionConfig, IncludeSpec } from "@rebasepro/types";
 import type { LogicalCondition } from "@rebasepro/types";
 import { type FieldViewer } from "@rebasepro/common";
 /**
@@ -39,7 +39,7 @@ export declare function requestViewer(c: {
     get: (key: never) => unknown;
 }): FieldViewer;
 /** Which query parameter a refused field arrived in, for the message. */
-type Where = "filter" | "orderBy" | "fields" | "select" | "groupBy";
+type Where = "filter" | "orderBy" | "fields" | "select" | "groupBy" | "vector_search";
 /**
  * Refuse the request when any of `names` is a field this caller cannot read.
  *
@@ -62,5 +62,9 @@ export declare function assertQueryFieldsReadable(options: {
         field: string;
     }[];
     fields?: string[];
+    include?: IncludeSpec;
+    vectorSearch?: {
+        property: string;
+    };
 }, collection: CollectionConfig, viewer: FieldViewer | undefined): void;
 export {};

package/dist/api/rest/idempotency.d.ts

@@ -10,8 +10,14 @@ import { DataDriver } from "@rebasepro/types";
  * carrying corrected rows from the retry of an unanswered one, which is the
  * difference between "here is your earlier answer" and silently discarding a
  * correction.
+ *
+ * The query string separates instructions sent to one path: `?hard=true` purges
+ * where the same `DELETE` without it soft-deletes, and `?on_conflict=` makes a
+ * create an upsert. Left out, a purge sent under the soft delete's key was
+ * answered with that delete's `204` and never ran. A request with no query
+ * string fingerprints exactly as it did before one could enter.
  */
-export declare function requestFingerprint(method: string, path: string, body: unknown): Promise<string>;
+export declare function requestFingerprint(method: string, path: string, body: unknown, query?: URLSearchParams): Promise<string>;
 /**
  * What a caller may do with a key.
  *

package/dist/api/rest/nested-write-access.d.ts

@@ -0,0 +1,46 @@
+import { type CollectionConfig, type ResolvedRelation } from "@rebasepro/types";
+import { type FieldViewer } from "@rebasepro/common";
+/** The last hop of a nested path: the parent, the relation it names, and that relation's target. */
+export interface NestedWriteHop {
+    parentCollection: CollectionConfig;
+    relation: ResolvedRelation;
+    targetCollection: CollectionConfig;
+}
+/**
+ * What a write through a nested path does to the row the path addresses.
+ *
+ *  - `create`: a new row under the parent (`POST /bands/7/members`);
+ *  - `update`: an existing row reached through the parent (`PATCH …/members/3`);
+ *  - `pivot`: the columns of one many-to-many link (`PATCH …/tags/5 { _pivot }`);
+ *  - `unlink`: a `DELETE` through a nested path. Through a many-to-many one it
+ *    drops the link; through an owning one it deletes the row, which writes
+ *    no relation and is the row's own delete rules' to answer.
+ */
+export type NestedWriteKind = "create" | "update" | "pivot" | "unlink";
+/**
+ * Refuse a write through a parent that sets a relation the caller may not write.
+ *
+ * A body is checked against the target's field rules, and that is all the
+ * nested routes used to check. But the address writes too, and what it writes
+ * is not in the body:
+ *
+ *  - A create under a parent whose target carries the parent's key
+ *    (`hasMany`/`hasOne`) has that key stamped from the URL — `POST
+ *    /bands/7/members` sets `members.band_id = 7`, which `POST /members
+ *    { bandId: 7 }` answers `FIELD_NOT_WRITABLE` for when `members.band` is
+ *    closed to the caller.
+ *  - A create is also a new member of the parent's relation, and every write
+ *    through a many-to-many path is set membership: it links on create and on
+ *    update, edits the link with `_pivot`, and drops it on delete. That is a
+ *    write of the parent's relation property — `PATCH /posts/1 { tags: [5] }`
+ *    when `posts.tags` is closed — and its rules hold here.
+ *
+ * An update through an owning parent changes neither: the driver refuses it
+ * unless the row is already the parent's, and does not write the key.
+ *
+ * One rule for every door that takes a nested path — the REST routes and the
+ * realtime socket — asked of the same fields `assertNoClosedFields` judges a
+ * body by, so the answer (`FIELD_NOT_WRITABLE`, or `VALIDATION_EXCLUDED_FIELDS`
+ * for an `excludeFromApi` relation) is the one the root route gives.
+ */
+export declare function assertNestedWriteAllowed(hop: NestedWriteHop, kind: NestedWriteKind, path: string, viewer: FieldViewer | undefined): void;

package/dist/api/rest/write-validation.d.ts

@@ -1,5 +1,37 @@
-import { CollectionConfig } from "@rebasepro/types";
+import { CollectionConfig, type IncludeSpec } from "@rebasepro/types";
 import { type FieldViewer } from "@rebasepro/common";
+/**
+ * Refuse a write naming a field this caller may not set.
+ *
+ * `excludeFromApi` means what the generated SDK already says it means: "absent
+ * from Row, Insert and Update — the API surface does not mention it, in either
+ * direction". The server only ever enforced the read half, so the column a
+ * collection had declared unservable was still writable by anyone whose
+ * policies let them write the row.
+ *
+ * On the user store that is the sharp one. `users_write_own` lets you update
+ * your own row, `password_hash` is a column on it, and setting it directly is a
+ * password change that does not need the old password — so a stolen access
+ * token, which expires within the hour, becomes a password the attacker chose.
+ * Everything else the flag protects is the same shape: a verification token, a
+ * rotation counter, a secret the server owns.
+ *
+ * `access.write: ["editor"]` is the same rule with a role list instead of an
+ * empty one, and answers `FIELD_NOT_WRITABLE` rather than
+ * `VALIDATION_EXCLUDED_FIELDS`. Both refuse rather than dropping the key: a
+ * write that silently discards a field reports success for an edit that did not
+ * happen, which is the one outcome a form cannot recover from.
+ *
+ * The empty-list half is refused for every caller, not only unprivileged ones,
+ * and regardless of `strictWrites`. The framework's own auth paths do not come
+ * through here — `prepareUserCreation` builds the row itself — so what is left
+ * is callers the rule was written to exclude.
+ *
+ * Exported for the history revert, which writes a stored version rather than a
+ * body and so asks this question of the fields the revert would change, not of
+ * every key the snapshot holds. `where` prefixes the message.
+ */
+export declare function assertNoClosedFields(values: Record<string, unknown>, collection: CollectionConfig, where: string, viewer: FieldViewer | undefined): void;
 /**
  * Reject a write naming a field the collection does not have.
  *
@@ -119,7 +151,7 @@ export declare function assertWriteValuesValid(values: Record<string, unknown>,
  * assuming one.
  */
 export declare function projectResponseFields<T extends Record<string, unknown>>(rows: T[], fields: readonly string[] | undefined, collection: CollectionConfig, options?: {
-    include?: readonly string[];
+    include?: IncludeSpec;
 }): T[];
 /**
  * Both write checks, as one call, for a transport that is not the REST router.

package/dist/api/types.d.ts

@@ -31,8 +31,24 @@ export type HonoEnv = {
          */
         recipientEmail?: string;
         driver?: DataDriver;
-        /** Set when the request is authenticated via a Service API Key. */
+        /** Set when the request is authenticated with an API key (`rk_`). */
         apiKey?: ApiKeyMasked;
+        /**
+         * What the caller may do, when its credential is narrower than its
+         * person — an API key or an MCP token. Absent for a person's own
+         * session, who holds what their roles hold. Read it through
+         * `callerScopes` / `hasScope`, which fill in that second case.
+         */
+        scopes?: string[];
+        /**
+         * Who asked, when an administrator's request runs as another user
+         * (`x-rebase-impersonate`). `user` and `driver` are then the
+         * impersonated user's; this is the only place the administrator
+         * remains. See `auth/impersonation.ts`.
+         */
+        impersonator?: {
+            uid: string;
+        };
         /** Unique request correlation ID (generated or propagated from X-Request-ID header). */
         requestId?: string;
         /**