@dokebi/websocket 0.4.3 → 0.4.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AI.md +2 -2
- package/dist/gateway.js +22 -5
- package/dist/index.js +1 -1
- package/dist/types.d.ts +6 -0
- package/package.json +2 -2
package/AI.md
CHANGED
|
@@ -72,7 +72,7 @@ export const chatSocket = (app: AppContext) => defineSocket({
|
|
|
72
72
|
- Message format: JSON `{ type, data?, id? }`. `reply` and `error` are reserved types. An unknown type is `UNKNOWN_TYPE`, a malformed message `INVALID_MESSAGE`, and a handler error answers `{ type: 'error', id?, code }` with the error's `code` (upper-case form) or `HANDLER_FAILED` (message and stack are not sent; they go to the server log, §7).
|
|
73
73
|
- `socket` (`SocketContext`): `session`, `identity`, `send(type, data)` (this connection), `broadcast(type, data, { room?, member? })` (through the hub, tenant fixed → receipt `{ id, recipients }`). Receiving sockets get the same `{ type, data }` text frame as `send`.
|
|
74
74
|
- Multi-app: `sockets: (app) => [chatSocket(app)]` of @dokebi/app. The same path is registered separately per app, and the hub tenant is `<namespace>:<tenant>` (the default namespace is the app name, D-0061). The `namespace` that `authenticate` returns is read and removed by @dokebi/app; this package leaves `namespace` out when it registers with the hub.
|
|
75
|
-
- Route id (D-0140): `config: { id }` (`defineSocket` or `route`) becomes the Fastify config of the upgrade route, so `dokebi describe` lists it as `routes[].id`, `web.routes()` and the per-route hooks of dokebi-web (`web.routeHook`, an audit log's `onResponse`) see it, and the upgrade request reads it as `request.routeOptions.config.id`. dokebi-web checks it at start exactly like a web route's id: 1 to 64 letters, digits, `.`, `_` or `-`, starting with a letter (`INVALID_ROUTE_CONFIG`); the same id on two routes of one app (a web route, a socket or an event stream) fails the start with `DUPLICATE_ROUTE_ID`. `config` takes only `id`: null, a string or another key (`auth`, `csrf`, …) is `INVALID_ROUTE` at `route`. The refusal logs carry it as `routeId` (§7).
|
|
75
|
+
- Route id (D-0140): `config: { id }` (`defineSocket` or `route`) becomes the Fastify config of the upgrade route, so `dokebi describe` lists it as `routes[].id`, `web.routes()` and the per-route hooks of dokebi-web (`web.routeHook`, an audit log's `onResponse`) see it, and the upgrade request reads it as `request.routeOptions.config.id`. dokebi-web checks it at start exactly like a web route's id: 1 to 64 letters, digits, `.`, `_` or `-`, starting with a letter (`INVALID_ROUTE_CONFIG`); the same id on two routes of one app (a web route, a socket or an event stream) fails the start with `DUPLICATE_ROUTE_ID`. `config` takes only `id`: null, a string or another key (`auth`, `csrf`, …) is `INVALID_ROUTE` at `route`. The refusal logs carry it as `routeId` (§7). **`auth: false`** (0.4.5, [D-0230](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0230-machine-sockets-dev-modules-vue-imports.md)): `config: { id, auth: false }` leaves @dokebi/auth's route check out of the upgrade, so the route's own `authenticate` is its only check — a machine client with a key of its own (another server's agent: `Authorization: Bearer <key>`) under `default: required`. `auth` takes only `false` (`INVALID_ROUTE` otherwise; a socket already follows the default), and any other key is `INVALID_ROUTE` too. Example 85.
|
|
76
76
|
- Low level: `context.get(ws).route({ path, config?, origins?, constraints?, version?, seal?, authenticate, authorizeRoom?, message(data, session), presence? })` (`WebsocketRoute`). session (`WebsocketSession`): `id`, `identity`, `send`, `broadcast(bytes, target?)`, `join(room)`, `leave(room)`, `close(code?, reason?)`, `reportError?(error, details)` (§7). `connections` is the number of open connections of this process, and `sealing` says whether a seal provider is registered.
|
|
77
77
|
- Exports: `createPlugin`, `defineSocket`, `options`, `WebsocketError`, `SEAL_PROTOCOL`, `PLAIN_PROTOCOL`, types `WebsocketApi`, `WebsocketOptions`, `WebsocketRoute`, `WebsocketRouteConfig`, `WebsocketSession`, `WebsocketIdentity`, `WebsocketPeer`, `WebsocketPresence`, `WebsocketErrorDetails`, `WebsocketConnectionInfo`, `WebsocketFilter`, `WebsocketReceipt`, `WebsocketKickReceipt`, `SocketDefinition`, `SocketContext`, `SocketHandler`, `SocketCodecProvider`, `SocketCodec`, `SocketCodecConnection`, `SocketNonceStore`, `WebsocketTransport`, `WebsocketNamespaceHandle`, `WebsocketNamespaceTarget`, `WebsocketErrorCode`.
|
|
78
78
|
|
|
@@ -182,7 +182,7 @@ stop: block new work → wait for received handlers and broadcasts being sent
|
|
|
182
182
|
|
|
183
183
|
## 9. Cautions
|
|
184
184
|
|
|
185
|
-
- Never use `origins: '*'` on a cookie-authenticated route (Cross-Site WebSocket Hijacking). When a proxy rewrites Host, set web `trustProxy` accordingly or list the public origin in `origins`.
|
|
185
|
+
- Never use `origins: '*'` on a cookie-authenticated route (Cross-Site WebSocket Hijacking). Without `origins` the same Host passes with either scheme, except one case: an upgrade that came over **https** (the socket, or `X-Forwarded-Proto` from a proxy in web `trustProxy`) with an **`http://`** Origin of that host is 403 — an http page can be rewritten on the path and must not open the wss socket with the user's cookies. List `http://…` in `origins` if a page really has to. An upgrade that looks like http (a TLS proxy the app does not trust) is not held to this: name the proxy in `trustProxy`. When a proxy rewrites Host, set web `trustProxy` accordingly or list the public origin in `origins`.
|
|
186
186
|
- Examples that trust a header value as the identity (example 23) are for tests only.
|
|
187
187
|
- `hub.events` is consumed only by this plugin. No other code reads it.
|
|
188
188
|
- Broadcasts are at most once. They can be missed across reconnects, leader changes and slow consumers, and resending after `OUTCOME_UNKNOWN` can deliver twice.
|
package/dist/gateway.js
CHANGED
|
@@ -115,11 +115,22 @@ function configOf(route) {
|
|
|
115
115
|
throw new WebsocketError('INVALID_ROUTE', "WebSocket route config is an object such as { id: 'chat' }");
|
|
116
116
|
const values = value;
|
|
117
117
|
const keys = Object.keys(values).filter((key) => values[key] !== undefined);
|
|
118
|
-
const other = keys.find((key) => key !== 'id');
|
|
118
|
+
const other = keys.find((key) => key !== 'id' && key !== 'auth');
|
|
119
119
|
if (other !== undefined)
|
|
120
|
-
throw new WebsocketError('INVALID_ROUTE', `WebSocket route config takes only id, not ${JSON.stringify(other.slice(0, 64))}`);
|
|
120
|
+
throw new WebsocketError('INVALID_ROUTE', `WebSocket route config takes only id and auth, not ${JSON.stringify(other.slice(0, 64))}`);
|
|
121
|
+
// `auth: false` (D-0230): the route authenticates itself (its own authenticate is the only check);
|
|
122
|
+
// @dokebi/auth's route check, which a default of required puts on every route, is left out. No
|
|
123
|
+
// other value: a socket or stream already follows that default, and a login rule of its own
|
|
124
|
+
// belongs in authenticate.
|
|
125
|
+
if (values.auth !== undefined && values.auth !== false)
|
|
126
|
+
throw new WebsocketError('INVALID_ROUTE', `WebSocket route config auth may only be false (the route's own authenticate is then its only check), not ${JSON.stringify(values.auth)}`);
|
|
121
127
|
// Typed as the route config declares it; a value that is not a valid id fails the start.
|
|
122
|
-
|
|
128
|
+
if (!keys.length)
|
|
129
|
+
return undefined;
|
|
130
|
+
return Object.freeze({
|
|
131
|
+
...(values.id === undefined ? {} : { id: values.id }),
|
|
132
|
+
...(values.auth === false ? { auth: false } : {}),
|
|
133
|
+
});
|
|
123
134
|
}
|
|
124
135
|
/** Allow-list entries must be exact http(s) origins such as `https://app.example.com`. */
|
|
125
136
|
function parseOrigins(value) {
|
|
@@ -148,7 +159,7 @@ function parseOrigins(value) {
|
|
|
148
159
|
* Browsers always send Origin on WebSocket upgrades, so a foreign page cannot reuse the user's
|
|
149
160
|
* cookies (CSWSH) unless its origin is allowed. Clients without Origin are not browsers.
|
|
150
161
|
*/
|
|
151
|
-
function originAllowed(origin, host, allowed) {
|
|
162
|
+
function originAllowed(origin, host, allowed, secure = false) {
|
|
152
163
|
if (origin === undefined || allowed === '*')
|
|
153
164
|
return true;
|
|
154
165
|
if (typeof origin !== 'string')
|
|
@@ -166,6 +177,12 @@ function originAllowed(origin, host, allowed) {
|
|
|
166
177
|
return true;
|
|
167
178
|
if (typeof host !== 'string' || !host)
|
|
168
179
|
return false;
|
|
180
|
+
// The same host over plain http is another origin for a request that came over https: an
|
|
181
|
+
// http page (which anyone on the path can rewrite) must not open the wss socket with the
|
|
182
|
+
// user's cookies. The other way round is not refused: behind a TLS proxy the app does not
|
|
183
|
+
// trust, the request looks like http while the page really is https.
|
|
184
|
+
if (secure && url.protocol === 'http:')
|
|
185
|
+
return false;
|
|
169
186
|
try {
|
|
170
187
|
return new URL(`${url.protocol}//${host}`).host === url.host;
|
|
171
188
|
}
|
|
@@ -397,7 +414,7 @@ export class Gateway {
|
|
|
397
414
|
// D-0140: dokebi-web records and checks `config.id` (describe, duplicates, route hooks).
|
|
398
415
|
...(config ? { config: { ...config } } : {}),
|
|
399
416
|
preValidation: async (request, reply) => {
|
|
400
|
-
if (!originAllowed(request.headers.origin, this.web.requestHost(request), origins)) {
|
|
417
|
+
if (!originAllowed(request.headers.origin, this.web.requestHost(request), origins, request.protocol === 'https')) {
|
|
401
418
|
if (logger.isEnabled('debug'))
|
|
402
419
|
logger.log('debug', 'WebSocket origin refused', {
|
|
403
420
|
path: route.path,
|
package/dist/index.js
CHANGED
|
@@ -59,7 +59,7 @@ class WebsocketRuntime {
|
|
|
59
59
|
/** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-websocket']`. */
|
|
60
60
|
export const createPlugin = definePlugin({
|
|
61
61
|
name: 'dokebi-websocket',
|
|
62
|
-
version: '0.4.
|
|
62
|
+
version: '0.4.5',
|
|
63
63
|
core: '^0.4.2',
|
|
64
64
|
options,
|
|
65
65
|
contributes: [realtime],
|
package/dist/types.d.ts
CHANGED
|
@@ -88,6 +88,12 @@ export interface WebsocketRouteConfig {
|
|
|
88
88
|
* (INVALID_ROUTE_CONFIG); the same id on two routes of one app fails it (DUPLICATE_ROUTE_ID).
|
|
89
89
|
*/
|
|
90
90
|
readonly id?: string;
|
|
91
|
+
/**
|
|
92
|
+
* `false` (D-0230): this route authenticates itself, so its own `authenticate` is its only check
|
|
93
|
+
* (a machine client with a key of its own). @dokebi/auth's route check, which `default: required`
|
|
94
|
+
* puts on every route, is left out. No other value is taken (INVALID_ROUTE).
|
|
95
|
+
*/
|
|
96
|
+
readonly auth?: false;
|
|
91
97
|
}
|
|
92
98
|
export interface WebsocketRoute {
|
|
93
99
|
readonly path: string;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dokebi/websocket",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.5",
|
|
4
4
|
"description": "WebSocket routes on @dokebi/web with rooms and broadcast across servers through @dokebi/websocket-hub.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dokebi",
|
|
@@ -49,7 +49,7 @@
|
|
|
49
49
|
"@dokebi/websocket-hub": "^0.4.0"
|
|
50
50
|
},
|
|
51
51
|
"devDependencies": {
|
|
52
|
-
"@dokebi/web": "0.4.
|
|
52
|
+
"@dokebi/web": "0.4.12",
|
|
53
53
|
"@dokebi/websocket-hub": "0.4.3"
|
|
54
54
|
},
|
|
55
55
|
"dokebi": {
|