@ultimat3/realtime 22.0.0 → 22.1.0

package/CLAUDE.md

@@ -149,6 +149,9 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **A hub that closed opens nothing**: `close()` sets `#closed` before the walk; `#open` closes a
   late subscription and RAISES `X_TRANSPORT_UNAVAILABLE`. `#release` takes the reserved bridge, never
   a name.
+- **An upgrade from a foreign page is `403 X_SOCKET_ORIGIN_REFUSED`** before `authenticate`
+  (`sync-origin.ts`, core's `proveSameOrigin`); `AcceptBudget` is reserved before `authenticate`,
+  `refund()`ed on every exit that takes no socket.
 - **A socket's actor comes from `createSyncNode({ authenticate })` only**, run before
   `server.upgrade`. `null` = 401 `X_SOCKET_UNAUTHENTICATED`; a throw = 503
   `X_SOCKET_AUTH_UNAVAILABLE`. Absent = anonymous, and `start()` warns. The actor lives only in the
@@ -188,16 +191,22 @@ Tier 3 package. Channels, live queries, local-first sync. One protocol for all t
 - **The pump has one way out, `#die`**, which records the failure, stops the confirm timer, closes and
   nulls the connection. `start()` awaits the previous pump before it dials. **`stop()` releases
   everything before it reports anything.**
-- **`REPLICA IDENTITY FULL` is checked at preflight, warned, and counted — never thrown** — ahead of
-  `pg_create_logical_replication_slot`. `ReplicationStreamStats.partialBefore` reads
-  `PgRelation.replicaIdentity`, never the tuple.
+- **The replicator ensures its publication** (`pg-publication.ts`, from preflight): `CREATE … FOR
+  TABLE` every entity table, or `ALTER … ADD TABLE` the missing; never a DROP, never `FOR ALL
+  TABLES`. Only a server ErrorResponse becomes the refusal. No not-live declaration exists.
+- **A fix handing over `REPLICATION` carries `REPLICATION_GRANT_WARNING`** (cluster-wide grant).
+- **TLS is libpq's `sslmode`** (`pg-tls.ts`): only `verify-*` verify; the runtime never rejects
+  (`rejectUnauthorized: false`), `judgeHandshake` decides; the raw socket is DEAF after
+  `upgradeTLS` (Bun feeds it ciphertext).
+- **Only a table with NO replica identity is warned** (`NOTHING`, or keyless `DEFAULT`), before the
+  slot. A keyed DEFAULT table is correct: the window decides (`pg-identity-window.live.test.ts`).
 - **Every session pins `datestyle=ISO`, `intervalstyle=postgres`, `extra_float_digits=3`** in the
-  startup packet (`pg-connection.ts`, pinned by `pg-connection.test.ts`), byte for byte what
-  Postgres' own walreceiver sends.
-- A change lsn is `<16 hex commit position><8 hex row position>`; never order by either half alone,
-  never depend on wall time or a process counter.
+  startup packet (`pg-connection.ts`), as Postgres' own walreceiver does.
+- A change lsn is `<16 hex commit position><8 hex row position>`; never order by one half, a wall
+  time or a counter.
 - Slot, publication and entity names match `[a-z_][a-z0-9_]*` before interpolation — a security
-  boundary. A SQLSTATE is data: `pg-wire.ts`'s `FIXES` is read with `Object.hasOwn`.
+  boundary (`pg-identifier.ts`, the one `assertIdentifier`). A SQLSTATE is data: `pg-wire.ts`'s
+  `FIXES` is read with `Object.hasOwn`.
 - **A live row equals a repository row**: `pg-entity-row.ts` decodes through `@ultimat3/entity`'s
   own `decodeRow` / `entityForTable`, so money (three physical columns), scale and every other kind
   fold exactly as `postgresRepo` folds them.

package/README.md

@@ -316,7 +316,23 @@ never stumbled into.
 On drain, `drainPlan()` gives every client its own jittered slot in a spread window and the node
 sends a `reconnect` frame carrying that delay — clients redistribute instead of stampeding.
 `AcceptBudget` is the receiving node's token bucket, and a refusal always carries a retry delay,
-because refusing without one just moves the herd next door.
+because refusing without one just moves the herd next door. **A token is reserved before `authenticate`
+and refunded on every exit that takes no socket** (22.1.0): a 401, an authenticator that throws, a
+shed after it, an upgrade that did not take. Reserved first, so a reconnect herd reaches the token
+service bounded by the burst; refunded, because spent-and-kept, one client dialling with no
+credential drained the bucket and every signed-in reconnect behind it was shed. Not per client IP:
+behind an ingress every dial has the ingress's address, and a forwarded header is the caller's own
+claim.
+
+**A socket from a foreign page is refused** — `403 X_SOCKET_ORIGIN_REFUSED`, before `authenticate`
+and before the budget. A websocket carries the session cookie and no CORS applies to it, so a page on
+a sibling host (same-site, which `SameSite=Lax` does not stop) could open one as its visitor. The
+rule is `@ultimat3/core`'s `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks, with two
+admissions of the node's own (`sync-origin.ts`): no `Origin` header (RFC 6455 has every browser send
+one, so its absence is not a browser), and the node's own host name at any port or scheme (cookies
+are not port-isolated, and the Compose rung serves the page on `:3000` and the node on `:3001`). A
+page on another host is admitted by `createSyncNode({ allowedOrigins })` — the CLI passes
+`APP_URL`'s origin.
 
 The client dials itself back. A closed socket arms one timer — the node's delay when a `reconnect`
 frame assigned one, otherwise `@ultimat3/core`'s `backoffDelay()` on the client's `BackoffPolicy` — and that timer calls `connect()`, which re-subscribes
@@ -506,7 +522,11 @@ wire twice by a reconnect that raced an ack.
   (SCRAM-SHA-256, in-band TLS, CopyBoth), no driver dependency. It preflights `wal_level`, the
   publication, every entity's replica identity and the slot — in that order, because the identity
   check is worthless once the slot exists — creates the slot when there is none, and confirms the
-  slot as it goes so the WAL does not grow without bound. `InMemoryChangeFeed` + `InProcessTransport` remain the
+  slot as it goes so the WAL does not grow without bound. **The publication is ensured, not merely
+  checked** (`pg-publication.ts`): missing, it is created `FOR TABLE` every entity table; present,
+  it gains the entity tables it lacks (`ALTER PUBLICATION … ADD TABLE`) and loses none. `FOR TABLE`
+  because a table's owner may publish it without a superuser; a role that may not is refused with
+  `X_REPLICATION_FAILED` and the statement to run as one that may. `InMemoryChangeFeed` + `InProcessTransport` remain the
   defaults for `x dev` and every test.
 - **`selectChangeFeed(env, { entities })` decides which feed a boot installs** — same law
   `selectMailDriver` follows: an unset variable means the embedded default. It returns `{ feed,
@@ -519,6 +539,25 @@ wire twice by a reconnect that raced an ack.
   wrong database's WAL would be silently wrong forever. `REPLICATION_SLOT` (default `x_replicator`)
   and `REPLICATION_PUBLICATION` (default `x_changes`) name the slot and publication, both checked
   against `[a-z_][a-z0-9_]*` before they reach a replication command.
+- **TLS follows libpq's `sslmode`** (`pg-tls.ts`, 22.1.0): `disable`; `allow`, `prefer` (the
+  default) and `require` encrypt and verify **nothing**; `verify-ca` checks the chain;
+  `verify-full` the chain and the host name. `sslrootcert=<path>` is the only trust anchor when
+  set (and turns `require` into `verify-ca`, as libpq does); `sslrootcert=system` means the runtime
+  store and `verify-full`. With neither, the runtime store is used — it honours
+  `NODE_EXTRA_CA_CERTS`; libpq's `~/.postgresql/root.crt` is never read. `allow` is served as
+  `prefer` (TLS offered first), never cleartext first. The runtime never rejects on its own
+  (`rejectUnauthorized: false`); the handshake's report is judged per mode, and a failure is
+  `X_REPLICATION_TLS` naming the check. Until 22.1.0 `prefer` verified — every private-CA server
+  (CNPG) failed as a refused write — and the raw socket kept feeding ciphertext to the reader
+  after the upgrade, so a trusted CA still hung the stream.
+- **`REPLICATION` is a cluster-wide grant.** A `replication=database` session may also run
+  `BASE_BACKUP` and `START_REPLICATION PHYSICAL` with no database check, so on a shared Postgres
+  cluster the role could copy every database, `pg_authid` included, drop other slots and exhaust
+  the walsenders. Run the replicator against a cluster dedicated to the app, or give it its own role
+  through `REPLICATION_URL` with `pg_hba.conf`'s `replication` lines restricted to it — never grant
+  `REPLICATION` to an app role on a shared cluster. Every fix line that hands the grant over says
+  so (`REPLICATION_GRANT_WARNING`, `pg-wire.ts`) and links
+  [`docs/ops/01-kubernetes.md`](../../docs/ops/01-kubernetes.md#replication-is-a-cluster-wide-grant).
 - **`PgAdvisoryLock` is the production `AdvisoryLock`** — `SELECT
   pg_try_advisory_lock(hashtext('x:replicator:<slot>'))` on its own session. Session-scoped, so a
   crashed replicator releases it automatically: no lease renewal, no fencing token, no split brain.
@@ -553,18 +592,17 @@ wire twice by a reconnect that raced an ack.
   *transactions* in commit order, so per-record WAL positions are not monotonic across them. The
   pair sorts in delivery order and is byte-identical on replay, which is what turns at-least-once
   redelivery into a drop instead of a duplicate.
-- **A live query needs `REPLICA IDENTITY FULL`, and the replicator now says so** (`As of
-  2026-08-19`). Deciding whether a row *left* a result set needs the old values; with the default
-  identity a delete replicates only the key columns, and `toRow` accepts that tuple because it only
-  requires a text `id`. `preflight` asks `pg_class.relreplident` for every entity in the list — the
-  fourth question it asks, and **before** `pg_create_logical_replication_slot`, since changing the
-  identity after a slot exists does not reach the rows that slot will decode. It is a **coded
-  warning**, `X_LIVE_REPLICA_IDENTITY`, whose `fix:` is the `ALTER TABLE <t> REPLICA IDENTITY FULL;`
-  per named table — not a throw, because every app on the default identity would otherwise stop
-  booting, which is worse than the partial rows. `ReplicationStreamStats.partialBefore` is the
-  running half: one per change delivered off a relation that is not FULL, so the decisions it
-  actually cost are countable rather than silent. A hard refusal at `x verify` time is the
-  follow-up.
+- **A keyed table does not need `REPLICA IDENTITY FULL`; a table with NO identity is warned**
+  (`As of 2026-09-23`). Under DEFAULT an update carries no old tuple and a delete only the key, and
+  neither decides a live query: the shared window holds the whole row, so a row leaving the result
+  set is decided from the window and a delete by `holds(id)` — proved on real WAL by
+  `pg-identity-window.live.test.ts` (out of the filter, into it, delete, a row never held).
+  `preflight`'s fourth question, **before** `pg_create_logical_replication_slot`, names only the
+  entity tables with no identity (`NOTHING`, or `DEFAULT` with no primary key), whose `UPDATE` and
+  `DELETE` Postgres refuses once published: a **coded warning**, `X_LIVE_REPLICA_IDENTITY`, fix
+  `ALTER TABLE <t> REPLICA IDENTITY FULL;` per table — not a throw. Until 22.1.0 it named every
+  table not on FULL, on every boot. `ReplicationStreamStats.partialBefore` still counts changes off
+  a non-FULL relation — a volume figure, not a correctness one.
 - The record store is **per page**, in memory, and it is not a query cache: it answers "what is
   record X now", never "have I run this query before". Nothing evicts by time or size — a record
   lives as long as something holds it. Persisting it (IndexedDB) is plan 101 slice 12.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "22.0.0",
+  "version": "22.1.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -38,9 +38,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "22.0.0",
-    "@ultimat3/entity": "22.0.0",
-    "@ultimat3/query": "22.0.0",
+    "@ultimat3/core": "22.1.0",
+    "@ultimat3/entity": "22.1.0",
+    "@ultimat3/query": "22.1.0",
     "nats": "2.29.3"
   }
 }

package/src/errors.ts

@@ -34,6 +34,8 @@ export const REALTIME_OWNED_ERROR_CODES = [
   'X_SOCKET_UNAUTHENTICATED',
   'X_SOCKET_AUTH_UNAVAILABLE',
   'X_REALTIME_TOPOLOGY',
+  'X_REPLICATION_TLS',
+  'X_SOCKET_ORIGIN_REFUSED',
 ] as const;
 
 /**
@@ -138,10 +140,12 @@ export const REALTIME_ERROR_TITLES: Readonly<Record<RealtimeOwnedErrorCode, stri
   X_LIVE_SERVER_RENDER: 'a browser-only live operation ran during a server render',
   X_LIVE_ROW_UNIDENTIFIED: 'a live query returned a row with no id',
   X_LIVE_QUERY_UNKNOWN: 'no live query is registered under the name a subscribe frame asked for',
-  X_LIVE_REPLICA_IDENTITY: 'a replicated table sends a key-only row on delete',
+  X_LIVE_REPLICA_IDENTITY: 'a replicated table has no replica identity',
   X_SOCKET_UNAUTHENTICATED: 'the sync upgrade carried no credential this app accepts',
   X_SOCKET_AUTH_UNAVAILABLE: 'the sync node could not decide who a connecting socket is',
   X_REALTIME_TOPOLOGY: 'a sync node boots on a real database with no reachable change feed',
+  X_REPLICATION_TLS: 'the replication connection failed TLS',
+  X_SOCKET_ORIGIN_REFUSED: 'the websocket upgrade came from another origin',
 };
 
 // One unconditional call, so a second package claiming one of realtime's codes throws
@@ -172,6 +176,7 @@ export {
   ReplicaIdentityError,
   ReplicationFailedError,
   ReplicationProtocolError,
+  ReplicationTlsError,
   ReplicatorSlotHeldError,
 } from './replication-errors';
 
@@ -351,6 +356,22 @@ export class SocketUnauthenticatedError extends RealtimeError {
   }
 }
 
+/**
+ * A browser page on another origin asked for a socket. No CORS applies to a websocket and the
+ * session cookie rides it, so admitting the upgrade would open a socket AS the visitor for a page
+ * that is not this app — cross-site websocket hijacking. Decided before `authenticate` and before
+ * the accept budget, so a hostile page costs neither.
+ */
+export class SocketOriginRefusedError extends RealtimeError {
+  constructor(args: { reason: string }) {
+    super({
+      code: 'X_SOCKET_ORIGIN_REFUSED',
+      cause: `the websocket upgrade was refused: ${args.reason}`,
+      fix: 'export APP_URL="https://www.example.com"   # on the sync role: the origin the page is served on (or createSyncNode({ allowedOrigins }))',
+    });
+  }
+}
+
 /**
  * `authenticate` raised instead of deciding. The same rule the row gate follows: a failure is not a
  * denial, so the client is told to come back rather than told it may not connect — a token service

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   ReplicaIdentityError,
   ReplicationFailedError,
   ReplicationProtocolError,
+  ReplicationTlsError,
   ReplicatorSlotHeldError,
   ServerRenderLiveError,
   SubscriptionLimitError,

package/src/pg-identifier.ts

@@ -0,0 +1,23 @@
+// Single responsibility: the identifier charset every replication statement interpolates through.
+// Its own module because the preflight and the publication both assert through it, and either
+// importing the other for it would close a cycle.
+
+import { ReplicationFailedError } from './errors';
+
+/** Identifiers reach a simple query unparameterised, so the charset is the injection boundary. */
+const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
+
+/**
+ * The one gate between a caller-supplied name and a simple query. `PgReplicationStream` checks its
+ * slot, publication and entity names in its CONSTRUCTOR — a mistyped `REPLICATION_SLOT` is a
+ * boot-time fact, and finding it at the first WAL read means a replicator that reported itself
+ * started and then never delivered a change.
+ */
+export const assertIdentifier = (kind: string, value: string): string => {
+  if (IDENTIFIER.test(value)) return value;
+  throw new ReplicationFailedError({
+    stage: 'preflight',
+    detail: `${kind} "${value}" is not a lower-case postgres identifier`,
+    fix: `rename the ${kind} to match [a-z_][a-z0-9_]* — it is interpolated into a replication command`,
+  });
+};

package/src/pg-preflight.ts

@@ -1,35 +1,20 @@
-// Single responsibility: the four questions asked of a database BEFORE `START_REPLICATION`, and
-// the identifier charset every one of them interpolates through. Three refuse the boot with the
-// exact statement that fixes them; the fourth warns, because refusing it would stop every app on
-// the default replica identity from starting.
+// Single responsibility: the four questions asked of a database BEFORE `START_REPLICATION`. Two
+// refuse the boot with the exact statement that fixes them, one — the publication — is answered by
+// ensuring it (`pg-publication.ts`), and the fourth warns, because refusing it would stop every app
+// on the default replica identity from starting.
 
 import { logger } from '@ultimat3/core';
 import { ReplicaIdentityError, ReplicationFailedError } from './errors';
 import type { PgConnection } from './pg-connection';
-
-/** Identifiers reach a simple query unparameterised, so the charset is the injection boundary. */
-const IDENTIFIER = /^[a-z_][a-z0-9_]*$/;
-
-/**
- * The one gate between a caller-supplied name and a simple query. Exported because
- * `PgReplicationStream` checks its slot, publication and entity names in its CONSTRUCTOR — a
- * mistyped `REPLICATION_SLOT` is a boot-time fact, and finding it at the first WAL read means a
- * replicator that reported itself started and then never delivered a change.
- */
-export const assertIdentifier = (kind: string, value: string): string => {
-  if (IDENTIFIER.test(value)) return value;
-  throw new ReplicationFailedError({
-    stage: 'preflight',
-    detail: `${kind} "${value}" is not a lower-case postgres identifier`,
-    fix: `rename the ${kind} to match [a-z_][a-z0-9_]* — it is interpolated into a replication command`,
-  });
-};
+import { assertIdentifier } from './pg-identifier';
+import { ensurePublication } from './pg-publication';
 
 /**
- * The four things that are always misconfigured. Three produce an unreadable server message if
- * left to the server, so each gets its own `fix:` line; the fourth is `warnPartialIdentity` and
- * only warns. `slot` and `publication` are interpolated into simple queries, so the `IDENTIFIER`
- * charset is the injection boundary; re-asserted here rather than trusted, so the guarantee
+ * The four things that are always misconfigured. `wal_level` and the slot produce an unreadable
+ * server message if left to the server, so each gets its own `fix:` line; the publication is
+ * created or extended here, and refused with its statement only when this role may not; the
+ * fourth is `warnPartialIdentity` and only warns. `slot` and `publication` are interpolated into
+ * simple queries, so the identifier charset is the injection boundary; re-asserted here rather than trusted, so the guarantee
  * travels with the function instead of living only in `start()`.
  */
 export async function preflight(
@@ -50,17 +35,7 @@ export async function preflight(
       fix: "set wal_level=logical in the server configuration — postgresql.conf, your managed provider's database flags, or `postgres -c wal_level=logical` on a container — then restart postgres",
     });
   }
-  const publications = await connection.query(
-    `SELECT 1 FROM pg_publication WHERE pubname = '${publication}'`,
-  );
-  if (publications.length === 0) {
-    const [role] = await connection.query('SELECT current_user');
-    throw new ReplicationFailedError({
-      stage: 'preflight',
-      detail: `no publication named "${publication}" exists`,
-      fix: publicationFix(publication, entities, role?.[0]),
-    });
-  }
+  await ensurePublication(connection, publication, entities);
   await warnPartialIdentity(connection, entities);
   const [existing] = await connection.query(
     `SELECT plugin FROM pg_replication_slots WHERE slot_name = '${slot}'`,
@@ -81,34 +56,16 @@ export async function preflight(
 }
 
 /**
- * The publication an app needs is exactly its entities' tables, and `FOR TABLE` is what an app role
- * that owns them may create — `FOR ALL TABLES`, which this said, needs a superuser a managed
- * database never hands out. Streaming also needs the `REPLICATION` role attribute, which no fix
- * line named. Every name here already passed `assertIdentifier`; the role is quoted, because a
- * role name is whatever the operator chose.
- */
-function publicationFix(
-  publication: string,
-  entities: ReadonlySet<string>,
-  role: string | null | undefined,
-): string {
-  const tables = [...entities].sort().join(', ');
-  const create = `CREATE PUBLICATION ${publication} FOR TABLE ${tables};`;
-  const who =
-    typeof role === 'string' && role !== '' ? `"${role.replaceAll('"', '""')}"` : 'CURRENT_USER';
-  return `${create} -- and, if the role cannot stream yet: ALTER ROLE ${who} WITH REPLICATION;`;
-}
-
-/**
- * The fourth preflight question, and the one that does NOT refuse. A live query decides whether a
- * row left its result set from `change.before`, and under any replica identity but FULL that tuple
- * is the key columns alone — which `toRow` accepts, since it only requires a text `id`.
+ * The fourth preflight question, and the one that does NOT refuse: which entity tables have NO
+ * replica identity. Once such a table is in the publication, Postgres refuses its UPDATE and
+ * DELETE outright, and a change could not be keyed if it did not. A table with a primary key is
+ * not named: under DEFAULT a delete carries its key, and a live query decides against the whole
+ * row its shared window holds, never against `change.before` alone.
  *
  * It runs BEFORE `pg_create_logical_replication_slot`: a slot decodes with the identity the
  * catalog held when the rows were written, so asking after the slot exists answers about a stream
- * nobody is reading yet. It WARNS rather than throws because every app on the default identity
- * would otherwise stop booting, and a replicator that will not start is worse than the partial
- * rows it is complaining about — `ReplicationStreamStats.partialBefore` is the running half.
+ * nobody is reading yet. It WARNS rather than throws, as it always has — a replicator that will
+ * not start is worse than the tables it is naming.
  *
  * Entity names are the ones the constructor already put through `assertIdentifier`, which is what
  * makes both the interpolation and the `fix:` safe; a name postgres answers with that is not in
@@ -120,9 +77,17 @@ async function warnPartialIdentity(
 ): Promise<void> {
   if (entities.size === 0) return;
   const names = [...entities].map((name) => `'${name}'`).join(', ');
+  // NO identity, not "not FULL": `n` (NOTHING), `d` (DEFAULT) with no primary key, or `i` whose
+  // index is gone.
+  // A keyed table replicates correctly under DEFAULT — a delete names its key, and the shared
+  // window holds the whole row a live query decides on — so naming it was noise on every boot.
   const rows = await connection.query(
-    `SELECT relname FROM pg_class WHERE relkind = 'r' AND relreplident <> 'f' ` +
-      `AND relname IN (${names})`,
+    `SELECT c.relname FROM pg_class c WHERE c.relkind = 'r' AND c.relname IN (${names}) ` +
+      `AND (c.relreplident = 'n' OR (c.relreplident = 'd' AND NOT EXISTS ` +
+      `(SELECT 1 FROM pg_index i WHERE i.indrelid = c.oid AND i.indisprimary)) ` +
+      // USING INDEX whose index was dropped: `relreplident` stays 'i' and it behaves as NOTHING.
+      `OR (c.relreplident = 'i' AND NOT EXISTS ` +
+      `(SELECT 1 FROM pg_index i WHERE i.indrelid = c.oid AND i.indisreplident)))`,
   );
   const tables = [
     ...new Set(

package/src/pg-publication.ts

@@ -0,0 +1,95 @@
+// Single responsibility: the replicator's publication, ensured at boot — created FOR every entity
+// table when missing, extended by the entity tables it lacks when present, never shrunk. The one
+// way an app gets it: a migration is `x db gen`'s, and `FOR ALL TABLES` needs a superuser.
+
+import { logger, stringField } from '@ultimat3/core';
+import { ReplicationFailedError } from './errors';
+import type { PgConnection } from './pg-connection';
+import { assertIdentifier } from './pg-identifier';
+import { REPLICATION_GRANT_WARNING } from './pg-wire';
+
+/** What `ensurePublication` did — `added` is sorted, and empty when the publication was complete. */
+export interface PublicationOutcome {
+  readonly created: boolean;
+  readonly added: readonly string[];
+}
+
+/**
+ * Ensures `publication` carries every table in `entities`.
+ *
+ * `FOR TABLE`, because a table's OWNER may publish it without a superuser — and the app role that
+ * ran the migrations owns every entity table. Membership is read through `pg_publication_tables`,
+ * which also expands `FOR ALL TABLES` and `FOR TABLES IN SCHEMA`, so an operator's broader
+ * publication is recognised as complete rather than ALTERed into an error. Cast through `regclass`
+ * so a table on the search path compares by the bare name the entity list uses.
+ *
+ * Never `DROP TABLE` from it: a table the operator added is theirs. A statement the role may not
+ * run is refused with the exact statement to run as a role that may — the refusal preflight always
+ * raised, now reached only when the boot could not fix it itself.
+ */
+export async function ensurePublication(
+  connection: Pick<PgConnection, 'query'>,
+  publication: string,
+  entities: ReadonlySet<string>,
+): Promise<PublicationOutcome> {
+  assertIdentifier('publication', publication);
+  const tables = [...entities].map((name) => assertIdentifier('entity', name)).sort();
+  const exists = await connection.query(
+    `SELECT 1 FROM pg_publication WHERE pubname = '${publication}'`,
+  );
+  if (exists.length === 0) {
+    const create = `CREATE PUBLICATION ${publication} FOR TABLE ${tables.join(', ')}`;
+    await attempt(connection, create, `no publication named "${publication}" exists`);
+    logger.info('realtime.publication.created', { publication, tables });
+    return { created: true, added: tables };
+  }
+  const members = await connection.query(
+    `SELECT (quote_ident(schemaname) || '.' || quote_ident(tablename))::regclass::text ` +
+      `FROM pg_publication_tables WHERE pubname = '${publication}'`,
+  );
+  const present = new Set(members.map((row) => row[0]));
+  const missing = tables.filter((name) => !present.has(name));
+  if (missing.length === 0) return { created: false, added: [] };
+  const alter = `ALTER PUBLICATION ${publication} ADD TABLE ${missing.join(', ')}`;
+  await attempt(connection, alter, `publication "${publication}" lacks ${missing.join(', ')}`);
+  logger.info('realtime.publication.extended', { publication, tables: missing });
+  return { created: false, added: missing };
+}
+
+/**
+ * Runs `statement`, or refuses with it. Only a server's ErrorResponse is this function's to
+ * explain — a dead socket is not a privilege question, so anything else propagates unchanged.
+ */
+async function attempt(
+  connection: Pick<PgConnection, 'query'>,
+  statement: string,
+  why: string,
+): Promise<void> {
+  try {
+    await connection.query(statement);
+  } catch (error) {
+    if (!(error instanceof ReplicationFailedError)) throw error;
+    const server = stringField(error, 'cause') ?? 'the server refused it';
+    const [role] = await connection.query('SELECT current_user');
+    throw new ReplicationFailedError({
+      stage: 'preflight',
+      detail: `${why}, and this role could not ${statement.split(' ')[0]?.toLowerCase()} it: ${server}`,
+      fix: statementFix(statement, role?.[0]),
+    });
+  }
+}
+
+/**
+ * The statement to run as a role that owns the tables, plus the `REPLICATION` role attribute
+ * streaming needs — which no fix line named until one did. Every name in `statement` already
+ * passed `assertIdentifier`; the role is quoted, because a role name is whatever the operator chose.
+ */
+function statementFix(statement: string, role: string | null | undefined): string {
+  const who =
+    typeof role === 'string' && role !== '' ? `"${role.replaceAll('"', '""')}"` : 'CURRENT_USER';
+  return (
+    `${statement}; -- as a role that owns those tables and holds CREATE on the database, then restart the replicator. ` +
+    `And, if the role cannot stream yet: ALTER ROLE ${who} WITH REPLICATION; -- ` +
+    REPLICATION_GRANT_WARNING
+  );
+}

package/src/pg-replication.ts

@@ -10,7 +10,8 @@ import { isRow, type Row } from './json';
 import { ByteReader, ByteWriter, epochMsToPgTimestamp, printLsn } from './pg-bytes';
 import { PgConnection } from './pg-connection';
 import { entityRow } from './pg-entity-row';
-import { assertIdentifier, preflight } from './pg-preflight';
+import { assertIdentifier } from './pg-identifier';
+import { preflight } from './pg-preflight';
 import { bunPgStream, parsePgUrl } from './pg-socket';
 import type { PhysicalRow } from './pg-values';
 import { keyedWrite, PgOutputDecoder, type PgOutputMessage, type PgRelation } from './pgoutput';

package/src/pg-socket.ts

@@ -2,15 +2,23 @@
 // and the SSLRequest handshake that has to happen before the first protocol byte. Bun pushes bytes
 // at handlers while the connection pulls messages, so a queue sits between them.
 
-import { ReplicationFailedError, ReplicationProtocolError } from './errors';
+import { renderThrowable } from '@ultimat3/core';
+import { ReplicationFailedError, ReplicationProtocolError, ReplicationTlsError } from './errors';
+import { judgeHandshake, parseSsl, rootCertificate, type SslMode } from './pg-tls';
 import { type PgStream, sslRequest } from './pg-wire';
 
+export type { SslMode } from './pg-tls';
+
 /** Structural view of Bun's socket, declared here so the contract does not need bun-types. */
 export interface SocketLike {
   write(data: Uint8Array): number;
   end(): void;
   upgradeTLS(options: {
-    readonly tls: { readonly serverName: string; readonly rejectUnauthorized?: boolean };
+    readonly tls: {
+      readonly serverName: string;
+      readonly rejectUnauthorized: boolean;
+      readonly ca?: string;
+    };
     readonly socket: SocketHandlers;
   }): readonly SocketLike[];
 }
@@ -21,6 +29,8 @@ export interface SocketHandlers {
   end(): void;
   drain(): void;
   error(socket: SocketLike, error: Error): void;
+  /** TLS sockets only: Bun reports the verification it did instead of acting on it. */
+  handshake?(socket: SocketLike, success: boolean, authorizationError: Error | null): void;
 }
 
 export interface BunConnect {
@@ -31,9 +41,6 @@ export interface BunConnect {
   }): Promise<SocketLike>;
 }
 
-/** `disable` never offers TLS, `prefer` accepts a refusal, `require` treats one as a failure. */
-export type SslMode = 'disable' | 'prefer' | 'require';
-
 export interface PgTarget {
   readonly host: string;
   readonly port: number;
@@ -41,10 +48,10 @@ export interface PgTarget {
   readonly user: string;
   readonly password: string | undefined;
   readonly ssl: SslMode;
+  /** `sslrootcert`: a PEM path, `'system'`, or absent for the runtime's trust store. */
+  readonly rootCert?: string | undefined;
 }
 
-const SSL_MODES = new Set<string>(['disable', 'prefer', 'require']);
-
 /** `postgres://user:pass@host:5432/db?sslmode=require`. The one place a connection URL is read. */
 export function parsePgUrl(url: string): PgTarget {
   let parsed: URL;
@@ -67,14 +74,7 @@ export function parsePgUrl(url: string): PgTarget {
       fix: 'set DATABASE_URL to postgres://user:password@host:5432/database',
     });
   }
-  const mode = parsed.searchParams.get('sslmode') ?? 'prefer';
-  if (!SSL_MODES.has(mode)) {
-    throw new ReplicationFailedError({
-      stage: 'connect',
-      detail: `sslmode=${mode} is not one of disable, prefer, require`,
-      fix: 'use ?sslmode=require for a managed database, ?sslmode=disable for a local one',
-    });
-  }
+  const { ssl, rootCert } = parseSsl(parsed.searchParams);
   const database = decodeURIComponent(parsed.pathname.replace(/^\//, ''));
   return {
     host: parsed.hostname,
@@ -82,7 +82,8 @@ export function parsePgUrl(url: string): PgTarget {
     database: database === '' ? 'postgres' : database,
     user: decodeURIComponent(parsed.username) || 'postgres',
     password: parsed.password === '' ? undefined : decodeURIComponent(parsed.password),
-    ssl: mode as SslMode,
+    ssl,
+    rootCert,
   };
 }
 
@@ -156,8 +157,24 @@ export const bunPgStream = (target: PgTarget): Promise<PgStream> =>
  * happen here rather than in the message layer.
  */
 export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promise<PgStream> {
+  // Before any socket exists: a trust anchor that cannot be read is a setting, not a connection,
+  // and refused after the connect it left the raw socket open — one descriptor per retry.
+  const ca = target.ssl === 'disable' ? undefined : await rootCertificate(target.rootCert);
   const queue = new ChunkQueue();
   let draining: (() => void) | undefined;
+  /**
+   * Set the moment the socket is upgraded. Bun keeps calling the RAW socket's handlers after
+   * `upgradeTLS` — with the ciphertext — so those handlers go deaf here, or the reader receives
+   * TLS records as protocol bytes: a read that never completes, or "closed with 2007 bytes of a
+   * partial message".
+   */
+  let upgraded = false;
+
+  const resume = (): void => {
+    const parked = draining;
+    draining = undefined;
+    parked?.();
+  };
 
   /**
    * A write parked for `drain` can never get one from a socket that is gone, so it is released
@@ -165,31 +182,35 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
    * side ends cleanly because an EOF that matters is already an error one layer up.
    */
   const died = (): void => {
-    const resume = draining;
-    draining = undefined;
-    resume?.();
+    resume();
     queue.end();
   };
 
+  const connectFailure = (error: Error): ReplicationFailedError =>
+    new ReplicationFailedError({
+      stage: 'connect',
+      detail: error.message,
+      fix: `open the route to ${target.host}:${target.port}, then: x doctor db`,
+    });
+
   const handlers: SocketHandlers = {
     // Copied, not retained: Bun promises nothing about the chunk's contents — or that it is even
     // the same buffer — once the handler returns, and this one outlives it in the queue.
-    data: (_socket, data) => queue.push(data.slice()),
-    close: died,
-    end: died,
+    data: (_socket, data) => {
+      if (!upgraded) queue.push(data.slice());
+    },
+    close: () => {
+      if (!upgraded) died();
+    },
+    end: () => {
+      if (!upgraded) died();
+    },
     drain: () => {
-      const resume = draining;
-      draining = undefined;
-      resume?.();
+      if (!upgraded) resume();
+    },
+    error: (_socket, error) => {
+      if (!upgraded) queue.fail(connectFailure(error));
     },
-    error: (_socket, error) =>
-      queue.fail(
-        new ReplicationFailedError({
-          stage: 'connect',
-          detail: error.message,
-          fix: `open the route to ${target.host}:${target.port}, then: x doctor db`,
-        }),
-      ),
   };
 
   let socket = await runtime.connect({
@@ -219,7 +240,86 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
     }
   };
 
-  if (target.ssl !== 'disable') {
+  /**
+   * The upgrade, awaited to its HANDSHAKE rather than assumed: the runtime is told never to
+   * reject (`rejectUnauthorized: false`), because libpq's `prefer` and `require` verify nothing,
+   * and `judgeHandshake` decides what its report means under the mode that was asked for. A
+   * failure is `X_REPLICATION_TLS` here, never a refused write one step later.
+   */
+  const upgrade = async (): Promise<SocketLike> => {
+    let settle: ((failure: ReplicationTlsError | undefined) => void) | undefined;
+    const handshake = new Promise<ReplicationTlsError | undefined>((resolve) => {
+      settle = resolve;
+    });
+    const decide = (failure: ReplicationTlsError | undefined): void => {
+      const once = settle;
+      settle = undefined;
+      once?.(failure);
+    };
+    const lost = (detail: string): ReplicationTlsError =>
+      new ReplicationTlsError({
+        detail,
+        fix: `confirm ${target.host}:${target.port} is postgres with ssl=on, or use ?sslmode=disable if it does not speak TLS`,
+      });
+    const tlsHandlers: SocketHandlers = {
+      data: (_socket, data) => queue.push(data.slice()),
+      close: () => {
+        decide(lost('the server closed the connection during the TLS handshake'));
+        died();
+      },
+      end: () => {
+        decide(lost('the server ended the connection during the TLS handshake'));
+        died();
+      },
+      drain: resume,
+      error: (_socket, error) => {
+        decide(lost(`the TLS handshake failed: ${renderThrowable(error)}`));
+        queue.fail(connectFailure(error));
+      },
+      handshake: (_socket, _success, authorizationError) =>
+        decide(judgeHandshake(target, authorizationError)),
+    };
+    upgraded = true;
+    // Bun hands back `[raw, tls]`; every later read and write goes through the second one.
+    const tls = socket.upgradeTLS({
+      tls: {
+        serverName: target.host,
+        rejectUnauthorized: false,
+        ...(ca === undefined ? {} : { ca }),
+      },
+      socket: tlsHandlers,
+    })[1];
+    if (tls === undefined) {
+      throw new ReplicationFailedError({
+        stage: 'ssl',
+        detail: 'the runtime returned no TLS socket for the upgrade',
+        fix: 'bun upgrade   # in-band TLS needs bun >= 1.3',
+      });
+    }
+    const failure = await handshake;
+    if (failure !== undefined) {
+      tls.end();
+      throw failure;
+    }
+    return tls;
+  };
+
+  // Every refusal below owns the socket it opened: the caller never receives a stream to close.
+  try {
+    await negotiate();
+  } catch (failure) {
+    socket.end();
+    throw failure;
+  }
+
+  return {
+    read: () => queue.read(),
+    write: flush,
+    close: () => socket.end(),
+  };
+
+  async function negotiate(): Promise<void> {
+    if (target.ssl === 'disable') return;
     await flush(sslRequest());
     const answer = (await queue.read()) ?? new Uint8Array(0);
     const verdict = answer[0];
@@ -240,29 +340,15 @@ export async function pgStreamOver(runtime: BunConnect, target: PgTarget): Promi
           fix: 'point the replication URL at postgres itself — a proxy answers like this',
         });
       }
-      // Bun hands back `[raw, tls]`; every later read and write goes through the second one, and
-      // the handlers are re-registered because the upgraded socket is a different object.
-      const upgraded = socket.upgradeTLS({ tls: { serverName: target.host }, socket: handlers })[1];
-      if (upgraded === undefined) {
-        throw new ReplicationFailedError({
-          stage: 'ssl',
-          detail: 'the runtime returned no TLS socket for the upgrade',
-          fix: 'bun upgrade   # in-band TLS needs bun >= 1.3',
-        });
-      }
-      socket = upgraded;
-    } else if (target.ssl === 'require') {
+      socket = await upgrade();
+    } else if (target.ssl !== 'allow' && target.ssl !== 'prefer') {
+      // `X_REPLICATION_FAILED`, as it always was: a server that says no is a connection outcome,
+      // and moving it to the TLS code would break whoever already matches on it.
       throw new ReplicationFailedError({
         stage: 'ssl',
-        detail: 'the server refused TLS but sslmode=require was asked for',
+        detail: `the server refused TLS but sslmode=${target.ssl} was asked for`,
         fix: `enable ssl on ${target.host}, or use ?sslmode=prefer to accept a cleartext session`,
       });
     }
   }
-
-  return {
-    read: () => queue.read(),
-    write: flush,
-    close: () => socket.end(),
-  };
 }

package/src/pg-tls.ts

@@ -0,0 +1,124 @@
+// Single responsibility: libpq's `sslmode` / `sslrootcert` semantics for the replicator's own wire
+// client — which modes exist, which of them VERIFY, what a handshake's authorization error means
+// under each, and where the trust anchor comes from. The socket mechanics are `pg-socket.ts`'s.
+
+import { renderFixShellArg, renderThrowable, stringField } from '@ultimat3/core';
+import { ReplicationFailedError, ReplicationTlsError } from './errors';
+
+/**
+ * libpq's six. `disable` never offers TLS; `allow`, `prefer` and `require` encrypt and verify
+ * NOTHING; `verify-ca` checks the chain; `verify-full` checks the chain and the host name.
+ */
+export type SslMode = 'disable' | 'allow' | 'prefer' | 'require' | 'verify-ca' | 'verify-full';
+
+const SSL_MODES: readonly SslMode[] = [
+  'disable',
+  'allow',
+  'prefer',
+  'require',
+  'verify-ca',
+  'verify-full',
+];
+
+const isSslMode = (value: string): value is SslMode =>
+  (SSL_MODES as readonly string[]).includes(value);
+
+/** A path to a PEM file, `'system'` for the runtime's store, or `undefined` for its default. */
+export interface SslSettings {
+  readonly ssl: SslMode;
+  readonly rootCert: string | undefined;
+}
+
+/**
+ * The connection URL's TLS half, with libpq's two couplings: `require` with a root certificate
+ * FILE behaves as `verify-ca` (a CA the operator named is one they meant to be checked against),
+ * and `sslrootcert=system` defaults to `verify-full` and refuses anything weaker — the system
+ * store trusts every public CA, so only the host name makes it mean anything.
+ */
+export function parseSsl(params: URLSearchParams): SslSettings {
+  const given = params.get('sslmode');
+  const rootCert = params.get('sslrootcert') ?? undefined;
+  const mode = given ?? (rootCert === 'system' ? 'verify-full' : 'prefer');
+  if (!isSslMode(mode)) {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `sslmode=${mode} is not one of ${SSL_MODES.join(', ')}`,
+      fix: 'use ?sslmode=verify-full for a managed database, ?sslmode=disable for a local one',
+    });
+  }
+  if (rootCert === 'system' && mode !== 'verify-full') {
+    throw new ReplicationFailedError({
+      stage: 'connect',
+      detail: `sslrootcert=system trusts every public CA, so sslmode=${mode} would prove nothing`,
+      fix: 'use ?sslrootcert=system&sslmode=verify-full, or name your CA: ?sslrootcert=/path/ca.crt',
+    });
+  }
+  if (mode === 'require' && rootCert !== undefined && rootCert !== 'system') {
+    return { ssl: 'verify-ca', rootCert };
+  }
+  return { ssl: mode, rootCert };
+}
+
+/** Whether a mode asks the runtime for the verification at all. */
+export const verifies = (ssl: SslMode): boolean => ssl === 'verify-ca' || ssl === 'verify-full';
+
+/** OpenSSL's code for a certificate whose chain verified but whose names do not include the host. */
+const HOST_MISMATCH = 'ERR_TLS_CERT_ALTNAME_INVALID';
+
+/**
+ * The verdict on a completed handshake. The runtime is always asked NOT to reject
+ * (`rejectUnauthorized: false`) and reports what it found instead, chain errors ahead of the host
+ * name; this decides what that report means under `ssl`. `undefined` is "carry on".
+ */
+export function judgeHandshake(
+  target: { readonly ssl: SslMode; readonly host: string; readonly port: number },
+  authorizationError: unknown,
+): ReplicationTlsError | undefined {
+  if (!verifies(target.ssl)) return undefined;
+  if (authorizationError === null || authorizationError === undefined) return undefined;
+  const code =
+    stringField(authorizationError, 'code') ??
+    (typeof authorizationError === 'string'
+      ? authorizationError
+      : renderThrowable(authorizationError));
+  if (code === HOST_MISMATCH) {
+    if (target.ssl === 'verify-ca') return undefined;
+    return new ReplicationTlsError({
+      detail: `the server certificate does not name ${target.host} (${code}) and sslmode=verify-full checks it`,
+      // The target's own host and port, so the pasted command reaches this server; a host a shell
+      // would misread becomes the libpq env pair instead, which a shell expands rather than runs.
+      fix: `openssl s_client -starttls postgres -connect ${renderFixShellArg(`${target.host}:${target.port}`, '"$PGHOST:$PGPORT"')} </dev/null | openssl x509 -noout -ext subjectAltName   # connect with a name it lists, or use ?sslmode=verify-ca to check the chain alone`,
+    });
+  }
+  return new ReplicationTlsError({
+    detail: `the server certificate did not verify (${code}) and sslmode=${target.ssl} checks it`,
+    fix: 'pass the server CA with ?sslrootcert=/path/to/ca.crt, or use ?sslmode=require to encrypt without verifying',
+  });
+}
+
+/**
+ * The trust anchor `upgradeTLS` gets as `ca`: a named file REPLACES the runtime store, as libpq's
+ * `root.crt` does; `system` and absent both leave the runtime's store (which honours
+ * `NODE_EXTRA_CA_CERTS`). libpq reads `~/.postgresql/root.crt` when nothing is named — a container
+ * has no such home, so this build never looks there.
+ */
+export async function rootCertificate(rootCert: string | undefined): Promise<string | undefined> {
+  if (rootCert === undefined || rootCert === 'system') return undefined;
+  const file = Bun.file(rootCert);
+  if (!(await file.exists())) {
+    throw new ReplicationTlsError({
+      detail: 'sslrootcert names a file that does not exist',
+      fix: 'mount the server CA and point ?sslrootcert= at it, or use ?sslrootcert=system for a public CA',
+    });
+  }
+  // `exists()` is not readability: a secret mounted 0600 for another user exists and still refuses
+  // the read, which escaped as a raw runtime error with no code.
+  try {
+    return await file.text();
+  } catch (error) {
+    throw new ReplicationTlsError({
+      detail: `sslrootcert names a file this process cannot read: ${renderThrowable(error)}`,
+      fix: 'id -u   # the replicator runs as this user: mount the CA readable by it, or use ?sslrootcert=system for a public CA',
+    });
+  }
+}

package/src/pg-wire.ts

@@ -213,10 +213,23 @@ export const describeFields = (fields: Readonly<Record<string, string>>): string
  * not: `changefeed-env -> changefeed -> pg-replication -> pg-wire` is already a chain, so reading
  * the constant here would close it into a cycle. Not re-exported from `index.ts`.
  */
+export const REPLICATION_EXPOSURE_DOC =
+  'https://github.com/developerz-ai/ultimate/blob/main/docs/ops/01-kubernetes.md#replication-is-a-cluster-wide-grant';
+
+/**
+ * What granting `REPLICATION` costs, said wherever a fix hands the grant over. The attribute is
+ * CLUSTER-wide: a `replication=database` session may run `BASE_BACKUP` or `START_REPLICATION
+ * PHYSICAL` with no database check, so on a shared cluster the app role could copy every database,
+ * `pg_authid` included, drop other slots and exhaust the walsenders.
+ */
+export const REPLICATION_GRANT_WARNING =
+  `only on a Postgres cluster dedicated to this app — on a shared cluster REPLICATION lets this ` +
+  `role copy every database (${REPLICATION_EXPOSURE_DOC})`;
+
 export const FIXES: Readonly<Record<string, string>> = {
   '28P01': 'correct the password in the replication URL — the server refused the credentials',
   '28000': 'add a `host replication <user> <cidr> scram-sha-256` line to pg_hba.conf and reload',
-  '42501': 'grant the role REPLICATION: ALTER ROLE <user> WITH REPLICATION',
+  '42501': `ALTER ROLE <user> WITH REPLICATION; -- ${REPLICATION_GRANT_WARNING}`,
   '55006': 'another replicator holds the slot — exactly one replicator per database, by design',
   // NOT `x db replication init`, which this line said until 2026-08-20 and which is not a command:
   // `x db` takes gen, migrate, reset, seed, studio, branch and backfill. It shipped because a fix

package/src/replication-errors.ts

@@ -1,5 +1,5 @@
-// The four refusals the Postgres replication half raises: the wire, the connection, the slot, and
-// the replica identity it warns about.
+// The five refusals the Postgres replication half raises: the wire, the connection, its TLS, the
+// slot, and the replica identity it warns about.
 //
 // Split out of `errors.ts` on the one seam this package already draws — these are the only codes
 // no browser can reach, thrown by `pg-*.ts` and the replicator and by nothing on the client half.
@@ -40,6 +40,22 @@ export class ReplicationFailedError extends RealtimeError {
   }
 }
 
+/**
+ * The replication connection failed TLS: the certificate failed the verification the `sslmode`
+ * asked for, `sslrootcert` named nothing readable, or the handshake itself failed. Its own code
+ * because the fix is a TLS setting, never the network — a certificate refusal used to surface as
+ * `X_REPLICATION_FAILED` "the socket refused a 139-byte write", one step after a silent close.
+ */
+export class ReplicationTlsError extends RealtimeError {
+  constructor(args: { detail: string; fix: string }) {
+    super({
+      code: 'X_REPLICATION_TLS',
+      cause: `postgres replication tls failed: ${args.detail}`,
+      fix: args.fix,
+    });
+  }
+}
+
 /**
  * A second replicator found the advisory lock held. Distinct from `X_REPLICATION_FAILED` because
  * nothing is wrong with this process: the database already has its one replicator, and a second
@@ -59,29 +75,26 @@ export class ReplicatorSlotHeldError extends RealtimeError {
 }
 
 /**
- * A table in the entity list replicates with a replica identity other than FULL, so its `delete`
- * (and any key-changing `update`) carries the KEY COLUMNS ONLY. `toRow` accepts that tuple —
- * it only requires a text `id` — so the live matcher decides "did this row leave the result set"
- * from a one-column row, and a row policy written against `!row.private` reads `undefined`.
- *
- * **Raised at preflight and LOGGED, never thrown.** Every app running today on the default
- * identity would stop booting, and the replicator refusing to start is a worse outcome than the
- * partial rows it is warning about. The runtime half is `ReplicationStreamStats.partialBefore`,
- * which counts the changes this actually affects. Refusing it at `x verify` time is the follow-up.
+ * A table in the entity list has NO replica identity — no primary key under DEFAULT, or
+ * `REPLICA IDENTITY NOTHING`. Once it is in the publication Postgres refuses its UPDATE and DELETE
+ * (`cannot update table … because it does not have a replica identity and publishes updates`),
+ * and a change the replicator did see could not be keyed. A keyed table under DEFAULT is correct
+ * and is never named: the shared window holds the whole row a live query decides on.
  *
- * The tables are named because the fix is per table, and they are the entity list's own names —
- * every one has already passed `assertIdentifier`, so the `fix:` is SQL that can be pasted.
+ * **Raised at preflight and LOGGED, never thrown**, as it always was: a replicator that will not
+ * start is worse than the tables it names. The tables are the entity list's own names — every one
+ * has already passed `assertIdentifier`, so the `fix:` is SQL that can be pasted.
  */
 export class ReplicaIdentityError extends RealtimeError {
   constructor(args: { tables: readonly string[] }) {
     super({
       code: 'X_LIVE_REPLICA_IDENTITY',
       cause:
-        `${args.tables.join(', ')} replicate with a replica identity other than FULL, so a ` +
-        'delete carries the key columns only and a live query decides visibility from a partial row',
+        `${args.tables.join(', ')} have no replica identity (no primary key, or REPLICA IDENTITY ` +
+        'NOTHING), so once published an UPDATE or DELETE on them fails and a change cannot be keyed',
       fix:
         `${args.tables.map((table) => `ALTER TABLE ${table} REPLICA IDENTITY FULL;`).join(' ')}` +
-        ' -- rows already written to the WAL keep the identity they were written with',
+        ' -- or give each a primary key; rows already in the WAL keep the identity they were written with',
     });
   }
 }

package/src/sync-node-contract.ts

@@ -53,6 +53,12 @@ export interface SyncNodeOptions {
    * is a single-tenant node, and `start()` says so in the log.
    */
   readonly authenticate?: SyncAuthenticator;
+  /**
+   * Exact origins a page may open a socket from, besides this node's own host name — the page's
+   * origin when it is served on another host (`SYNC_URL` on a separate domain). Anything else is
+   * refused `X_SOCKET_ORIGIN_REFUSED` before `authenticate` runs.
+   */
+  readonly allowedOrigins?: readonly string[];
   /** How often an expired grant is re-decided. The clock a socket's authority runs on. */
   readonly reauthenticateIntervalMs?: number;
   readonly clock?: Clock;

package/src/sync-node.ts

@@ -269,6 +269,7 @@ export function createSyncNode(options: SyncNodeOptions): SyncNode {
           socketCount: () => sockets.count,
           newSocketId: () => uuid(),
           authenticate: options.authenticate,
+          allowedOrigins: options.allowedOrigins,
           onGranted: (socketId, grant) => grants.set(socketId, grant),
           // The other half of recording the grant before the upgrade: an upgrade that never took
           // gets no `close` callback, so this is the only thing that can free its entry.

package/src/sync-origin.ts

@@ -0,0 +1,33 @@
+// Single responsibility: whether a websocket upgrade may carry this app's ambient credential. No
+// CORS applies to a websocket and the session cookie rides it, so without this a page on a sibling
+// host (same-site, so `SameSite=Lax` does not stop it) opened a socket as its visitor. The rule is
+// core's `proveSameOrigin`, the one `@ultimat3/http`'s CSRF check asks too.
+
+import { type OriginVerdict, proveSameOrigin } from '@ultimat3/core';
+
+/**
+ * Admitted, in order:
+ * - **no `Origin`** — RFC 6455 has a browser send one on every handshake, so a dial without it is
+ *   not a browser and no visitor's cookie can be riding it;
+ * - **the node's own host name**, whatever the port or scheme — cookies are not port-isolated, so
+ *   the page on `:3000` dialling the Compose rung's `:3001` is the same credential boundary, and a
+ *   TLS-terminating ingress means the node cannot know the page's scheme;
+ * - otherwise core's rule, with `allowedOrigins` as the exact list (`APP_URL`'s origin, from the
+ *   CLI, when the page is served on another host than the node).
+ */
+export function upgradeOrigin(
+  request: Request,
+  url: URL,
+  allowedOrigins: readonly string[],
+): OriginVerdict {
+  const origin = request.headers.get('origin');
+  if (origin === null) return { ok: true };
+  if (URL.parse(origin)?.hostname === url.hostname) return { ok: true };
+  return proveSameOrigin({
+    selfOrigins: allowedOrigins,
+    origin,
+    secFetchSite: request.headers.get('sec-fetch-site'),
+    listed: () => false,
+    listName: 'APP_URL or createSyncNode({ allowedOrigins })',
+  });
+}

package/src/sync-upgrade.ts

@@ -3,8 +3,13 @@
 // from what the socket then does — the same line `sync-frames.ts` and `sync-listen.ts` already draw.
 
 import { healthzPayload, readyzPayload, reportError } from '@ultimat3/core';
-import { SocketAuthUnavailableError, SocketUnauthenticatedError } from './errors';
+import {
+  SocketAuthUnavailableError,
+  SocketOriginRefusedError,
+  SocketUnauthenticatedError,
+} from './errors';
 import type { SyncAuthenticator, SyncGrant } from './sync-auth';
+import { upgradeOrigin } from './sync-origin';
 import { toWireError } from './sync-protocol';
 import type { AcceptBudget, Rng } from './thundering-herd';
 
@@ -43,6 +48,11 @@ export interface UpgradeDeps {
   socketCount(): number;
   newSocketId(): string;
   readonly authenticate?: SyncAuthenticator | undefined;
+  /**
+   * Exact origins a page may dial from besides the node's own host name — `APP_URL`'s, when the
+   * page is served on another host than the node (`sync-origin.ts`).
+   */
+  readonly allowedOrigins?: readonly string[] | undefined;
   /**
    * Recorded BEFORE `server.upgrade`, because Bun runs `websocket.open` synchronously inside it
    * (measured on bun 1.4.0) and `open` is where the node reads this grant to build the socket's
@@ -79,12 +89,19 @@ export async function handleUpgrade(
     return deps.ready() ? json(payload) : json({ status: 503, body: payload.body });
   }
   if (url.pathname !== deps.path) return new Response('not found', { status: 404 });
-  // The count, not the rate. Shed the same way and with the same delay attached: a client refused
-  // for a full node and one refused for a fast one have the same next move, and the refusal is
-  // decided before `authenticate` so a full node costs no token service call.
-  if (deps.socketCount() >= deps.maxConnections || !deps.ready() || !deps.accept.tryAccept()) {
-    return shed(deps);
-  }
+  // First, and before anything is spent: a foreign page is refused whatever the node's load.
+  const origin = upgradeOrigin(request, url, deps.allowedOrigins ?? []);
+  if (!origin.ok)
+    return wireErrorResponse(403, new SocketOriginRefusedError({ reason: origin.reason }));
+  // The count and readiness. Decided before `authenticate` so a full node costs no token service
+  // call.
+  if (deps.socketCount() >= deps.maxConnections || !deps.ready()) return shed(deps);
+  // The RATE is RESERVED here and REFUNDED on every exit that takes no socket. Reserved first, so a
+  // reconnect herd reaches `authenticate` bounded by the burst — the token service is the first
+  // thing a herd would otherwise flatten. Refunded, because spent-and-kept, one client dialling
+  // with no credential drained the bucket and every signed-in reconnect behind it was shed.
+  if (!deps.accept.tryAccept()) return shed(deps);
+  const refund = (): void => deps.accept.refund();
   let grant: SyncGrant | null = null;
   if (deps.authenticate) {
     try {
@@ -93,6 +110,7 @@ export async function handleUpgrade(
       // A failure is not a denial. The token service timing out must not read to a client as "you
       // may not connect" — it is told to come back, and this node is the one that pages.
       reportError(error, { source: 'realtime', scope: { operation: 'sync.authenticate' } });
+      refund();
       return wireErrorResponse(
         503,
         new SocketAuthUnavailableError({ detail: 'see the node log for the cause' }),
@@ -101,6 +119,7 @@ export async function handleUpgrade(
     // The decision, made before a socket exists: an upgrade is the cheapest thing to refuse and the
     // most expensive thing to take back.
     if (grant === null) {
+      refund();
       return wireErrorResponse(
         401,
         new SocketUnauthenticatedError({ reason: 'authenticate() resolved no actor' }),
@@ -120,8 +139,11 @@ export async function handleUpgrade(
   // sockets as there were parked requests, and `maxConnections` bounded nothing that a herd could
   // reach. Sound because there is no await between this line and `server.upgrade`, and the count
   // moves INSIDE it: Bun runs `websocket.open` synchronously there, which is where `sockets.add`
-  // runs. No second `tryAccept()`: that budget was spent above.
-  if (!deps.ready() || deps.socketCount() >= deps.maxConnections) return shed(deps);
+  // runs.
+  if (!deps.ready() || deps.socketCount() >= deps.maxConnections) {
+    refund();
+    return shed(deps);
+  }
   const data: WsData = {
     socketId: deps.newSocketId(),
     // The node's own id is "not skewed until the hello says so", never "current forever".
@@ -144,10 +166,12 @@ export async function handleUpgrade(
     // failing upgrades left 20 grants. Rethrown untouched — the throw is the operator's diagnosis,
     // and this line owes it the release, not a verdict.
     deps.onUngranted(data.socketId);
+    refund();
     throw error;
   }
   if (!upgraded) {
     deps.onUngranted(data.socketId);
+    refund();
     return new Response('expected websocket', { status: 426 });
   }
   return undefined;

package/src/thundering-herd.ts

@@ -188,6 +188,15 @@ export class AcceptBudget {
     return true;
   }
 
+  /**
+   * Hands back a token `tryAccept` reserved for work that took no socket — an upgrade whose
+   * credential was refused, or whose authenticator failed. Never past `burst`.
+   */
+  refund(): void {
+    this.#refill();
+    this.#tokens = Math.min(this.#burst, this.#tokens + 1);
+  }
+
   /** Delay to hand a refused client, jittered so refusals do not re-synchronise the herd. */
   retryAfterMs(rng: Rng = Math.random): number {
     const base = Math.ceil(1000 / this.#perSecond);