@camstack/server 0.1.3

package/src/api/addon-upload.ts

@@ -0,0 +1,472 @@
+import type { FastifyInstance, FastifyReply } from 'fastify'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import { execFileSync } from 'node:child_process'
+import type { IScopedLogger, TokenScope } from '@camstack/types'
+import { checkScopeAccess } from './trpc/scope-access.js'
+import type { AddonBridgeService } from '../core/addon-bridge/addon-bridge.service'
+import type { AddonRegistryService } from '../core/addon/addon-registry.service'
+import type { AuthService } from '../core/auth/auth.service'
+import type { MoleculerService } from '../core/moleculer/moleculer.service'
+
+interface ScopedTokenLike {
+  readonly scopes: readonly TokenScope[]
+}
+interface UserManagementLike {
+  validateScopedToken(input: { token: string }): Promise<ScopedTokenLike | null>
+}
+
+/**
+ * Validate a `cst_*` scoped token via the `user-management` cap singleton.
+ *
+ * The local `AuthService.validateScopedToken` indirection is unused (the
+ * `setScopedTokenManager` wire-up was never invoked), so we go straight
+ * to the cap registry — same path the generic addon-route handler in
+ * `main.ts` uses (the one that actually works end-to-end).
+ *
+ * Returns null when the singleton isn't mounted yet (boot race) or the
+ * token doesn't validate. Caller treats both as auth failure.
+ */
+async function validateScopedTokenViaCap(
+  addonRegistry: AddonRegistryService,
+  token: string,
+): Promise<ScopedTokenLike | null> {
+  const capRegistry = addonRegistry.getCapabilityRegistry()
+  const userMgmt = capRegistry.getSingleton('user-management') as UserManagementLike | undefined
+  if (!userMgmt) return null
+  return userMgmt.validateScopedToken({ token })
+}
+
+/**
+ * REST endpoint `/api/addons/upload` shares the scope-gate of the
+ * `addons.installPackage` cap method (semantically equivalent — both
+ * install a tarball under the system-scope `addons` cap with `create`
+ * access). Reuse the shared scope matcher so the gate stays in sync
+ * with the tRPC middleware — no parallel REST-only ACL.
+ *
+ * Why not `addons.upload`? There is no `upload` method on the cap
+ * definition (this endpoint is Fastify-only), so `METHOD_ACCESS_MAP`
+ * has no row for it and `checkScopeAccess` falls through to deny.
+ */
+const UPLOAD_TRPC_PATH = 'addons.installPackage'
+function isUploadAllowed(scoped: ScopedTokenLike): boolean {
+  return checkScopeAccess(scoped.scopes, UPLOAD_TRPC_PATH).ok
+}
+
+const TARBALL_EXTENSIONS = ['.tgz', '.tar.gz']
+const MAX_UPLOAD_BYTES = 50 * 1024 * 1024
+const AGENT_DEPLOY_TIMEOUT_MS = 60_000
+
+interface TarballManifest {
+  readonly name: string
+  readonly version: string
+}
+
+interface AgentDeployResponse {
+  readonly success: boolean
+  readonly addonId: string
+  readonly path?: string
+}
+
+function isTarball(filename: string): boolean {
+  return TARBALL_EXTENSIONS.some(ext => filename.endsWith(ext))
+}
+
+/**
+ * Validate an uploaded tarball by extracting its `package.json` and
+ * checking it declares `name` + `version`. Runs BEFORE the hub/agent
+ * branch so broken archives are rejected at the gateway instead of
+ * failing mid-extraction on the agent (which has no clean rollback).
+ *
+ * The routine writes the buffer to a scratch path and invokes `tar` with
+ * `-xzO` to stream-extract just `package/package.json` to stdout. No full
+ * unpack is needed — npm-pack layout always puts the manifest at that
+ * fixed inner path. Returns null (not throw) on malformed archives so
+ * the caller can surface a precise 400 response.
+ */
+function validateTarball(buffer: Buffer, filename: string): TarballManifest | null {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'camstack-tarball-check-'))
+  const tgzPath = path.join(tmpDir, filename)
+  try {
+    fs.writeFileSync(tgzPath, buffer)
+    const output = execFileSync('tar', ['-xzO', '-f', tgzPath, 'package/package.json'], {
+      timeout: 5_000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    })
+    const parsed: unknown = JSON.parse(output.toString('utf8'))
+    if (!parsed || typeof parsed !== 'object') return null
+    const pkg = parsed as Record<string, unknown>
+    if (typeof pkg['name'] !== 'string' || typeof pkg['version'] !== 'string') return null
+    return { name: pkg['name'], version: pkg['version'] }
+  } catch {
+    return null
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  }
+}
+
+export async function registerAddonUploadRoute(
+  fastify: FastifyInstance,
+  addonBridge: AddonBridgeService,
+  authService: AuthService,
+  moleculer: MoleculerService,
+  addonRegistry: AddonRegistryService,
+  logger: IScopedLogger,
+): Promise<void> {
+  await fastify.register(import('@fastify/multipart'), {
+    limits: { fileSize: MAX_UPLOAD_BYTES },
+  })
+
+  fastify.post('/api/addons/upload', async (request, reply) => {
+    const authHeader = request.headers.authorization
+    if (!authHeader) {
+      return reply.status(401).send({ error: 'Unauthorized' })
+    }
+
+    // Auth chain: JWT (isAdmin) OR scoped token whose scopes grant
+    // `create` access on the `addons` capability. The scoped path is the
+    // CLI's `camstack login` flow — fetches a long-lived upload-scoped
+    // token so headless deploys don't need an admin password on disk.
+    const token = authHeader.replace('Bearer ', '')
+    let authOk = false
+    let authReason: string | undefined
+    // Try JWT first — fastest path + carries isAdmin flag directly.
+    try {
+      const payload = authService.verifyToken(token)
+      if (payload.isAdmin) {
+        authOk = true
+      } else {
+        authReason = 'JWT is not admin'
+      }
+    } catch {
+      // Not a JWT (or invalid signature) — fall through to scoped-token path.
+    }
+    if (!authOk) {
+      // `cst_*` scoped tokens — only the cap-registry singleton actually
+      // validates; the local AuthService bridge was never wired. See main.ts:652.
+      try {
+        const record = await validateScopedTokenViaCap(addonRegistry, token)
+        if (!record) {
+          authReason = authReason ?? 'token not recognised'
+        } else if (isUploadAllowed(record)) {
+          authOk = true
+        } else {
+          authReason = `scoped token lacks create access on '${UPLOAD_TRPC_PATH}'`
+        }
+      } catch (err) {
+        authReason = `scoped token validation failed: ${err instanceof Error ? err.message : String(err)}`
+      }
+    }
+    if (!authOk) {
+      return reply.status(403).send({ error: `Forbidden: ${authReason ?? 'admin or upload-scoped token required'}` })
+    }
+
+    const data = await request.file()
+    if (!data) {
+      return reply.status(400).send({ error: 'No file uploaded' })
+    }
+    if (!isTarball(data.filename)) {
+      return reply.status(400).send({ error: 'File must be a .tgz or .tar.gz archive' })
+    }
+
+    // `nodeId` and `addonId` come through as multipart text fields.
+    // `data.fields[X].value` is the parsed string; we narrow defensively
+    // because the multipart plugin types it as `unknown`.
+    const nodeIdField = data.fields['nodeId']
+    const addonIdField = data.fields['addonId']
+    const nodeId = typeof nodeIdField === 'object' && nodeIdField !== null && 'value' in nodeIdField && typeof nodeIdField.value === 'string'
+      ? nodeIdField.value
+      : null
+    const addonIdHint = typeof addonIdField === 'object' && addonIdField !== null && 'value' in addonIdField && typeof addonIdField.value === 'string'
+      ? addonIdField.value
+      : null
+
+    const buffer = await data.toBuffer()
+
+    // Gate: reject archives that don't expose a parseable package.json with
+    // name + version. The hub installer did this implicitly via npm; the
+    // agent path would otherwise fail mid-extraction with no clean rollback.
+    const manifest = validateTarball(buffer, data.filename)
+    if (!manifest) {
+      return reply.status(400).send({ error: 'Tarball missing or malformed package/package.json (name + version required)' })
+    }
+
+    // Branch by deployment target. `nodeId === 'hub'` (or absent) installs on
+    // the hub AND broadcasts to every connected agent that can run any of
+    // the package's addons (i.e. anything not marked hub-only). Any other
+    // explicit `nodeId` value routes only to that agent via `$agent.deploy`.
+    if (!nodeId || nodeId === 'hub') {
+      return installToHub(reply, addonBridge, addonRegistry, moleculer, logger, data.filename, buffer)
+    }
+    const agentAddonId = addonIdHint ?? manifest.name
+    return deployToAgent(reply, moleculer, nodeId, agentAddonId, buffer)
+  })
+}
+
+interface AddonExecutionLike {
+  readonly placement?: 'hub-only' | 'agent-only' | 'any-node'
+}
+interface CamstackAddonDeclLike {
+  readonly id?: unknown
+  readonly execution?: AddonExecutionLike
+}
+
+/**
+ * Read the on-disk package.json and decide whether the package contains
+ * anything that needs to land on agents. We deliberately read from disk
+ * (rather than `addonRegistry.listAddons()`) so the function is safe to
+ * call before `loadNewAddons()` and so `agent-only` addons — which the
+ * hub registry intentionally skips — still show up here.
+ *
+ * Returns `true` if at least one addon's `execution.placement` is anything
+ * other than `'hub-only'`. Absence of `execution` defaults to hub-only so
+ * legacy packages don't suddenly broadcast cluster-wide.
+ */
+function packageHasAgentDeployable(addonsDir: string, packageName: string): boolean {
+  try {
+    const pkgPath = path.join(addonsDir, packageName, 'package.json')
+    const parsed: unknown = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+    if (parsed === null || typeof parsed !== 'object') return false
+    const camstack = (parsed as { camstack?: { addons?: readonly CamstackAddonDeclLike[] } }).camstack
+    const addons = camstack?.addons ?? []
+    return addons.some((a) => {
+      const placement = a.execution?.placement ?? 'hub-only'
+      return placement === 'agent-only' || placement === 'any-node'
+    })
+  } catch {
+    return false
+  }
+}
+
+interface AgentDeployResult {
+  readonly nodeId: string
+  readonly success: boolean
+  readonly loaded?: readonly string[]
+  readonly error?: string
+}
+
+interface MoleculerBrokerLike {
+  call(action: string, params: Record<string, unknown>, options: { nodeID: string; timeout: number }): Promise<unknown>
+  registry?: {
+    getNodeList?: (opts: { onlyAvailable: boolean }) => readonly { id: string }[]
+  }
+}
+
+/**
+ * Push `buffer` (a tarball) to every connected non-hub node and trigger a
+ * `$agent.reload` so the freshly extracted dist is picked up immediately
+ * without an agent restart. Agents that fail are reported per-node — one
+ * unreachable agent must not block the others or the hub install.
+ */
+async function propagateToAgents(
+  moleculer: MoleculerService,
+  logger: IScopedLogger,
+  packageName: string,
+  buffer: Buffer,
+): Promise<readonly AgentDeployResult[]> {
+  const broker = moleculer.broker as unknown as MoleculerBrokerLike
+  const nodes = broker.registry?.getNodeList?.({ onlyAvailable: true }) ?? []
+  // Moleculer reports both top-level nodes (`hub`, `dev-agent-0`, …) AND
+  // their child per-addon runner processes (`hub/detection-pipeline`, `dev-agent-0/foo`).
+  // Only the top-level agent nodes have the `$agent` service — calling
+  // `$agent.deploy` on a child would hang until timeout. The hub itself
+  // is excluded (it was already installed via `installToHub`).
+  const allNodeIds = nodes.map((n) => n.id)
+  const agentNodeIds = allNodeIds.filter((id) => id !== 'hub' && !id.includes('/'))
+  logger.info('propagate: enumerated broker nodes', {
+    meta: {
+      packageName,
+      allNodeIds,
+      targetAgents: agentNodeIds,
+    },
+  })
+  if (agentNodeIds.length === 0) return []
+  const results: AgentDeployResult[] = []
+  for (const nodeId of agentNodeIds) {
+    try {
+      const deployRaw = await broker.call(
+        '$agent.deploy',
+        { addonId: packageName, bundle: buffer },
+        { nodeID: nodeId, timeout: AGENT_DEPLOY_TIMEOUT_MS },
+      )
+      if (!isAgentDeployResponse(deployRaw)) {
+        results.push({ nodeId, success: false, error: 'malformed deploy response' })
+        continue
+      }
+      const reloadRaw = await broker.call(
+        '$agent.reload',
+        {},
+        { nodeID: nodeId, timeout: AGENT_DEPLOY_TIMEOUT_MS },
+      )
+      const reloaded =
+        reloadRaw !== null &&
+        typeof reloadRaw === 'object' &&
+        'loaded' in (reloadRaw as Record<string, unknown>)
+          ? ((reloadRaw as { loaded: readonly string[] }).loaded)
+          : []
+      results.push({ nodeId, success: true, loaded: reloaded })
+    } catch (err: unknown) {
+      results.push({
+        nodeId,
+        success: false,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+  return results
+}
+
+/**
+ * Hub install path: write the tgz, refresh the manifest list, then drive the
+ * registry through (a) `loadNewAddons` for brand-new addonIds and (b)
+ * `restartAddon` for each addonId already tied to this package. The restart
+ * branch is the hot-update story — group-hosted addons re-fork their child
+ * process (fresh dist code is loaded) and in-process addons re-init in place.
+ * Without this the CLI push was write-to-disk-only and required a server
+ * restart to actually run the new code.
+ */
+async function installToHub(
+  reply: FastifyReply,
+  addonBridge: AddonBridgeService,
+  addonRegistry: AddonRegistryService,
+  moleculer: MoleculerService,
+  logger: IScopedLogger,
+  filename: string,
+  buffer: Buffer,
+): Promise<void> {
+  const tmpDir = path.join(os.tmpdir(), `camstack-addon-upload-${Date.now()}`)
+  fs.mkdirSync(tmpDir, { recursive: true })
+  const tgzPath = path.join(tmpDir, filename)
+  fs.writeFileSync(tgzPath, buffer)
+
+  try {
+    const installer = addonBridge.getInstaller()
+    if (!installer) {
+      return reply.status(500).send({ error: 'Addon installer not available' })
+    }
+
+    // Snapshot addonIds tied to this package BEFORE installation. Used after
+    // reload to distinguish "new" vs "updated". installFromTgz only writes
+    // to disk; `addonRegistry.listAddons()` reflects in-memory state, so the
+    // order (snapshot first vs install first) doesn't matter here — kept
+    // pre-install for readability.
+    const result = await installer.installFromTgz(tgzPath)
+    const preInstallAddonIds = addonRegistry
+      .listAddons()
+      .filter((row) => row.manifest.packageName === result.name)
+      .map((row) => row.manifest.id)
+
+    const addonsDir = path.resolve(process.env['CAMSTACK_DATA'] ?? 'camstack-data', 'addons')
+    fs.writeFileSync(path.join(addonsDir, result.name, '.install-source'), 'upload')
+
+    // `addonRegistry.loadNewAddons()` already runs its own fresh filesystem
+    // scan, diff'ing against existing `addonEntries` — it updates metadata
+    // for known addons without touching their live instances + initializes
+    // only entries it hasn't seen before. The previous `addonBridge.
+    // reloadPackages()` call here was redundant AND destructive: it built
+    // a brand-new `AddonLoader` and replaced the global, which knocked
+    // every isolated group-runner's IPC channel offline (visible as
+    // `Group-runner hub/<X>-isolated disconnected` for 6+ addons after
+    // a single `camstack deploy`). `loadNewAddons` alone is enough.
+    const loadResult = await addonRegistry.loadNewAddons()
+
+    // Hot-update + cluster propagation are FIRE-AND-FORGET. The upload
+    // route must respond quickly so the CLI / UI sees confirmation; the
+    // capability re-registration after a forked group-runner respawn can
+    // legitimately take 30s–several minutes (Python pool warmup, native
+    // module init, broken external deps) and we don't want operator
+    // tooling to hang waiting for it. `restartAddon` and
+    // `propagateToAgents` each log their own progress; operators monitor
+    // status through the topology cap or the addons UI.
+    const propagatable = packageHasAgentDeployable(addonsDir, result.name)
+    logger.info('hub install OK', {
+      meta: {
+        packageName: result.name,
+        packageVersion: result.version,
+        loaded: loadResult.loaded,
+        restartTargets: preInstallAddonIds,
+        propagatable,
+      },
+    })
+    for (const id of preInstallAddonIds) {
+      void addonRegistry.restartAddon(id).then((r) => {
+        if (!r.success) {
+          logger.warn('background restart failed', { tags: { addonId: id }, meta: { error: r.error ?? 'unknown' } })
+        } else {
+          logger.info('background restart OK', { tags: { addonId: id } })
+        }
+      })
+    }
+    if (propagatable) {
+      void propagateToAgents(moleculer, logger, result.name, buffer).then((agentResults) => {
+        logger.info('propagation done', { meta: { packageName: result.name, agents: agentResults } })
+      })
+    }
+
+    return reply.send({
+      success: true,
+      target: 'hub',
+      packageName: result.name,
+      version: result.version,
+      loaded: loadResult.loaded,
+      restartingInBackground: preInstallAddonIds,
+      propagatingToAgentsInBackground: propagatable,
+      failures: loadResult.failed,
+    })
+  } finally {
+    fs.rmSync(tmpDir, { recursive: true, force: true })
+  }
+}
+
+function isAgentDeployResponse(value: unknown): value is AgentDeployResponse {
+  if (value === null || typeof value !== 'object') return false
+  const v = value as { success?: unknown; addonId?: unknown; path?: unknown }
+  if (typeof v.success !== 'boolean') return false
+  if (typeof v.addonId !== 'string') return false
+  if (v.path !== undefined && typeof v.path !== 'string') return false
+  return true
+}
+
+/**
+ * Typed view over Moleculer's `ServiceBroker.call`. The library's published
+ * types resolve to `any`, which the typed-eslint ruleset rejects across this
+ * file. Casting the broker once at the boundary lets every downstream call
+ * site read as a normal typed `Promise<unknown>`.
+ */
+interface TypedBrokerCall {
+  call(
+    action: string,
+    params: Record<string, unknown>,
+    options: { nodeID: string; timeout: number },
+  ): Promise<unknown>
+}
+
+async function deployToAgent(
+  reply: FastifyReply,
+  moleculer: MoleculerService,
+  nodeId: string,
+  addonId: string,
+  buffer: Buffer,
+): Promise<void> {
+  try {
+    const broker = moleculer.broker as unknown as TypedBrokerCall
+    const raw = await broker.call(
+      '$agent.deploy',
+      { addonId, bundle: buffer },
+      { nodeID: nodeId, timeout: AGENT_DEPLOY_TIMEOUT_MS },
+    )
+    if (!isAgentDeployResponse(raw)) {
+      return reply.status(502).send({ error: 'Agent deploy returned malformed response' })
+    }
+    return reply.send({
+      success: true,
+      target: nodeId,
+      addonId: raw.addonId,
+      path: raw.path,
+    })
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err)
+    return reply.status(502).send({ error: `Agent deploy failed: ${msg}` })
+  }
+}

package/src/api/addons-custom.router.ts

@@ -0,0 +1,100 @@
+/**
+ * `api.addons.custom` — generic dispatcher for addon-defined custom actions.
+ *
+ * Task 7.2 of the device-proxy redesign. Addons declare a catalog of
+ * custom actions at boot via `AddonInitResult.customActions` + a single
+ * `handleCustomAction(action, input)` handler. The catalog is registered
+ * with a per-process `CustomActionRegistry` (Task 7.1). This endpoint is
+ * the single tRPC entry point that resolves an `(addonId, action)` pair,
+ * validates input + output against the action's Zod schemas, enforces the
+ * action's declared auth level, and dispatches to the addon handler.
+ *
+ * The factory returns a record of procedures (not a router) so the caller
+ * can spread it into the existing `addons` namespace:
+ *
+ *   trpcRouter({
+ *     ...existingAddonsProcedures,
+ *     ...createAddonsCustomProcedures({ getCustomActionRegistry: ... }),
+ *   })
+ *
+ * This avoids `mergeRouters` (which requires sharing the `t` instance
+ * across modules) while still mounting the procedure at `api.addons.custom`.
+ */
+import { z } from 'zod'
+import { TRPCError } from '@trpc/server'
+import type { CustomActionRegistry } from '@camstack/kernel'
+import type { CapabilityMethodAuth } from '@camstack/types'
+import type { TrpcContext } from './trpc/trpc.context.js'
+import { protectedProcedure } from './trpc/trpc.middleware.js'
+
+export interface AddonsCustomDeps {
+  readonly getCustomActionRegistry: () => CustomActionRegistry
+}
+
+/**
+ * Build the procedure record for the `custom` endpoint.
+ *
+ * The OUTER procedure is `protectedProcedure` — every caller must be
+ * authenticated. The INNER per-action auth declared in `spec.auth` is
+ * enforced manually by `ensureAuth` because the auth level is not known
+ * until after the registry lookup.
+ */
+export function createAddonsCustomProcedures(deps: AddonsCustomDeps) {
+  return {
+    custom: protectedProcedure
+      .input(z.object({
+        addonId: z.string().min(1),
+        action: z.string().min(1),
+        input: z.unknown(),
+      }))
+      .output(z.unknown())
+      .mutation(async ({ input, ctx }) => {
+        const registry = deps.getCustomActionRegistry()
+        const entry = registry.resolve(input.addonId, input.action)
+        if (!entry) {
+          throw new TRPCError({
+            code: 'NOT_FOUND',
+            message: `addon '${input.addonId}' has no custom action '${input.action}'`,
+          })
+        }
+
+        // Per-action authorization. The outer procedure already requires
+        // authentication; here we additionally enforce the declared role
+        // when it's stricter than 'protected'.
+        ensureAuth(ctx, entry.spec.auth)
+
+        // Validate input against the action's declared Zod schema.
+        const parsedInput = entry.spec.input.parse(input.input)
+
+
+        // Dispatch through the addon handler.
+        const result = await entry.handler(parsedInput)
+
+        // Validate the addon's output. Crash-early on misbehaving addons.
+        return entry.spec.output.parse(result)
+      }),
+  } as const
+}
+
+/**
+ * Enforce the action's declared auth level.
+ *
+ * Mirrors the role checks performed by `protectedProcedure` and
+ * `adminProcedure` in trpc.middleware.ts:
+ *   - public:    no auth
+ *   - protected: any authenticated user
+ *   - admin:     isAdmin only (scoped tokens bounce)
+ */
+function ensureAuth(ctx: TrpcContext, level: CapabilityMethodAuth): void {
+  if (level === 'public') return
+  if (!ctx.user) {
+    throw new TRPCError({ code: 'UNAUTHORIZED' })
+  }
+  if (level === 'protected') return
+  if (level === 'admin') {
+    if (!ctx.user.isAdmin) {
+      throw new TRPCError({ code: 'FORBIDDEN', message: 'custom action requires admin' })
+    }
+    return
+  }
+}

package/src/api/auth-whoami.ts

@@ -0,0 +1,99 @@
+/**
+ * `GET /api/auth/whoami` — validate the caller's token and surface the
+ * canonical identity + scope summary the server sees.
+ *
+ * Designed for the CLI `camstack whoami` command, which used to trust
+ * the local cache blindly. Hitting this endpoint catches:
+ *   • revocation (token was deleted server-side after the local cache)
+ *   • expiry
+ *   • orphan-cleanup (e.g. owner deleted, see local-auth boot migration)
+ *
+ * Accepts both JWT and `cst_*` scoped tokens. Returns 401 on auth fail;
+ * 200 with the resolved identity otherwise. We intentionally do NOT
+ * expose `tokenHash` or the raw token — only `tokenPrefix` + scopes for
+ * the client to confirm the cached blob matches what the server has.
+ */
+import type { FastifyInstance } from 'fastify'
+import type { AuthService } from '../core/auth/auth.service'
+import type { AddonRegistryService } from '../core/addon/addon-registry.service'
+
+interface ScopedTokenLike {
+  readonly id: string
+  readonly userId: string
+  readonly name: string
+  readonly tokenPrefix: string
+  readonly scopes: readonly { type: string; target: string }[]
+  readonly expiresAt?: number | null
+  readonly lastUsedAt?: number | null
+  readonly createdAt: number
+}
+interface UserManagementLike {
+  validateScopedToken(input: { token: string }): Promise<ScopedTokenLike | null>
+}
+
+interface WhoamiOk {
+  readonly ok: true
+  readonly kind: 'jwt' | 'scoped'
+  readonly userId: string
+  readonly username: string
+  readonly isAdmin?: boolean
+  readonly tokenPrefix?: string
+  readonly scopes?: readonly { type: string; target: string }[]
+  readonly expiresAt?: number | null
+  readonly createdAt?: number
+}
+
+export async function registerAuthWhoamiRoute(
+  fastify: FastifyInstance,
+  authService: AuthService,
+  addonRegistry: AddonRegistryService,
+): Promise<void> {
+  fastify.get('/api/auth/whoami', async (request, reply) => {
+    const authHeader = request.headers.authorization
+    if (!authHeader) {
+      return reply.status(401).send({ ok: false, error: 'No Authorization header' })
+    }
+    const token = authHeader.replace('Bearer ', '')
+
+    // JWT fast path — same logic as addon-upload auth chain.
+    try {
+      const payload = authService.verifyToken(token)
+      const ok: WhoamiOk = {
+        ok: true,
+        kind: 'jwt',
+        userId: payload.userId ?? payload.keyId ?? 'unknown',
+        username: payload.username ?? 'unknown',
+        isAdmin: payload.isAdmin,
+      }
+      return reply.send(ok)
+    } catch {
+      // Not a JWT — try scoped token via cap registry.
+    }
+
+    try {
+      const capRegistry = addonRegistry.getCapabilityRegistry()
+      const userMgmt = capRegistry.getSingleton('user-management') as UserManagementLike | undefined
+      if (!userMgmt) {
+        return reply.status(503).send({ ok: false, error: 'user-management cap not mounted' })
+      }
+      const record = await userMgmt.validateScopedToken({ token })
+      if (!record) {
+        return reply.status(401).send({ ok: false, error: 'Token not recognised (revoked, expired, or never issued)' })
+      }
+      const ok: WhoamiOk = {
+        ok: true,
+        kind: 'scoped',
+        userId: record.userId,
+        username: record.userId,
+        tokenPrefix: record.tokenPrefix,
+        scopes: record.scopes,
+        expiresAt: record.expiresAt ?? null,
+        createdAt: record.createdAt,
+      }
+      return reply.send(ok)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      return reply.status(500).send({ ok: false, error: `Validation failed: ${msg}` })
+    }
+  })
+}