@fuzdev/fuz_app 0.140.0 → 0.142.0

package/dist/auth/cell_item_action_specs.js

@@ -13,6 +13,7 @@ import { z } from 'zod';
 import { Uuid, bounded_string } from '../primitive_schemas.js';
 import { FRACTIONAL_INDEX_LENGTH_MAX, FRACTIONAL_INDEX_REGEX } from '@fuzdev/fuz_util/fractional_index.ts';
 import { ActingActor } from '../http/auth_shape.js';
+import { CellRelationListLimit } from './cell_relation_list_limit.js';
 // -- Error reasons ----------------------------------------------------------
 /** Error reason — `cell_item_list` got neither `parent_id` nor `child_id`. */
 export const ERROR_CELL_ITEM_LIST_REQUIRES_PARENT_OR_CHILD = 'cell_item_list_requires_parent_or_child';
@@ -101,10 +102,11 @@ export const CellItemDeleteOutput = z.strictObject({
  * authz (child view-check gates the call; per-parent view-check filters
  * the rows).
  *
- * Forward listing supports cursor pagination via `position_after`
- * (return rows with `position > position_after`). The reverse listing
- * doesn't paginate (the result set is small in practice — number of
- * parents containing a given child).
+ * Either direction returns a page of up to `limit` items (default
+ * `CELL_RELATION_LIST_LIMIT_DEFAULT`) whose other end the caller can view —
+ * the view check runs before the limit. Forward listing pages on via
+ * `position_after` (return rows with `position > position_after`); the
+ * reverse listing has no cursor, oldest item first.
  */
 export const CellItemListInput = z
     .strictObject({
@@ -117,9 +119,7 @@ export const CellItemListInput = z
     position_after: CellItemPosition.optional().meta({
         description: 'Cursor for forward pagination — return rows whose position > this.'
     }),
-    limit: z.number().int().positive().max(500).optional().meta({
-        description: 'Page size cap (max 500). Omit for unbounded — explicit list calls escape the bundled `cell_get` cap.'
-    }),
+    limit: CellRelationListLimit,
     acting: ActingActor
 })
     .refine((v) => Boolean(v.parent_id) !== Boolean(v.child_id), {

package/dist/auth/cell_item_actions.d.ts

@@ -12,11 +12,12 @@
  *   collision-error shape as insert.
  * - `cell_item_delete` — admin / owner / editor-grant on `parent`.
  *   Idempotent: `deleted: false` when no row matched.
- * - `cell_item_list` — bidirectional. Forward (pass `parent_id`) is
- *   gated on `can_view_cell(parent)` and filters children to those the
- *   caller may view (strict target-visibility, batched). Reverse (pass
- *   `child_id`) has 2-layer authz: gate on `can_view_cell(child)`, then
- *   filter rows by `can_view_cell(parent)`.
+ * - `cell_item_list` — bidirectional, a page of up to `limit` items whose
+ *   other end the caller may view (filtered in SQL, before the limit).
+ *   Forward (pass `parent_id`) is gated on `can_view_cell(parent)` and
+ *   pages the items whose child is viewable (strict target-visibility).
+ *   Reverse (pass `child_id`) has 2-layer authz: gate on
+ *   `can_view_cell(child)`, then page the items whose parent is viewable.
  *
  * IDOR-mask 404s on cell-miss / cell-unviewable, mirroring the existence-
  * leak guards in `auth/cell_actions.ts`.

package/dist/auth/cell_item_actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cell_item_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_item_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAeN,KAAK,QAAQ,EACb,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EAMN,KAAK,WAAW,EAChB,MAAM,4BAA4B,CAAC;AAOpC,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAEnD,eAAO,MAAM,YAAY,GAAI,KAAK,WAAW,KAAG,QAS9C,CAAC;AAOH,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,GAAI,MAAM,kBAAkB,KAAG,KAAK,CAAC,SAAS,CA2KlF,CAAC"}
+{"version":3,"file":"cell_item_actions.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_item_actions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,0BAA0B,CAAC;AAGlC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD,OAAO,EAeN,KAAK,QAAQ,EACb,MAAM,6BAA6B,CAAC;AAMrC,OAAO,EAMN,KAAK,WAAW,EAChB,MAAM,4BAA4B,CAAC;AAOpC,MAAM,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAEnD,eAAO,MAAM,YAAY,GAAI,KAAK,WAAW,KAAG,QAS9C,CAAC;AAOH,iDAAiD;AACjD,eAAO,MAAM,wBAAwB,GAAI,MAAM,kBAAkB,KAAG,KAAK,CAAC,SAAS,CAwKlF,CAAC"}

package/dist/auth/cell_item_actions.js

@@ -12,11 +12,12 @@
  *   collision-error shape as insert.
  * - `cell_item_delete` — admin / owner / editor-grant on `parent`.
  *   Idempotent: `deleted: false` when no row matched.
- * - `cell_item_list` — bidirectional. Forward (pass `parent_id`) is
- *   gated on `can_view_cell(parent)` and filters children to those the
- *   caller may view (strict target-visibility, batched). Reverse (pass
- *   `child_id`) has 2-layer authz: gate on `can_view_cell(child)`, then
- *   filter rows by `can_view_cell(parent)`.
+ * - `cell_item_list` — bidirectional, a page of up to `limit` items whose
+ *   other end the caller may view (filtered in SQL, before the limit).
+ *   Forward (pass `parent_id`) is gated on `can_view_cell(parent)` and
+ *   pages the items whose child is viewable (strict target-visibility).
+ *   Reverse (pass `child_id`) has 2-layer authz: gate on
+ *   `can_view_cell(child)`, then page the items whose parent is viewable.
  *
  * IDOR-mask 404s on cell-miss / cell-unviewable, mirroring the existence-
  * leak guards in `auth/cell_actions.ts`.
@@ -31,8 +32,8 @@ import { jsonrpc_errors } from '../http/jsonrpc_errors.js';
 import { is_pg_unique_violation } from '../db/pg_error.js';
 import { cell_item_insert_action_spec, cell_item_move_action_spec, cell_item_delete_action_spec, cell_item_list_action_spec, ERROR_CELL_ITEM_POSITION_TAKEN } from './cell_item_action_specs.js';
 import { ERROR_CELL_NOT_FOUND } from './cell_action_specs.js';
-import { can_view_cell, can_edit_cell } from './cell_authorize.js';
-import { filter_visible_target_ids } from './cell_relation_visibility.js';
+import { can_view_cell, can_edit_cell, cell_viewer_from_auth } from './cell_authorize.js';
+import { CELL_RELATION_LIST_LIMIT_DEFAULT } from './cell_relation_list_limit.js';
 import { query_cell_get } from '../db/cell_queries.js';
 import { query_cell_grant_list_for_cell } from '../db/cell_grant_queries.js';
 import { query_cell_item_insert, query_cell_item_move, query_cell_item_delete, query_cell_item_list_for_parent, query_cell_item_list_for_child } from '../db/cell_item_queries.js';
@@ -160,8 +161,11 @@ export const create_cell_item_actions = (deps) => {
     };
     const list_handler = async (input, ctx) => {
         const auth = ctx.auth;
-        // Forward listing: gate on can_view_cell(parent), then filter the
-        // children to those the caller may view (strict target-visibility).
+        // an omitted limit is the default page, either direction
+        const limit = input.limit ?? CELL_RELATION_LIST_LIMIT_DEFAULT;
+        // Forward listing: gate on can_view_cell(parent), then page the items
+        // whose child the caller may view (strict target-visibility, in SQL
+        // before the limit).
         if (input.parent_id !== undefined) {
             const parent = await query_cell_get(ctx, input.parent_id);
             if (!parent) {
@@ -171,12 +175,8 @@ export const create_cell_item_actions = (deps) => {
             if (!can_view_cell(auth, parent, parent_grants)) {
                 throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
             }
-            const rows = await query_cell_item_list_for_parent(ctx, parent.id, {
-                limit: input.limit,
-                position_after: input.position_after
-            });
-            const visible_children = await filter_visible_target_ids(ctx, auth, rows.map((r) => r.child_id));
-            return { items: rows.filter((r) => visible_children.has(r.child_id)).map(to_item_json) };
+            const rows = await query_cell_item_list_for_parent(ctx, cell_viewer_from_auth(auth), parent.id, { limit, position_after: input.position_after });
+            return { items: rows.map(to_item_json) };
         }
         // Reverse listing: 2-layer authz. First, can_view_cell(child).
         const child = await query_cell_get(ctx, input.child_id);
@@ -187,13 +187,14 @@ export const create_cell_item_actions = (deps) => {
         if (!can_view_cell(auth, child, child_grants)) {
             throw jsonrpc_errors.not_found('cell', { reason: ERROR_CELL_NOT_FOUND });
         }
-        // Then filter rows by per-parent can_view_cell. Batched (not N+1):
-        // one bulk visibility filter over all parent ids, same as the forward
-        // branch. Bounded by `limit` at the query so a heavily inbound-linked
-        // child can't force an unbounded fetch on this public endpoint.
-        const rows = await query_cell_item_list_for_child(ctx, child.id, { limit: input.limit });
-        const visible_parents = await filter_visible_target_ids(ctx, auth, rows.map((r) => r.parent_id));
-        return { items: rows.filter((r) => visible_parents.has(r.parent_id)).map(to_item_json) };
+        // Then page the items whose parent the caller may view — filtered in
+        // SQL before the limit, so hidden parents never crowd out visible ones,
+        // and bounded so a heavily inbound-linked child can't force an
+        // unbounded read on this public endpoint.
+        const rows = await query_cell_item_list_for_child(ctx, cell_viewer_from_auth(auth), child.id, {
+            limit
+        });
+        return { items: rows.map(to_item_json) };
     };
     return [
         rpc_action(cell_item_insert_action_spec, insert_handler),

package/dist/auth/cell_relation_list_limit.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The page bound the two relation lists share — `cell_field_list` and
+ * `cell_item_list`, forward and reverse alike. A page is up to `limit` edges
+ * whose other end the caller can view. Both are public reads, so an omitted
+ * `limit` is the default page, never unbounded: anyone can pad a public
+ * cell's inbound links, and the reverse lists have no cursor.
+ *
+ * Twin of the Rust spine's `CELL_RELATION_LIST_LIMIT_MAX` /
+ * `CELL_RELATION_LIST_LIMIT_DEFAULT`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Cap on a relation-list page, forward and reverse alike. */
+export declare const CELL_RELATION_LIST_LIMIT_MAX = 500;
+/** The page size a relation list that omits `limit` gets, forward and reverse alike. */
+export declare const CELL_RELATION_LIST_LIMIT_DEFAULT = 50;
+/** The `limit` input of `cell_field_list` and `cell_item_list`. */
+export declare const CellRelationListLimit: z.ZodOptional<z.ZodNumber>;
+//# sourceMappingURL=cell_relation_list_limit.d.ts.map

package/dist/auth/cell_relation_list_limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell_relation_list_limit.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_relation_list_limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8DAA8D;AAC9D,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAEhD,wFAAwF;AACxF,eAAO,MAAM,gCAAgC,KAAK,CAAC;AAEnD,mEAAmE;AACnE,eAAO,MAAM,qBAAqB,4BAQ/B,CAAC"}

package/dist/auth/cell_relation_list_limit.js

@@ -0,0 +1,27 @@
+/**
+ * The page bound the two relation lists share — `cell_field_list` and
+ * `cell_item_list`, forward and reverse alike. A page is up to `limit` edges
+ * whose other end the caller can view. Both are public reads, so an omitted
+ * `limit` is the default page, never unbounded: anyone can pad a public
+ * cell's inbound links, and the reverse lists have no cursor.
+ *
+ * Twin of the Rust spine's `CELL_RELATION_LIST_LIMIT_MAX` /
+ * `CELL_RELATION_LIST_LIMIT_DEFAULT`.
+ *
+ * @module
+ */
+import { z } from 'zod';
+/** Cap on a relation-list page, forward and reverse alike. */
+export const CELL_RELATION_LIST_LIMIT_MAX = 500;
+/** The page size a relation list that omits `limit` gets, forward and reverse alike. */
+export const CELL_RELATION_LIST_LIMIT_DEFAULT = 50;
+/** The `limit` input of `cell_field_list` and `cell_item_list`. */
+export const CellRelationListLimit = z
+    .number()
+    .int()
+    .positive()
+    .max(CELL_RELATION_LIST_LIMIT_MAX)
+    .optional()
+    .meta({
+    description: `The most edges a page holds, each one whose other end the caller can view — forward and reverse alike: default ${CELL_RELATION_LIST_LIMIT_DEFAULT}, max ${CELL_RELATION_LIST_LIMIT_MAX}.`
+});

package/dist/auth/cell_relation_visibility.d.ts

@@ -6,9 +6,10 @@
  * target the caller cannot view — otherwise an editor of a public parent
  * could enumerate private children by id, or a public cell could leak the
  * existence of private linked cells. This helper bulk-loads the target
- * cells + their grants and runs `can_view_cell` per target in memory,
- * returning the set of viewable target ids. Batched (two queries for the
- * whole id-set) to avoid the N+1 a naive per-row check would cause.
+ * cells' view facts (`CELL_VIEW_COLUMNS` — never the `data` payload) and
+ * their grants, then runs `can_view_cell` per target in memory, returning
+ * the set of viewable target ids. Batched (two queries for the whole
+ * id-set) to avoid the N+1 a naive per-row check would cause.
  *
  * @module
  */

package/dist/auth/cell_relation_visibility.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cell_relation_visibility.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_relation_visibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,MAAM,cAAc,GAAG,IAAI,EAC3B,YAAY,aAAa,CAAC,IAAI,CAAC,KAC7B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAwBnB,CAAC"}
+{"version":3,"file":"cell_relation_visibility.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_relation_visibility.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,yBAAyB,GACrC,MAAM,SAAS,EACf,MAAM,cAAc,GAAG,IAAI,EAC3B,YAAY,aAAa,CAAC,IAAI,CAAC,KAC7B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAwBnB,CAAC"}

package/dist/auth/cell_relation_visibility.js

@@ -6,14 +6,15 @@
  * target the caller cannot view — otherwise an editor of a public parent
  * could enumerate private children by id, or a public cell could leak the
  * existence of private linked cells. This helper bulk-loads the target
- * cells + their grants and runs `can_view_cell` per target in memory,
- * returning the set of viewable target ids. Batched (two queries for the
- * whole id-set) to avoid the N+1 a naive per-row check would cause.
+ * cells' view facts (`CELL_VIEW_COLUMNS` — never the `data` payload) and
+ * their grants, then runs `can_view_cell` per target in memory, returning
+ * the set of viewable target ids. Batched (two queries for the whole
+ * id-set) to avoid the N+1 a naive per-row check would cause.
  *
  * @module
  */
 import { can_view_cell } from './cell_authorize.js';
-import { query_cell_load_many } from '../db/cell_queries.js';
+import { query_cell_view_load_many } from '../db/cell_queries.js';
 import { query_cell_grant_list_for_cells } from '../db/cell_grant_queries.js';
 /**
  * Return the subset of `target_ids` the caller may view.
@@ -33,7 +34,7 @@ export const filter_visible_target_ids = async (deps, auth, target_ids) => {
     if (target_ids.length === 0)
         return visible;
     const unique = [...new Set(target_ids)];
-    const cells = await query_cell_load_many(deps, unique);
+    const cells = await query_cell_view_load_many(deps, unique);
     // Grants only matter for authenticated callers — null auth admits via
     // the public branch alone, so skip the grant load entirely.
     const grants_by_cell = new Map();

package/dist/auth/cell_steward.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The steward read arm, with the governing-root load it needs.
+ *
+ * `can_steward_cell` (`auth/cell_authorize.ts`) is pure over
+ * `(auth, cell, root)`; `cell_steward_admits` is the composition every steward
+ * site runs after `can_view_cell` denies: it loads the governing root (active
+ * rows only, so a soft-deleted root stewards nothing) and applies the
+ * predicate. It short-circuits with no query unless the caller is
+ * authenticated and the cell is a pending or rejected contribution.
+ *
+ * **Where the steward arm applies** — the surfaces a moderator works from:
+ * `cell_get`, `cell_moderate` (whose root-authority check it lets a non-admin
+ * root owner reach), the cell-scoped fact route, and `cell_list`'s general
+ * predicate (the SQL twin in `query_cell_list`).
+ *
+ * **Where it must not** — every other read keeps `can_view_cell` alone:
+ * `cell_clone` (a steward copying a contribution out from under its
+ * moderation), the parent check on `cell_create` (a steward contributing under
+ * a pending post), the relation endpoint gates, `filter_visible_target_ids`
+ * (the `cell_get` bundle), the field / item lists' SQL view filter
+ * (`db/cell_view_sql.ts`),
+ * `cell_list`'s `shared_with` semi-join (a grant footprint, not a moderation
+ * queue), and `cell_grant_revoke`'s `still_admitted` recompute. Widening one of
+ * these is a decision, not a sweep. Twin of the Rust `fuz_cell::cell_steward`.
+ *
+ * @module
+ */
+import type { QueryDeps } from '../db/query_deps.js';
+import { type CellRow } from '../db/cell_queries.js';
+import type { RequestContext } from './request_context.js';
+/**
+ * Whether `auth` stewards `cell` — loads the governing root and applies
+ * `can_steward_cell`.
+ *
+ * Resolves `false` without a query for an unauthenticated caller, a root, or a
+ * cell whose moderation isn't `'pending'` / `'rejected'`; a missing or
+ * soft-deleted root is `false` too.
+ *
+ * @param deps - query deps
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell the caller couldn't otherwise view
+ * @returns whether the steward arm admits the caller
+ */
+export declare const cell_steward_admits: (deps: QueryDeps, auth: RequestContext | null, cell: CellRow) => Promise<boolean>;
+//# sourceMappingURL=cell_steward.d.ts.map

package/dist/auth/cell_steward.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell_steward.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/cell_steward.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAkB,KAAK,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAC/B,MAAM,SAAS,EACf,MAAM,cAAc,GAAG,IAAI,EAC3B,MAAM,OAAO,KACX,OAAO,CAAC,OAAO,CAMjB,CAAC"}

package/dist/auth/cell_steward.js

@@ -0,0 +1,53 @@
+/**
+ * The steward read arm, with the governing-root load it needs.
+ *
+ * `can_steward_cell` (`auth/cell_authorize.ts`) is pure over
+ * `(auth, cell, root)`; `cell_steward_admits` is the composition every steward
+ * site runs after `can_view_cell` denies: it loads the governing root (active
+ * rows only, so a soft-deleted root stewards nothing) and applies the
+ * predicate. It short-circuits with no query unless the caller is
+ * authenticated and the cell is a pending or rejected contribution.
+ *
+ * **Where the steward arm applies** — the surfaces a moderator works from:
+ * `cell_get`, `cell_moderate` (whose root-authority check it lets a non-admin
+ * root owner reach), the cell-scoped fact route, and `cell_list`'s general
+ * predicate (the SQL twin in `query_cell_list`).
+ *
+ * **Where it must not** — every other read keeps `can_view_cell` alone:
+ * `cell_clone` (a steward copying a contribution out from under its
+ * moderation), the parent check on `cell_create` (a steward contributing under
+ * a pending post), the relation endpoint gates, `filter_visible_target_ids`
+ * (the `cell_get` bundle), the field / item lists' SQL view filter
+ * (`db/cell_view_sql.ts`),
+ * `cell_list`'s `shared_with` semi-join (a grant footprint, not a moderation
+ * queue), and `cell_grant_revoke`'s `still_admitted` recompute. Widening one of
+ * these is a decision, not a sweep. Twin of the Rust `fuz_cell::cell_steward`.
+ *
+ * @module
+ */
+import { query_cell_get } from '../db/cell_queries.js';
+import { cell_moderation_is_stewardable } from '../db/cell_moderation.js';
+import { can_steward_cell } from './cell_authorize.js';
+/**
+ * Whether `auth` stewards `cell` — loads the governing root and applies
+ * `can_steward_cell`.
+ *
+ * Resolves `false` without a query for an unauthenticated caller, a root, or a
+ * cell whose moderation isn't `'pending'` / `'rejected'`; a missing or
+ * soft-deleted root is `false` too.
+ *
+ * @param deps - query deps
+ * @param auth - request context, or `null` for unauthenticated callers
+ * @param cell - the cell the caller couldn't otherwise view
+ * @returns whether the steward arm admits the caller
+ */
+export const cell_steward_admits = async (deps, auth, cell) => {
+    if (auth === null || cell.root_id === null)
+        return false;
+    if (!cell_moderation_is_stewardable(cell.moderation))
+        return false;
+    const root = await query_cell_get(deps, cell.root_id);
+    if (!root)
+        return false;
+    return can_steward_cell(auth, cell, root);
+};

package/dist/auth/cleanup.d.ts

@@ -22,12 +22,12 @@
  * stream ends). Otherwise a swept session's connections would be reachable
  * only by an account-wide revocation.
  *
- * The contract that follows: **a connection outlives its session's expiry by
- * at most one cleanup interval** (plus the pass itself). In a process that
- * does not schedule the sweep, expiry ends no connection at all. The contract
- * is for sessions only: an expired API token's row is not swept, so nothing
- * here closes a connection opened on one — and `account_token_revoke` still
- * finds the row to close for.
+ * The sweep's close is the second on expiry, not the first: every connection
+ * already closes at its credential's deadline (`auth/credential_deadline.ts`)
+ * in the process holding it, whether or not a sweep runs. The sweep is for
+ * sessions only: an expired API token's row is not swept — its connections
+ * close at their deadline, and `account_token_revoke` still finds the row to
+ * close for.
  *
  * The closes run after the delete's commit, which is the rule every
  * revocation close keeps (see `actions/connection_closer.ts`). An expired
@@ -118,9 +118,9 @@ import type { AuditEmitter } from './audit_emitter.js';
  * `DEFAULT_AUTH_CLEANUP_INTERVAL`.
  *
  * An expired session or offer is already refused by every check that reads
- * it, so the interval bounds three things: how long a connection outlives
- * the expiry of the session it opened on, how late an offer expiry's audit
- * row lands, and how long dead rows linger.
+ * it, and a connection closes at its credential's deadline on its own, so the
+ * interval bounds two things: how late an offer expiry's audit row lands, and
+ * how long dead rows linger.
  */
 export declare const DEFAULT_AUTH_CLEANUP_INTERVAL_MS: number;
 /**

package/dist/auth/cleanup.js

@@ -22,12 +22,12 @@
  * stream ends). Otherwise a swept session's connections would be reachable
  * only by an account-wide revocation.
  *
- * The contract that follows: **a connection outlives its session's expiry by
- * at most one cleanup interval** (plus the pass itself). In a process that
- * does not schedule the sweep, expiry ends no connection at all. The contract
- * is for sessions only: an expired API token's row is not swept, so nothing
- * here closes a connection opened on one — and `account_token_revoke` still
- * finds the row to close for.
+ * The sweep's close is the second on expiry, not the first: every connection
+ * already closes at its credential's deadline (`auth/credential_deadline.ts`)
+ * in the process holding it, whether or not a sweep runs. The sweep is for
+ * sessions only: an expired API token's row is not swept — its connections
+ * close at their deadline, and `account_token_revoke` still finds the row to
+ * close for.
  *
  * The closes run after the delete's commit, which is the rule every
  * revocation close keeps (see `actions/connection_closer.ts`). An expired
@@ -117,9 +117,9 @@ import { query_audit_log } from './audit_log_queries.js';
  * `DEFAULT_AUTH_CLEANUP_INTERVAL`.
  *
  * An expired session or offer is already refused by every check that reads
- * it, so the interval bounds three things: how long a connection outlives
- * the expiry of the session it opened on, how late an offer expiry's audit
- * row lands, and how long dead rows linger.
+ * it, and a connection closes at its credential's deadline on its own, so the
+ * interval bounds two things: how late an offer expiry's audit row lands, and
+ * how long dead rows linger.
  */
 export const DEFAULT_AUTH_CLEANUP_INTERVAL_MS = 10 * 60 * 1000;
 /**

package/dist/auth/credential_deadline.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The credential deadline — the moment a resolved credential stops
+ * authenticating, which a long-lived connection opened on it must not outlive.
+ *
+ * A WebSocket or an SSE stream is authorized once, at open, and closed on
+ * revocation by identity. Expiry has no revocation event: nothing is written
+ * when a session or token passes its `expires_at`. So the auth middleware
+ * computes the deadline once (`CREDENTIAL_DEADLINE_KEY`, gathered onto
+ * `ResolvedAuth.credential_deadline`) and the transport closes the connection
+ * when it arrives (`schedule_credential_deadline`).
+ *
+ * The deadline is the earliest of what the credential carries:
+ *
+ * - **Session** — the signed cookie's embedded expiry and the `auth_session`
+ *   row's `expires_at`.
+ * - **API token** — the `api_token` row's `expires_at`; an eternal token
+ *   (`expires_at IS NULL`) has none.
+ * - **Daemon token** — none: it has no row and no expiry, and a rotation
+ *   closes no connection.
+ *
+ * A row's expiry is read as **remaining time measured on the database clock**
+ * (`EXPIRES_IN_MS_SQL`, `expires_at - NOW()` in the same statement that checks
+ * `expires_at > NOW()`), then anchored to this process's monotonic clock
+ * (`performance.now()`) — so a skew between the database's clock and the
+ * server's moves no deadline. The cookie's expiry is a wall-clock second this
+ * server signed, read against the same wall clock the cookie check reads.
+ *
+ * The monotonic clock stops while the host is suspended, so a deadline on it
+ * alone would hold a connection past its credential by the time asleep. The
+ * wait (`schedule_credential_deadline`) therefore also carries the deadline on
+ * the wall clock (`Date.now()`), which keeps running through a suspend, and
+ * fires at whichever is reached first: after a resume, within one timer step
+ * (`CREDENTIAL_DEADLINE_TIMER_CAP_MS`, an hour). The wall deadline is taken
+ * from the time left when the wait starts, so a skew between the database's
+ * clock and the server's still moves nothing. A wall clock stepped forward
+ * can fire it early; the client reconnects through the gates, the fail-closed
+ * side of the trade.
+ *
+ * The twin of the Rust spine's `fuz_auth::ResolvedAuth::credential_deadline`
+ * and `fuz_realtime`'s deadline wait.
+ *
+ * @module
+ */
+/**
+ * SQL expression for a row's remaining lifetime in milliseconds, measured on
+ * the database clock — `NULL` when `expires_at` is `NULL` (an eternal API
+ * token). `float8`, so every driver reads it as a JS number.
+ */
+export declare const EXPIRES_IN_MS_SQL = "(EXTRACT(EPOCH FROM (expires_at - NOW())) * 1000)::float8";
+/**
+ * The longest single timer the deadline wait sets — one hour, far inside
+ * `setTimeout`'s ceiling (2^31 - 1 ms, about 24.8 days, past which a timer
+ * fires at once) and the Rust twin's tokio ceiling, and short enough that a
+ * resume from suspend is noticed within it. A longer deadline is reached
+ * through several.
+ */
+export declare const CREDENTIAL_DEADLINE_TIMER_CAP_MS = 3600000;
+/**
+ * The deadline `now` plus the shortest of `remaining_ms`, as a monotonic
+ * `performance.now()` timestamp, or `null` when no entry carries one.
+ *
+ * A negative or `NaN` entry — a row its own `expires_at > NOW()` check
+ * already refused, read at the boundary — counts as zero.
+ *
+ * @param remaining_ms - each source's remaining lifetime in ms, `null` for none
+ * @param now - the monotonic clock reading to anchor to
+ * @returns the deadline, or `null` for a credential with no expiry
+ */
+export declare const credential_deadline_after: (remaining_ms: ReadonlyArray<number | null>, now?: number) => number | null;
+/**
+ * The next timer toward `deadline` from `now`: what remains, capped at
+ * `CREDENTIAL_DEADLINE_TIMER_CAP_MS`, or `null` once the deadline is reached.
+ *
+ * @param deadline - the monotonic deadline
+ * @param now - the monotonic clock reading
+ * @returns the next delay in ms, or `null` when the deadline has passed
+ */
+export declare const next_credential_deadline_delay: (deadline: number, now: number) => number | null;
+/**
+ * Call `on_expire` once `deadline` has passed, waiting in timers of at most
+ * `CREDENTIAL_DEADLINE_TIMER_CAP_MS`, each re-reading the clock against the
+ * absolute deadline — so a session's 30 days (past `setTimeout`'s ceiling)
+ * does not fire at once. Each wake-up also checks the same deadline on the
+ * wall clock, so a host suspend, which stops the monotonic clock, delays the
+ * close by at most one timer after the resume (module doc).
+ *
+ * A `null` deadline schedules nothing. The returned function cancels the wait
+ * and is safe to call more than once, before or after it fires.
+ *
+ * @param deadline - the monotonic deadline (`ResolvedAuth.credential_deadline`)
+ * @param on_expire - run once, when the deadline passes
+ * @returns a cancel function
+ */
+export declare const schedule_credential_deadline: (deadline: number | null, on_expire: () => void) => (() => void);
+//# sourceMappingURL=credential_deadline.d.ts.map

package/dist/auth/credential_deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential_deadline.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/credential_deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,8DAA8D,CAAC;AAE7F;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,UAAY,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACrC,cAAc,aAAa,CAAC,MAAM,GAAG,IAAI,CAAC,EAC1C,MAAK,MAA0B,KAC7B,MAAM,GAAG,IAQX,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,GAAI,UAAU,MAAM,EAAE,KAAK,MAAM,KAAG,MAAM,GAAG,IAIvF,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAU,MAAM,GAAG,IAAI,EACvB,WAAW,MAAM,IAAI,KACnB,CAAC,MAAM,IAAI,CA2Bb,CAAC"}