@camstack/server 1.0.0 → 1.0.1

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

@@ -1,110 +0,0 @@
-/**
- * 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

@@ -1,258 +0,0 @@
-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

@@ -1,146 +0,0 @@
-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'
-import { formatTrpcError } from './cap-route-error-formatter.js'
-
-const t = initTRPC.context<TrpcContext>().create({
-  transformer: superjson,
-  errorFormatter: 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.
- */
-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 } })
-})