@spfn/core 0.3.0-beta.32 → 0.3.0-beta.34

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@spfn/core",
-    "version": "0.3.0-beta.32",
+    "version": "0.3.0-beta.34",
     "description": "Full-stack TypeScript backend for Next.js: file-based typed routes, Drizzle entities and repositories, PostgreSQL transactions and a generated end-to-end client, in one fixed vertical slice per feature",
     "type": "module",
     "exports": {

package/src/db/README.md

@@ -18,14 +18,14 @@ import {
     findOne, findMany, create, createMany, upsert,
     updateOne, updateMany, deleteOne, deleteMany, count,
     // Repository
-    BaseRepository, RepositoryError,
+    BaseRepository, TenantRepository, RepositoryError,
     // Connection (sub-module: manager/)
     initDatabase, getDatabase, closeDatabase, getDatabaseInfo,
     // Transactions (sub-module: transaction/)
     Transactional, runWithTransaction, getTransaction,
     onBeforeCommit, onAfterCommit, onAfterRollback,
     // Schema helpers (sub-module: schema/)
-    id, uuid, timestamps, foreignKey, enumText, typedJsonb, createSchema,
+    id, uuid, timestamps, foreignKey, tenantKey, enumText, typedJsonb, createSchema,
     // Error mapping
     fromPostgresError,
 } from '@spfn/core/db';
@@ -44,8 +44,9 @@ Everything re-exported from `@spfn/core/db` (`src/db/index.ts`):
 `findOne`, `findMany`, `create`, `createMany`, `upsert`, `updateOne`, `updateMany`,
 `deleteOne`, `deleteMany`, `count`
 
-**Repository** (`repository.ts`):
-`BaseRepository` (abstract class), `RepositoryError` (class), `RepositoryDatabase` (type)
+**Repository** (`repository.ts`, `tenant/`):
+`BaseRepository` (abstract class), `TenantRepository` (abstract class, tables shared by many
+tenants), `RepositoryError` (class), `RepositoryDatabase` (type), `CountOptions` (type)
 
 **PostgreSQL error mapping** (`postgres-errors.ts`):
 `fromPostgresError`
@@ -69,7 +70,7 @@ Types: `TransactionContext`, `TransactionDB`, `TransactionalOptions`,
 
 **Schema helpers** (sub-module — see [schema/README](./schema/README.md), re-exported via
 `export * from './schema'`):
-`id`, `uuid`, `timestamps`, `foreignKey`, `optionalForeignKey`, `auditFields`,
+`id`, `uuid`, `timestamps`, `foreignKey`, `optionalForeignKey`, `tenantKey`, `auditFields`,
 `publishingFields`, `softDelete`, `verificationTimestamp`, `utcTimestamp`, `enumText`,
 `typedJsonb`, `createSchema`, `packageNameToSchema`, `getSchemaInfo`
 
@@ -250,6 +251,7 @@ inside repository methods.
 |--------|---------|
 | `_findOne(table, where)` | `T \| null` |
 | `_findMany(table, options?)` | `T[]` |
+| `_findManyKeyset(table, { cursorColumn, limit, after?, order?, where? })` | `T[]` |
 | `_create(table, data)` | `T` |
 | `_createMany(table, data[])` | `T[]` |
 | `_upsert(table, data, { target, set? })` | `T` |
@@ -257,7 +259,12 @@ inside repository methods.
 | `_updateMany(table, where, data)` | `T[]` |
 | `_deleteOne(table, where)` | `T \| null` |
 | `_deleteMany(table, where)` | `T[]` |
-| `_count(table, where?)` | `number` |
+| `_count(table, where?, { cap? })` | `number` — with `cap`, at most `cap + 1` |
+
+`_count` with `cap` stops counting past `cap` rows: it reads at most `cap + 1` rows through a
+limited subquery, and a result of `cap + 1` means "more than `cap`". A list label such as
+"1,000+" needs nothing more, and the count no longer scans every matching row on each
+request.
 
 These are `protected` — calling `userRepo._findOne(...)` from outside is a TypeScript
 error. Expose a domain method (`findById`) instead.
@@ -324,6 +331,102 @@ export class UserRepository extends BaseRepository<AppRelations, AppDatabase>
 
 ---
 
+## TenantRepository (`tenant/`) — tables shared by many tenants
+
+For an app that keeps many tenants (workspaces, organizations, customers) in the same
+tables. Mark a table's tenant column with `tenantKey()`; extend `TenantRepository` instead of
+`BaseRepository`. Every method takes the tenant id first and writes the tenant condition
+into the query itself, so a query this class builds cannot reach another tenant's rows.
+Packages that never call `tenantKey()` are unaffected.
+
+```typescript
+import { createSchema, foreignKey, id, tenantKey, timestamps, TenantRepository } from '@spfn/core/db';
+import { index, text } from 'drizzle-orm/pg-core';
+import { eq } from 'drizzle-orm';
+
+const schema = createSchema('@acme/notes');
+
+export const authors = schema.table('authors', {
+    id: id(),
+    tenantId: tenantKey(),                          // tenant_id bigint not null
+    name: text('name').notNull(),
+}, (t) => [index('authors_tenant_id_idx').on(t.tenantId, t.id)]);
+
+export const notes = schema.table('notes', {
+    id: id(),
+    tenantId: tenantKey(),
+    authorId: foreignKey('author', () => authors.id),
+    title: text('title').notNull(),
+    ...timestamps(),
+}, (t) => [index('notes_tenant_id_idx').on(t.tenantId, t.id)]);
+
+export class NoteRepository extends TenantRepository
+{
+    async list(tenantId: number, after?: number)
+    {
+        return this._findManyKeyset(tenantId, notes, { cursorColumn: notes.id, after, limit: 50 });
+    }
+
+    async listWithAuthor(tenantId: number)
+    {
+        return this._select(tenantId, { title: notes.title, author: authors.name })
+            .from(notes)
+            .innerJoin(authors, eq(notes.authorId, authors.id));
+    }
+}
+```
+
+`listWithAuthor(7)` runs:
+
+```sql
+select "notes"."title", "authors"."name"
+from "acme_notes"."notes"
+inner join "acme_notes"."authors"
+    on ("notes"."author_id" = "authors"."id" and "authors"."tenant_id" = $1)
+where "notes"."tenant_id" = $2
+```
+
+| Method | Tenant handling |
+|--------|-----------------|
+| `_findOne(tenantId, table, where)` | added to WHERE |
+| `_findMany(tenantId, table, options?)` | added to WHERE |
+| `_findManyKeyset(tenantId, table, options)` | added to WHERE |
+| `_count(tenantId, table, where?, { cap? })` | added to WHERE |
+| `_create` / `_createMany(tenantId, table, data)` | written to the tenant column; a different tenant value in `data` throws, and `_createMany` checks every row before writing any |
+| `_upsert(tenantId, table, data, { target, set? })` | written to the tenant column; `target` must include the tenant column, `set` must not change it |
+| `_updateOne` / `_updateMany(tenantId, table, where, data)` | added to WHERE; `data` naming the tenant column throws |
+| `_deleteOne` / `_deleteMany(tenantId, table, where)` | added to WHERE |
+| `_select(tenantId, fields?)` | the `from` table in WHERE, each joined tenant-aware table in its ON clause |
+
+- **The tenant id must be a positive safe integer.** Anything else — `0`, `NaN`,
+  `undefined`, a string — throws before a query is built.
+- **Every method takes tenant-aware tables only.** An ordinary table throws; it can still be
+  joined in `_select`, where it gets no tenant condition.
+- **Joined tables get the condition in ON, not WHERE.** In WHERE, a left join's unmatched
+  rows would be filtered out and it would behave as an inner join. `_select` scopes
+  `innerJoin` and `leftJoin` (aliases included); `rightJoin`, `fullJoin`, `crossJoin`, the
+  lateral joins and set operators (`union`, … — the methods and the standalone functions)
+  throw — write those on `this.readDb`.
+- **A view cannot be joined.** A view's columns are its own, so `_select` cannot tell which
+  holds the tenant; joining one throws, as `.from(view)` does. Join the underlying table.
+- **The upsert target must include the tenant column.** With `target: [table.id]`, an insert
+  could collide with another tenant's row and update it.
+- **Update and delete still need a where of their own,** as in `BaseRepository`: the tenant
+  condition alone does not count, so a bare call cannot rewrite or delete a whole tenant.
+- **Index on the tenant column first.** `tenantKey()` cannot create an index (a Drizzle
+  column cannot); declare each index in the table's third argument starting with the tenant
+  column, e.g. `(tenant_id, id)` for keyset pages.
+- **`this.db` / `this.readDb` remain available and are not scoped,** nor is a subquery you
+  pass as a condition or join source. In local and development runs (`NODE_ENV` `local` or
+  `development`; an unset `NODE_ENV` is `local`), the database connection logs a warning —
+  once per SQL text, with the SQL — when a query reads, updates or deletes a tenant-aware
+  table without a condition on its tenant column. It reads SQL text, so it is a development
+  aid, not isolation: an alias it cannot resolve, a raw `sql` template or an unusual shape can
+  make it miss a query or warn about a scoped one. A failure inside the check never fails the
+  query. Other environments attach no logger.
+
+---
+
 ## Where clauses & query options (`query-utils.ts`)
 
 Both the helpers and `BaseRepository._*` methods accept the same two `where` forms,

package/src/db/schema/README.md

@@ -11,7 +11,7 @@ re-exported from `@spfn/core/db`. Import from there.
 ```typescript
 import {
     id, uuid, timestamps,
-    foreignKey, optionalForeignKey,
+    foreignKey, optionalForeignKey, tenantKey,
     auditFields, publishingFields, softDelete,
     verificationTimestamp, utcTimestamp, enumText, typedJsonb,
     createSchema, packageNameToSchema, getSchemaInfo,
@@ -36,6 +36,7 @@ Column helpers (`entity-helper.ts`):
 - `timestamps()` — `createdAt` + `updatedAt` (timestamptz, not null, both written by the database clock)
 - `foreignKey(name, reference, options?)` — required FK (bigint, cascade by default)
 - `optionalForeignKey(name, reference, options?)` — nullable FK (set null by default)
+- `tenantKey(name?)` — not-null bigint tenant column that makes a table tenant-aware (`tenant_id` by default)
 - `auditFields()` — `createdBy` + `updatedBy` (text, nullable)
 - `publishingFields()` — `publishedAt` (timestamptz, nullable) + `publishedBy` (text)
 - `softDelete()` — `deletedAt` (timestamptz, nullable) + `deletedBy` (text)
@@ -141,6 +142,23 @@ categoryId: optionalForeignKey('category', () => cats.id), // category_id BIGINT
 - There is **no** `onUpdate` option on these helpers. For `onUpdate` (or FK to a uuid PK),
   use drizzle's table-level `foreignKey({ columns, foreignColumns, onUpdate })` instead.
 
+### `tenantKey(name?)`
+
+The tenant column of a table that many tenants share: a not-null `bigint` (JS `number`),
+named `tenant_id` unless you pass a name. Declaring it makes the table tenant-aware —
+`TenantRepository` requires it and scopes every query to one tenant (see the
+[db README](../README.md#tenantrepository-tenant--tables-shared-by-many-tenants)). One per
+table; a second throws when the schema module loads. It creates no index — declare indexes
+in the table's third argument, each starting with the tenant column:
+
+```typescript
+export const notes = schema.table('notes', {
+    id: id(),
+    tenantId: tenantKey(),
+    title: text('title').notNull(),
+}, (t) => [index('notes_tenant_id_idx').on(t.tenantId, t.id)]);
+```
+
 ### `auditFields()`, `publishingFields()`, `softDelete()`
 
 ```typescript

package/src/event/README.md

@@ -59,7 +59,9 @@ From `@spfn/core/event/sse`:
 
 - `createSSEHandler(router, config?, tokenManager?)` — Hono GET handler
 - `SSETokenManager` (class), `CacheTokenStore` (class)
-- Types: `SSEToken`, `SSETokenStore`, `SSETokenManagerConfig`, `SSEMessage`,
+- `closeSSEConnectionsByKey(keyId)` — close the streams a device key opened, on every pod
+  (see [Closing the streams of a revoked device key](#closing-the-streams-of-a-revoked-device-key))
+- Types: `SSEToken`, `SSETokenStore`, `SSETokenManagerConfig`, `SSEKeyVerifier`, `SSEMessage`,
   `SSEHandlerConfig`, `SSEHandlerAuthConfig`, `SSEAuthConfig`, `SSEClientConfig`,
   `SSEEventHandler`, `SSEEventHandlers`, `SSESubscribeOptions`, `SSESubscriptionChange`,
   `SSEConnectionState`, `SSEUnsubscribe`, `ConnectedPayload`
@@ -269,10 +271,10 @@ can't ride along on the stream request. SPFN uses a **token exchange**: an authe
 ```
 Client                              Server
   │  POST /events/token (Bearer JWT) │  ← protected by config.middlewares (e.g. authenticate)
-  │ ───────────────────────────────► │  getSubject(c) → issue one-time token
+  │ ───────────────────────────────► │  getSubject(c), getKeyId(c) → issue one-time token
   │  ◄─────────────────────────────  │  { token: "..." }   (default TTL 30s)
   │  GET /events/stream?token=…&events=…
-  │ ───────────────────────────────► │  verify+consume token (one-time)
+  │ ───────────────────────────────► │  consume token (one-time) → verifyKey(keyId) when tagged
   │                                   │  → authorize(subject, events)
   │                                   │  → resolvePrincipal(subject, request)   (once)
   │                                   │  → event.canSubscribe(ctx)              (once per event)
@@ -295,7 +297,7 @@ export default defineServerConfig()
         auth: { enabled: true },
     })
     .build();
-// → POST /events/token   (mints token; subject = c.get('auth').userId by default)
+// → POST /events/token   (mints token; subject = c.get('auth').userId, keyId = c.get('auth').keyId by default)
 // → GET  /events/stream?token=…&events=…
 ```
 
@@ -359,6 +361,54 @@ export default defineServerConfig()
 ```
 
 When `tokenManager` is provided, `store`/`tokenTtl` are ignored (the external manager owns them).
+`@spfn/auth`'s manager also checks the device key at consume (`verifyKey`, below), so sharing it
+is what makes a token minted before a sign-out useless after it.
+
+### Closing the streams of a revoked device key
+
+A stream outlives the token that opened it: the token is checked once, at open, and pings keep
+the stream alive. So the token carries the **device key** it was minted for, and revoking that
+key ends what it opened.
+
+- **The token is tagged.** The token endpoint passes `getKeyId(c)` (default
+  `c.get('auth')?.keyId`; an app without `auth` is fine) to `issue(subject, { keyId })`. An
+  empty, `null` or `undefined` key leaves the token untagged — such a stream is never closed by
+  key. A non-device value (`'service'`) is stored as given; nothing asks to close it.
+- **A token minted before the revocation is refused at open.** `SSETokenManagerConfig.verifyKey`
+  runs when a tagged token is consumed; `false` or a throw refuses it (`401`). The token is
+  consumed first, so a refused token is never retried. The throw is warned without its text.
+- **`closeSSEConnectionsByKey(keyId)` ends the open ones.** It closes, on this process, every
+  stream whose token carried `keyId` — every `createSSEHandler` of the process, not one — and a
+  connect of that key still in admission ends at open, with no `connected` frame and no
+  subscription. With a cache (resolved lazily from `getCache()`, so a pod serving no events
+  publishes too) it then publishes `{ kind: 'close', keyId }` on the same control channel as
+  `grant` / `revoke`, `<channelPrefix>$control`
+  ([Multi-instance broadcast](#multi-instance-broadcast-cross-pod-fan-out)), so every other pod
+  whose events are wired through the cache closes its own — whatever events it serves; a pod
+  skips its own echo, and a close without a string `keyId` is malformed and ignored. A failed publish is warned and swallowed: the promise
+  always resolves. A close this pod cannot publish while the transport's breaker is open, or
+  whose publish fails, closes this pod's streams at once and is re-sent when the breaker
+  cooldown ends and whenever the next publish succeeds; while it is pending, the key's streams on
+  other pods stay open. A held close is lost only when the Redis outage outlasts this pod (its
+  shutdown disposes held closes) or when more than 1000 closes are held (the oldest are dropped);
+  those streams then stay open until they disconnect, and their next token mint is refused. At most 1000 closes wait; past
+  that the oldest is dropped, with a warning that gives the count. The log says how many closed and why — never the key id.
+
+```typescript
+import { closeSSEConnectionsByKey } from '@spfn/core/event/sse';
+import { onAfterCommit } from '@spfn/core/db';
+
+// after your own revocation statement
+onAfterCommit(() => closeSSEConnectionsByKey(revokedKeyId));
+```
+
+`@spfn/auth` does this for every key revocation (sign out one device, sign out everywhere,
+logout, password change and reset, account deletion, rotation, renewal, re-login): an app on
+`tokenManager: () => getOneTimeTokenManager()` gets it with no configuration change. The client
+whose stream closed reconnects within `reconnectDelay`; its token mint then answers `401` and
+it stops (`onClose('unauthorized')`, see the [client](#createauthsseclientconfig--with-auth-recommended)).
+A device whose key was *replaced* (rotation, renewal) reconnects with the new key, which the
+response installed meanwhile.
 
 ### Authorization hooks
 
@@ -553,6 +603,7 @@ client.subscribe({
 | `store` | `SSETokenStore` | auto (Cache → InMemory) | token storage backend |
 | `tokenManager` | `SSETokenManager \| () => SSETokenManager` | — | reuse an external manager (lazy resolver recommended); overrides `store`/`tokenTtl` |
 | `getSubject` | `(c: Context) => string \| null` | `c.get('auth')?.userId ?? null` | extract subject on the token endpoint |
+| `getKeyId` | `(c: Context) => string \| null \| undefined` | `c.get('auth')?.keyId` | the device key the token is tagged with; empty → untagged ([revoked keys](#closing-the-streams-of-a-revoked-device-key)) |
 | `authorize` | `(subject, events[]) => events[] \| Promise<…>` | — | subscription authorization (once on connect) |
 | `filter` | `{ [event]?: (subject, payload) => boolean }` | — | per-event payload filter |
 | `resolvePrincipal` | `(subject, request) => unknown \| Promise<unknown>` | — | principal for every `canSubscribe` (once per connection); a throw ⇒ `403` |
@@ -659,6 +710,13 @@ export const { GET, POST } = createRpcProxy({
 });
 ```
 
+**A `401` from the token mint is final.** When `acquireToken` rejects with an error whose
+`statusCode` (a registered class such as `UnauthorizedError`) or `status` (the api client's
+`ApiError`, and `createAuthSSEClient`'s own error) is `401`, the client closes the
+subscription and calls `onClose('unauthorized')` once, instead of reconnecting — the session
+is gone (its device key was revoked), and retrying would mint and fail every `reconnectDelay`
+forever. Any other rejection reconnects as before. `onClose` stays assignable from `() => void`.
+
 ### `subscribeToEvents(events, handlers, config?)` — one-shot helper
 
 ```typescript
@@ -742,7 +800,8 @@ payload can't serialize, the event is **still delivered to this pod's own subscr
 asymmetric case where the publish succeeds but **this pod's subscriber socket is down** (its
 echo — the only path to same-pod streams — wouldn't arrive). A sustained publish outage trips
 a short circuit breaker so emits fast-path to local instead of each paying the publish timeout.
-A publish never crashes `emit` or kills a stream. ioredis auto-reconnects and re-subscribes
+A publish never crashes `emit` or kills a stream. Events are not re-sent; a key close is (see
+`closeSSEConnectionsByKey`). ioredis auto-reconnects and re-subscribes
 (autoResubscribe, default true). A per-event SUBSCRIBE failure at
 startup degrades that event to in-process (logged) rather than aborting boot. Same-pod
 delivery costs one Redis round-trip — for a single-replica deploy with a cache, prefer
@@ -848,7 +907,8 @@ fully decoupled.
   this: on error with `acquireToken` set, it closes and reconnects through its own path to
   mint a fresh token. Don't disable `reconnect` expecting native retry to work with auth.
 - **Stream-time errors aren't subscription errors.** `authorize` returning `[]` ⇒ `403` at
-  connect; invalid event names ⇒ `400`; missing/expired token ⇒ `401`. `onError` on the
+  connect; invalid event names ⇒ `400`; missing/expired token, or one whose key `verifyKey`
+  refuses ⇒ `401`. `onError` on the
   client fires for transport-level drops, not for these HTTP rejections — check the network
   response when a connection never opens.
 - **Subject default.** Without a custom `getSubject`, the token endpoint reads

package/src/state/README.md

@@ -608,7 +608,7 @@ export function Shell({ initial, workspaceId }: { initial: StateClientInitial<ty
 | `current(id, key?)` | Synchronous: `{ at, value, data?, status }`, `{ status: 'revoked' }` for a state revoked before any value arrived, or `undefined`. The same frozen object until a change is applied |
 | `connection()` | Synchronous: the connection status ([Connection status](#connection-status)), a frozen object, the same reference until it changes |
 | `subscribeConnection(listener)` | Registers `listener(status)`, called with the new status on every change, after `connection()` returns it; returns its unsubscribe (idempotent). The same function subscribed twice is two subscriptions |
-| `retry()` | When `'failed'` or `'reconnecting'`: reads the first snapshot now (its retry count reset), or, once the manifest is known, reopens the stream now. A no-op when `'connected'`, while the first snapshot is in flight, and with nothing subscribed — after `close()` too, until a new `subscribe` |
+| `retry()` | When `'failed'`, `'reconnecting'` or `'closed'` (unauthorized — after the user signed in again): reads the first snapshot now (its retry count reset), or, once the manifest is known, reopens the stream now. A no-op when `'connected'`, while the first snapshot is in flight, and with nothing subscribed — after `close()` too, until a new `subscribe` |
 | `close()` | Closes the stream, drops every listener — connection listeners too — and stops listening to `online`; the status is back to `'reconnecting'` 0. Idempotent. A `subscribe` after it starts the client again, without `online`: `retry()` restarts it as before |
 
 `onError` receives a failure of something the client ran on its own — the first snapshot, the
@@ -695,6 +695,7 @@ first snapshot — so it says where they stand. `connection()` is one of:
 | `{ status: 'connected' }` | a stream is open (the SSE `onOpen`) |
 | `{ status: 'reconnecting', attempt }` | no stream open — not yet, or nothing subscribed — or the SSE client retrying a dropped one: `attempt` is its count (`onReconnect`), reset when a stream opens; `0` before the first stream opens, while the first snapshot is read or retried, and after `retry()` |
 | `{ status: 'failed' }` | the retries are exhausted: the SSE client's `maxReconnectAttempts` (its `onClose`, the attempts spent), or `maxRetries` for the first snapshot. Nothing more is tried until a restart (below) or, with the manifest unknown, a `get`, `write` or `snapshot` that brings it |
+| `{ status: 'closed', reason: 'unauthorized' }` | the stream's token mint answered `401` (the SSE client's `onClose('unauthorized')`): the session is gone — its device key was revoked, e.g. "sign out this device" from another one. No retry is set, and neither `online` nor a `subscribe` reopens it; only the app's own `retry()`, once the user signed in again, does |
 
 - **Start value** `{ status: 'reconnecting', attempt: 0 }`, a client built with `initial` too:
   its entries are ready, its stream is not.
@@ -715,10 +716,17 @@ first snapshot — so it says where they stand. `connection()` is one of:
 - **`close()`** sets `'reconnecting'` 0, drops the connection listeners and removes the
   `online` listener; its own teardown is not `'failed'`. A `subscribe` after it starts the
   client again, and `retry()` restarts it; `online` is not listened to again.
+- **`'closed'` / `'unauthorized'`** is not a network failure, so nothing restarts it on its
+  own: not `online`, not a `subscribe`. `retry()` reopens the stream (`'reconnecting'` 0); the
+  last unsubscribe resets the client to the start value, as from any status.
 
 ```tsx
 const connection = useConnectionStatus(state);
 
+if (connection.status === 'closed')
+{
+    return <Banner>You were signed out on this device.</Banner>;   // connection.reason === 'unauthorized'
+}
 if (connection.status === 'failed')
 {
     return <Banner action={() => state.retry()}>The server has a problem.</Banner>;