@camstack/server 0.2.2 → 1.0.1

package/dist/api/trpc/cap-mount-helpers.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireSingleton = requireSingleton;
+exports.requireDeviceScoped = requireDeviceScoped;
+exports.concatCollection = concatCollection;
+exports.firstSupported = firstSupported;
+exports.anySupports = anySupports;
+/**
+ * Small helpers for wiring capability routers to the `CapabilityRegistry`
+ * in `trpc.router.ts`. These functions don't generate code — they just
+ * remove boilerplate from the mount lambdas we pass to `createCapRouter_X`.
+ *
+ * When to use what:
+ *   - `requireSingleton(registry, name)` — singleton caps with no custom
+ *     composition. Returns the active provider or null (the codegen'd
+ *     router itself throws PRECONDITION_FAILED when null).
+ *   - `concatCollection(providers, method)` — collection caps whose
+ *     methods return arrays and where the desired behaviour is "union of
+ *     every provider's contribution" (e.g. `turn-provider.getTurnServers`).
+ *   - `firstSupported(providers, probe, action)` — collection caps where
+ *     exactly one provider should handle each request, selected by a
+ *     probe method (e.g. `snapshot-provider.supportsDevice`).
+ *
+ * Collections that route by an input key (e.g. `webrtc` picking the
+ * provider responsible for a given `streamId`) are NOT covered here —
+ * they have app-specific routing logic that belongs in the mount.
+ */
+const server_1 = require("@trpc/server");
+/**
+ * Fetch the currently active singleton provider for a capability.
+ * Returns null if no provider is registered; the downstream codegen'd
+ * router surfaces this as `PRECONDITION_FAILED` to the caller.
+ */
+function requireSingleton(registry, capName) {
+    return registry?.getSingleton(capName) ?? null;
+}
+/**
+ * Build a per-device dispatcher that satisfies the singleton-provider
+ * shape but resolves the actual implementation lazily via
+ * `registry.getNativeProvider(capName, deviceId)` on every method call.
+ *
+ * Use for device-scoped caps that have NO system-level wrapper (PTZ,
+ * reboot, doorbell, brightness, motion-trigger, switch, …) — drivers
+ * register per-device native providers via
+ * `DeviceContext.registerNativeCap`, and this helper bridges the cap-
+ * router's "fetch a singleton then call methods on it" flow into a
+ * "resolve native by deviceId per call" flow.
+ *
+ * Method input MUST carry `deviceId: number`. Methods without that
+ * field (auto-injected `getStatus({deviceId})` for caps with a status
+ * block, every business method that follows the cap-definition
+ * convention) work transparently.
+ *
+ * Throws PRECONDITION_FAILED with a device-specific message when no
+ * native provider exists for the requested deviceId — much friendlier
+ * than the singleton fallthrough's "no provider" generic error.
+ */
+function requireDeviceScoped(registry, capName) {
+    if (!registry)
+        return null;
+    // The Proxy is the singleton stand-in. Each property access returns
+    // a function that, on call, looks up the per-device native and
+    // forwards the call. No caching — the lookup is cheap (Map.get) and
+    // re-doing it per call lets devices come/go without stale refs.
+    const dispatcher = new Proxy({}, {
+        get(_target, prop) {
+            if (typeof prop !== 'string')
+                return undefined;
+            return async (input) => {
+                const deviceId = input?.deviceId;
+                if (typeof deviceId !== 'number') {
+                    throw new server_1.TRPCError({
+                        code: 'BAD_REQUEST',
+                        message: `${String(capName)}.${prop}: input must carry numeric "deviceId"`,
+                    });
+                }
+                const native = registry.getNativeProvider(capName, deviceId);
+                if (!native) {
+                    throw new server_1.TRPCError({
+                        code: 'PRECONDITION_FAILED',
+                        message: `Capability "${String(capName)}" not registered for device ${deviceId}`,
+                    });
+                }
+                const fn = native[prop];
+                if (typeof fn !== 'function') {
+                    throw new server_1.TRPCError({
+                        code: 'NOT_IMPLEMENTED',
+                        message: `Capability "${String(capName)}" provider for device ${deviceId} does not implement "${prop}"`,
+                    });
+                }
+                const result = await fn.call(native, input);
+                // Device-property-wiring overlay (read-time): only `getStatus`, and only
+                // when the device has links for this cap (resolveLinkedStatus returns
+                // null otherwise → base result untouched). One in-process singleton hop.
+                if (prop === 'getStatus') {
+                    const deviceManager = registry.getSingleton('device-manager');
+                    const overlaid = await deviceManager?.resolveLinkedStatus?.({
+                        deviceId,
+                        cap: String(capName),
+                        baseStatus: result,
+                    });
+                    if (overlaid != null)
+                        return overlaid;
+                }
+                return result;
+            };
+        },
+    });
+    return dispatcher;
+}
+/**
+ * Build a method that fan-outs a call to every provider in a collection
+ * and concatenates their array results. Useful for contribution-style
+ * caps where each provider adds to a shared pool.
+ */
+function concatCollection(providers, method) {
+    const wrapper = async (...args) => {
+        const results = await Promise.all(providers.map(async (p) => {
+            const member = Reflect.get(p, method);
+            if (typeof member !== 'function')
+                return [];
+            // `Reflect.apply` returns `any`; funnel through unknown.
+            const out = await Reflect.apply(member, p, args);
+            if (!Array.isArray(out))
+                return [];
+            const arr = out;
+            return arr;
+        }));
+        return results.flat();
+    };
+    // Type-level bridge: the runtime wrapper signature (unknown → Promise<unknown[]>)
+    // matches the declared generic conditional return; TypeScript's
+    // conditional types can't be narrowed inside a function body, so this
+    // boundary assertion is required.
+    return wrapper;
+}
+/**
+ * Iterate a collection asking each provider "do you handle this?" via a
+ * probe method, then call an action on the first one that answers yes.
+ * Each provider is tried in registration order; errors are swallowed and
+ * the next provider is attempted. Returns null if no provider matches or
+ * if every matching provider's action throws/returns null.
+ */
+function firstSupported(providers, probe, action) {
+    const wrapper = async (...args) => {
+        const [first] = args;
+        for (const p of providers) {
+            try {
+                const probeMember = Reflect.get(p, probe);
+                if (typeof probeMember !== 'function')
+                    continue;
+                const supported = await Reflect.apply(probeMember, p, [first]);
+                if (supported !== true)
+                    continue;
+                const actionMember = Reflect.get(p, action);
+                if (typeof actionMember !== 'function')
+                    continue;
+                const result = await Reflect.apply(actionMember, p, args);
+                if (result !== null && result !== undefined)
+                    return result;
+            }
+            catch {
+                // try next provider
+            }
+        }
+        return null;
+    };
+    // Type-level bridge — see concatCollection for the same pattern.
+    return wrapper;
+}
+/**
+ * Convenience for collection caps that want a "logical OR of probes"
+ * (e.g. `supportsDevice` across every snapshot-provider).
+ */
+function anySupports(providers, probe) {
+    const wrapper = async (...args) => {
+        for (const p of providers) {
+            const member = Reflect.get(p, probe);
+            if (typeof member !== 'function')
+                continue;
+            try {
+                const result = await Reflect.apply(member, p, args);
+                if (result === true)
+                    return true;
+            }
+            catch {
+                /* next */
+            }
+        }
+        return false;
+    };
+    // Type-level bridge — see concatCollection for the same pattern.
+    return wrapper;
+}

package/dist/api/trpc/cap-route-error-formatter.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatTrpcError = formatTrpcError;
+/**
+ * tRPC error formatter that serializes CapRouteError diagnostic fields
+ * across the server→client boundary.
+ *
+ * tRPC only carries `error.message` by default. This formatter augments
+ * the default shape's `data` block with typed CapRouteError fields so the
+ * admin-UI can read `capRouteReason` instead of substring-matching message text.
+ *
+ * Fields added (all optional — absent when the error is not a CapRouteError):
+ *   - `capRouteReason` — 'no-provider' | 'node-offline' | 'cap-unknown' | 'transport-failed'
+ *   - `capRouteRejected` — array of `{ kind: string; why: string }` route-rejection descriptors
+ *   - `capRouteNodeId` — the target node id, when known
+ *
+ * The formatter is EXPORTED for unit testing (no side-effects, pure function).
+ */
+const kernel_1 = require("@camstack/kernel");
+// ---------------------------------------------------------------------------
+// Type guards
+// ---------------------------------------------------------------------------
+/** Known CapRouteError reason values — used as a runtime safety rail. */
+const KNOWN_REASONS = new Set([
+    'no-provider',
+    'node-offline',
+    'cap-unknown',
+    'transport-failed',
+]);
+/** Narrows a plain string to the `CapRouteError['reason']` union. */
+function isCapRouteReason(r) {
+    return KNOWN_REASONS.has(r);
+}
+/** Narrows an `unknown` value to `RejectedRoute` by checking structural shape. */
+function isRejectedRoute(r) {
+    if (typeof r !== 'object' || r === null)
+        return false;
+    const kind = Reflect.get(r, 'kind');
+    const why = Reflect.get(r, 'why');
+    return typeof kind === 'string' && typeof why === 'string';
+}
+// ---------------------------------------------------------------------------
+// CapRouteError extraction helpers
+// ---------------------------------------------------------------------------
+/**
+ * Walks the `.cause` chain of an error to find a CapRouteError.
+ * Returns the first one found, or null.
+ *
+ * Detection is dual-mode:
+ *   1. `instanceof CapRouteError` — works when the same module is loaded.
+ *   2. Duck-type: `name === 'CapRouteError'` + `typeof reason === 'string'`
+ *      — robust against module-boundary issues (self-contained addons).
+ */
+function extractCapRouteError(err) {
+    let current = err;
+    for (let depth = 0; depth < 8; depth++) {
+        if (current === null || current === undefined)
+            return null;
+        if (current instanceof kernel_1.CapRouteError) {
+            return current;
+        }
+        // Duck-type fallback: err.name + err.reason field present
+        if (typeof current === 'object' && Reflect.get(current, 'name') === 'CapRouteError') {
+            const rawReason = Reflect.get(current, 'reason');
+            if (typeof rawReason === 'string') {
+                // Runtime safety: reject unrecognised reason strings so the formatter
+                // only promotes values it knows are valid CapRouteError reasons.
+                if (!isCapRouteReason(rawReason)) {
+                    // Unrecognised reason — treat as a non-CapRouteError and keep walking
+                    const cause = Reflect.get(current, 'cause');
+                    if (cause === current)
+                        return null;
+                    current = cause;
+                    continue;
+                }
+                const reason = rawReason;
+                const rawRejected = Reflect.get(current, 'rejected');
+                const rejected = Array.isArray(rawRejected)
+                    ? rawRejected.filter(isRejectedRoute)
+                    : [];
+                const nodeId = Reflect.get(current, 'nodeId');
+                const message = Reflect.get(current, 'message');
+                const rawCapName = Reflect.get(current, 'capName');
+                const capName = typeof rawCapName === 'string' ? rawCapName : '(unknown)';
+                // Build a minimal object with the same shape — enough for the formatter.
+                const synthetic = Object.assign(new kernel_1.CapRouteError(capName, undefined, {
+                    reason,
+                    rejected,
+                    ...(typeof nodeId === 'string' ? { nodeId } : {}),
+                }), {
+                    // Override message from the original if available
+                    message: typeof message === 'string' ? message : '(duck-typed CapRouteError)',
+                });
+                return synthetic;
+            }
+        }
+        // Walk the cause chain
+        if (typeof current !== 'object')
+            return null;
+        const cause = Reflect.get(current, 'cause');
+        if (cause === current)
+            return null; // Guard against circular refs
+        current = cause;
+    }
+    return null;
+}
+/**
+ * Augments the default tRPC error shape with CapRouteError diagnostic fields
+ * when the thrown error (or any error in its `.cause` chain) is a CapRouteError.
+ * Returns the shape unchanged for all other errors.
+ */
+function formatTrpcError(opts) {
+    const { error, shape } = opts;
+    // extractCapRouteError already walks the full .cause chain, so a single call
+    // starting from `error` covers both `error instanceof CapRouteError` and
+    // `error.cause` (and deeper nesting). No second call needed.
+    const capRouteError = extractCapRouteError(error);
+    if (capRouteError === null) {
+        return { ...shape, data: { ...shape.data } };
+    }
+    const extraData = {
+        capRouteReason: capRouteError.reason,
+        capRouteRejected: capRouteError.rejected,
+        ...(capRouteError.nodeId !== undefined ? { capRouteNodeId: capRouteError.nodeId } : {}),
+    };
+    return {
+        ...shape,
+        data: {
+            ...shape.data,
+            ...extraData,
+        },
+    };
+}

package/dist/api/trpc/client-ip.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractClientIp = extractClientIp;
+exports.extractUserAgent = extractUserAgent;
+exports.isRemoteClientIp = isRemoteClientIp;
+/**
+ * Best-effort extraction of the originating client IP from a tRPC
+ * request. Order of preference:
+ *   1. `X-Forwarded-For` first hop (when behind a reverse proxy — the
+ *      hub is typically fronted by Caddy/nginx/Cloudflare for remote
+ *      access, so the socket peer is the proxy, not the viewer).
+ *   2. Fastify's `req.ip` (already proxy-aware when `trustProxy` is on).
+ *   3. The raw socket remote address.
+ *
+ * Returns `null` when no address can be determined (e.g. mesh-originated
+ * calls that carry no HTTP request) — the caller treats `null` as "not
+ * remote" so the LAN/direct path stays the safe default.
+ */
+function extractClientIp(req) {
+    if (!req)
+        return null;
+    // 1. X-Forwarded-For — comma-separated list, client is the FIRST entry.
+    const xff = req.headers['x-forwarded-for'];
+    const xffValue = Array.isArray(xff) ? xff[0] : xff;
+    if (typeof xffValue === 'string' && xffValue.length > 0) {
+        const first = xffValue.split(',')[0]?.trim();
+        if (first)
+            return normalizeIp(first);
+    }
+    // 2. Fastify's parsed `req.ip` (honours `trustProxy` config).
+    if ('ip' in req && typeof req.ip === 'string' && req.ip.length > 0) {
+        return normalizeIp(req.ip);
+    }
+    // 3. Raw socket peer (WS / IncomingMessage path).
+    const remote = req.socket?.remoteAddress;
+    if (typeof remote === 'string' && remote.length > 0) {
+        return normalizeIp(remote);
+    }
+    return null;
+}
+/**
+ * Best-effort read of the originating client's `User-Agent` header. Both
+ * request shapes in the union (`FastifyRequest` and the raw WS-transport
+ * `IncomingMessage`) expose `.headers['user-agent']`. Returns `null` when
+ * absent (mesh-originated calls carry no HTTP request, and some clients
+ * omit the header). Used by the `webrtc-session` mount to tag a browser
+ * subscriber's broker attribution with the viewer's UA — the SERVER reads
+ * it from the request context; any client-supplied value is ignored.
+ */
+function extractUserAgent(req) {
+    if (!req)
+        return null;
+    const ua = req.headers['user-agent'];
+    const value = Array.isArray(ua) ? ua[0] : ua;
+    if (typeof value === 'string' && value.length > 0)
+        return value;
+    return null;
+}
+/**
+ * Strip an IPv4-mapped IPv6 prefix (`::ffff:192.168.1.5` → `192.168.1.5`)
+ * and any zone id (`fe80::1%en0` → `fe80::1`) so the range checks below
+ * see a clean address.
+ */
+function normalizeIp(ip) {
+    let out = ip.trim();
+    if (out.startsWith('::ffff:'))
+        out = out.slice('::ffff:'.length);
+    const pct = out.indexOf('%');
+    if (pct !== -1)
+        out = out.slice(0, pct);
+    return out;
+}
+/**
+ * True when the address is NOT in a private / loopback / link-local /
+ * Tailscale range — i.e. an internet (remote) viewer. Covers IPv4
+ * (10/8, 172.16/12, 192.168/16, 127/8, 100.64/10 Tailscale CGNAT) and
+ * IPv6 (::1, fc00::/7 unique-local, fe80::/10 link-local — fd7a::/16
+ * Tailscale ULA is a subset of fc00::/7 and is therefore already
+ * covered).
+ *
+ * Tailscale clients (the 100.64.0.0/10 CGNAT overlay or the fd7a::/16
+ * ULA overlay) are deliberately classified LOCAL: over the Tailscale
+ * mesh BOTH peers sit on the 100.x / fd7a:: overlay and are mutually
+ * reachable, so the broker offers ALL candidates (host/srflx/relay)
+ * — including the hub's Tailscale host candidate — and a direct
+ * host↔host pair wins ICE with native (non-re-encoded) media. Forcing
+ * relay-only for Tailscale would push them onto the broken relay path.
+ *
+ * Unparseable or null addresses return `false` (treated as LAN — the
+ * safe default that preserves the existing direct path).
+ */
+function isRemoteClientIp(ip) {
+    if (!ip)
+        return false;
+    if (ip.includes(':'))
+        return !isPrivateIpv6(ip);
+    if (isIpv4(ip))
+        return !isPrivateIpv4(ip);
+    // Not a recognisable IP literal — be conservative, treat as LAN.
+    return false;
+}
+function isIpv4(ip) {
+    const parts = ip.split('.');
+    if (parts.length !== 4)
+        return false;
+    return parts.every((p) => {
+        if (!/^\d{1,3}$/.test(p))
+            return false;
+        const n = Number.parseInt(p, 10);
+        return n >= 0 && n <= 255;
+    });
+}
+function isPrivateIpv4(ip) {
+    const parts = ip.split('.').map((p) => Number.parseInt(p, 10));
+    const [a, b] = parts;
+    if (a === undefined || b === undefined)
+        return false;
+    if (a === 10)
+        return true; // 10.0.0.0/8
+    if (a === 127)
+        return true; // 127.0.0.0/8 loopback
+    if (a === 172 && b >= 16 && b <= 31)
+        return true; // 172.16.0.0/12
+    if (a === 192 && b === 168)
+        return true; // 192.168.0.0/16
+    if (a === 169 && b === 254)
+        return true; // 169.254.0.0/16 link-local
+    // 100.64.0.0/10 — Tailscale CGNAT overlay (100.64.0.0 – 100.127.255.255).
+    // Both Tailscale peers are mutually reachable on this overlay, so treat
+    // it as local (direct host↔host pair, no relay).
+    if (a === 100 && b >= 64 && b <= 127)
+        return true;
+    return false;
+}
+function isPrivateIpv6(ip) {
+    const lower = ip.toLowerCase();
+    if (lower === '::1')
+        return true; // loopback
+    if (lower === '::')
+        return true; // unspecified
+    if (lower.startsWith('fe80'))
+        return true; // fe80::/10 link-local
+    // fc00::/7 unique-local — covers fc.. and fd..
+    if (lower.startsWith('fc') || lower.startsWith('fd'))
+        return true;
+    return false;
+}

package/dist/api/trpc/core-cap-bridge.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCoreCapService = buildCoreCapService;
+const kernel_1 = require("@camstack/kernel");
+const trpc_middleware_js_1 = require("./trpc.middleware.js");
+const trpc_context_js_1 = require("./trpc.context.js");
+/**
+ * appRouter namespaces that back the CORE API surface and must be
+ * reachable cross-process. This is the core-router list from
+ * `trpc.router.ts` (`buildCapabilityRouters`) minus the deliberate
+ * exclusions below.
+ *
+ * Excluded on purpose:
+ *  - `auth` — issuing service / scoped tokens over the trusted mesh
+ *    would let any forked addon mint admin credentials. Addons must
+ *    not perform authentication operations; this stays hub-local.
+ *  - `live`, `systemEvents` — listed in `NEVER_BRIDGED_CAPS`
+ *    (`trpc-links.ts`). They are hub-only push streams, not
+ *    request/reply, and the worker side fast-fails on them by design.
+ */
+const CORE_NAMESPACES = new Set([
+    // Service-backed cap routers (no addon provider).
+    'system',
+    'toast',
+    'integrations',
+    'nodes',
+    'addons',
+    // Hand-written single-impl core routers.
+    'capabilities',
+    'notifications',
+    'logs',
+    'hwaccel',
+    'streamProbe',
+    'settingsBackend',
+    'eventBusProxy',
+    'repl',
+    'addonSettingsRaw',
+]);
+/**
+ * camelCase → kebab-case. Mirrors `toKebab` in `trpc-links.ts` so the
+ * action name matches what `brokerTransportLink` derives from `op.path`.
+ */
+function toKebab(name) {
+    return name.replace(/[A-Z]/g, (m, i) => (i > 0 ? '-' : '') + m.toLowerCase());
+}
+function isProcedureNode(value) {
+    // A built tRPC procedure is a callable object — `_def.procedures`
+    // stores the procedure function directly, not a wrapper object.
+    if (value === null || (typeof value !== 'object' && typeof value !== 'function'))
+        return false;
+    const def = value._def;
+    return (def !== null && typeof def === 'object' && def.procedure === true);
+}
+/**
+ * Recursively flatten a tRPC router record to dotted procedure paths.
+ * Robust to both layouts tRPC v11 may use for `_def.procedures`: a
+ * nested record of sub-routers, or a flat record already keyed by
+ * dotted path (a flat key simply yields its key verbatim).
+ */
+function collectProcedures(record, prefix, out) {
+    for (const [key, value] of Object.entries(record)) {
+        const path = prefix.length > 0 ? `${prefix}.${key}` : key;
+        if (isProcedureNode(value)) {
+            const type = value._def.type;
+            out.push({ path, type: typeof type === 'string' ? type : 'query' });
+        }
+        else if (value !== null && typeof value === 'object') {
+            collectProcedures(value, path, out);
+        }
+    }
+}
+/**
+ * Navigate the decorated caller record (a recursive proxy) to the
+ * procedure function at `path`. Every node on the proxy is callable,
+ * so navigation uses `Reflect.get` across both objects and functions.
+ */
+function resolveInvoker(caller, path) {
+    let node = caller;
+    for (const segment of path.split('.')) {
+        if (node === null || (typeof node !== 'object' && typeof node !== 'function'))
+            return null;
+        // Documented boundary: `node` is an object or function past the
+        // guard above; `Reflect.get` is typed for `object` targets.
+        node = Reflect.get(node, segment);
+    }
+    return typeof node === 'function' ? node : null;
+}
+/**
+ * Build the `$core-caps` Moleculer service schema from the hub
+ * appRouter. Query + mutation procedures in {@link CORE_NAMESPACES} are
+ * exposed; subscriptions are skipped (the broker transport is
+ * request/reply only).
+ */
+function buildCoreCapService(appRouter) {
+    const meshCaller = (0, trpc_middleware_js_1.createCallerFactory)(appRouter)((0, trpc_context_js_1.createMeshTrpcContext)());
+    const discovered = [];
+    collectProcedures(appRouter._def.procedures, '', discovered);
+    const actions = [];
+    for (const { path, type } of discovered) {
+        const dot = path.indexOf('.');
+        if (dot < 0)
+            continue;
+        const namespace = path.slice(0, dot);
+        if (!CORE_NAMESPACES.has(namespace))
+            continue;
+        if (type === 'subscription')
+            continue;
+        const invoke = resolveInvoker(meshCaller, path);
+        if (invoke === null)
+            continue;
+        const method = path.slice(dot + 1);
+        actions.push({ actionName: `${toKebab(namespace)}.${method}`, invoke });
+    }
+    return (0, kernel_1.createCoreCapService)({ actions });
+}