@db3.ai/app 0.1.0-beta.1 → 0.1.0

package/dist/server/registerHttpErrorHandler.js

@@ -0,0 +1,93 @@
+import { errorCodeForStatus, isDevelopmentEnvironment, isSqlError } from '@db3.ai/pure';
+import { ulid } from '@db3.ai/pure/ulid';
+import { RecordNotFoundError } from '../db/index.js';
+import { publicServerErrorMessage } from './publicServerErrorMessage.js';
+import { registerBrowserJsonFormatting } from './registerBrowserJsonFormatting.js';
+/**
+ * Installs framework error logging and production-safe HTTP responses.
+ *
+ * Call immediately after constructing Fastify, before registering any routes or
+ * plugins. The inherited send hook also sanitizes explicit 5xx responses and
+ * child-plugin error handlers. Only deliberate mapped client errors and Fastify
+ * request errors retain public messages. Browser JSON formatting is installed
+ * after this boundary so it only sees the safe serialized response. Never send
+ * internal errors as 2xx data.
+ *
+ * @param fastify - HTTP host, still owned and closed by the caller.
+ * @param options - Application error classification and support-record observer.
+ * @example
+ * const server = Fastify({ logger: true });
+ * registerHttpErrorHandler(server);
+ * server.get('/example', async () => loadExample());
+ */
+export function registerHttpErrorHandler(fastify, options = {}) {
+    const failures = new WeakMap();
+    /** Records the original exception once, keeping support-store failures private. */
+    function recordFailure(request, reply, error, responseBody) {
+        const existing = failures.get(reply);
+        if (existing?.reference)
+            return existing.reference;
+        const reference = ulid();
+        failures.set(reply, { error, reference });
+        const context = { request, statusCode: reply.statusCode, reference, responseBody };
+        request.log.error({ err: error, requestMethod: request.method, requestUrl: request.url, statusCode: reply.statusCode, reference, responseBody }, 'Request failed with server error');
+        try {
+            options.onServerError?.(error, context);
+        }
+        catch (observerError) {
+            request.log.error({ err: observerError, reference }, 'Server error observer failed');
+        }
+        return reference;
+    }
+    fastify.addHook('onError', (_request, reply, error, done) => {
+        failures.set(reply, { error });
+        done();
+    });
+    fastify.setErrorHandler((error, request, reply) => {
+        const mapped = isSqlError(error) ? undefined : options.mapError?.(error);
+        const response = mapped && Number.isInteger(mapped.statusCode) && mapped.statusCode >= 400 && mapped.statusCode <= 599
+            ? mapped
+            : defaultErrorResponse(error);
+        reply.type('application/json').code(response.statusCode);
+        if (response.statusCode < 500)
+            return reply.send(response.body);
+        const reference = recordFailure(request, reply, error);
+        return reply.send({ ...response.body, reference });
+    });
+    fastify.addHook('onSend', (request, reply, payload, done) => {
+        const failure = failures.get(reply);
+        if (reply.statusCode < 500) {
+            if (!isSqlError(failure?.error))
+                return done(null, payload);
+            // A child handler cannot make a database failure public by labelling
+            // it a client error or a successful response.
+            reply.code(500);
+        }
+        const responseBody = typeof payload === 'string' ? payload : Buffer.isBuffer(payload) ? payload.toString('utf8') : undefined;
+        const reference = recordFailure(request, reply, failure?.error ?? new Error(`HTTP ${reply.statusCode} response`), responseBody);
+        if (isDevelopmentEnvironment(process.env.NODE_ENV))
+            return done(null, payload);
+        // Replace the serialized body too: route schemas and child handlers must
+        // not reintroduce stack traces, SQL, provider codes or arbitrary metadata.
+        if (payload && typeof payload === 'object' && 'destroy' in payload && typeof payload.destroy === 'function')
+            payload.destroy();
+        reply.removeHeader('content-length');
+        reply.removeHeader('content-encoding');
+        reply.type('application/json').header('cache-control', 'no-store');
+        return done(null, JSON.stringify({ error: 'server_error', message: publicServerErrorMessage(failure?.error), reference }));
+    });
+    registerBrowserJsonFormatting(fastify);
+}
+/** Classifies framework client errors without trusting third-party status codes. */
+function defaultErrorResponse(error) {
+    if (!isSqlError(error) && error instanceof RecordNotFoundError) {
+        return { statusCode: 404, body: { error: 'not_found', message: error.message } };
+    }
+    if (!isSqlError(error) && error instanceof Error) {
+        const { code, statusCode } = error;
+        if (typeof code === 'string' && code.startsWith('FST_') && typeof statusCode === 'number' && Number.isInteger(statusCode) && statusCode >= 400 && statusCode < 500) {
+            return { statusCode, body: { error: errorCodeForStatus(statusCode), message: error.message } };
+        }
+    }
+    return { statusCode: 500, body: { error: 'server_error', message: publicServerErrorMessage(error) } };
+}

package/dist/ssr/vite/contracts/ViteSsrOptions.d.ts

@@ -28,6 +28,8 @@ export interface FastifyViteSsrOptions<TState extends object = SsrState> {
     template?: string;
     /** Vite development server-entry module id. */
     developmentEntry?: string;
+    /** Additional development-only Vite source routes, for example ['/client/*', '/apps/*']. */
+    developmentAssetRoutes?: readonly string[];
     /** Production client build directory containing the transformed template. */
     clientOutDir?: string;
     /** Production server bundle exporting the application renderer. */

package/dist/ssr/vite/fastifyViteSsr.js

@@ -46,7 +46,7 @@ export function fastifyViteSsr(options) {
             const runtime = await developmentRuntime(server.server, options);
             await server.register((await import('@fastify/middie')).default);
             server.use(runtime.vite.middlewares);
-            registerDevelopmentAssetRoutes(server);
+            registerDevelopmentAssetRoutes(server, options.developmentAssetRoutes);
             server.addHook('onClose', async () => {
                 await runtime.vite.close();
             });
@@ -82,9 +82,10 @@ export function fastifyViteSsr(options) {
  * application's ordinary not-found boundary remains authoritative.
  *
  * @param server - Encapsulated Fastify instance hosting the Vite middleware.
+ * @param additionalRoutes - Explicit browser source namespaces owned by this application.
  */
-function registerDevelopmentAssetRoutes(server) {
-    for (const route of DEVELOPMENT_ASSET_ROUTES) {
+function registerDevelopmentAssetRoutes(server, additionalRoutes = []) {
+    for (const route of new Set([...DEVELOPMENT_ASSET_ROUTES, ...additionalRoutes])) {
         server.get(route, (_request, reply) => reply.callNotFound());
     }
 }

package/dist/storage/drivers/FlystorageDisk.js

@@ -1,5 +1,5 @@
-import { storageContentsToBuffer } from '../contents.js';
-import { mimeTypeFromPath } from '../mime.js';
+import { storageContentsToBuffer } from '../storageContentsToBuffer.js';
+import { mimeTypeFromPath } from '../mimeTypeFromPath.js';
 import { normalizeStorageDirectoryPath, normalizeStoragePath } from '../path.js';
 import { FlystorageListing } from './FlystorageListing.js';
 /**

package/dist/storage/index.d.ts

@@ -1,7 +1,7 @@
 export * from './Storage.js';
-export * from './contents.js';
+export * from './storageContentsToBuffer.js';
 export * from './contracts/index.js';
 export * from './drivers/index.js';
-export * from './mime.js';
+export * from './mimeTypeFromPath.js';
 export * from './path.js';
 export * from './types.js';

package/dist/storage/index.js

@@ -1,7 +1,7 @@
 export * from './Storage.js';
-export * from './contents.js';
+export * from './storageContentsToBuffer.js';
 export * from './contracts/index.js';
 export * from './drivers/index.js';
-export * from './mime.js';
+export * from './mimeTypeFromPath.js';
 export * from './path.js';
 export * from './types.js';

package/dist/websocket/WebSocketChannels.d.ts

@@ -0,0 +1,18 @@
+import type { WebSocketContext, WebSocketChannelDefinition } from './contracts/index.js';
+/** Local fan-out for trusted server memberships and authorized browser subscriptions. */
+export declare class WebSocketChannels {
+    #private;
+    /** Joins an already-authorized connection and automatically leaves when its signal aborts. */
+    join(name: string, context: WebSocketContext<any>): () => void;
+    /** Sends JSON to current local members. Returns accepted transport sends, never durable delivery. */
+    publish(name: string, data: unknown): Promise<number>;
+    /**
+     * Handles the reserved subscription protocol. Unknown channels and denied access reveal no payload.
+     * @returns Whether this was a framework subscription command.
+     */
+    handle(definitions: readonly WebSocketChannelDefinition[], context: WebSocketContext<any>, data: unknown): Promise<boolean>;
+    /** Publishes a named event only to current authorized resource subscribers in this process. */
+    publishEvent(name: string, event: string, data: unknown): Promise<number>;
+    /** Drops local memberships during application shutdown. */
+    clear(): void;
+}

package/dist/websocket/WebSocketChannels.js

@@ -0,0 +1,129 @@
+/** Local fan-out for trusted server memberships and authorized browser subscriptions. */
+export class WebSocketChannels {
+    #subscriptions = new Map();
+    #counts = new Map();
+    #channels = new Map();
+    /** Joins an already-authorized connection and automatically leaves when its signal aborts. */
+    join(name, context) {
+        if (context.signal.aborted)
+            return () => { };
+        let members = this.#channels.get(name);
+        if (!members) {
+            members = new Map();
+            this.#channels.set(name, members);
+        }
+        const existing = members.get(context.id);
+        if (existing)
+            return existing.leave;
+        /** Removes only this membership and releases its abort listener. */
+        const leave = () => {
+            if (members.get(context.id)?.context === context)
+                members.delete(context.id);
+            if (!members.size && this.#channels.get(name) === members)
+                this.#channels.delete(name);
+            context.signal.removeEventListener('abort', leave);
+        };
+        context.signal.addEventListener('abort', leave, { once: true });
+        members.set(context.id, { context, leave });
+        return leave;
+    }
+    /** Sends JSON to current local members. Returns accepted transport sends, never durable delivery. */
+    async publish(name, data) {
+        const results = await Promise.all([...this.#channels.get(name)?.values() ?? []].map(member => member.context.send(data)));
+        return results.filter(Boolean).length;
+    }
+    /**
+     * Handles the reserved subscription protocol. Unknown channels and denied access reveal no payload.
+     * @returns Whether this was a framework subscription command.
+     */
+    async handle(definitions, context, data) {
+        if (!data || typeof data !== 'object' || !('type' in data) || !['channel.subscribe', 'channel.unsubscribe'].includes(String(data.type)))
+            return false;
+        const name = 'channel' in data ? data.channel : null;
+        if (typeof name !== 'string' || name.length > 256 || !/^[a-zA-Z0-9_.-]+(?::[a-zA-Z0-9_.-]+)*$/.test(name)) {
+            context.close();
+            return true;
+        }
+        const existing = this.#subscriptions.get(name)?.get(context.id);
+        if (data.type === 'channel.unsubscribe') {
+            existing?.leave();
+            return true;
+        }
+        const matches = definitions.map(definition => ({ definition, params: matchChannel(definition.pattern, name) })).filter(match => match.params !== null);
+        const match = matches.length === 1 ? matches[0] : undefined;
+        if (!context.user || !context.userId || !match || !await match.definition.authorize({ ...context, userId: context.userId, channel: name, params: match.params })) {
+            existing?.leave();
+            await context.send({ type: 'channel.denied', channel: name });
+            return true;
+        }
+        if (context.signal.aborted)
+            return true;
+        if (!existing) {
+            if ((this.#counts.get(context.id) ?? 0) >= 128) {
+                await context.send({ type: 'channel.denied', channel: name });
+                return true;
+            }
+            let members = this.#subscriptions.get(name);
+            if (!members) {
+                members = new Map();
+                this.#subscriptions.set(name, members);
+            }
+            /** Removes this connection's subscription exactly once, including during in-flight authorization. */
+            const leave = () => {
+                if (!members.delete(context.id))
+                    return;
+                if (!members.size)
+                    this.#subscriptions.delete(name);
+                const count = (this.#counts.get(context.id) ?? 1) - 1;
+                if (count)
+                    this.#counts.set(context.id, count);
+                else
+                    this.#counts.delete(context.id);
+                context.signal.removeEventListener('abort', leave);
+            };
+            members.set(context.id, { context, definition: match.definition, params: match.params, leave });
+            this.#counts.set(context.id, (this.#counts.get(context.id) ?? 0) + 1);
+            context.signal.addEventListener('abort', leave, { once: true });
+        }
+        await context.send({ type: 'channel.subscribed', channel: name });
+        return true;
+    }
+    /** Publishes a named event only to current authorized resource subscribers in this process. */
+    async publishEvent(name, event, data) {
+        if (!event || event.length > 256)
+            throw new Error('Invalid channel event.');
+        const members = this.#subscriptions.get(name);
+        const results = await Promise.all([...members?.values() ?? []].map(member => member.context.send({ type: 'channel.event', channel: name, event, data }, async (context) => {
+            if (members?.get(context.id) !== member)
+                return false;
+            if (!context.user || !context.userId || !await member.definition.authorize({ ...context, userId: context.userId, channel: name, params: member.params })) {
+                member.leave();
+                return false;
+            }
+            return members?.get(context.id) === member;
+        })));
+        return results.filter(Boolean).length;
+    }
+    /** Drops local memberships during application shutdown. */
+    clear() { for (const members of this.#subscriptions.values())
+        for (const member of members.values())
+            member.leave(); for (const members of this.#channels.values())
+        for (const member of members.values())
+            member.leave(); }
+}
+/** Matches whole colon-delimited segments; parameter values never include separators. */
+function matchChannel(pattern, name) {
+    const expected = pattern.split(':');
+    const actual = name.split(':');
+    if (expected.length !== actual.length)
+        return null;
+    const params = Object.create(null);
+    for (let index = 0; index < expected.length; index++) {
+        const segment = expected[index];
+        if (/^\{[a-zA-Z][a-zA-Z0-9_]*\}$/.test(segment))
+            params[segment.slice(1, -1)] = actual[index];
+        else if (segment !== actual[index])
+            return null;
+    }
+    return params;
+}

package/dist/websocket/WebSocketConnection.d.ts

@@ -0,0 +1,25 @@
+import type { IncomingMessage } from 'node:http';
+import { WebSocket } from 'ws';
+import type { App } from '../server/App.js';
+import type * as socket from './contracts/index.js';
+/** One bounded JSON connection with fresh request authentication for application work. */
+export declare class WebSocketConnection {
+    #private;
+    readonly ws: WebSocket;
+    readonly request: IncomingMessage;
+    readonly app: App;
+    readonly endpoint: socket.WebSocketEndpoint<any, any>;
+    readonly limits: socket.WebSocketLimits;
+    readonly report: (error: unknown) => void;
+    readonly presenceChanged: () => void;
+    readonly resolveToken?: socket.WebSocketOptions['resolveToken'];
+    readonly id: `${string}-${string}-${string}-${string}-${string}`;
+    /** Attaches listeners synchronously so early frames cannot bypass authentication. */
+    constructor(ws: WebSocket, request: IncomingMessage, app: App, endpoint: socket.WebSocketEndpoint<any, any>, limits: socket.WebSocketLimits, report: (error: unknown) => void, presenceChanged: () => void, resolveToken?: socket.WebSocketOptions['resolveToken']);
+    /** Stops delivery immediately and bounds the close handshake for unresponsive peers. */
+    stop(code?: number): void;
+    /** Resolves when the socket and application cleanup are finished. */
+    finished(): Promise<void>;
+    /** Returns local presence only after authorization and until shutdown/disconnection. */
+    get userId(): string | null;
+}

package/dist/websocket/WebSocketConnection.js

@@ -0,0 +1,244 @@
+import { randomUUID } from 'node:crypto';
+import { WebSocket } from 'ws';
+/** One bounded JSON connection with fresh request authentication for application work. */
+export class WebSocketConnection {
+    ws;
+    request;
+    app;
+    endpoint;
+    limits;
+    report;
+    presenceChanged;
+    resolveToken;
+    id = randomUUID();
+    #abort = new AbortController();
+    #token = '';
+    #userId = '';
+    #ready = false;
+    #pending = 0;
+    /** Bounds retained payloads and concurrent access checks before transport buffering. */
+    #pendingSends = 0;
+    #chain = Promise.resolve();
+    #alive = true;
+    #checking = false;
+    #timer;
+    #heartbeat;
+    #finished;
+    #finish;
+    /** Attaches listeners synchronously so early frames cannot bypass authentication. */
+    constructor(ws, request, app, endpoint, limits, report, presenceChanged, resolveToken) {
+        this.ws = ws;
+        this.request = request;
+        this.app = app;
+        this.endpoint = endpoint;
+        this.limits = limits;
+        this.report = report;
+        this.presenceChanged = presenceChanged;
+        this.resolveToken = resolveToken;
+        this.#finished = new Promise(resolve => { this.#finish = resolve; });
+        this.#abort.signal.addEventListener('abort', () => { if (this.#ready)
+            this.presenceChanged(); }, { once: true });
+        this.#timer = setTimeout(() => this.stop(4401), limits.authTimeoutMs);
+        this.#heartbeat = setInterval(() => void this.#tick(), limits.heartbeatMs);
+        this.#timer.unref();
+        this.#heartbeat.unref();
+        ws.on('pong', () => { this.#alive = true; });
+        ws.on('error', () => this.stop(1011));
+        ws.on('message', (data, binary) => this.#receive(data, binary));
+        ws.once('close', code => {
+            this.#abort.abort();
+            this.#token = '';
+            clearTimeout(this.#timer);
+            clearInterval(this.#heartbeat);
+            // Wait for open/message work before cleanup, including an open action that closed itself.
+            void this.#chain.then(async () => {
+                if (this.#ready)
+                    await this.endpoint.close?.({ id: this.id, userId: this.#userId || null, code });
+            }).catch(this.report).finally(this.#finish);
+        });
+    }
+    /** Stops delivery immediately and bounds the close handshake for unresponsive peers. */
+    stop(code = 1000) {
+        if (this.#abort.signal.aborted)
+            return;
+        this.#abort.abort();
+        clearTimeout(this.#timer);
+        clearInterval(this.#heartbeat);
+        this.ws.close(code);
+        this.#timer = setTimeout(() => this.ws.terminate(), this.limits.shutdownTimeoutMs);
+        this.#timer.unref();
+    }
+    /** Resolves when the socket and application cleanup are finished. */
+    finished() { return this.#finished; }
+    /** Returns local presence only after authorization and until shutdown/disconnection. */
+    get userId() { return this.#ready && !this.#abort.signal.aborted ? this.#userId : null; }
+    /** Queues bounded text messages; the first frame is reserved for authentication. */
+    #receive(data, binary) {
+        if (this.#abort.signal.aborted)
+            return;
+        if (binary) {
+            this.stop(1003);
+            return;
+        }
+        if (++this.#pending > this.limits.maxPendingMessages) {
+            this.stop(1008);
+            return;
+        }
+        const text = data.toString();
+        this.#chain = this.#chain.then(async () => {
+            if (this.#abort.signal.aborted)
+                return;
+            let frame;
+            try {
+                frame = JSON.parse(text);
+            }
+            catch {
+                this.stop(1007);
+                return;
+            }
+            if (!this.#ready) {
+                if (this.endpoint.auth === 'public') {
+                    if (frame?.type !== 'connect') {
+                        this.stop(1008);
+                        return;
+                    }
+                }
+                else {
+                    if (frame?.type !== 'authenticate') {
+                        this.stop(4401);
+                        return;
+                    }
+                    const token = this.resolveToken ? await this.resolveToken(this.request) : frame.token;
+                    if (typeof token !== 'string' || !token || token.length > 4096) {
+                        this.stop(4401);
+                        return;
+                    }
+                    this.#token = token;
+                }
+                await this.#authorized(async (context) => {
+                    this.#ready = true;
+                    clearTimeout(this.#timer);
+                    this.#write({ type: 'ready' });
+                    this.presenceChanged();
+                    await this.endpoint.open?.(context);
+                });
+                return;
+            }
+            if (frame?.type !== 'message' || !Object.hasOwn(frame, 'data')) {
+                this.stop(1008);
+                return;
+            }
+            await this.#authorized(async (context) => {
+                if (await this.app.webSockets.channels.handle(this.endpoint.channels ?? [], context, frame.data))
+                    return;
+                let data;
+                try {
+                    data = this.endpoint.parse ? await this.endpoint.parse(frame.data) : frame.data;
+                }
+                catch {
+                    this.stop(1008);
+                    return;
+                }
+                if (!this.#abort.signal.aborted)
+                    await this.endpoint.message?.(context, data);
+            });
+        }).catch(error => { this.report(error); this.stop(1011); }).finally(() => { this.#pending--; });
+    }
+    /** Revalidates sessions and application access without retaining request-scoped Auth memoization. */
+    async #authorized(action) {
+        if (this.#abort.signal.aborted)
+            return false;
+        return this.app.requestContext.run(async () => {
+            const publicEndpoint = this.endpoint.auth === 'public';
+            const user = publicEndpoint ? null : await this.app.auth.authenticateToken(this.#token);
+            if (this.#abort.signal.aborted)
+                return false;
+            if (!publicEndpoint && !user) {
+                this.stop(4401);
+                return false;
+            }
+            const userId = user ? String(user.get(user.constructor.primaryKey)) : null;
+            if (this.#userId && this.#userId !== userId) {
+                this.stop(4401);
+                return false;
+            }
+            this.#userId = userId ?? '';
+            const context = {
+                id: this.id, userId, user, request: this.request, signal: this.#abort.signal,
+                send: (data, authorize) => this.#send(data, authorize), close: () => this.stop(),
+            };
+            if (this.endpoint.authorize && !await this.endpoint.authorize(context)) {
+                this.stop(4403);
+                return false;
+            }
+            if (this.#abort.signal.aborted)
+                return false;
+            await action(context);
+            return true;
+        });
+    }
+    /** Bounds in-flight sends before fresh access checks; overload disconnects without queuing or replay. */
+    async #send(data, authorize) {
+        if (this.#abort.signal.aborted)
+            return false;
+        if (this.#pendingSends >= this.limits.maxPendingSends) {
+            this.stop(1013);
+            return false;
+        }
+        this.#pendingSends++;
+        try {
+            let sent = false;
+            await this.#authorized(async (context) => {
+                if (!authorize || await authorize(context))
+                    sent = this.#write({ type: 'message', data });
+            });
+            return sent;
+        }
+        catch (error) {
+            this.report(error);
+            this.stop(1011);
+            return false;
+        }
+        finally {
+            this.#pendingSends--;
+        }
+    }
+    /** Enforces frame and buffered-byte limits before handing data to the socket. */
+    #write(frame) {
+        if (this.#abort.signal.aborted || this.ws.readyState !== WebSocket.OPEN)
+            return false;
+        const value = JSON.stringify(frame);
+        const bytes = Buffer.byteLength(value);
+        if (bytes > this.limits.maxPayloadBytes || this.ws.bufferedAmount + bytes > this.limits.maxBufferedBytes) {
+            this.stop(1009);
+            return false;
+        }
+        this.ws.send(value, error => { if (error)
+            this.stop(1011); });
+        return true;
+    }
+    /** Detects dead peers and revokes idle authenticated sockets as well as active ones. */
+    async #tick() {
+        if (this.#abort.signal.aborted)
+            return;
+        if (!this.#alive || this.#checking) {
+            this.stop(1011);
+            return;
+        }
+        this.#alive = false;
+        this.ws.ping();
+        if (!this.#ready)
+            return;
+        this.#checking = true;
+        try {
+            await this.#authorized(async () => { });
+        }
+        catch (error) {
+            this.report(error);
+            this.stop(1011);
+        }
+        finally {
+            this.#checking = false;
+        }
+    }
+}

package/dist/websocket/WebSockets.d.ts

@@ -0,0 +1,41 @@
+import type { Server } from 'node:http';
+import type { App } from '../server/App.js';
+import { WebSocketChannels } from './WebSocketChannels.js';
+import type * as socket from './contracts/index.js';
+/** App-owned WebSocket endpoints on an existing Node HTTP/S listener. */
+export declare class WebSockets {
+    #private;
+    readonly app: App;
+    readonly options: socket.WebSocketServiceOptions;
+    /** Process-local, server-authorized channels. Each delivery rechecks the connection's policy. */
+    readonly channels: WebSocketChannels;
+    /** Configures worker HTTP delivery without opening a connection or starting a polling loop. */
+    constructor(app: App, options?: socket.WebSocketServiceOptions);
+    /** Returns a publisher for a concrete authorized resource channel. No client subscription is created. */
+    channel(name: string): socket.WebSocketChannelPublisher;
+    /**
+     * Mounts exact-path endpoint actions on one existing HTTP/S server.
+     * @param server - Host-owned listener; the service never opens or closes its port.
+     * @param options - Allowed origins, controller definitions and resource limits.
+     */
+    mount(server: Server, options: socket.WebSocketOptions): void;
+    /** Stops accepting upgrades and bounds socket/application cleanup; safe to call repeatedly. */
+    close(): Promise<void>;
+    /**
+     * Lists distinct authenticated users connected to an exact endpoint in this process.
+     * Application code must authorize disclosure; this is never exposed automatically.
+     * Presence is approximate and excludes the other instance during blue/green overlap.
+     * @param path - Registered endpoint path, excluding query parameters.
+     * @returns Current user IDs and connection counts; no session tokens or profile data.
+     */
+    presence(path: string): socket.WebSocketPresence[];
+    /**
+     * Subscribes to local presence changes on one exact endpoint, without exposing them to browsers.
+     * Call presence(path) inside the listener to read current users. The listener has no Auth context
+     * and does not serialize asynchronous listeners; connection.send() reauthenticates its recipient.
+     * @param path - Exact endpoint whose authenticated connections should be observed.
+     * @param listener - Application callback for connect, disconnect or revocation changes.
+     * @returns Idempotent unsubscribe callback; register it on the owning connection's abort signal.
+     */
+    onPresence(path: string, listener: () => void | Promise<void>): () => void;
+}