@camstack/server 1.0.0 → 1.0.1

package/dist/api/trpc/scope-access.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkScopeAccess = checkScopeAccess;
+/**
+ * Pure scope-access matcher.
+ *
+ * Extracted from `trpc.middleware.ts` so the spec can exercise it
+ * without spinning up the tRPC initTRPC machinery. The function is
+ * stateless aside from an optional device-ancestor lookup callback.
+ *
+ * Algorithm (v2 — four scope types):
+ *   1. Look the tRPC `path` up in `METHOD_ACCESS_MAP`. Unknown =
+ *      FORBIDDEN (codegen drift; fail closed).
+ *   2. For each scope on the caller, check if it matches:
+ *      - `category`   — scope.target matches meta.capScope ('device'|'system')
+ *      - `capability` — scope.target matches meta.capName exactly
+ *      - `addon`      — scope.target matches meta.addonId (when set)
+ *      - `device`     — input.deviceId (OR any of its ancestor deviceIds
+ *                       via `getDeviceAncestors`) is in scope.targets.
+ *                       Auto-inheritance means granting a Reolink camera
+ *                       implicitly grants its siren / floodlight / PIR
+ *                       child accessories without re-listing them.
+ *   3. On a target match, accept iff `scope.access` includes the
+ *      method's required `access` flavour.
+ *   4. No matching scope → FORBIDDEN with a human-readable reason.
+ */
+const types_1 = require("@camstack/types");
+/**
+ * Pull `deviceId` off a tRPC request input. Device-scope cap methods
+ * uniformly take `{deviceId: number, ...}` per the DeviceProxy contract,
+ * so a single extractor covers every device-scope call. Returns null when
+ * the input doesn't carry a deviceId (system-scope cap, void input, …).
+ */
+function extractDeviceId(input) {
+    if (input === null || typeof input !== 'object')
+        return null;
+    const candidate = input['deviceId'];
+    return typeof candidate === 'number' ? candidate : null;
+}
+/**
+ * Build the set of deviceIds that count as "this request" for the
+ * device-scope match: the deviceId itself plus every ancestor (so a
+ * scope on the parent camera covers accessory children).
+ */
+function effectiveDeviceIds(deviceId, getAncestors) {
+    if (!getAncestors)
+        return [String(deviceId)];
+    const out = new Set([String(deviceId)]);
+    for (const ancestor of getAncestors(deviceId))
+        out.add(String(ancestor));
+    return [...out];
+}
+function checkScopeAccess(scopes, path, input, getDeviceAncestors) {
+    const meta = types_1.METHOD_ACCESS_MAP[path];
+    if (!meta) {
+        return { ok: false, reason: `Unknown method '${path}' — codegen drift` };
+    }
+    const deviceId = meta.capScope === 'device' ? extractDeviceId(input) : null;
+    const deviceChain = deviceId !== null ? effectiveDeviceIds(deviceId, getDeviceAncestors) : [];
+    for (const s of scopes) {
+        let targetMatches = false;
+        switch (s.type) {
+            case 'category':
+                targetMatches = s.target === meta.capScope;
+                break;
+            case 'capability':
+                targetMatches = s.target === meta.capName;
+                break;
+            case 'addon':
+                targetMatches = meta.addonId !== null && s.target === meta.addonId;
+                break;
+            case 'device':
+                // Match if the request's device — or any of its ancestors — is
+                // in the grant's target list. Accessory children inherit the
+                // parent's scope without re-enumeration.
+                targetMatches = deviceChain.some((id) => s.targets.includes(id));
+                break;
+        }
+        if (!targetMatches)
+            continue;
+        if (s.access.includes(meta.access))
+            return { ok: true, access: meta.access };
+    }
+    return {
+        ok: false,
+        reason: `No scope grants ${meta.access} on '${meta.capName}' (${meta.capScope}-scope cap${deviceId !== null ? `, device=${deviceId}` : ''}). Have: ${scopes
+            .map((s) => {
+            const target = s.type === 'device' ? `[${s.targets.join(',')}]` : s.target;
+            return `${s.type}:${target}[${s.access.join(',')}]`;
+        })
+            .join(', ') || '(none)'}`,
+    };
+}

package/dist/api/trpc/trpc.context.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createMeshTrpcContext = createMeshTrpcContext;
+exports.createTrpcContext = createTrpcContext;
+exports.createWsTrpcContext = createWsTrpcContext;
+/** Read `req.query` if present (Fastify-only) without losing type safety. */
+function readQuery(req) {
+    if (!('query' in req))
+        return null;
+    const q = Reflect.get(req, 'query');
+    if (q === null || typeof q !== 'object' || Array.isArray(q))
+        return null;
+    return { ...q };
+}
+/**
+ * Extract a JWT token from an HTTP request.
+ * Priority: Authorization header → Fastify req.query → URL query string
+ */
+function extractTokenFromRequest(req) {
+    const authHeader = req.headers.authorization;
+    if (authHeader && typeof authHeader === 'string') {
+        const [scheme, token] = authHeader.split(' ');
+        if (scheme === 'Bearer' && token)
+            return token;
+    }
+    // Fastify-parsed query object (HTTP tRPC requests)
+    const q = readQuery(req);
+    if (q && typeof q.token === 'string') {
+        return q.token;
+    }
+    // Raw URL query string fallback (IncomingMessage or Fastify w/o parsed query)
+    const url = req.url;
+    if (url) {
+        const qIdx = url.indexOf('?');
+        if (qIdx !== -1) {
+            const t = new URLSearchParams(url.slice(qIdx + 1)).get('token');
+            if (t)
+                return t;
+        }
+    }
+    return null;
+}
+/**
+ * Resolve an AuthenticatedAgent from a raw token. Handles both JWT
+ * (sync, via authService) and `cst_*` scoped tokens (async, via the
+ * `user-management` cap singleton — same path addon-upload uses for
+ * its REST auth chain).
+ *
+ * Returns `null` for: missing token, malformed JWT, unknown scoped
+ * token. Caller (protectedProcedure) decides the failure response
+ * (typically UNAUTHORIZED).
+ */
+async function resolveUser(token, authService, addonRegistry) {
+    if (!token)
+        return null;
+    // Scoped-token path: hit the user-management cap. Synthetic user
+    // with `isAdmin: false` so admin-gated procedures bounce while
+    // protectedProcedure can still gate by scope match.
+    if (token.startsWith('cst_')) {
+        try {
+            const userMgmt = addonRegistry.getCapabilityRegistry().getSingleton('user-management');
+            if (!userMgmt)
+                return null;
+            const record = await userMgmt.validateScopedToken({ token });
+            if (!record)
+                return null;
+            return {
+                id: record.userId,
+                // Display label — `scoped:<prefix>` makes audit logs read
+                // naturally without exposing the token hash.
+                username: `scoped:${record.tokenPrefix}`,
+                isAdmin: false,
+                permissions: {
+                    isAdmin: false,
+                    allowedProviders: '*',
+                    allowedDevices: {},
+                },
+                isApiKey: true,
+                isScoped: true,
+                scopes: record.scopes,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    // JWT path.
+    try {
+        const payload = authService.verifyToken(token);
+        // Reject pre-v2 JWTs at the boundary. Tokens issued before the
+        // role → isAdmin migration don't carry the `isAdmin` field, so
+        // letting them through would degrade silently into "non-admin
+        // with no scopes" → locked out of every cap. Returning null forces
+        // the client to land on 401 → re-login, where it picks up a fresh
+        // v2 token. No back-compat shim — the role enum is gone.
+        if (typeof payload.isAdmin !== 'boolean') {
+            return null;
+        }
+        return {
+            id: payload.userId ?? payload.keyId ?? 'unknown',
+            username: payload.username ?? 'unknown',
+            isAdmin: payload.isAdmin,
+            permissions: {
+                isAdmin: payload.isAdmin,
+                allowedProviders: payload.allowedProviders,
+                allowedDevices: payload.allowedDevices,
+            },
+            isApiKey: payload.type === 'api_key',
+            agentId: payload.agentId,
+            // Scopes are baked into the JWT at login; the middleware uses
+            // them to gate every call until the user re-logs.
+            ...(payload.scopes !== undefined ? { scopes: payload.scopes } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build the parent-chain walker for the scope-access matcher. Returns
+ * every ancestor deviceId of `deviceId` (parent, grandparent, …) so a
+ * grant on a Reolink camera covers its accessory children without
+ * re-enumerating them.
+ *
+ * Bounded by hop count (defence-in-depth — the device tree should
+ * never exceed 2-3 levels but a corrupt registry shouldn't loop forever).
+ */
+function makeAncestorLookup(addonRegistry) {
+    return (deviceId) => {
+        const out = [];
+        const registry = addonRegistry.getDeviceRegistry();
+        let current = registry.getById(deviceId);
+        for (let hop = 0; hop < 8 && current?.parentDeviceId != null; hop++) {
+            out.push(current.parentDeviceId);
+            current = registry.getById(current.parentDeviceId);
+        }
+        return out;
+    };
+}
+/**
+ * Context factory for hub-internal calls originating from the trusted
+ * Moleculer mesh (the `$core-caps` bridge service in `core-cap-bridge.ts`).
+ *
+ * Cluster membership is gated by `CAMSTACK_CLUSTER_SECRET`, so a
+ * mesh-originated call is treated as a fully-trusted admin: it carries
+ * a synthetic `isAdmin` user, which makes `protectedProcedure` /
+ * `adminProcedure` pass without a JWT and skips the scope-access
+ * matcher entirely. There is no HTTP request behind the call.
+ */
+function createMeshTrpcContext() {
+    const user = {
+        id: 'mesh',
+        username: 'mesh',
+        isAdmin: true,
+        permissions: { isAdmin: true, allowedProviders: '*', allowedDevices: {} },
+        isApiKey: true,
+    };
+    return { user };
+}
+/** Context factory for HTTP tRPC requests (Fastify adapter). */
+async function createTrpcContext(req, authService, addonRegistry) {
+    const token = extractTokenFromRequest(req);
+    return {
+        user: await resolveUser(token, authService, addonRegistry),
+        req,
+        getDeviceAncestors: makeAncestorLookup(addonRegistry),
+    };
+}
+/**
+ * Context factory for WebSocket tRPC connections (applyWSSHandler).
+ * Token is sent via tRPC connectionParams (a JSON message sent right after
+ * the WS handshake), which is more reliable than query params through proxies.
+ */
+async function createWsTrpcContext(opts, authService, addonRegistry) {
+    // 1. connectionParams.token (sent by BackendClient's createWSClient)
+    const paramToken = opts.info.connectionParams?.['token'];
+    const token = (typeof paramToken === 'string' ? paramToken : null) ?? extractTokenFromRequest(opts.req);
+    const user = await resolveUser(token, authService, addonRegistry);
+    return {
+        user,
+        req: opts.req,
+        getDeviceAncestors: makeAncestorLookup(addonRegistry),
+    };
+}

package/dist/api/trpc/trpc.middleware.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentProcedure = exports.adminProcedure = exports.protectedProcedure = exports.createCallerFactory = exports.publicProcedure = exports.trpcRouter = void 0;
+exports.iterableSubscription = iterableSubscription;
+exports.iterableInterval = iterableInterval;
+const server_1 = require("@trpc/server");
+const superjson_1 = __importDefault(require("superjson"));
+const types_1 = require("@camstack/types");
+const scope_access_js_1 = require("./scope-access.js");
+const cap_route_error_formatter_js_1 = require("./cap-route-error-formatter.js");
+const t = server_1.initTRPC.context().create({
+    transformer: superjson_1.default,
+    errorFormatter: cap_route_error_formatter_js_1.formatTrpcError,
+});
+// ---------------------------------------------------------------------------
+// Async-generator subscription helpers (tRPC v11 — replaces deprecated observable)
+// ---------------------------------------------------------------------------
+/**
+ * Convert a push-based subscription (callback → unsubscribe) into an async generator
+ * suitable for tRPC v11 `.subscription()`.
+ *
+ * @param subscribe — called once; receives a `push` callback and must return an unsubscribe fn.
+ */
+async function* iterableSubscription(subscribe) {
+    const queue = [];
+    let resolve = null;
+    const unsub = subscribe((value) => {
+        queue.push(value);
+        resolve?.();
+    });
+    try {
+        while (true) {
+            while (queue.length > 0) {
+                yield queue.shift();
+            }
+            await new Promise((r) => {
+                resolve = r;
+            });
+        }
+    }
+    finally {
+        unsub();
+    }
+}
+/**
+ * Create an interval-based async generator that yields a value on each tick.
+ * Useful for polling subscriptions.
+ */
+async function* iterableInterval(intervalMs, getValue) {
+    try {
+        while (true) {
+            yield getValue();
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+    }
+    finally {
+        // cleanup handled by generator return
+    }
+}
+exports.trpcRouter = t.router;
+exports.publicProcedure = t.procedure;
+/**
+ * Server-side caller factory — turns the hub appRouter into a directly
+ * invokable record under a supplied `TrpcContext`. The core-cap bridge
+ * (`core-cap-bridge.ts`) uses it to expose core routers over the
+ * Moleculer mesh without an HTTP round-trip.
+ */
+exports.createCallerFactory = t.createCallerFactory;
+/**
+ * Caps-only authenticated procedure (v2).
+ *
+ *   - `isAdmin: true` → pass-through. Admin's `scopes` field is ignored.
+ *   - `isAdmin: false` → `METHOD_ACCESS_MAP[path]` lookup + scope match.
+ *     The caller's scope set must grant the required (capName, access)
+ *     pair via one of the three forms (`category`/`capability`/`addon`).
+ *
+ * Hand-written core routers (`auth.*`, `system.info`, etc.) are not
+ * codegen'd from cap definitions and therefore not in
+ * `METHOD_ACCESS_MAP`. Those routes carry their own gating via
+ * `adminProcedure` when destructive; the bare `protectedProcedure`
+ * authentication check is the only gate. The middleware skips the
+ * scope-check for unknown paths so the SDK boot probe (`auth.me`) and
+ * `system.info` reach non-admin / scoped-token callers — without
+ * pulling every core route into the codegen map.
+ *
+ * Single source of authority for caps: `isAdmin`. The legacy role enum
+ * collapsed onto this boolean in v2.
+ */
+exports.protectedProcedure = t.procedure.use(async ({ ctx, next, path, getRawInput }) => {
+    if (!ctx.user) {
+        throw new server_1.TRPCError({ code: 'UNAUTHORIZED' });
+    }
+    // Spread+reassign of `user` narrows downstream ctx from `User | null`
+    // to `User` so `adminProcedure` / `agentProcedure` can read fields
+    // without re-checking.
+    if (ctx.user.isAdmin) {
+        return next({ ctx: { ...ctx, user: ctx.user } });
+    }
+    // Hand-written core route — no cap entry. Authentication has already
+    // passed; defer further gating to any explicit `adminProcedure`
+    // chained on top of this one.
+    if (!(path in types_1.METHOD_ACCESS_MAP)) {
+        return next({ ctx: { ...ctx, user: ctx.user } });
+    }
+    // Device-scope caps may be gated by a `device:N` scope. Resolve the
+    // raw input once so the matcher can read `input.deviceId` without
+    // re-doing the Zod parse (tRPC caches the parsed input downstream).
+    // The `getDeviceAncestors` hook lets the matcher walk parent → child
+    // accessory inheritance (grant on Reolink also covers its siren / PIR).
+    const rawInput = await getRawInput();
+    const result = (0, scope_access_js_1.checkScopeAccess)(ctx.user.scopes ?? [], path, rawInput, ctx.getDeviceAncestors);
+    if (!result.ok) {
+        throw new server_1.TRPCError({ code: 'FORBIDDEN', message: result.reason });
+    }
+    return next({ ctx: { ...ctx, user: ctx.user } });
+});
+/**
+ * Destructive-ops gate. Adds an explicit admin check on top of
+ * `protectedProcedure`. Useful on hand-written routes whose admin-only
+ * nature should be obvious to a code reader.
+ */
+exports.adminProcedure = exports.protectedProcedure.use(({ ctx, next }) => {
+    if (!ctx.user.isAdmin) {
+        throw new server_1.TRPCError({ code: 'FORBIDDEN', message: 'Admin required' });
+    }
+    return next({ ctx });
+});
+/**
+ * Procedure for agent service accounts. After the v2 collapse, agents
+ * are admin sessions issued via `createServiceToken` — they all get
+ * `isAdmin: true`. This procedure is identical to `adminProcedure`;
+ * kept for naming clarity on agent-specific routes.
+ */
+exports.agentProcedure = exports.adminProcedure.use(({ ctx, next }) => {
+    return next({ ctx: { ...ctx, agentId: ctx.user.agentId ?? ctx.user.id } });
+});

package/dist/api/trpc/trpc.router.js

@@ -0,0 +1,188 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enrichInputWithUserAgent = enrichInputWithUserAgent;
+exports.wrapWebrtcSessionProviderWithRelay = wrapWebrtcSessionProviderWithRelay;
+exports.buildAppRouter = buildAppRouter;
+const trpc_middleware_1 = require("./trpc.middleware");
+const generated_cap_routers_1 = require("./generated-cap-routers");
+const generated_cap_mounts_js_1 = require("./generated-cap-mounts.js");
+const cap_providers_js_1 = require("../core/cap-providers.js");
+const auth_router_js_1 = require("../core/auth.router.js");
+const addon_settings_router_js_1 = require("../core/addon-settings.router.js");
+const settings_backend_router_js_1 = require("../core/settings-backend.router.js");
+const event_bus_proxy_router_js_1 = require("../core/event-bus-proxy.router.js");
+const repl_router_js_1 = require("../core/repl.router.js");
+const notifications_router_js_1 = require("../core/notifications.router.js");
+const logs_router_js_1 = require("../core/logs.router.js");
+const system_events_router_js_1 = require("../core/system-events.router.js");
+const live_events_router_js_1 = require("../core/live-events.router.js");
+const capabilities_router_js_1 = require("../core/capabilities.router.js");
+const stream_probe_router_js_1 = require("../core/stream-probe.router.js");
+const hwaccel_router_js_1 = require("../core/hwaccel.router.js");
+const cap_mount_helpers_js_1 = require("./cap-mount-helpers.js");
+const client_ip_js_1 = require("./client-ip.js");
+/**
+ * Merge the server-read User-Agent into a signaling call's
+ * `consumerAttribution`, building a NEW input object (immutable — never
+ * mutates the caller's input). When `userAgent` is null (mesh-originated
+ * call, or a client that omits the header) the input passes through
+ * unchanged. Any client-supplied `userAgent` is OVERWRITTEN — the hub
+ * trusts only the request context, never the client.
+ */
+function enrichInputWithUserAgent(input, userAgent) {
+    if (userAgent === null)
+        return input;
+    const base = input.consumerAttribution ?? { kind: 'webrtc-browser' };
+    return {
+        ...input,
+        consumerAttribution: { ...base, userAgent },
+    };
+}
+/**
+ * Relay-only forcing for remote viewers is DISABLED (2026-05-26).
+ *
+ * It was meant to give CGNAT/4G viewers a clean relay↔relay path, but werift's
+ * TURN media-forward is unreliable between two real TURN servers (relay↔relay
+ * connects yet media never arrives → connected-but-black), and forcing relay
+ * ALSO kills the direct LAN/Tailscale host pair — which carries full native
+ * quality with no relay. We now offer ALL candidates (host incl. the hub's
+ * advertised Tailscale address, srflx, relay) and let ICE nominate the best
+ * reachable pair: direct when possible, relay only as a fallback. The
+ * `relayOnly` cap field + broker support remain for when relay media-forward
+ * is fixed.
+ *
+ * The wrapper additionally enriches the `createSession` / `handleOffer`
+ * subscriber attribution with the originating client's User-Agent, read
+ * from the tRPC request context (browser sessions). All OTHER methods
+ * delegate straight through — auth, the remote-proxy factory and every
+ * signaling behaviour are untouched.
+ */
+function wrapWebrtcSessionProviderWithRelay(provider, ctx) {
+    const userAgent = (0, client_ip_js_1.extractUserAgent)(ctx.req);
+    return {
+        ...provider,
+        createSession: (input) => provider.createSession(enrichInputWithUserAgent(input, userAgent)),
+        handleOffer: (input) => provider.handleOffer(enrichInputWithUserAgent(input, userAgent)),
+    };
+}
+/**
+ * Build the AppRouter. Mounts every codegen'd cap router via the auto-
+ * mount entrypoint and overrides the handful that need service-backed
+ * providers or custom collection dispatch. Non-cap (core) routers ride
+ * alongside in the same root object.
+ *
+ * Override-by-spread: spread `mountAllCaps(services)` first, then the
+ * overrides AFTER — the later property wins. The drift guard in
+ * `scripts/codegen.ts` ensures every codegen'd `createCapRouter_X` is
+ * present in the auto-mount inventory (or explicitly in the legacy
+ * skip-list), so the override list below NEVER needs to add a new entry
+ * just to mount a new cap — only to swap in a custom provider.
+ */
+function buildCapabilityRouters(services) {
+    return {
+        // ── Auto-mount: every codegen'd cap router with a canonical
+        //    provider shape. Everything below this line OVERRIDES the
+        //    auto-mount entry for caps with service-backed providers,
+        //    custom collection routing, or a hub-only `null` remote proxy.
+        ...(0, generated_cap_mounts_js_1.mountAllCaps)(services),
+        // ── Non-cap (core) routers — hand-written, single-impl ──────────
+        notifications: (0, notifications_router_js_1.createNotificationsRouter)(services.notificationService),
+        // Raw DB proxy for forked workers to read/write addon store.
+        // Workers use ctx.api.addonSettingsRaw.getGlobal.query({...}).
+        // NOT the three-level settings gateway — that's the codegen'd
+        // `addonSettings` cap router (mounted via auto-mount above).
+        addonSettingsRaw: (0, addon_settings_router_js_1.createAddonSettingsRouter)(services.configService),
+        settingsBackend: (0, settings_backend_router_js_1.createSettingsBackendRouter)(() => services.addonRegistry.getSettingsBackend()),
+        eventBusProxy: (0, event_bus_proxy_router_js_1.createEventBusProxyRouter)(services.eventBus),
+        repl: (0, repl_router_js_1.createReplRouter)(services.replEngine),
+        systemEvents: (0, system_events_router_js_1.createSystemEventsRouter)(services.eventBus),
+        capabilities: (0, capabilities_router_js_1.createCapabilitiesRouter)(services.capabilityRegistry, services.configService),
+        logs: (0, logs_router_js_1.createLogsRouter)(services.loggingService),
+        live: (0, live_events_router_js_1.createLiveEventsRouter)(services.eventBus, services.addonRegistry),
+        // stream-probe — fixed core API (ffprobe wrapper), not a cap.
+        streamProbe: (0, stream_probe_router_js_1.createStreamProbeRouter)(services.streamProbe),
+        // hwaccel — fixed core API, wraps the per-node `$hwaccel` Moleculer
+        // service. UI pipeline / NodeDetail pages query per-node to show
+        // which hardware backend each agent will use.
+        hwaccel: (0, hwaccel_router_js_1.createHwAccelRouter)(services.moleculer?.broker ?? null),
+        auth: (0, auth_router_js_1.createAuthRouter)(services.authService, services.capabilityRegistry),
+        // ── Cap overrides: service-backed providers ─────────────────────
+        // These caps don't have an addon registering a provider in the
+        // CapabilityRegistry — the provider is built on-demand from
+        // backend services. `mountAllCaps` would return `null` for them
+        // (registry lookup miss), so we re-mount with `buildXProvider`.
+        networkQuality: (0, generated_cap_routers_1.createCapRouter_networkQuality)((_ctx) => (0, cap_providers_js_1.buildNetworkQualityProvider)(services.networkQualityService)),
+        system: (0, generated_cap_routers_1.createCapRouter_system)((_ctx) => (0, cap_providers_js_1.buildSystemProvider)(services.featureService, services.capabilityRegistry)),
+        toast: (0, generated_cap_routers_1.createCapRouter_toast)((ctx) => (0, cap_providers_js_1.buildToastProvider)(services.toastService, ctx)),
+        integrations: (0, generated_cap_routers_1.createCapRouter_integrations)((_ctx) => (0, cap_providers_js_1.buildIntegrationsProvider)(services.addonRegistry, services.eventBus, services.loggingService, services.capabilityRegistry)),
+        nodes: (0, generated_cap_routers_1.createCapRouter_nodes)((_ctx) => (0, cap_providers_js_1.buildNodesProvider)(services.agentRegistry, services.moleculer, services.addonRegistry)),
+        addons: (0, generated_cap_routers_1.createCapRouter_addons)((ctx) => (0, cap_providers_js_1.buildAddonsProvider)(services.addonRegistry, services.addonPackageService, services.loggingService, services.moleculer, services.configService, ctx, services.eventBus)),
+        // ── Cap overrides: cross-node remote-proxy cast ─────────────────
+        // These caps' providers have manual interface types that pre-date
+        // `InferProvider<typeof xCap>` — structurally identical, nominally
+        // distinct. Casting at the override site is cheaper than reworking
+        // the provider declarations. Auto-mount can't infer the cast.
+        pipelineExecutor: (0, generated_cap_routers_1.createCapRouter_pipelineExecutor)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'pipeline-executor'), (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        pipelineRunner: (0, generated_cap_routers_1.createCapRouter_pipelineRunner)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'pipeline-runner'), (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        pipelineOrchestrator: (0, generated_cap_routers_1.createCapRouter_pipelineOrchestrator)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'pipeline-orchestrator'), (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        audioAnalyzer: (0, generated_cap_routers_1.createCapRouter_audioAnalyzer)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'audio-analyzer'), (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        audioCodec: (0, generated_cap_routers_1.createCapRouter_audioCodec)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'audio-codec'), (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        decoder: (0, generated_cap_routers_1.createCapRouter_decoder)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'decoder'), (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        platformProbe: (0, generated_cap_routers_1.createCapRouter_platformProbe)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'platform-probe'), (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        // ── Cap overrides: hub-only, no remote fallback ─────────────────
+        // The cap is intentionally single-node; agents are not directly
+        // addressable. Auto-mount would still set up a proxy factory; we
+        // explicitly return `null` to short-circuit any cross-node attempt.
+        localNetwork: (0, generated_cap_routers_1.createCapRouter_localNetwork)((_ctx) => (0, cap_mount_helpers_js_1.requireSingleton)(services.capabilityRegistry, 'local-network'), (_capName, _nodeId) => null),
+        // ── Cap overrides: collection dispatch (contribution / probe) ──
+        // `turn-provider.getTurnServers` is now handled generically by the
+        // auto-mount: it's an array-output method on a `collection` cap, so
+        // `mountAllCaps` fans it across every enabled provider via
+        // `concatCollection` when no `addonId` is supplied. No hand-written
+        // override needed.
+        //
+        // `snapshot-provider.supportsDevice` is an OR across providers;
+        // `getSnapshot` picks the first one that claims the device. The
+        // generic first-provider resolver from the auto-mount can't model
+        // this — we hand-write the probe + fan-out logic.
+        snapshotProvider: (0, generated_cap_routers_1.createCapRouter_snapshotProvider)((_ctx) => {
+            const reg = services.capabilityRegistry;
+            if (!reg)
+                return null;
+            const providers = reg.getCollection('snapshot-provider');
+            if (!providers || providers.length === 0)
+                return null;
+            const supportsDevice = (0, cap_mount_helpers_js_1.anySupports)(providers, 'supportsDevice');
+            const getSnapshot = (0, cap_mount_helpers_js_1.firstSupported)(providers, 'supportsDevice', 'getSnapshot');
+            return { supportsDevice, getSnapshot };
+        }),
+        // ── Cap override: server-detected remote → relay-only ────────────
+        // The broker (a forked addon) can't see the HTTP request, so it
+        // can't tell a LAN viewer from a remote one. We override only the
+        // `getProvider` accessor to return a per-request provider whose
+        // `createSession` carries a server-computed `relayOnly` flag derived
+        // from the client IP in `ctx.req`. Remote (CGNAT/4G) viewers force
+        // TURN-relay-only ICE; LAN viewers keep the direct host/srflx path.
+        // All other methods delegate straight through, and the cross-node
+        // remote-proxy routing is preserved (forked/agent-hosted brokers).
+        webrtcSession: (0, generated_cap_routers_1.createCapRouter_webrtcSession)((ctx) => {
+            const provider = services.capabilityRegistry?.getSingleton('webrtc-session') ?? null;
+            return provider ? wrapWebrtcSessionProviderWithRelay(provider, ctx) : null;
+        }, (capName, nodeId) => services.moleculer.createCapabilityProxy(capName, nodeId)),
+        // NOT MOUNTED — legacy provider shapes (positional args / sync
+        // returns) that don't match the codegen routers' {input}-object +
+        // Promise<T> contract. Tracked by `LEGACY_SHAPE_SKIP` in
+        // `generated-cap-mounts.ts` until the provider refactor (task #195):
+        //   - addon-routes        (IAddonRouteProvider: getRoutes sync)
+        //   - auth-provider       (IAuthProvider: positional credentials)
+        //   - log-destination     (ILogDestination: positional + extra lifecycle)
+        //   - restreamer          (IRestreamer: registerDevice positional)
+        //   - streaming-engine    (IStreamingEngine: registerStream positional)
+        //   - webrtc              (IWebRtcProvider: missing hasAdaptiveBitrate)
+    };
+}
+function buildAppRouter(services) {
+    return (0, trpc_middleware_1.trpcRouter)({
+        ...buildCapabilityRouters(services),
+    });
+}

package/dist/auth/session-cookie.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_COOKIE = void 0;
+exports.buildSessionCookie = buildSessionCookie;
+exports.clearSessionCookie = clearSessionCookie;
+exports.shouldRedirectToLogin = shouldRedirectToLogin;
+exports.loginRedirectUrl = loginRedirectUrl;
+exports.isEmbedRedirectTarget = isEmbedRedirectTarget;
+/** Browser session cookie carrying the hub JWT. Set by POST /api/auth/session
+ *  after a tRPC login; read by the addon-route catch-all for `authenticated`
+ *  routes hit by a plain browser navigation. */
+exports.SESSION_COOKIE = 'camstack_session';
+function buildSessionCookie(token, ttlSec) {
+    return {
+        name: exports.SESSION_COOKIE,
+        value: token,
+        options: { httpOnly: true, sameSite: 'lax', secure: true, path: '/', maxAge: ttlSec },
+    };
+}
+function clearSessionCookie() {
+    return {
+        name: exports.SESSION_COOKIE,
+        value: '',
+        options: { httpOnly: true, sameSite: 'lax', secure: true, path: '/', maxAge: 0 },
+    };
+}
+/** A browser navigation we can bounce to the login page: a top-level GET
+ *  that wants HTML. Anything else (API call, POST, non-HTML) keeps the
+ *  401 behavior so programmatic clients get a clean error. */
+function shouldRedirectToLogin(method, accept) {
+    return method === 'GET' && typeof accept === 'string' && accept.includes('text/html');
+}
+/** Build the `/login?next=…` URL for an unauthenticated browser request. */
+function loginRedirectUrl(originalUrl) {
+    return `/login?next=${encodeURIComponent(originalUrl)}`;
+}
+/** Allowed redirect target for `GET /api/embed-auth`: a same-origin RELATIVE
+ *  path to a stream-broker embed page. Defeats open-redirects — the endpoint
+ *  sets the session cookie from a Bearer token, so the `next` must be safe to
+ *  bounce to. Rejects absolute/protocol-relative URLs, backslashes, and `..`. */
+function isEmbedRedirectTarget(next) {
+    if (!next.startsWith('/addon/stream-broker/embed/'))
+        return false;
+    if (next.includes('\\') || next.includes('://') || next.includes('..'))
+        return false;
+    return true;
+}