@camstack/server 0.1.3

package/src/api/trpc/scope-access.ts

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+import { METHOD_ACCESS_MAP } from '@camstack/types'
+import type { MethodAccess, TokenScope } from '@camstack/types'
+
+export type ScopeAccessResult =
+  | { ok: true; access: MethodAccess }
+  | { ok: false; reason: string }
+
+/**
+ * Resolves a deviceId to its ancestor chain (parent, grandparent, …).
+ * Empty / omitted for top-level devices. Order is irrelevant — the
+ * matcher only checks set membership.
+ */
+export type DeviceAncestorLookup = (deviceId: number) => readonly number[]
+
+/**
+ * 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: unknown): number | null {
+  if (input === null || typeof input !== 'object') return null
+  const candidate = (input as Record<string, unknown>)['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: number,
+  getAncestors: DeviceAncestorLookup | undefined,
+): readonly string[] {
+  if (!getAncestors) return [String(deviceId)]
+  const out = new Set<string>([String(deviceId)])
+  for (const ancestor of getAncestors(deviceId)) out.add(String(ancestor))
+  return [...out]
+}
+
+export function checkScopeAccess(
+  scopes: readonly TokenScope[],
+  path: string,
+  input?: unknown,
+  getDeviceAncestors?: DeviceAncestorLookup,
+): ScopeAccessResult {
+  const meta = 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/src/api/trpc/trpc.context.ts

@@ -0,0 +1,255 @@
+import type { FastifyRequest } from 'fastify'
+import type { IncomingMessage } from 'node:http'
+import type { CreateWSSContextFnOptions } from '@trpc/server/adapters/ws'
+import type { AuthenticatedUser, TokenScope } from '@camstack/types'
+import type { AuthService } from '../../core/auth/auth.service'
+import type { AddonRegistryService } from '../../core/addon/addon-registry.service'
+
+/** AuthenticatedUser extended with agent identity + scoped-token fields. */
+export interface AuthenticatedAgent extends AuthenticatedUser {
+  agentId?: string
+  /** True iff this user was resolved from a `cst_*` scoped token. */
+  isScoped?: boolean
+  /**
+   * The scope set that gated this request. Procedures with admin gates
+   * reject `isScoped` callers outright; the `protectedProcedure`
+   * middleware matches scopes against the request path to decide
+   * whether the call is permitted.
+   */
+  scopes?: readonly TokenScope[]
+}
+
+interface ScopedTokenLike {
+  readonly id: string
+  readonly userId: string
+  readonly tokenPrefix: string
+  readonly scopes: readonly TokenScope[]
+}
+interface UserManagementLike {
+  validateScopedToken(input: { token: string }): Promise<ScopedTokenLike | null>
+}
+
+/**
+ * Request union accepted by the tRPC context.
+ *
+ * HTTP tRPC requests arrive as `FastifyRequest`, but the WS adapter provides
+ * a raw `IncomingMessage` with no `.query`. Callers must narrow before reading
+ * Fastify-specific properties.
+ */
+export type TrpcRequest = FastifyRequest | IncomingMessage
+
+export interface TrpcContext {
+  user: AuthenticatedAgent | null
+  /**
+   * The originating HTTP/WS request. Absent for mesh-originated calls
+   * (the core-cap bridge invokes procedures via `createCaller`, with no
+   * request behind them). No procedure reads `req` today; it is kept
+   * for diagnostics and future request-scoped logic.
+   */
+  req?: TrpcRequest
+  /**
+   * Walks the parent-chain of a deviceId — used by the scope-access
+   * matcher so a `device:5` grant implicitly covers every accessory
+   * (siren / floodlight / PIR / …) whose `parentDeviceId` is 5.
+   * Populated by `createTrpcContext` from the live device registry;
+   * omitted on the WS / test paths where the registry isn't wired in.
+   */
+  getDeviceAncestors?: (deviceId: number) => readonly number[]
+}
+
+/** Read `req.query` if present (Fastify-only) without losing type safety. */
+function readQuery(req: TrpcRequest): Record<string, unknown> | null {
+  if (!('query' in req)) return null
+  const q: unknown = 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: TrpcRequest): string | null {
+  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: string | null | undefined,
+  authService: AuthService,
+  addonRegistry: AddonRegistryService,
+): Promise<AuthenticatedAgent | null> {
+  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') as UserManagementLike | undefined
+      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: AddonRegistryService): (deviceId: number) => readonly number[] {
+  return (deviceId: number) => {
+    const out: number[] = []
+    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.
+ */
+export function createMeshTrpcContext(): TrpcContext {
+  const user: AuthenticatedAgent = {
+    id: 'mesh',
+    username: 'mesh',
+    isAdmin: true,
+    permissions: { isAdmin: true, allowedProviders: '*', allowedDevices: {} },
+    isApiKey: true,
+  }
+  return { user }
+}
+
+/** Context factory for HTTP tRPC requests (Fastify adapter). */
+export async function createTrpcContext(
+  req: TrpcRequest,
+  authService: AuthService,
+  addonRegistry: AddonRegistryService,
+): Promise<TrpcContext> {
+  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.
+ */
+export async function createWsTrpcContext(
+  opts: CreateWSSContextFnOptions,
+  authService: AuthService,
+  addonRegistry: AddonRegistryService,
+): Promise<TrpcContext> {
+  // 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/src/api/trpc/trpc.middleware.ts

@@ -0,0 +1,140 @@
+import { initTRPC, TRPCError } from '@trpc/server'
+import superjson from 'superjson'
+import { METHOD_ACCESS_MAP } from '@camstack/types'
+import type { TrpcContext } from './trpc.context'
+import { checkScopeAccess } from './scope-access.js'
+
+const t = initTRPC.context<TrpcContext>().create({ transformer: superjson })
+
+// ---------------------------------------------------------------------------
+// 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.
+ */
+export async function* iterableSubscription<T>(
+  subscribe: (push: (value: T) => void) => (() => void),
+): AsyncGenerator<T> {
+  const queue: T[] = []
+  let resolve: (() => void) | null = null
+
+  const unsub = subscribe((value) => {
+    queue.push(value)
+    resolve?.()
+  })
+
+  try {
+    while (true) {
+      while (queue.length > 0) {
+        yield queue.shift()!
+      }
+      await new Promise<void>((r) => { resolve = r })
+    }
+  } finally {
+    unsub()
+  }
+}
+
+/**
+ * Create an interval-based async generator that yields a value on each tick.
+ * Useful for polling subscriptions.
+ */
+export async function* iterableInterval<T>(
+  intervalMs: number,
+  getValue: () => T,
+): AsyncGenerator<T> {
+  try {
+    while (true) {
+      yield getValue()
+      await new Promise<void>((r) => setTimeout(r, intervalMs))
+    }
+  } finally {
+    // cleanup handled by generator return
+  }
+}
+
+export const trpcRouter = t.router
+export const 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.
+ */
+export const 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.
+ */
+export const protectedProcedure = t.procedure.use(async ({ ctx, next, path, getRawInput }) => {
+  if (!ctx.user) {
+    throw new 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 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 = checkScopeAccess(ctx.user.scopes ?? [], path, rawInput, ctx.getDeviceAncestors)
+  if (!result.ok) {
+    throw new 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.
+ */
+export const adminProcedure = protectedProcedure.use(({ ctx, next }) => {
+  if (!ctx.user.isAdmin) {
+    throw new 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.
+ */
+export const agentProcedure = adminProcedure.use(({ ctx, next }) => {
+  return next({ ctx: { ...ctx, agentId: ctx.user.agentId ?? ctx.user.id } })
+})