@fitzzero/quickdraw-core 5.1.1 → 5.1.2

package/dist/server/express/index.d.ts

@@ -18,7 +18,13 @@ declare function stripIp(raw: string | undefined): string;
 /**
  * Key by Bearer token when present, falling back to client IP. Lets
  * token-authenticated clients get their own bucket instead of sharing
- * a NAT'd IP.
+ * a NAT'd IP. Nothing here checks the token (the 5.1 audit's
+ * TRANSPORT-4): a caller that sends a new made-up token on each request
+ * gets a fresh bucket each time, even behind `requireSession`, which signs
+ * a request in by its cookie first and never reads the bearer token then.
+ * Key a limiter mounted behind `requireSession` by the user it verified
+ * instead (`keyGenerator: (req) => sessionOf(req).userId`), and anonymous
+ * traffic by IP, as `createPublicApiLimiter` does.
  */
 declare function bearerOrIp(req: Request): string;
 /**
@@ -39,7 +45,8 @@ declare function createPublicApiLimiter(overrides?: PartialOptions): RateLimitRe
  * minute per IP, refused with `429 { ok: false, e: { code: "RATE_LIMITED",
  * message, data: { retryAfterMs } } }`. Server-side prefetch reaches the API
  * from the web server's address, so key it some other way (`keyGenerator`)
- * or raise `max` when the web server prefetches for many users.
+ * or raise `max` when the web server prefetches for many users; never by
+ * an unverified bearer token (`bearerOrIp`).
  */
 declare function createCallLimiter(overrides?: PartialOptions): RateLimitRequestHandler;
 

package/dist/server/express/index.js

@@ -7,7 +7,7 @@ import {
   createPublicApiLimiter,
   createWebhookLimiter,
   stripIp
-} from "../../chunk-TBMKJ26R.js";
+} from "../../chunk-NW6U45HX.js";
 export {
   bearerOrIp,
   createAuthLimiter,

package/dist/server/index.d.ts

@@ -1,20 +1,21 @@
-import { J as AnyContract, at as ProjectionName, ai as FullProjectionOf, ac as CollectionName, ap as MethodName, d as StandardSchemaV1, c as InferOutput, N as NullableProjection, P as ProjectionList, aq as MethodOf, as as ParsedInputOf, ao as KindOf, A as AccessLevel, af as EntityOf, ar as OutputOf } from '../infer-Teo1xpsd.js';
-import { M as ModelName, v as PolicyFor, w as RowForms, x as AccessFor, H as HandlerContext, y as ModelColumn, z as WatchAccess, B as PublicAccess, E as HandlerArgs, G as CustomAccess, I as ShareMode, J as ChannelOptions, K as StreamOptions, u as RoomLeaveHandler, L as ChannelsRequired, h as Service, N as BaseContext, O as CallerFor, l as RunContext, m as RunOptions, o as StreamHandle, P as Presence, n as ServerRooms, Q as AccessPolicy, T as AnyAccessPolicy, V as PolicyColumns, X as PolicyForeign, Y as PolicyTools, k as AccessFilter, Z as RowAccess, q as AccessEngine, b as StorageWhere } from '../caller-CXTFswBO.js';
-export { aI as ANY_FIELD, aA as AccessForm, aB as AccessRequest, _ as AffectsLink, p as AnyContext, A as AnyService, r as AppRooms, aC as AuthenticatedAccess, aq as CallOptions, d as Caller, a9 as ChannelAccess, aa as ChannelContext, ab as ChannelHandler, ac as ChannelImplementation, ad as ChannelRoomOf, a4 as CollectionScope, a6 as ContextRooms, a7 as ContextServices, C as CountArgs, a3 as DEFAULT_BULK_THRESHOLD, i as DevWarning, D as DevWarningError, j as DevWarningKind, aD as EntryAccess, F as FindManyArgs, f as FlushInfo, e as FlushSink, at as ForeignColumns, au as ForeignColumnsOf, aE as IdKeyOf, aF as IdSelector, av as MembershipRead, ar as MethodCaller, aM as N_PLUS_ONE_STATEMENTS, aw as ParentLink, ax as PolicyKind, ay as PolicyReads, $ as ProjectedOutput, a0 as Projection, ae as RoomLeave, af as RoomLeaveReason, ag as RoomLeft, ah as RoomTarget, az as RowLevel, R as RowLevels, aG as ScopeAccess, aH as ServiceAccess, as as ServiceCaller, ai as ServiceChannel, a5 as ServiceCollection, g as ServiceMethod, aj as ServiceStream, c as StatementCount, S as StorageAdapter, a as StorageRow, ak as StreamImplementation, al as StreamPushArgs, am as StreamPushManyArgs, an as StreamSeed, ao as StreamSeedContext, t as StreamSubscriptions, ap as StreamValidation, a1 as TierGroup, a2 as Tiers, a8 as TouchOptions, aJ as UnitOfWork, U as UnitOfWorkFactory, aK as UnitOfWorkScope, W as WriteRecord, aL as formatDevWarning, s as storageOf } from '../caller-CXTFswBO.js';
-import { S as ServerOptions, Q as QuickdrawServer } from '../createServer-CP9eDHZZ.js';
-export { C as ClusterClient, u as ClusterOptions, D as DEFAULT_STALL_INTERVAL_MS, e as DEFAULT_STALL_MAX_MS, f as DEFAULT_STALL_THRESHOLD_MS, p as DisconnectUserOptions, E as EntitySubscription, a as EntitySubscriptions, H as HttpApp, I as IoRedisLike, L as LegacyReply, t as LegacyWireOptions, M as MIN_STALL_INTERVAL_MS, m as QuickdrawIo, n as QuickdrawServerSocket, o as QuickdrawSocketData, y as RateLimitOptions, z as RateLimiter, R as RotateOptions, g as STALL_RESOLUTION_MS, b as ScopeSubscription, c as ScopeSubscriptions, l as ServerOnlyOptions, h as SlowMethod, q as SocketCors, r as SocketOptions, s as SocketRateLimitOptions, i as StallReport, j as StallWatchdogOptions, T as TopicWatch, d as TopicWatches, w as applyRateLimitMiddleware, v as createRateLimiter, k as createServer, x as createTieredRateLimiter } from '../createServer-CP9eDHZZ.js';
-import { ad as Version } from '../envelope-Cp3YcVxC.js';
-import { Q as QuickdrawTypes, D as DbOf, d as PrincipalKindOf, c as PrincipalOf, M as MaybePromise, b as McpContextOf, C as ContextExtensionOf, P as Principal } from '../types-Cu0vmx7c.js';
-export { a as McpContext, T as Transport } from '../types-Cu0vmx7c.js';
-import { a as DispatcherOptions, D as Dispatcher, c as DispatcherCollections } from '../http-Djj2Inuu.js';
-export { o as AccessChange, p as AccessChangeListener, A as AccessOptions, d as ChangeLogOptions, C as ContractOfServices, j as DEFAULT_LIMITS, f as DbOfServices, h as DispatchRequest, i as DispatchResult, n as DispatcherAccess, k as DispatcherLimits, s as HttpMiddleware, H as HttpRouter, u as HttpRouterOptions, b as HttpTransportOptions, L as LimitsOptions, l as PipelineOptions, P as PrincipalOfServices, R as RegisteredMethod, g as Registry, S as SharedData, m as SubscriptionLimits, T as TrackingOptions, V as VersionRequest, q as VersionSource, e as createDispatcher, r as createHttpRouter, t as toCallReply } from '../http-Djj2Inuu.js';
-import { l as CrudMethodName, d as CrudContractOptions, S as ScalarFieldOf, N as NumberFieldOf, m as CrudMethods, H as AdminMethodsOf, w as AdminContractOptions, G as AdminMethods } from '../admin-DKwkIh5i.js';
-import { S as SearchContractOptions, T as TextFieldOf, b as SearchMethods, n as SharingMethodName, f as SharingByNameMethod, g as SharingContractOptions, o as SharingMethods } from '../sharing-DVa8W-yR.js';
-import { x as AdminNeverWritable, l as AdminFieldConfig } from '../adminSchemas-2DUA_hZ8.js';
-export { a as CallOutcome, C as CallRecord } from '../metrics-BdBu5o8G.js';
-export { b as AuthenticateRequest, A as AuthenticateResult, c as HttpAuthenticateRequest, d as HttpCredentialSource, S as ServerAuth, e as ServiceAccessSource, a as ServiceGrants, f as SocketAuthenticateRequest, r as recordSocketSession } from '../auth-BhWqdyb-.js';
+import { J as AnyContract, at as ProjectionName, ai as FullProjectionOf, ac as CollectionName, ap as MethodName, d as StandardSchemaV1, c as InferOutput, N as NullableProjection, P as ProjectionList, aq as MethodOf, as as ParsedInputOf, ao as KindOf, A as AccessLevel, af as EntityOf, ar as OutputOf } from '../infer-BmoZsL9a.js';
+import { M as ModelName, v as PolicyFor, w as RowForms, x as AccessFor, H as HandlerContext, y as ModelColumn, z as WatchAccess, B as PublicAccess, E as HandlerArgs, G as CustomAccess, I as ShareMode, J as ChannelOptions, K as StreamOptions, u as RoomLeaveHandler, L as ChannelsRequired, h as Service, N as BaseContext, O as CallerFor, l as RunContext, m as RunOptions, o as StreamHandle, P as Presence, n as ServerRooms, Q as AccessPolicy, T as AnyAccessPolicy, V as PolicyColumns, X as PolicyForeign, Y as PolicyTools, k as AccessFilter, Z as RowAccess, q as AccessEngine, b as StorageWhere } from '../caller-BT-Mv4bD.js';
+export { aI as ANY_FIELD, aA as AccessForm, aB as AccessRequest, _ as AffectsLink, p as AnyContext, A as AnyService, r as AppRooms, aC as AuthenticatedAccess, aq as CallOptions, d as Caller, a9 as ChannelAccess, aa as ChannelContext, ab as ChannelHandler, ac as ChannelImplementation, ad as ChannelRoomOf, a4 as CollectionScope, a6 as ContextRooms, a7 as ContextServices, C as CountArgs, a3 as DEFAULT_BULK_THRESHOLD, i as DevWarning, D as DevWarningError, j as DevWarningKind, aD as EntryAccess, F as FindManyArgs, f as FlushInfo, e as FlushSink, at as ForeignColumns, au as ForeignColumnsOf, aE as IdKeyOf, aF as IdSelector, aL as LinkInterest, av as MembershipRead, ar as MethodCaller, aN as N_PLUS_ONE_STATEMENTS, aw as ParentLink, ax as PolicyKind, ay as PolicyReads, $ as ProjectedOutput, a0 as Projection, ae as RoomLeave, af as RoomLeaveReason, ag as RoomLeft, ah as RoomTarget, az as RowLevel, R as RowLevels, aG as ScopeAccess, aH as ServiceAccess, as as ServiceCaller, ai as ServiceChannel, a5 as ServiceCollection, g as ServiceMethod, aj as ServiceStream, c as StatementCount, S as StorageAdapter, a as StorageRow, ak as StreamImplementation, al as StreamPushArgs, am as StreamPushManyArgs, an as StreamSeed, ao as StreamSeedContext, t as StreamSubscriptions, ap as StreamValidation, a1 as TierGroup, a2 as Tiers, a8 as TouchOptions, aJ as UnitOfWork, U as UnitOfWorkFactory, aK as UnitOfWorkScope, W as WriteRecord, aM as formatDevWarning, s as storageOf } from '../caller-BT-Mv4bD.js';
+import { S as ServerOptions, Q as QuickdrawServer } from '../createServer-Cp-Wk500.js';
+export { C as ClusterClient, u as ClusterOptions, D as DEFAULT_STALL_INTERVAL_MS, e as DEFAULT_STALL_MAX_MS, f as DEFAULT_STALL_THRESHOLD_MS, p as DisconnectUserOptions, E as EntitySubscription, a as EntitySubscriptions, H as HttpApp, I as IoRedisLike, L as LegacyReply, t as LegacyWireOptions, M as MIN_STALL_INTERVAL_MS, m as QuickdrawIo, n as QuickdrawServerSocket, o as QuickdrawSocketData, y as RateLimitOptions, z as RateLimiter, R as RotateOptions, g as STALL_RESOLUTION_MS, b as ScopeSubscription, c as ScopeSubscriptions, l as ServerOnlyOptions, h as SlowMethod, q as SocketCors, r as SocketOptions, s as SocketRateLimitOptions, i as StallReport, j as StallWatchdogOptions, T as TopicWatch, d as TopicWatches, w as applyRateLimitMiddleware, v as createRateLimiter, k as createServer, x as createTieredRateLimiter } from '../createServer-Cp-Wk500.js';
+import { ad as Version } from '../envelope-DzWyIXjj.js';
+export { ag as MAX_ENTITY_IDS_PER_SOCKET, ah as MAX_SCOPES_PER_SOCKET, ai as MAX_TOPICS_PER_SOCKET } from '../envelope-DzWyIXjj.js';
+import { Q as QuickdrawTypes, D as DbOf, d as PrincipalKindOf, c as PrincipalOf, M as MaybePromise, b as McpContextOf, C as ContextExtensionOf, P as Principal } from '../types-CYliTP65.js';
+export { a as McpContext, T as Transport } from '../types-CYliTP65.js';
+import { c as DispatcherOptions, D as Dispatcher, d as DispatcherCollections } from '../http-DotQ5bj8.js';
+export { p as AccessChange, q as AccessChangeListener, A as AccessOptions, e as ChangeLogOptions, C as ContractOfServices, k as DEFAULT_LIMITS, g as DbOfServices, i as DispatchRequest, j as DispatchResult, o as DispatcherAccess, a as DispatcherBaseOptions, l as DispatcherLimits, u as HttpMiddleware, H as HttpRouter, v as HttpRouterOptions, b as HttpTransportOptions, L as LimitsOptions, m as PipelineOptions, P as PrincipalOfServices, R as RegisteredMethod, h as Registry, S as SharedData, n as SubscriptionLimits, T as TrackingOptions, V as VersionRequest, r as VersionSource, f as createDispatcher, s as createHttpRouter, t as toCallReply } from '../http-DotQ5bj8.js';
+import { l as CrudMethodName, d as CrudContractOptions, S as ScalarFieldOf, N as NumberFieldOf, m as CrudMethods, H as AdminMethodsOf, w as AdminContractOptions, G as AdminMethods } from '../admin-DWWrT1h6.js';
+import { S as SearchContractOptions, T as TextFieldOf, b as SearchMethods, n as SharingMethodName, f as SharingByNameMethod, g as SharingContractOptions, o as SharingMethods } from '../sharing-UDLn1049.js';
+import { x as AdminNeverWritable, l as AdminFieldConfig } from '../adminSchemas-D4bFKsrb.js';
+export { a as CallOutcome, C as CallRecord } from '../metrics-DW80Exve.js';
+export { b as AuthenticateRequest, A as AuthenticateResult, c as HttpAuthenticateRequest, d as HttpCredentialSource, S as ServerAuth, e as ServiceAccessSource, a as ServiceGrants, f as SocketAuthenticateRequest, r as recordSocketSession } from '../auth-DXiSJZaf.js';
 import { Server } from 'socket.io';
-import { L as Logger } from '../logger-BY28acW-.js';
+import { L as Logger } from '../logger-Yz93KzdV.js';
 import 'node:http';
 import '../errors-S-bxEIBC.js';
 
@@ -31,9 +32,6 @@ declare const MAX_APP_ROOMS = 100;
 /** The most scopes one stream keeps a seed for; the scope pushed to least recently goes first. */
 declare const STREAM_MAX_SCOPES = 10000;
 
-/** The most stream feeds one socket may subscribe to at once. */
-declare const MAX_STREAMS_PER_SOCKET = 500;
-
 /**
  * A JSON column's value as a database client types it: structurally
  * Prisma's `JsonValue` (and its `InputJsonValue` objects and arrays). A row
@@ -113,6 +111,9 @@ type HandlerOutputOf<C extends AnyContract, M extends MethodName<C>, Proj = Reco
  *   that row, through its service's policy. Deleting the row closes its
  *   scopes (`qd:revoked` with reason `"anchor-deleted"`).
  * - `scopeAccess: "self"`: the scope value is the subscriber's own user id.
+ *   On a service with an access policy its items still follow that policy:
+ *   only the rows its user may read at `Read`, and a row the user loses goes
+ *   out `removed`.
  *
  * A service-wide `Admin` grant on this service passes either check, as it
  * passes every check of the service. `bulkThreshold` (default 200) is how
@@ -208,9 +209,15 @@ type ShareOptions<A> = {
     /**
      * Run identical concurrent calls once: `"caller"` per principal, `"all"`
      * across principals. Every caller is authorized before it joins; the
-     * handler runs with the first caller's `ctx`, so a `"all"` handler must
-     * not depend on who asks. `"all"` is not allowed with `custom` access,
-     * whose result may depend on who asks.
+     * handler runs with the first caller's `ctx`, and every caller gets its
+     * result, so a `"all"` result must depend on the input only: its
+     * handler reads nothing of the caller (in development, reading
+     * `ctx.principal`, `ctx.services` or `ctx.mcp` warns
+     * `[quickdraw:shared-principal]`, and a strict test app fails the
+     * call). `"all"` is not allowed with `custom` access, nor on the kit
+     * methods whose result depends on who asks (the read/write kit's
+     * `list` and `getMany`, `search`, the sharing kit's `listShares` and
+     * `listMembers`, the admin kit's `adminList` and `adminGet`).
      */
     readonly share: A extends CustomAccess<never, never> ? "caller" : ShareMode;
     /** Reuse a successful result for this long after its run, in milliseconds. */
@@ -252,6 +259,22 @@ type MethodImplementation<T extends QuickdrawTypes, C extends AnyContract, M ext
      * signed out. Leave it out for the service's list.
      */
     readonly kinds?: readonly PrincipalKindOf<T>[];
+    /**
+     * A requirement on the caller's verified claims (`principal.claims`, a
+     * token's `scope`), beside `access`: the call passes only when it returns
+     * `true`. It adds to the form, so `{ entry: "Moderate" }` with `claims`
+     * needs Moderate on the row and the claims. It runs right after `kinds`,
+     * outside the access engine, so no grant passes it, a service-wide
+     * `Admin` grant included. Without a principal the call is
+     * `UNAUTHENTICATED`; when it returns anything but `true`, `FORBIDDEN`. It
+     * is synchronous, and a `"public"` method takes none. Never write a check
+     * on claims as `custom`: that form replaces the row check, and an Admin
+     * grant skips it.
+     *
+     * @example
+     * claims: (claims) => claims?.scope === "triage",
+     */
+    readonly claims?: (claims: PrincipalOf<T>["claims"], input: ParsedInputOf<C, M>) => boolean;
     /**
      * Runs the method. For a projection output it returns the database row
      * (or rows, or `null`), which the framework projects: only the
@@ -263,11 +286,15 @@ type MethodImplementation<T extends QuickdrawTypes, C extends AnyContract, M ext
     /**
      * Says the access form is this method's whole check on purpose. On a
      * service with an access policy, `defineService` refuses a method whose
-     * input has `id` while its access is `"public"`, `"authenticated"` or `{
-     * service: L }` below `Admin`, since any caller the form admits could then
-     * reach any row by its id: give it `{ entry: L }` so the policy decides,
-     * or `rowless: true` when every such caller may reach any row (public
-     * profiles, lookups by an id that tells nothing).
+     * input has `id` while its access checks some other row or none:
+     * `"public"`, `"authenticated"`, `{ service: L }` below `Admin`,
+     * `custom(fn)`, `{ scope, of, id }`, or `{ entry, id }` naming another
+     * key. Any caller the form admits could then reach any row by its id:
+     * give it `{ entry: L }` so the policy decides (with `claims` beside it
+     * for a check on the caller's claims), or `rowless: true` when every such
+     * caller may reach any row (public profiles, lookups by an id that tells
+     * nothing), or when `id` names a row the method creates (an id the client
+     * made).
      */
     readonly rowless?: true;
 } & (KindOf<C, M> extends "query" ? QueryOptions<T, C, M, A> : MutationOptions);
@@ -315,7 +342,8 @@ interface ServiceDefinition<T extends QuickdrawTypes, C extends AnyContract, A,
      * section 7.1): `{ anchor: contract }`, the contract whose rows the scope
      * values are ids of, or `{ scopeAccess: "self" }` for a scope that is the
      * subscriber's user id; plus `bulkThreshold`. Required when the contract
-     * declares collections. Needs `model`.
+     * declares collections. Needs `model`. A self scope's items still follow
+     * the service's `access` policy, when it has one.
      */
     readonly collections?: CollectionOptions<C>;
     /**
@@ -535,6 +563,9 @@ declare const CHANNEL_ABUSE_WINDOW_MS = 10000;
 /** A socket is disconnected once its drops within the window exceed this many times the channel's rate. */
 declare const CHANNEL_ABUSE_MULTIPLIER = 100;
 
+/** The most stream feeds one socket may subscribe to at once. */
+declare const MAX_STREAMS_PER_SOCKET = 500;
+
 /**
  * A custom access check: the call passes when `check(ctx, input)` resolves
  * `true`. The caller must be authenticated first, so `ctx.principal` is
@@ -543,6 +574,11 @@ declare const CHANNEL_ABUSE_MULTIPLIER = 100;
  * custom access cannot `share: "all"`, because its result may depend on who
  * asks.
  *
+ * It replaces the row check: on a service with an access policy,
+ * `defineService` refuses it on a method whose input has `id` unless the
+ * method says `rowless: true`. A check on the caller's claims is the
+ * method's `claims`, beside an `entry` form: no grant skips that.
+ *
  * @example
  * access: custom((ctx, input) => ctx.principal.userId === input.ownerId),
  */
@@ -578,7 +614,11 @@ declare function jsonAcl<const Field extends string, const Owner extends string
 
 /** Options of {@link members}. */
 interface MembersOptions<Model extends string = string, Entry extends string = string, User extends string = string, Level extends string = string> {
-    /** The membership model, named as the client names it: `"projectMember"`. */
+    /**
+     * The membership model, named as the client names it: `"projectMember"`.
+     * It needs an `id` column (keep the pair unique with `@@unique`, never a
+     * composite `@@id`), or its writes are not tracked and never revoke.
+     */
     readonly model: Model;
     /** The column holding the id of the row the membership is on: `"projectId"`. */
     readonly entry: Entry;
@@ -589,14 +629,20 @@ interface MembersOptions<Model extends string = string, Entry extends string = s
     /**
      * Maps stored roles to access levels: `{ owner: "Admin", editor: "Moderate", viewer: "Read" }`.
      * Without it a stored role must be a level name. A role that maps to no
-     * level grants nothing.
+     * level grants nothing. Roles that map to one level are peers: with
+     * `{ owner: "Admin", admin: "Admin" }` the sharing kit lets an `admin`
+     * demote or remove the `owner`. To make an owner untouchable, give the
+     * row an owner column (`anyOf(owner("ownerId"), members(...))`, or
+     * `jsonAcl(..., { owner })`).
      */
     readonly levels?: Readonly<Record<string, AccessLevel>>;
 }
 /**
  * The level comes from the principal's row in a membership table: one query
  * per lookup, filtered by the entry ids and the user id. Several rows for one
- * user and entry give the highest level among them.
+ * user and entry give the highest level among them. The table needs an `id`
+ * column, or no write to it is tracked and a removed member keeps what they
+ * subscribed to; `createServer` names such a table at start.
  *
  * @example
  * access: members({ model: "projectMember", entry: "projectId", user: "userId", level: "role" }),
@@ -666,7 +712,8 @@ interface ResolverOptions<P extends Principal = Principal, Column extends string
     /**
      * A filter matching exactly the rows on which the principal has at least
      * `level`, or `"none"`. Without it, list filters through this policy match
-     * no row.
+     * no row, and the read/write kit's `reorder` moves none below a
+     * service-wide grant.
      */
     readonly where?: (principal: P, level: AccessLevel, tools: PolicyTools) => MaybePromise<AccessFilter>;
     /**
@@ -819,22 +866,31 @@ interface CrudHandlersOptions<C extends AnyContract, A, Db = unknown> {
      * Who may call each of the kit's methods: one form per method, required.
      * `get`, `update`, `delete` and `reorder` take `{ entry: L }` to check the
      * row; the methods on many rows also keep only the rows the service's
-     * policy gives the caller at the form's level.
+     * policy gives the caller at the form's level. A bulk method whose form
+     * names no level takes its single-row counterpart's row level (`delete`'s
+     * for `bulkDelete`, `update`'s for `bulkUpdate`) when it is higher than
+     * `Moderate`; give `{ entry: L, id: "ids" }` to refuse the whole call
+     * instead of skipping rows.
      */
     readonly access: A & NoInfer<NotAKitMethod<C, A>>;
     /**
      * What `create` writes, from its parsed input: set owner or scope columns
      * from `ctx.principal`, an ordinal from `nextOrdinal`. `create` writes the
-     * input as it is without it.
+     * input as it is without it. An owner or access-list column (one the
+     * policy reads) comes only from here: the caller may not send one. The
+     * anchors of what it returns (each `inherit` parent and anchored
+     * collection's scope it sets) are checked at the method's row level, and
+     * it returns column values only, never a relation or a nested write.
      */
     readonly prepare?: [CrudCreateOf<C>] extends [never] ? `crud.handlers: prepare is for the kit's create, which ${C["name"]} does not have` : CrudPrepare<ParsedInputOf<C, CrudCreateOf<C>>, KitContext, Db>;
     /**
      * The kit's methods whose access form is their whole check on purpose:
      * each gets `rowless: true`. On a service with an access policy,
-     * `defineService` refuses `get` under `"public"`, `"authenticated"` or
-     * `{ service: L }` below `Admin` (any such caller could read any row by
-     * its id) unless it is named here: `rowless: ["get"]` for public
-     * profiles, say. `update`, `delete` and `reorder` check the row whatever
+     * `defineService` refuses `get` under a form that asks the policy nothing
+     * about the row its `id` names (`"public"`, `"authenticated"`,
+     * `{ service: L }` below `Admin`, `custom`, `{ scope }`, or `{ entry }` on
+     * another key: any such caller could read any row by its id) unless it is
+     * named here: `rowless: ["get"]` for public profiles, say. `update`, `delete` and `reorder` check the row whatever
      * their form, and need nothing.
      */
     readonly rowless?: readonly CrudMethodsOf<C>[];
@@ -963,7 +1019,8 @@ type SearchStrategy<Ctx = SearchStrategyContext> = {
      * The filter of the rows that match `q`, in the database client's
      * `where` shape: a Postgres full-text condition, say. The kit adds the
      * access filter and the scope, and pages the rows by keyset cursor in
-     * the scope collection's order (else by id).
+     * the scope collection's order when the call passes a scope, else by
+     * id.
      */
     readonly where: (q: string, ctx: Ctx) => MaybePromise<StorageWhere>;
     readonly ids?: never;
@@ -1086,9 +1143,13 @@ interface SharingUserLookup {
     readonly email?: string;
 }
 /**
- * Finds the user a by-name method means: their user id, or `null` (or
+ * Finds the one user a by-name method means: their user id, or `null` (or
  * `undefined`) when there is no such user, which fails the call with
- * `NOT_FOUND`.
+ * `NOT_FOUND`. It must name exactly one user: look a user up by something
+ * unique and verified (an email, with `findUnique`), and take a display
+ * name's user only when exactly one user has that name, else `null`. A
+ * `findFirst` by name hands the share to whoever registered the name first
+ * (the 5.1 audit's SHARE-2).
  */
 type SharingResolveUser<Db = unknown> = (lookup: SharingUserLookup, ctx: KitContext, db: Db) => MaybePromise<string | null | undefined>;
 type NotASharingMethod<C extends AnyContract, A> = [Exclude<keyof A, SharingMethodsOf<C>>] extends [
@@ -1110,17 +1171,25 @@ type SharingHandlersOptions<C extends AnyContract, A, Db = unknown> = {
     readonly onChange?: SharingOnChange<Db>;
     /**
      * The kit's methods whose access form is their whole check on purpose:
-     * each gets `rowless: true`. On a service with an access policy,
+     * each gets `rowless: true`. A change still never touches a user above
+     * the caller's own level on the row, which under such a form is their
+     * level on the row (often none): name `service` in the form for a
+     * service-wide grant to count. On a service with an access policy,
      * `defineService` refuses an access-list method (`share`, `unshare`,
      * `setLevel`, `listShares`, `shareByName`: their input names the row as
-     * `id`) under `"public"`, `"authenticated"` or `{ service: L }` below
-     * `Admin` unless it is named here.
+     * `id`) under a form that asks the policy nothing about that row
+     * (`"public"`, `"authenticated"`, `{ service: L }` below `Admin`,
+     * `custom`, `{ scope }`, or `{ entry }` on another key) unless it is named
+     * here.
      */
     readonly rowless?: readonly SharingMethodsOf<C>[];
 } & ([SharingByNameOf<C>] extends [never] ? {
     readonly resolveUser?: `sharing.handlers: resolveUser is for shareByName and inviteByName, which ${C["name"]} does not have`;
 } : {
-    /** Finds the user `shareByName` and `inviteByName` mean, by name or email. */
+    /**
+     * Finds the one user `shareByName` and `inviteByName` mean, by name or
+     * email, or `null`: never the first of several (`SharingResolveUser`).
+     */
     readonly resolveUser: SharingResolveUser<Db>;
 });
 /** `sharing.handlers`' options argument: required when the contract has a by-name method. */
@@ -1233,26 +1302,29 @@ interface AdminHandlersOptions<C extends AnyContract, A, Db = unknown> {
     readonly displayName?: string;
     /**
      * Fields the kit leaves out entirely: from `adminMeta`, from the rows it
-     * returns and from what it writes. `acl`, `serviceAccess` and
-     * `service_access` are always hidden, as in 4.1, unless `grants` shows
-     * the last two.
+     * returns and from what it writes. `acl`, `serviceAccess`,
+     * `service_access` and the column the dispatcher's `serviceAccessSource`
+     * names on this service's model are always hidden (the first three as in
+     * 4.1), unless `grants` shows the grants field.
      */
     readonly hiddenFields?: readonly Exclude<AdminFieldOf<C>, "id">[];
     /**
-     * Show and write the entity's `serviceAccess` (or `service_access`), the
-     * user's service-wide grants, which the kit hides by default: an admin
-     * screen then edits grants through `adminUpdate` (a JSON field, checked by
-     * the entity's schema). Only a caller whose own service-wide grant on this
-     * service is `Admin` reads or writes it, whatever `access` gives a method;
-     * anyone else is refused a write, filter or sort naming it (`FORBIDDEN`)
-     * and gets rows without it. Such an Admin can grant any service,
-     * themself included, so give that grant only to those who may. With
-     * `auth.serviceAccessSource` naming the column, a change reaches the
-     * user's open sockets on every node at once (`qd:access`, their
-     * subscriptions resolved again), as any tracked write to it does. Only for
-     * an entity with such a field. Default `false`.
-     */
-    readonly grants?: [Extract<AdminFieldOf<C>, "serviceAccess" | "service_access">] extends [never] ? never : boolean;
+     * Show and write the entity's grants field, the user's service-wide
+     * grants, which the kit hides by default: `serviceAccess`,
+     * `service_access`, or the column `auth.serviceAccessSource` names on this
+     * service's model, whatever its name. An admin screen then edits grants
+     * through `adminUpdate` (a JSON field, checked by the entity's schema).
+     * Only a caller whose own service-wide grant on this service is `Admin`
+     * reads or writes it, whatever `access` gives a method; anyone else is
+     * refused a write, filter or sort naming it (`FORBIDDEN`) and gets rows
+     * without it. Such an Admin can grant any service, themself included, so
+     * give that grant only to those who may. With `auth.serviceAccessSource`
+     * naming the column, a change reaches the user's open sockets on every
+     * node at once (`qd:access`, their subscriptions resolved again), as any
+     * tracked write to it does. The dispatcher refuses `true` for an entity
+     * without a grants field, when it is made. Default `false`.
+     */
+    readonly grants?: boolean;
     /**
      * The only fields `adminCreate` and `adminUpdate` write (finding R1.4 of
      * the 5.0.0 review): `adminMeta` reports every other field `editable:
@@ -1273,9 +1345,10 @@ interface AdminHandlersOptions<C extends AnyContract, A, Db = unknown> {
      * The kit's methods whose access form is their whole check on purpose:
      * each gets `rowless: true`. On a service with an access policy,
      * `defineService` refuses `adminGet`, `adminUpdate` or `adminDelete`
-     * under a form below the default that checks no row (`{ service:
-     * "Moderate" }`, `"authenticated"`) unless it is named here, since any
-     * caller the form admits reaches any row by its id.
+     * under a form below the default that asks the policy nothing about the
+     * row its `id` names (`{ service: "Moderate" }`, `"authenticated"`,
+     * `custom`, `{ scope }`, or `{ entry }` on another key) unless it is named
+     * here, since any caller the form admits reaches any row by its id.
      */
     readonly rowless?: readonly AdminMethodsOf<C>[];
     /**
@@ -1411,11 +1484,18 @@ interface RedisAdapterOptions {
      */
     password?: string;
     /**
-     * Redis database number (default: 0)
+     * Redis database number (default: 0). It does not separate deployments:
+     * pub/sub is shared across a server's databases, so two deployments on one
+     * Valkey hear each other's events whatever their `db`; give each its own
+     * Valkey, or its own `cluster.keyPrefix` (docs/deploying.md).
      */
     db?: number;
     /**
-     * Key prefix for Socket.io adapter (default: 'socket.io')
+     * The adapter's key, which names its pub/sub channels. Default: the
+     * server's `cluster.keyPrefix` ("quickdraw" without one), so deployments
+     * with their own prefixes use their own channels. 5.1.0 and earlier used
+     * "socket.io": pass `keyPrefix: "socket.io"` for the deploy that moves a
+     * cluster from such nodes, so old and new nodes keep hearing each other.
      */
     keyPrefix?: string;
     /**