@camstack/server 0.1.3

package/src/core/addon-widgets/addon-widgets.service.ts

@@ -0,0 +1,92 @@
+import * as path from 'node:path'
+import * as fs from 'node:fs'
+import { LoggingService } from '../logging/logging.service'
+import { CapabilityService } from '../capability/capability.service'
+import { AddonRegistryService } from '../addon/addon-registry.service'
+import type { IScopedLogger, IAddonWidgetsSourceProvider } from '@camstack/types'
+
+/**
+ * Strip the `@<nodeId>` suffix the CapabilityBridge appends to
+ * collection-provider registry keys for cross-node addons. The widget
+ * static-file route always receives the bare manifest id.
+ */
+function stripNodeSuffix(registryKey: string): string {
+  const at = registryKey.indexOf('@')
+  return at === -1 ? registryKey : registryKey.slice(0, at)
+}
+
+/**
+ * AddonWidgetsService — server-side helper that backs the static file
+ * route `/api/addon-widgets/:addonId/*` (registered in `main.ts`).
+ *
+ * Mirrors `AddonPagesService` exactly. The public listing surface
+ * (`addonWidgets.listWidgets` on the AppRouter) lives in the
+ * `addon-widgets-aggregator` builtin which walks every
+ * `addon-widgets-source` collection provider and stamps versioned
+ * `bundleUrl`s. Both ends flow through codegen.
+ *
+ * What stays here: filesystem path resolution + traversal protection
+ * for the static file route. The registered-provider check uses
+ * `CapabilityService` (so unknown / unregistered addons can't be
+ * probed via path traversal tricks); the on-disk path comes from
+ * `AddonRegistryService.getAddonInstallPath()` so bundled addons
+ * (where one npm package ships multiple addon entries under
+ * `dist/<entryId>/`) resolve to the right sub-folder instead of the
+ * pre-bundle `addons/@camstack/addon-<id>/dist/` layout.
+ */
+export class AddonWidgetsService {
+  private readonly logger: IScopedLogger
+
+  constructor(
+    private readonly loggingService: LoggingService,
+    private readonly caps: CapabilityService,
+    private readonly registry: AddonRegistryService,
+  ) {
+    this.logger = this.loggingService.createLogger('AddonWidgetsService')
+  }
+
+  /**
+   * Resolve the filesystem path to an addon's widget bundle file.
+   * Returns null if the addon is not registered, the file doesn't exist,
+   * or the path would escape the addon directory (path traversal protection).
+   */
+  resolveBundle(addonId: string, filePath: string): string | null {
+    // The collection cap doesn't carry an `id` on its provider, so we
+    // attribute via `getCollectionEntries` (returns `[addonId, provider]`).
+    //
+    // For cross-node addons the CapabilityBridge registers the provider
+    // under a node-qualified key `<addonId>@<nodeId>` (see
+    // `moleculer.service.ts`). The bundle is hub-resident and keyed by
+    // the bare manifest id, so the route always carries the bare
+    // `addonId` — match it against each registry key with the
+    // `@<nodeId>` suffix stripped.
+    const entries = this.caps.getCollectionEntries<IAddonWidgetsSourceProvider>('addon-widgets-source')
+    const isRegistered = entries.some(([id]) => stripNodeSuffix(id) === addonId)
+    if (!isRegistered) {
+      this.logger.warn('Bundle resolve failed: addon not registered as widget provider', { tags: { addonId } })
+      return null
+    }
+
+    const installPath = this.registry.getAddonInstallPath(addonId)
+    if (!installPath) {
+      this.logger.warn('Bundle resolve failed: addon install path not found', { tags: { addonId } })
+      return null
+    }
+
+    const resolvedBase = path.resolve(installPath.distDir)
+    const resolvedFile = path.resolve(installPath.distDir, filePath)
+
+    // Path traversal protection
+    if (!resolvedFile.startsWith(resolvedBase + path.sep) && resolvedFile !== resolvedBase) {
+      this.logger.warn('Path traversal denied for addon', { tags: { addonId }, meta: { filePath } })
+      return null
+    }
+
+    if (!fs.existsSync(resolvedFile)) {
+      this.logger.debug('Bundle file not found', { meta: { resolvedFile } })
+      return null
+    }
+
+    return resolvedFile
+  }
+}

package/src/core/agent/agent-registry.service.ts

@@ -0,0 +1,507 @@
+import { randomUUID } from 'node:crypto'
+import * as os from 'node:os'
+import { EventCategory, resolveAddonPlacement } from '@camstack/types'
+import type {
+  AgentListItem,
+  CameraRoleAssignment,
+  AgentCapability,
+  IMetricsProvider,
+} from '@camstack/types'
+import { EventBusService } from '../events/event-bus.service'
+import { MoleculerService } from '../moleculer/moleculer.service'
+import { CapabilityService } from '../capability/capability.service'
+import type { AddonRegistryService } from '../addon/addon-registry.service'
+
+/** Per-call timeout for `$agent.*` RPC during reconciliation. */
+const AGENT_RECONCILE_RPC_TIMEOUT_MS = 8_000
+
+/** Shape of one addon entry in the `$agent.status` response. */
+interface AgentStatusAddon {
+  readonly id: string
+  readonly status?: string
+  readonly version?: string
+  readonly packageName?: string
+}
+
+/**
+ * Narrow typed view of the Moleculer broker — its own `.d.ts` chains
+ * through eventemitter2 and resolves to `error`, tripping the
+ * `no-unsafe-*` rules. One documented cast through this interface
+ * (see the `broker` getter) keeps every call site type-safe.
+ */
+interface ReconcileBrokerLike {
+  call(
+    action: string,
+    params?: Record<string, unknown>,
+    options?: { nodeID?: string; timeout?: number },
+  ): Promise<unknown>
+  localBus: {
+    on(event: string, handler: (payload: { node: { id: string } }) => void): void
+  }
+}
+
+export class AgentRegistryService {
+  // Role assignments: key = `${cameraId}:${role}`
+  private readonly assignments: Map<string, CameraRoleAssignment> = new Map()
+  private readonly bootTimestamp = Date.now()
+
+  /**
+   * Hub addon registry — the source of truth for which addons are
+   * installed and their `execution.placement`. Injected via
+   * `setAddonRegistry()` rather than the constructor because
+   * `AddonRegistryService` is built AFTER this service in the boot
+   * order (see `manual-boot.ts`).
+   */
+  private addonRegistry: AddonRegistryService | null = null
+
+  constructor(
+    private readonly eventBus: EventBusService,
+    private readonly moleculer: MoleculerService,
+    private readonly capabilityService: CapabilityService,
+  ) {}
+
+  /** Wire the hub addon registry once it has been constructed. */
+  setAddonRegistry(addonRegistry: AddonRegistryService): void {
+    this.addonRegistry = addonRegistry
+  }
+
+  /** Typed view of the Moleculer broker — single documented cast. */
+  private get broker(): ReconcileBrokerLike {
+    return this.moleculer.broker as unknown as ReconcileBrokerLike
+  }
+
+  onModuleInit(): void {
+    const classifyNode = (id: string): 'agent' | 'worker' | null => {
+      if (id === 'hub') return null
+      if (id.includes('/')) return 'worker'
+      return 'agent'
+    }
+
+    // D3: reconcile placement when an agent completes the $hub.registerNode
+    // handshake — the manifest is authoritative and complete at that point,
+    // no grace delay needed. MoleculerService fires this callback from its
+    // onRegisterNode dep for every bare-ID agent node.
+    this.moleculer.setOnAgentRegistered((agentId) => {
+      void this.reconcileAgentAddons(agentId)
+    })
+
+    this.broker.localBus.on('$node.connected', ({ node }: { node: { id: string } }) => {
+      const kind = classifyNode(node.id)
+      if (!kind) return
+      if (kind === 'agent') {
+        console.log(`[agent-registry] Agent connected: ${node.id}`)
+        this.eventBus.emit({
+          id: randomUUID(),
+          timestamp: new Date(),
+          source: { type: 'core', id: 'agent-registry' },
+          category: EventCategory.AgentOnline,
+          data: { agentId: node.id },
+        })
+      } else {
+        this.eventBus.emit({
+          id: randomUUID(),
+          timestamp: new Date(),
+          source: { type: 'core', id: 'agent-registry' },
+          category: EventCategory.WorkerOnline,
+          data: { workerId: node.id },
+        })
+      }
+    })
+
+    this.broker.localBus.on('$node.disconnected', ({ node }: { node: { id: string } }) => {
+      const kind = classifyNode(node.id)
+      if (!kind) return
+      if (kind === 'agent') {
+        console.log(`[agent-registry] Agent disconnected: ${node.id}`)
+        this.eventBus.emit({
+          id: randomUUID(),
+          timestamp: new Date(),
+          source: { type: 'core', id: 'agent-registry' },
+          category: EventCategory.AgentOffline,
+          data: { agentId: node.id },
+        })
+      } else {
+        this.eventBus.emit({
+          id: randomUUID(),
+          timestamp: new Date(),
+          source: { type: 'core', id: 'agent-registry' },
+          category: EventCategory.WorkerOffline,
+          data: { workerId: node.id },
+        })
+      }
+    })
+
+    // Retroactive scan: emit lifecycle events for nodes already
+    // connected when the listener registers. Classifies each as
+    // agent or worker — same logic as the live handlers above.
+    try {
+      const registry = (this.moleculer.broker as unknown as Record<string, unknown>).registry as
+        | { getNodeList?: (opts: { onlyAvailable: boolean }) => readonly { id: string }[] }
+        | undefined
+      const existing = registry?.getNodeList?.({ onlyAvailable: true }) ?? []
+      for (const { id } of existing) {
+        const kind = classifyNode(id)
+        if (!kind) continue
+        if (kind === 'agent') {
+          this.eventBus.emit({
+            id: randomUUID(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'agent-registry' },
+            category: EventCategory.AgentOnline,
+            data: { agentId: id },
+          })
+        } else {
+          this.eventBus.emit({
+            id: randomUUID(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'agent-registry' },
+            category: EventCategory.WorkerOnline,
+            data: { workerId: id },
+          })
+        }
+      }
+    } catch {
+      // Registry shape varies across Moleculer versions — never fatal.
+    }
+  }
+
+  // ---- Placement reconciliation ----
+
+  /**
+   * Boot-time reconciliation pass. Agents already connected when the hub
+   * starts never fire a fresh `$node.connected` event, so the per-connect
+   * trigger would miss them — this method walks the current node list once
+   * and reconciles every connected agent. Must be invoked AFTER
+   * `AddonRegistryService.onModuleInit()` so the hub's installed-addon set
+   * is populated. Per-agent failures are isolated — one unreachable agent
+   * must not abort the pass or hub boot.
+   */
+  async reconcileConnectedAgents(): Promise<void> {
+    const registry = (this.moleculer.broker as unknown as Record<string, unknown>).registry as
+      | { getNodeList?: (opts: { onlyAvailable: boolean }) => readonly { id: string }[] }
+      | undefined
+    const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? []
+    const agentIds = nodes
+      .map((n) => n.id)
+      .filter((id) => id !== 'hub' && !id.includes('/'))
+    if (agentIds.length === 0) return
+    console.log(`[agent-registry] Boot reconcile: ${agentIds.length} connected agent(s)`)
+    for (const agentId of agentIds) {
+      await this.reconcileAgentAddons(agentId)
+    }
+  }
+
+  /**
+   * Reconcile a single agent's deployed addons against the hub's installed
+   * set + placements. An addon running on the agent is STALE — and must be
+   * undeployed — when it is either:
+   *   - not installed on the hub at all, or
+   *   - installed but declared `execution.placement: 'hub-only'`.
+   *
+   * `agent-only` / `any-node` addons that ARE installed on the hub are
+   * legitimate agent residents and left untouched.
+   *
+   * Matching is by addon DECLARATION id: `$agent.status` reports
+   * `addons[].id` (the decl id), and the hub's `listAddons()` rows expose
+   * the same decl id at `manifest.id`. Package names are NOT used for the
+   * match — a single package can ship multiple addons with distinct ids
+   * and placements.
+   *
+   * All errors are caught and logged so a single bad agent never breaks
+   * the caller (connect handler or boot pass).
+   */
+  async reconcileAgentAddons(agentId: string): Promise<void> {
+    if (!this.addonRegistry) {
+      console.warn(`[agent-registry] Reconcile skipped for ${agentId}: addon registry not wired`)
+      return
+    }
+    try {
+      const broker = this.broker
+      const statusRaw = await broker.call('$agent.status', {}, {
+        nodeID: agentId,
+        timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS,
+      })
+      const agentAddons = this.extractAgentAddons(statusRaw)
+      if (agentAddons.length === 0) return
+
+      // Build the hub's placement map: decl id → placement. Absence from
+      // this map means "not installed on the hub".
+      const hubPlacements = new Map<string, ReturnType<typeof resolveAddonPlacement>>()
+      for (const row of this.addonRegistry.listAddons()) {
+        const declId = row.manifest.id
+        if (typeof declId !== 'string') continue
+        const decl = row.declaration ?? row.manifest
+        hubPlacements.set(declId, resolveAddonPlacement(decl))
+      }
+
+      const stale = agentAddons.filter((addon) => {
+        const placement = hubPlacements.get(addon.id)
+        // Not installed on the hub → stale.
+        if (placement === undefined) return true
+        // Installed but pinned to the hub → must not run on an agent.
+        return placement === 'hub-only'
+      })
+
+      if (stale.length === 0) {
+        console.log(`[agent-registry] Reconcile ${agentId}: no stale addons (${agentAddons.length} checked)`)
+        return
+      }
+
+      for (const addon of stale) {
+        const reason = hubPlacements.has(addon.id)
+          ? 'placement is hub-only'
+          : 'not installed on hub'
+        try {
+          await broker.call('$agent.undeploy', { addonId: addon.id }, {
+            nodeID: agentId,
+            timeout: AGENT_RECONCILE_RPC_TIMEOUT_MS,
+          })
+          console.log(`[agent-registry] Reconcile ${agentId}: undeployed stale addon "${addon.id}" (${reason})`)
+          this.eventBus.emit({
+            id: randomUUID(),
+            timestamp: new Date(),
+            source: { type: 'core', id: 'agent-registry' },
+            category: EventCategory.AddonUninstalled,
+            data: { addonId: addon.id, agentId, reason },
+          })
+        } catch (err) {
+          console.error(
+            `[agent-registry] Reconcile ${agentId}: failed to undeploy "${addon.id}":`,
+            err instanceof Error ? err.message : String(err),
+          )
+        }
+      }
+    } catch (err) {
+      console.error(
+        `[agent-registry] Reconcile failed for agent ${agentId}:`,
+        err instanceof Error ? err.message : String(err),
+      )
+    }
+  }
+
+  /** Narrow the `$agent.status` response down to its addon list. */
+  private extractAgentAddons(statusRaw: unknown): readonly AgentStatusAddon[] {
+    if (statusRaw === null || typeof statusRaw !== 'object') return []
+    const addons = (statusRaw as { addons?: unknown }).addons
+    if (!Array.isArray(addons)) return []
+    const result: AgentStatusAddon[] = []
+    for (const entry of addons) {
+      if (entry === null || typeof entry !== 'object') continue
+      const id = (entry as { id?: unknown }).id
+      if (typeof id !== 'string' || id.length === 0) continue
+      result.push({ id })
+    }
+    return result
+  }
+
+  /** Log an agent rename (name changes are persisted via $agent.rename RPC). */
+  updateAgentName(nodeId: string, name: string): void {
+    console.log(`[agent-registry] Agent renamed: "${nodeId}" → "${name}"`)
+  }
+
+  async listNodes(): Promise<readonly AgentListItem[]> {
+    // Get child processes for hub via $process.list
+    let hubProcesses: readonly unknown[] = []
+    try {
+      const processes = await this.broker.call('$process.list') as readonly Record<string, unknown>[]
+      hubProcesses = processes.map((p) => ({
+        pid: (p.pid as number) ?? 0,
+        name: (p.name as string) ?? '',
+        command: 'moleculer-service',
+        state: (p.state as 'running' | 'stopped' | 'crashed') ?? 'running',
+        cpuPercent: (p.cpuPercent as number) ?? 0,
+        memoryRss: (p.memoryRss as number) ?? 0,
+        uptimeSeconds: (p.uptimeSeconds as number) ?? 0,
+        addonIds: (p.addonIds as readonly string[] | undefined) ?? [],
+        groupId: (p.groupId as string | undefined) ?? null,
+      }))
+    } catch {
+      // $process service may not be ready yet
+    }
+
+    const hubEntry = await this.buildHubEntry(hubProcesses)
+
+    const remoteEntries: AgentListItem[] = []
+    const registry = (this.moleculer.broker as unknown as Record<string, unknown>).registry as
+      | { getNodeList?: (opts: { onlyAvailable: boolean }) => Array<{ id: string }> }
+      | undefined
+    const nodes = registry?.getNodeList?.({ onlyAvailable: true }) ?? []
+
+    for (const node of nodes) {
+      const nodeId = node.id
+      // Skip hub (already included) and child processes (contain '/')
+      if (nodeId === 'hub' || nodeId.includes('/')) continue
+
+      try {
+        const status = await this.broker.call('$agent.status', {}, {
+          nodeID: nodeId,
+          timeout: 5000,
+        }) as Record<string, unknown>
+
+        // Get real sub-process stats from the agent's $process.list
+        let subProcesses: readonly unknown[] = []
+        try {
+          const processes = await this.broker.call('$process.list', {}, {
+            nodeID: nodeId,
+            timeout: 5000,
+          }) as readonly Record<string, unknown>[]
+          subProcesses = processes.map((p) => ({
+            pid: (p.pid as number) ?? 0,
+            name: (p.name as string) ?? '',
+            command: 'moleculer-service',
+            state: (p.state as 'running' | 'stopped' | 'crashed') ?? 'running',
+            cpuPercent: (p.cpuPercent as number) ?? 0,
+            memoryRss: (p.memoryRss as number) ?? 0,
+            uptimeSeconds: (p.uptimeSeconds as number) ?? 0,
+            addonIds: (p.addonIds as readonly string[] | undefined) ?? [],
+            groupId: (p.groupId as string | undefined) ?? null,
+          }))
+        } catch {
+          // Fall back to addon list from $agent.status (no stats)
+          subProcesses = (status.addons as readonly Record<string, unknown>[] | undefined)?.map((a) => ({
+            pid: 0,
+            name: (a.id as string) ?? '',
+            command: 'moleculer-service',
+            state: ((a.status as string) ?? 'running') as 'running' | 'stopped' | 'crashed',
+            cpuPercent: 0,
+            memoryRss: 0,
+            uptimeSeconds: 0,
+          })) ?? []
+        }
+
+        // Extract addon IDs from $agent.status
+        const agentAddons: readonly string[] = (status.addons as readonly { id: string }[] | undefined)
+          ?.map(a => a.id) ?? []
+
+        const hostname = typeof status.hostname === 'string' ? status.hostname : null
+        const agentName = typeof status.name === 'string' ? status.name : nodeId
+        remoteEntries.push({
+          info: {
+            id: nodeId,
+            name: agentName,
+            hostname: hostname ?? nodeId,
+            capabilities: [],
+            platform: (status.platform as string) ?? 'unknown',
+            arch: (status.arch as string) ?? 'unknown',
+            cpuCores: (status.cpuCores as number) ?? 0,
+            memoryMB: (status.totalMemoryMB as number) ?? 0,
+            cpuModel: status.cpuModel as string | undefined,
+          },
+          localIps: Array.isArray(status.localIps) ? status.localIps as string[] : [],
+          status: {
+            activeCameras: 0,
+            cpuPercent: (status.cpuPercent as number) ?? 0,
+            memoryPercent: (status.memoryPercent as number) ?? 0,
+            fps: {},
+            errors: [],
+          },
+          connectedSince: typeof status.uptime === 'number'
+            ? Date.now() - (status.uptime as number) * 1000
+            : Date.now(),
+          isHub: false,
+          subProcesses,
+          agentAddons,
+        })
+
+      } catch {
+        // Skip nodes without $agent service
+      }
+    }
+
+    // TODO(D3 follow-up): offline-agent history dropped with knownAgents.
+    // Previously, agents that disconnected were kept in a shadow map and
+    // surfaced here as offline rows. listNodes now reflects only live
+    // broker.registry nodes.
+
+    return [hubEntry, ...remoteEntries]
+  }
+
+  private async buildHubEntry(subProcesses: readonly unknown[] = []): Promise<AgentListItem> {
+    const cpus = os.cpus()
+
+    // Get live metrics from the metrics-provider capability (NativeMetricsProvider).
+    // The cap contract only exposes async snapshots; the cached read is cheap
+    // because the addon's background sampler keeps the snapshot warm.
+    let cpuPercent = 0
+    let memoryPercent = 0
+    const registry = this.capabilityService.getRegistry()
+    if (registry) {
+      const metricsProvider = registry.getSingleton<IMetricsProvider>('metrics-provider')
+      if (metricsProvider) {
+        const snapshot = await metricsProvider.getCached()
+        if (snapshot) {
+          cpuPercent = snapshot.cpu.total
+          memoryPercent = snapshot.memory.percent
+        }
+      }
+    }
+
+    return {
+      info: {
+        id: 'hub',
+        name: 'Hub',
+        hostname: os.hostname(),
+        capabilities: [],
+        platform: os.platform(),
+        arch: os.arch(),
+        cpuCores: cpus.length,
+        memoryMB: Math.round(os.totalmem() / 1024 / 1024),
+        cpuModel: cpus[0]?.model,
+      },
+      status: {
+        activeCameras: 0,
+        cpuPercent,
+        memoryPercent,
+        fps: {},
+        errors: [],
+      },
+      connectedSince: this.bootTimestamp,
+      isHub: true,
+      subProcesses,
+    }
+  }
+
+  // ---- Role assignments ----
+
+  getAssignments(cameraId?: number): CameraRoleAssignment[] {
+    const all = [...this.assignments.values()]
+    if (cameraId !== undefined) return all.filter((a) => a.cameraId === cameraId)
+    return all
+  }
+
+  setAssignment(assignment: CameraRoleAssignment): void {
+    const key = `${assignment.cameraId}:${assignment.role}`
+    this.assignments.set(key, { ...assignment })
+  }
+
+  removeAssignment(cameraId: number, role: AgentCapability): void {
+    const key = `${cameraId}:${role}`
+    this.assignments.delete(key)
+  }
+
+  activateBackup(cameraId: number, role: AgentCapability): void {
+    const primaryKey = `${cameraId}:${role}`
+    const primary = this.assignments.get(primaryKey)
+
+    const backup = [...this.assignments.values()].find(
+      (a) => a.cameraId === cameraId && a.role === role && a.priority === 'backup',
+    )
+
+    if (!backup) return
+
+    if (primary) {
+      this.assignments.delete(primaryKey)
+    }
+
+    const promoted: CameraRoleAssignment = { ...backup, priority: 'primary' }
+    this.assignments.set(primaryKey, promoted)
+
+    this.eventBus.emit({
+      id: randomUUID(),
+      timestamp: new Date(),
+      source: { type: 'core', id: 'agent-registry' },
+      category: EventCategory.AgentBackupActivated,
+      data: { cameraId, role, agentId: promoted.agentId },
+    })
+  }
+}

package/src/core/auth/auth.service.spec.ts

@@ -0,0 +1,88 @@
+ 
+import { describe, it, expect, beforeEach } from 'vitest'
+import { AuthService } from './auth.service'
+import type { ConfigService } from '../config/config.service'
+import type { TokenPayload } from '@camstack/types'
+
+function createMockConfig(overrides: Record<string, unknown> = {}): ConfigService {
+  return {
+    get: (path: string) => overrides[path],
+  } as unknown as ConfigService
+}
+
+describe('AuthService', () => {
+  let service: AuthService
+
+  beforeEach(() => {
+    service = new AuthService(createMockConfig({ 'auth.jwtSecret': 'test-secret' }))
+  })
+
+  describe('JWT sign/verify', () => {
+    it('should sign and verify a token (roundtrip)', () => {
+      const payload: Omit<TokenPayload, 'iat' | 'exp'> = {
+        userId: 'user-1',
+        username: 'admin',
+        role: 'admin',
+        allowedProviders: '*',
+        allowedDevices: {},
+      }
+
+      const token = service.signToken(payload)
+       
+      const decoded = service.verifyToken(token)
+
+       
+      expect(decoded.userId).toBe('user-1')
+       
+      expect(decoded.username).toBe('admin')
+       
+      expect(decoded.role).toBe('admin')
+       
+      expect(decoded.allowedProviders).toBe('*')
+       
+      expect(decoded.iat).toBeDefined()
+       
+      expect(decoded.exp).toBeDefined()
+    })
+
+    it('should reject invalid tokens', () => {
+      expect(() => service.verifyToken('invalid.token.here')).toThrow()
+    })
+  })
+
+  describe('password hashing', () => {
+    it('should hash and compare passwords correctly', async () => {
+      const password = 'my-secure-password'
+      const hash = await service.hashPassword(password)
+
+      expect(hash).not.toBe(password)
+      expect(await service.comparePassword(password, hash)).toBe(true)
+    })
+
+    it('should reject wrong passwords', async () => {
+      const hash = await service.hashPassword('correct-password')
+      expect(await service.comparePassword('wrong-password', hash)).toBe(false)
+    })
+  })
+
+  describe('API key generation', () => {
+    it('should generate an API key with token, hash, and prefix', () => {
+      const key = service.generateApiKey()
+
+      expect(key.token).toHaveLength(64) // 32 bytes hex
+      expect(key.hash).toHaveLength(64) // SHA-256 hex
+      expect(key.prefix).toHaveLength(8)
+      expect(key.token.startsWith(key.prefix)).toBe(true)
+    })
+
+    it('should validate API key token against hash (correct)', () => {
+      const key = service.generateApiKey()
+      expect(service.validateApiKey(key.token, key.hash)).toBe(true)
+    })
+
+    it('should reject wrong API key token', () => {
+      const key = service.generateApiKey()
+      expect(service.validateApiKey('wrong-token', key.hash)).toBe(false)
+    })
+  })
+})

package/src/core/auth/auth.service.ts

@@ -0,0 +1,8 @@
+import { AuthManager } from '@camstack/core'
+import { ConfigService } from '../config/config.service'
+
+export class AuthService extends AuthManager {
+  constructor(config: ConfigService) {
+    super(config)
+  }
+}