@nage-api/realtime 1.0.0-beta.2

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,88 @@
+# @nage-api/realtime
+
+Authenticated sockets and a cross-instance propagator (PLAN.md §8, §12, §25 P2).
+
+§12 names three specific defects in the legacy socket layer. This package exists
+to make all three unrepresentable.
+
+**No token in the query string.** A token in a URL is written to every access
+log, every proxy log, every `Referer` sent to a third-party asset, and the
+browser history. The handshake reads `Authorization: Bearer …` and nothing else
+— and _refuses_ a connection that puts a credential in the query rather than
+quietly ignoring it, because a client sending one has tokens in its URLs and its
+author needs to know.
+
+**No default guest.** A connection with no valid bearer token is refused. The
+legacy gateway assigned an identity, which made every "authenticated" room
+reachable by anyone who opened a socket.
+
+**Rooms are authorised.** Joining a room named by the client is an authorization
+decision, so `RoomPolicy.canJoin` runs on every join and the default policy
+refuses everything — an unconfigured gateway must not be an open one. A refusal
+never names the room back, because which rooms exist is not something an
+unauthorised caller may enumerate.
+
+```ts
+import { Module } from '@nestjs/common';
+import { NageRealtimeModule, type Propagator, type RealtimeTransport } from '@nage-api/realtime';
+import type { AuthUser } from '@nage-api/contracts';
+
+// The application's own token verification, over `@nage-api/auth`: a feature package
+// may not import a sibling feature package (§7.2), so the socket layer takes the
+// resolution as a port.
+declare const principals: { fromAccessToken(token: string): Promise<AuthUser> };
+// Both bindings are yours today; neither the Socket.IO transport nor the Redis
+// propagator is written (see "Not yet implemented").
+declare const socketIo: RealtimeTransport;
+declare const redisPropagator: Propagator;
+
+@Module({
+  imports: [
+    NageRealtimeModule.forRoot({
+      realtime: { enabled: true, adapter: 'redis' },
+      authenticator: { authenticate: (token) => principals.fromAccessToken(token) },
+      roomPolicy: { canJoin: (user, room) => room === `user:${String(user.id)}` },
+      transport: socketIo,
+      propagator: redisPropagator,
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`authenticator` is required and has no default, because the only possible
+default would be "accept anyone". `realtime.enabled` must be `true`: anything
+else contributes no providers at all, so `RealtimeGateway` is unavailable rather
+than present and inert.
+
+## Across instances
+
+Without a propagator, a two-pod deployment delivers each event to whichever
+fraction of users happens to be connected to the pod that emitted it. Events
+carry the emitting instance's id, so an event that comes back from the
+propagator is delivered locally exactly once rather than looping between pods.
+
+Asking for `adapter: 'redis'` without supplying a propagator is refused —
+accepting it would be a silent lie.
+
+Connections per principal are bounded, because a client in a reconnect loop
+otherwise accumulates sockets until the process runs out of file descriptors.
+
+## Transport-independent
+
+Which socket library carries the bytes is a binding; who may connect, who may
+join what, and what happens on a second instance are decisions. The decisions
+live here, where they are testable — testing them through a real socket server
+would be testing Socket.IO.
+
+With no `transport` supplied the gateway gets `MemoryTransport`, which records
+every emission and delivers to nobody. That is the right default for a test and
+the wrong one for a deployment: until the Socket.IO binding lands, a running
+application needs a `RealtimeTransport` of its own or its events go nowhere.
+
+## Not yet implemented
+
+- The Socket.IO binding (§27.5) and the Redis propagator. `RealtimeTransport`
+  and `Propagator` are the seams.
+- Per-connection rate limiting, and presence (who is in a room, across
+  instances).

package/dist/gateway.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The connection registry and the authorization around it (PLAN.md §12).
+ *
+ * Transport-independent on purpose: which socket library carries the bytes is
+ * a binding, but who may connect, who may join which room, and what happens on
+ * a second instance are decisions, and they belong somewhere testable.
+ */
+import type { AuthUser } from '@nage-api/contracts';
+import type { Clock, Connection, Handshake, Propagator, RealtimeTransport, RoomPolicy, SocketAuthenticator } from './ports.js';
+export interface RealtimeGatewayOptions {
+    readonly transport: RealtimeTransport;
+    readonly authenticator: SocketAuthenticator;
+    /** Refuses every room by default; supply one to allow any. */
+    readonly roomPolicy?: RoomPolicy;
+    readonly propagator?: Propagator;
+    /** Connections one principal may hold at once. */
+    readonly maxConnectionsPerUser?: number;
+    readonly clock?: Clock;
+}
+/** Refuses everything. The default, so an unconfigured gateway is not open. */
+export declare const DENY_ALL_ROOMS: RoomPolicy;
+export declare class RealtimeGateway {
+    #private;
+    constructor(options: RealtimeGatewayOptions);
+    /**
+     * Authenticate a connection attempt.
+     *
+     * @throws AuthenticationError when there is no valid bearer token
+     */
+    connect(handshake: Handshake): Promise<Connection>;
+    /**
+     * Admit a connection to a room.
+     *
+     * @throws AuthorizationError when the policy refuses
+     */
+    join(connectionId: string, room: string): Promise<void>;
+    leave(connectionId: string, room: string): void;
+    disconnect(connectionId: string, reason?: string): void;
+    /**
+     * Emit to a room, locally and on every other instance.
+     *
+     * The event is stamped with this instance's id so it comes back from the
+     * propagator recognisable and is not delivered twice.
+     */
+    emit(room: string, event: string, payload: unknown, requestId?: string): Promise<void>;
+    /** Emit to every connection a principal holds on this instance. */
+    emitToUser(userId: string, event: string, payload: unknown): number;
+    /** Connections in a room, on this instance. */
+    membersOf(room: string): readonly Connection[];
+    get connectionCount(): number;
+    connectionsFor(user: AuthUser): readonly string[];
+    close(): Promise<void>;
+}
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * The connection registry and the authorization around it (PLAN.md §12).
+ *
+ * Transport-independent on purpose: which socket library carries the bytes is
+ * a binding, but who may connect, who may join which room, and what happens on
+ * a second instance are decisions, and they belong somewhere testable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RealtimeGateway = exports.DENY_ALL_ROOMS = void 0;
+const core_1 = require("@nage-api/core");
+const handshake_js_1 = require("./handshake.js");
+const DEFAULT_MAX_CONNECTIONS_PER_USER = 10;
+/** Refuses everything. The default, so an unconfigured gateway is not open. */
+exports.DENY_ALL_ROOMS = { canJoin: () => false };
+class RealtimeGateway {
+    #transport;
+    #authenticator;
+    #roomPolicy;
+    #propagator;
+    #maxPerUser;
+    #clock;
+    #connections = new Map();
+    #byUser = new Map();
+    #instanceId = (0, core_1.randomId)();
+    constructor(options) {
+        this.#transport = options.transport;
+        this.#authenticator = options.authenticator;
+        this.#roomPolicy = options.roomPolicy ?? exports.DENY_ALL_ROOMS;
+        this.#propagator = options.propagator;
+        this.#maxPerUser = options.maxConnectionsPerUser ?? DEFAULT_MAX_CONNECTIONS_PER_USER;
+        this.#clock = options.clock ?? { now: () => Date.now() };
+        // Events from other instances are delivered locally, but never re-published
+        // — that would be an infinite loop between two pods.
+        this.#propagator?.subscribe((event) => {
+            if (event.origin === this.#instanceId)
+                return;
+            this.#transport.emit(event.room, event.event, event.payload);
+        });
+    }
+    /**
+     * Authenticate a connection attempt.
+     *
+     * @throws AuthenticationError when there is no valid bearer token
+     */
+    async connect(handshake) {
+        const token = (0, handshake_js_1.readHandshakeToken)(handshake);
+        const user = await this.#authenticator.authenticate(token);
+        const userId = String(user.id);
+        const existing = this.#byUser.get(userId) ?? new Set();
+        if (existing.size >= this.#maxPerUser) {
+            // A client in a reconnect loop otherwise accumulates sockets until the
+            // process runs out of file descriptors.
+            const oldest = existing.values().next();
+            if (!oldest.done)
+                this.disconnect(oldest.value, 'too many connections');
+        }
+        const connection = {
+            id: (0, core_1.randomId)(),
+            user,
+            rooms: new Set(),
+            connectedAt: this.#clock.now(),
+        };
+        const rooms = new Set();
+        this.#connections.set(connection.id, { connection: { ...connection, rooms }, rooms });
+        existing.add(connection.id);
+        this.#byUser.set(userId, existing);
+        return { ...connection, rooms };
+    }
+    /**
+     * Admit a connection to a room.
+     *
+     * @throws AuthorizationError when the policy refuses
+     */
+    async join(connectionId, room) {
+        const entry = this.#require(connectionId);
+        if (!(await this.#roomPolicy.canJoin(entry.connection.user, room))) {
+            // The client learns only that it was refused: which rooms exist is not
+            // something an unauthorised caller may enumerate.
+            throw new core_1.AuthorizationError('FORBIDDEN', {
+                message: 'You may not join that room.',
+                detail: `${String(entry.connection.user.id)} was refused room "${room}"`,
+                meta: { room },
+            });
+        }
+        entry.rooms.add(room);
+    }
+    leave(connectionId, room) {
+        this.#require(connectionId).rooms.delete(room);
+    }
+    disconnect(connectionId, reason = 'closed') {
+        const entry = this.#connections.get(connectionId);
+        if (entry === undefined)
+            return;
+        this.#connections.delete(connectionId);
+        const userId = String(entry.connection.user.id);
+        const held = this.#byUser.get(userId);
+        held?.delete(connectionId);
+        if (held?.size === 0)
+            this.#byUser.delete(userId);
+        this.#transport.disconnect(connectionId, reason);
+    }
+    /**
+     * Emit to a room, locally and on every other instance.
+     *
+     * The event is stamped with this instance's id so it comes back from the
+     * propagator recognisable and is not delivered twice.
+     */
+    async emit(room, event, payload, requestId) {
+        this.#transport.emit(room, event, payload);
+        if (this.#propagator === undefined)
+            return;
+        const message = {
+            room,
+            event,
+            payload,
+            origin: this.#instanceId,
+            ...(requestId === undefined ? {} : { requestId }),
+        };
+        await this.#propagator.publish(message);
+    }
+    /** Emit to every connection a principal holds on this instance. */
+    emitToUser(userId, event, payload) {
+        const held = this.#byUser.get(userId) ?? new Set();
+        for (const connectionId of held)
+            this.#transport.emitTo(connectionId, event, payload);
+        return held.size;
+    }
+    /** Connections in a room, on this instance. */
+    membersOf(room) {
+        return [...this.#connections.values()]
+            .filter((entry) => entry.rooms.has(room))
+            .map((entry) => entry.connection);
+    }
+    get connectionCount() {
+        return this.#connections.size;
+    }
+    connectionsFor(user) {
+        return [...(this.#byUser.get(String(user.id)) ?? [])];
+    }
+    async close() {
+        for (const id of [...this.#connections.keys()])
+            this.disconnect(id, 'shutting down');
+        await this.#propagator?.close();
+    }
+    #require(connectionId) {
+        const entry = this.#connections.get(connectionId);
+        if (entry === undefined) {
+            throw new core_1.AuthenticationError('AUTH_REQUIRED', {
+                detail: `Connection ${connectionId} is not registered`,
+            });
+        }
+        return entry;
+    }
+}
+exports.RealtimeGateway = RealtimeGateway;
+//# sourceMappingURL=gateway.js.map

package/dist/handshake.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Reading credentials off a connection attempt (PLAN.md §12).
+ *
+ * One rule: the token comes from the `Authorization` header and nowhere else.
+ *
+ * A token in a query string is not a lesser version of a token in a header —
+ * it is a token written into every access log, every proxy log, every
+ * `Referer` sent to a third-party asset, and the browser history. The legacy
+ * socket handshake accepted one, so this function refuses the connection
+ * outright when it sees one rather than quietly ignoring it: a client sending
+ * one has a token in its URLs and its author needs to know.
+ */
+import type { Handshake } from './ports.js';
+/**
+ * Extract the bearer token.
+ *
+ * @throws AuthenticationError when a credential is in the query string, or when
+ * there is no usable header — there is no anonymous fallback.
+ */
+export declare function readHandshakeToken(handshake: Handshake): string;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/handshake.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Reading credentials off a connection attempt (PLAN.md §12).
+ *
+ * One rule: the token comes from the `Authorization` header and nowhere else.
+ *
+ * A token in a query string is not a lesser version of a token in a header —
+ * it is a token written into every access log, every proxy log, every
+ * `Referer` sent to a third-party asset, and the browser history. The legacy
+ * socket handshake accepted one, so this function refuses the connection
+ * outright when it sees one rather than quietly ignoring it: a client sending
+ * one has a token in its URLs and its author needs to know.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readHandshakeToken = readHandshakeToken;
+const core_1 = require("@nage-api/core");
+/** Query parameters that would carry a credential. */
+const CREDENTIAL_PARAMETERS = [
+    'token',
+    'access_token',
+    'accesstoken',
+    'auth',
+    'authorization',
+    'jwt',
+    'apikey',
+    'api_key',
+];
+/**
+ * Extract the bearer token.
+ *
+ * @throws AuthenticationError when a credential is in the query string, or when
+ * there is no usable header — there is no anonymous fallback.
+ */
+function readHandshakeToken(handshake) {
+    const offending = Object.keys(handshake.query ?? {}).filter((key) => CREDENTIAL_PARAMETERS.includes(key.toLowerCase()));
+    if (offending.length > 0) {
+        throw new core_1.AuthenticationError('AUTH_TOKEN_INVALID', {
+            message: 'Send the token in the Authorization header, not the query string.',
+            detail: `Connection presented a credential in the query string (${offending.join(', ')}); it would be written to every access and proxy log`,
+            meta: { parameters: offending },
+        });
+    }
+    const header = handshake.authorization?.trim() ?? '';
+    const match = /^Bearer\s+(.+)$/i.exec(header);
+    if (match?.[1] === undefined) {
+        // No guest identity. The legacy gateway assigned one, which made every
+        // "authenticated" room reachable by anyone who opened a socket.
+        throw new core_1.AuthenticationError('AUTH_REQUIRED', {
+            detail: 'Connection had no Bearer token; anonymous sockets are not accepted',
+        });
+    }
+    return match[1];
+}
+//# sourceMappingURL=handshake.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `@nage-api/realtime` — authenticated sockets and a cross-instance propagator
+ * (PLAN.md §8, §12, §25 P2).
+ *
+ * The package's reason to exist is three named defects in the legacy socket
+ * layer: a token accepted from the query string, a default guest identity, and
+ * rooms joined without authorization. All three are refused here.
+ */
+export type * from '@nage-api/contracts';
+export { NageRealtimeModule, type NageRealtimeModuleOptions } from './realtime.module.js';
+export { RealtimeGateway, DENY_ALL_ROOMS, type RealtimeGatewayOptions } from './gateway.js';
+export { readHandshakeToken } from './handshake.js';
+export { MemoryPropagator, MemoryTransport, type EmittedEvent } from './memory.js';
+export { NAGE_REALTIME, NAGE_REALTIME_PROPAGATOR, NAGE_REALTIME_TRANSPORT } from './tokens.js';
+export { systemClock, type Clock, type Connection, type Handshake, type Propagator, type RealtimeEvent, type RealtimeTransport, type RoomPolicy, type SocketAuthenticator, } from './ports.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * `@nage-api/realtime` — authenticated sockets and a cross-instance propagator
+ * (PLAN.md §8, §12, §25 P2).
+ *
+ * The package's reason to exist is three named defects in the legacy socket
+ * layer: a token accepted from the query string, a default guest identity, and
+ * rooms joined without authorization. All three are refused here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = exports.NAGE_REALTIME_TRANSPORT = exports.NAGE_REALTIME_PROPAGATOR = exports.NAGE_REALTIME = exports.MemoryTransport = exports.MemoryPropagator = exports.readHandshakeToken = exports.DENY_ALL_ROOMS = exports.RealtimeGateway = exports.NageRealtimeModule = void 0;
+var realtime_module_js_1 = require("./realtime.module.js");
+Object.defineProperty(exports, "NageRealtimeModule", { enumerable: true, get: function () { return realtime_module_js_1.NageRealtimeModule; } });
+var gateway_js_1 = require("./gateway.js");
+Object.defineProperty(exports, "RealtimeGateway", { enumerable: true, get: function () { return gateway_js_1.RealtimeGateway; } });
+Object.defineProperty(exports, "DENY_ALL_ROOMS", { enumerable: true, get: function () { return gateway_js_1.DENY_ALL_ROOMS; } });
+var handshake_js_1 = require("./handshake.js");
+Object.defineProperty(exports, "readHandshakeToken", { enumerable: true, get: function () { return handshake_js_1.readHandshakeToken; } });
+var memory_js_1 = require("./memory.js");
+Object.defineProperty(exports, "MemoryPropagator", { enumerable: true, get: function () { return memory_js_1.MemoryPropagator; } });
+Object.defineProperty(exports, "MemoryTransport", { enumerable: true, get: function () { return memory_js_1.MemoryTransport; } });
+var tokens_js_1 = require("./tokens.js");
+Object.defineProperty(exports, "NAGE_REALTIME", { enumerable: true, get: function () { return tokens_js_1.NAGE_REALTIME; } });
+Object.defineProperty(exports, "NAGE_REALTIME_PROPAGATOR", { enumerable: true, get: function () { return tokens_js_1.NAGE_REALTIME_PROPAGATOR; } });
+Object.defineProperty(exports, "NAGE_REALTIME_TRANSPORT", { enumerable: true, get: function () { return tokens_js_1.NAGE_REALTIME_TRANSPORT; } });
+var ports_js_1 = require("./ports.js");
+Object.defineProperty(exports, "systemClock", { enumerable: true, get: function () { return ports_js_1.systemClock; } });
+//# sourceMappingURL=index.js.map

package/dist/memory.d.ts

@@ -0,0 +1,35 @@
+/**
+ * In-memory transport and propagator.
+ *
+ * The propagator is genuinely useful beyond tests: two gateways sharing one
+ * `MemoryPropagator` behave exactly like two pods sharing a Redis channel, so
+ * cross-instance delivery can be asserted without a broker.
+ */
+import type { Propagator, RealtimeEvent, RealtimeTransport } from './ports.js';
+export interface EmittedEvent {
+    readonly target: string;
+    readonly event: string;
+    readonly payload: unknown;
+}
+export declare class MemoryTransport implements RealtimeTransport {
+    readonly name = "memory";
+    readonly emitted: EmittedEvent[];
+    readonly disconnected: {
+        id: string;
+        reason: string;
+    }[];
+    emit(room: string, event: string, payload: unknown): void;
+    emitTo(connectionId: string, event: string, payload: unknown): void;
+    disconnect(connectionId: string, reason: string): void;
+    /** Events sent to one room or connection. */
+    to(target: string): readonly EmittedEvent[];
+}
+/** A propagator every subscriber on the same instance shares. */
+export declare class MemoryPropagator implements Propagator {
+    #private;
+    readonly published: RealtimeEvent[];
+    publish(event: RealtimeEvent): Promise<void>;
+    subscribe(handler: (event: RealtimeEvent) => void): void;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/memory.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * In-memory transport and propagator.
+ *
+ * The propagator is genuinely useful beyond tests: two gateways sharing one
+ * `MemoryPropagator` behave exactly like two pods sharing a Redis channel, so
+ * cross-instance delivery can be asserted without a broker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryPropagator = exports.MemoryTransport = void 0;
+class MemoryTransport {
+    name = 'memory';
+    emitted = [];
+    disconnected = [];
+    emit(room, event, payload) {
+        this.emitted.push({ target: room, event, payload });
+    }
+    emitTo(connectionId, event, payload) {
+        this.emitted.push({ target: connectionId, event, payload });
+    }
+    disconnect(connectionId, reason) {
+        this.disconnected.push({ id: connectionId, reason });
+    }
+    /** Events sent to one room or connection. */
+    to(target) {
+        return this.emitted.filter((entry) => entry.target === target);
+    }
+}
+exports.MemoryTransport = MemoryTransport;
+/** A propagator every subscriber on the same instance shares. */
+class MemoryPropagator {
+    published = [];
+    #handlers = [];
+    async publish(event) {
+        await Promise.resolve();
+        this.published.push(event);
+        for (const handler of this.#handlers)
+            handler(event);
+    }
+    subscribe(handler) {
+        this.#handlers.push(handler);
+    }
+    async close() {
+        await Promise.resolve();
+        this.#handlers.length = 0;
+    }
+}
+exports.MemoryPropagator = MemoryPropagator;
+//# sourceMappingURL=memory.js.map

package/dist/ports.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Realtime (PLAN.md §8, §12, §25 P2).
+ *
+ * §12 names three specific defects in the legacy socket layer, and this package
+ * exists to make them unrepresentable:
+ *
+ *  1. **no query-string token** — a token in a URL is written to every access
+ *     log, proxy log and `Referer` header between the client and the server;
+ *  2. **no default guest** — an unauthenticated connection was silently given
+ *     an identity, so every "authenticated" room was reachable by anyone;
+ *  3. **rooms are authorised** — joining a room named by the client is an
+ *     authorization decision, not a subscription.
+ *
+ * The transport is a port. Socket.IO is the intended binding (§27.5), but the
+ * decisions above are transport-independent, and testing them against a real
+ * socket server would be testing Socket.IO.
+ */
+import type { AuthUser } from '@nage-api/contracts';
+/** A connected client, after authentication. */
+export interface Connection {
+    readonly id: string;
+    readonly user: AuthUser;
+    /** Rooms this connection has been admitted to. */
+    readonly rooms: ReadonlySet<string>;
+    readonly connectedAt: number;
+}
+/** Credentials as they arrive on a connection attempt. */
+export interface Handshake {
+    /** `Authorization: Bearer …`, the only place a token is read from. */
+    readonly authorization?: string;
+    /** Parsed query parameters, inspected **only** to refuse tokens in them. */
+    readonly query?: Readonly<Record<string, string>>;
+    readonly ip?: string;
+    readonly userAgent?: string;
+}
+/**
+ * Verifies a bearer token and resolves the principal.
+ *
+ * Implemented by the application over `@nage-api/auth`; this package may not import
+ * a sibling feature package (§7.2).
+ */
+export interface SocketAuthenticator {
+    authenticate(token: string): Promise<AuthUser>;
+}
+/** Decides whether a principal may join a room. */
+export interface RoomPolicy {
+    /** Return false to refuse; the client is told nothing beyond "refused". */
+    canJoin(user: AuthUser, room: string): boolean | Promise<boolean>;
+}
+/** An event on its way to clients. */
+export interface RealtimeEvent<TPayload = unknown> {
+    readonly room: string;
+    readonly event: string;
+    readonly payload: TPayload;
+    /** Correlation id of the request that produced it. */
+    readonly requestId?: string;
+    /** Set when the emitting instance should not re-deliver it locally. */
+    readonly origin?: string;
+}
+/**
+ * Carries events between instances (§8: "Socket.IO + Redis propagator").
+ *
+ * Without one, a two-pod deployment delivers each event to whichever half of
+ * the users happen to be connected to the pod that emitted it.
+ */
+export interface Propagator {
+    publish(event: RealtimeEvent): Promise<void>;
+    subscribe(handler: (event: RealtimeEvent) => void): void;
+    close(): Promise<void>;
+}
+/** The transport a gateway drives. */
+export interface RealtimeTransport {
+    readonly name: string;
+    /** Deliver to every local connection in a room. */
+    emit(room: string, event: string, payload: unknown): void;
+    /** Deliver to one local connection. */
+    emitTo(connectionId: string, event: string, payload: unknown): void;
+    disconnect(connectionId: string, reason: string): void;
+}
+export interface Clock {
+    now(): number;
+}
+export declare const systemClock: Clock;
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * Realtime (PLAN.md §8, §12, §25 P2).
+ *
+ * §12 names three specific defects in the legacy socket layer, and this package
+ * exists to make them unrepresentable:
+ *
+ *  1. **no query-string token** — a token in a URL is written to every access
+ *     log, proxy log and `Referer` header between the client and the server;
+ *  2. **no default guest** — an unauthenticated connection was silently given
+ *     an identity, so every "authenticated" room was reachable by anyone;
+ *  3. **rooms are authorised** — joining a room named by the client is an
+ *     authorization decision, not a subscription.
+ *
+ * The transport is a port. Socket.IO is the intended binding (§27.5), but the
+ * decisions above are transport-independent, and testing them against a real
+ * socket server would be testing Socket.IO.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.systemClock = void 0;
+exports.systemClock = { now: () => Date.now() };
+//# sourceMappingURL=ports.js.map

package/dist/realtime.module.d.ts

@@ -0,0 +1,32 @@
+/**
+ * `NageRealtimeModule.forRoot(config)` (PLAN.md §11.1 item 6, §12).
+ *
+ * An authenticator is **required**. There is no default, because the only
+ * possible default would be "accept anyone", and that is the legacy defect
+ * this package exists to remove.
+ *
+ * A multi-instance deployment without a propagator is refused for the same
+ * reason: it appears to work, and delivers each event to whichever fraction of
+ * users happens to be connected to the pod that emitted it.
+ */
+import { type DynamicModule, type OnApplicationShutdown } from '@nestjs/common';
+import type { RealtimeConfig } from '@nage-api/contracts';
+import type { Clock, Propagator, RealtimeTransport, RoomPolicy, SocketAuthenticator } from './ports.js';
+export interface NageRealtimeModuleOptions {
+    readonly realtime?: RealtimeConfig;
+    readonly environment?: string;
+    /** Required: verifies a bearer token and resolves the principal. */
+    readonly authenticator?: SocketAuthenticator;
+    /** Refuses every room unless supplied. */
+    readonly roomPolicy?: RoomPolicy;
+    /** Socket.IO or another binding; in-memory when omitted. */
+    readonly transport?: RealtimeTransport;
+    readonly propagator?: Propagator;
+    readonly clock?: Clock;
+}
+export declare class NageRealtimeModule implements OnApplicationShutdown {
+    static forRoot(options?: NageRealtimeModuleOptions): DynamicModule;
+    onApplicationShutdown(): Promise<void>;
+    private static buildPropagator;
+}
+//# sourceMappingURL=realtime.module.d.ts.map

package/dist/realtime.module.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * `NageRealtimeModule.forRoot(config)` (PLAN.md §11.1 item 6, §12).
+ *
+ * An authenticator is **required**. There is no default, because the only
+ * possible default would be "accept anyone", and that is the legacy defect
+ * this package exists to remove.
+ *
+ * A multi-instance deployment without a propagator is refused for the same
+ * reason: it appears to work, and delivers each event to whichever fraction of
+ * users happens to be connected to the pod that emitted it.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var NageRealtimeModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NageRealtimeModule = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nage-api/core");
+const gateway_js_1 = require("./gateway.js");
+const memory_js_1 = require("./memory.js");
+const tokens_js_1 = require("./tokens.js");
+const gateways = [];
+let NageRealtimeModule = NageRealtimeModule_1 = class NageRealtimeModule {
+    static forRoot(options = {}) {
+        const config = options.realtime ?? {};
+        if (config.enabled !== true) {
+            return { module: NageRealtimeModule_1, providers: [], exports: [] };
+        }
+        if (options.authenticator === undefined) {
+            throw new core_1.ConfigurationError({
+                detail: 'NageRealtimeModule needs an authenticator; there is no anonymous fallback, because a default guest identity makes every authenticated room public',
+                meta: { setting: 'realtime.authenticator' },
+            });
+        }
+        const transport = options.transport ?? new memory_js_1.MemoryTransport();
+        const propagator = options.propagator ?? NageRealtimeModule_1.buildPropagator(config, options);
+        const gateway = new gateway_js_1.RealtimeGateway({
+            transport,
+            authenticator: options.authenticator,
+            ...(options.roomPolicy === undefined ? {} : { roomPolicy: options.roomPolicy }),
+            ...(propagator === undefined ? {} : { propagator }),
+            ...(options.clock === undefined ? {} : { clock: options.clock }),
+        });
+        gateways.push(gateway);
+        const providers = [
+            { provide: tokens_js_1.NAGE_REALTIME_TRANSPORT, useValue: transport },
+            { provide: tokens_js_1.NAGE_REALTIME, useValue: gateway },
+            { provide: gateway_js_1.RealtimeGateway, useValue: gateway },
+            ...(propagator === undefined
+                ? []
+                : [{ provide: tokens_js_1.NAGE_REALTIME_PROPAGATOR, useValue: propagator }]),
+        ];
+        return {
+            module: NageRealtimeModule_1,
+            providers,
+            exports: [
+                tokens_js_1.NAGE_REALTIME,
+                tokens_js_1.NAGE_REALTIME_TRANSPORT,
+                gateway_js_1.RealtimeGateway,
+                ...(propagator === undefined ? [] : [tokens_js_1.NAGE_REALTIME_PROPAGATOR]),
+            ],
+        };
+    }
+    async onApplicationShutdown() {
+        for (const gateway of gateways.splice(0))
+            await gateway.close();
+    }
+    static buildPropagator(config, options) {
+        if (config.adapter !== 'redis')
+            return new memory_js_1.MemoryPropagator();
+        // The in-memory propagator carries nothing between processes, so a
+        // deployment asking for `redis` and getting it would be a silent lie.
+        throw new core_1.ConfigurationError({
+            detail: 'realtime.adapter "redis" needs a propagator; pass one to NageRealtimeModule.forRoot({ propagator })',
+            meta: { setting: 'realtime.adapter', environment: options.environment },
+        });
+    }
+};
+exports.NageRealtimeModule = NageRealtimeModule;
+exports.NageRealtimeModule = NageRealtimeModule = NageRealtimeModule_1 = __decorate([
+    (0, common_1.Module)({})
+], NageRealtimeModule);
+//# sourceMappingURL=realtime.module.js.map

package/dist/tokens.d.ts

@@ -0,0 +1,8 @@
+/** DI tokens for realtime (PLAN.md §7.3). */
+import { type Token } from '@nage-api/core';
+import type { RealtimeGateway } from './gateway.js';
+import type { Propagator, RealtimeTransport } from './ports.js';
+export declare const NAGE_REALTIME: Token<RealtimeGateway>;
+export declare const NAGE_REALTIME_TRANSPORT: Token<RealtimeTransport>;
+export declare const NAGE_REALTIME_PROPAGATOR: Token<Propagator>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.js

@@ -0,0 +1,9 @@
+"use strict";
+/** DI tokens for realtime (PLAN.md §7.3). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NAGE_REALTIME_PROPAGATOR = exports.NAGE_REALTIME_TRANSPORT = exports.NAGE_REALTIME = void 0;
+const core_1 = require("@nage-api/core");
+exports.NAGE_REALTIME = (0, core_1.createToken)('NAGE_REALTIME');
+exports.NAGE_REALTIME_TRANSPORT = (0, core_1.createToken)('NAGE_REALTIME_TRANSPORT');
+exports.NAGE_REALTIME_PROPAGATOR = (0, core_1.createToken)('NAGE_REALTIME_PROPAGATOR');
+//# sourceMappingURL=tokens.js.map

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@nage-api/realtime",
+  "version": "1.0.0-beta.2",
+  "description": "Realtime for @nage-api — authenticated sockets and a cross-instance propagator",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/.tsbuildinfo",
+    "!dist/**/*.map",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nage-api/contracts": "1.0.0-beta.2",
+    "@nage-api/core": "1.0.0-beta.2"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "reflect-metadata": "^0.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.29",
+    "@nestjs/core": "11.1.29",
+    "@nestjs/testing": "11.1.29",
+    "@swc/core": "1.15.47",
+    "@types/node": "22.20.1",
+    "@vitest/coverage-v8": "4.1.10",
+    "reflect-metadata": "0.2.2",
+    "rimraf": "6.1.3",
+    "rxjs": "7.8.2",
+    "typescript": "5.9.3",
+    "unplugin-swc": "1.5.11",
+    "vitest": "4.1.10",
+    "@nage-api/testing": "1.0.0-beta.2"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "clean": "rimraf dist .turbo",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}