@camstack/server 0.1.7 → 0.2.0

package/src/__tests__/moleculer/uds-unowned-call.spec.ts

@@ -23,11 +23,16 @@ import { describe, it, expect, vi } from 'vitest'
 import {
   createParentUnownedCallHandler,
   CapRouteResolver,
+  CapRouteError,
+  HubNodeRegistry,
 } from '@camstack/kernel'
 import type {
   NodeCapAuthority,
   InProcessProviderLookup,
   CapRouteResolverDeps,
+  NodeNativeCapEntry,
+  HubLocalChildDispatcher,
+  CapCallInput,
 } from '@camstack/kernel'
 import type { ServiceBroker } from 'moleculer'
 
@@ -63,6 +68,44 @@ function hubBrokerFake(): ServiceBroker {
   return broker as unknown as ServiceBroker
 }
 
+/**
+ * Minimal `HubNodeRegistry`-shaped fake exposing only the lookup the unowned
+ * handler uses: `listNativeCapEntriesForDevice`. The handler depends solely on
+ * this method, so we don't need the full registry to exercise its routing.
+ */
+function nodeRegistryFake(
+  byDevice: Record<number, readonly NodeNativeCapEntry[]> = {},
+): HubNodeRegistry {
+  const fake = {
+    listNativeCapEntriesForDevice: (deviceId: number): readonly NodeNativeCapEntry[] =>
+      byDevice[deviceId] ?? [],
+  }
+  return fake as unknown as HubNodeRegistry
+}
+
+/**
+ * Hub-local UDS dispatcher fake (LocalChildRegistry surface). `resolveChildId`
+ * returns the configured childId on a (capName, deviceId) match else null;
+ * `callCapOnChild` records the call and echoes a sentinel result.
+ */
+function localDispatcherFake(owner?: { capName: string; deviceId: number; childId: string }): {
+  dispatcher: HubLocalChildDispatcher
+  resolveChildId: ReturnType<typeof vi.fn>
+  callCapOnChild: ReturnType<typeof vi.fn>
+} {
+  const resolveChildId = vi.fn((capName: string, deviceId?: number): string | null =>
+    owner !== undefined && capName === owner.capName && deviceId === owner.deviceId
+      ? owner.childId
+      : null,
+  )
+  const callCapOnChild = vi.fn(async (childId: string, input: CapCallInput) => ({
+    routedOverUds: childId,
+    capName: input.capName,
+  }))
+  const dispatcher: HubLocalChildDispatcher = { resolveChildId, callCapOnChild }
+  return { dispatcher, resolveChildId, callCapOnChild }
+}
+
 describe('hub onUnownedCall wiring (F0)', () => {
   it('resolver-first: resolves a hub-in-process cap through the real CapRouteResolver', async () => {
     const broker = hubBrokerFake()
@@ -71,7 +114,12 @@ describe('hub onUnownedCall wiring (F0)', () => {
     const settingsStore = { get: async (params: unknown) => ({ value: 'hub-resolved', params }) }
     const inProcessProviders: InProcessProviderLookup = (capName) =>
       capName === 'settings-store'
-        ? { invoke: (method, args) => Promise.resolve((settingsStore as Record<string, (a: unknown) => unknown>)[method](args)) }
+        ? {
+            invoke: (method, args) =>
+              Promise.resolve(
+                (settingsStore as Record<string, (a: unknown) => unknown>)[method](args),
+              ),
+          }
         : null
 
     const resolverDeps: CapRouteResolverDeps = {
@@ -83,12 +131,16 @@ describe('hub onUnownedCall wiring (F0)', () => {
     }
     const resolver = new CapRouteResolver(resolverDeps)
 
-    const handler = createParentUnownedCallHandler({ getResolver: () => resolver, broker })
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(),
+    })
 
     const result = await handler({ capName: 'settings-store', method: 'get', args: { key: 'k' } })
     expect(result).toEqual({ value: 'hub-resolved', params: { key: 'k' } })
     // Resolver served it — broker untouched.
-    expect((broker.call as ReturnType<typeof vi.fn>)).not.toHaveBeenCalled()
+    expect(broker.call as ReturnType<typeof vi.fn>).not.toHaveBeenCalled()
   })
 
   it('broker-fallback: a `$`-infra core service (`$core-caps.system.info`) routes via the broker', async () => {
@@ -104,7 +156,11 @@ describe('hub onUnownedCall wiring (F0)', () => {
       inProcessProviders: () => null,
     })
 
-    const handler = createParentUnownedCallHandler({ getResolver: () => resolver, broker })
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(),
+    })
 
     const result = await handler({ capName: 'system', method: 'info', args: undefined })
     expect(result).toEqual({ uptimeSec: 99, params: undefined })
@@ -115,9 +171,213 @@ describe('hub onUnownedCall wiring (F0)', () => {
     const broker = hubBrokerFake()
     // Mirrors the window before `this.resolver` is constructed: getResolver
     // returns null, so the handler goes straight to the broker fallback.
-    const handler = createParentUnownedCallHandler({ getResolver: () => null, broker })
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => null,
+      broker,
+      nodeRegistry: nodeRegistryFake(),
+    })
 
     const result = await handler({ capName: 'system', method: 'info', args: undefined })
     expect(result).toEqual({ uptimeSec: 99, params: undefined })
   })
+
+  it('deviceId-aware resolver: derives deviceId from args and routes via the resolver (no broker fallback)', async () => {
+    const broker = hubBrokerFake()
+
+    // A resolver-shaped fake that resolves a route ONLY when invoked with a
+    // deviceId — mirroring the real resolver routing a device-scoped native cap
+    // to its owning provider. Without a deviceId it returns no-provider.
+    let resolvedWithDeviceId: number | undefined
+    const resolver = {
+      resolveCapRoute: (capName: string, opts: { deviceId?: number }) => {
+        if (opts.deviceId === undefined) {
+          throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+        }
+        resolvedWithDeviceId = opts.deviceId
+        return { kind: 'hub-in-process', capName, deviceId: opts.deviceId }
+      },
+      dispatch: async () => ({ catalog: ['stream-a'] }),
+    }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(),
+    })
+
+    // deviceId lives ONLY in args, NOT top-level — the handler must derive it.
+    const result = await handler({
+      capName: 'stream-catalog',
+      method: 'getCatalog',
+      args: { deviceId: 7 },
+    })
+    expect(result).toEqual({ catalog: ['stream-a'] })
+    expect(resolvedWithDeviceId).toBe(7)
+    // Resolver served it via the derived deviceId — broker untouched.
+    expect(broker.call).not.toHaveBeenCalled()
+  })
+
+  it('pinned broker fallback: resolver finds nothing → call is pinned to the owning node', async () => {
+    const broker = hubBrokerFake()
+
+    // Resolver always returns no-provider for this device-scoped cap.
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => {
+        throw new Error('dispatch should not be reached')
+      },
+    }
+
+    const owner: NodeNativeCapEntry = {
+      nodeId: 'agent',
+      addonId: 'reolink',
+      capName: 'stream-catalog',
+      deviceId: 7,
+    }
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake({ 7: [owner] }),
+    })
+
+    await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } }).catch(
+      () => undefined,
+    )
+
+    // The broker call is pinned to the owning node via call-opts `{ nodeID }`.
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toEqual({ nodeID: 'agent' })
+  })
+
+  it('back-compat: no resolvable device-owner → broker call stays UNPINNED (load-balanced)', async () => {
+    const broker = hubBrokerFake()
+
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => {
+        throw new Error('dispatch should not be reached')
+      },
+    }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(), // no owners for any device
+    })
+
+    const result = await handler({ capName: 'system', method: 'info', args: undefined })
+    expect(result).toEqual({ uptimeSec: 99, params: undefined })
+    // Unpinned: third arg (call-opts) is undefined — today's behavior preserved.
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toBeUndefined()
+  })
+
+  it('hub-local owner: device-native cap owned by a hub-local UDS child routes over UDS (broker untouched)', async () => {
+    const broker = hubBrokerFake()
+    // Resolver misses the device-scoped native cap (mirrors live behavior).
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => {
+        throw new Error('dispatch should not be reached')
+      },
+    }
+    const { dispatcher, resolveChildId, callCapOnChild } = localDispatcherFake({
+      capName: 'stream-catalog',
+      deviceId: 7,
+      childId: 'child-reolink',
+    })
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake(), // empty — hub-local child is NOT in HubNodeRegistry
+      getLocalDispatcher: () => dispatcher,
+    })
+
+    const result = await handler({
+      capName: 'stream-catalog',
+      method: 'getCatalog',
+      args: { deviceId: 7 },
+    })
+    expect(result).toEqual({ routedOverUds: 'child-reolink', capName: 'stream-catalog' })
+    expect(resolveChildId).toHaveBeenCalledWith('stream-catalog', 7)
+    expect(callCapOnChild).toHaveBeenCalledWith('child-reolink', {
+      capName: 'stream-catalog',
+      method: 'getCatalog',
+      args: { deviceId: 7 },
+      deviceId: 7,
+    })
+    expect(broker.call).not.toHaveBeenCalled()
+  })
+
+  it('remote owner: hub-local dispatcher misses → pinned broker call', async () => {
+    const broker = hubBrokerFake()
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => {
+        throw new Error('dispatch should not be reached')
+      },
+    }
+    const { dispatcher, callCapOnChild } = localDispatcherFake() // no local owner
+    const owner: NodeNativeCapEntry = {
+      nodeId: 'agent',
+      addonId: 'reolink',
+      capName: 'stream-catalog',
+      deviceId: 7,
+    }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake({ 7: [owner] }),
+      getLocalDispatcher: () => dispatcher,
+    })
+
+    await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } }).catch(
+      () => undefined,
+    )
+
+    expect(callCapOnChild).not.toHaveBeenCalled()
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toEqual({ nodeID: 'agent' })
+  })
+
+  it('no local dispatcher (getter returns null): behaves as before — HubNodeRegistry → broker', async () => {
+    const broker = hubBrokerFake()
+    const resolver = {
+      resolveCapRoute: (capName: string) => {
+        throw new CapRouteError(capName, undefined, { reason: 'no-provider', rejected: [] })
+      },
+      dispatch: async () => {
+        throw new Error('dispatch should not be reached')
+      },
+    }
+    const owner: NodeNativeCapEntry = {
+      nodeId: 'agent',
+      addonId: 'reolink',
+      capName: 'stream-catalog',
+      deviceId: 7,
+    }
+
+    const handler = createParentUnownedCallHandler({
+      getResolver: () => resolver as unknown as CapRouteResolver,
+      broker,
+      nodeRegistry: nodeRegistryFake({ 7: [owner] }),
+      getLocalDispatcher: () => null,
+    })
+
+    await handler({ capName: 'stream-catalog', method: 'getCatalog', args: { deviceId: 7 } }).catch(
+      () => undefined,
+    )
+    const callArgs = (broker.call as ReturnType<typeof vi.fn>).mock.calls[0]
+    expect(callArgs[2]).toEqual({ nodeID: 'agent' })
+  })
 })

package/src/__tests__/moleculer-register-node-idempotency.spec.ts

@@ -46,7 +46,10 @@ import type { StreamProbeService } from '../core/streaming/stream-probe.service.
  */
 interface RegisterNodeDriver {
   onRegisterNode: (params: RegisterNodeParams) => void
-  createCapabilityProxy: (capabilityName: string, nodeId: string) => Record<string, (params: unknown) => Promise<unknown>> | null
+  createCapabilityProxy: (
+    capabilityName: string,
+    nodeId: string,
+  ) => Record<string, (params: unknown) => Promise<unknown>> | null
 }
 
 /** Build a harness whose declared caps are SINGLETON, for active-provider preference tests. */
@@ -55,7 +58,10 @@ function createSingletonHarness(capNames: readonly string[]): Harness {
 }
 
 /** A minimal real `CapabilityDefinition` so `getDefinition`/`expandCapMethods` resolve. */
-function makeCapDef(name: string, mode: 'collection' | 'singleton' = 'collection'): CapabilityDefinition {
+function makeCapDef(
+  name: string,
+  mode: 'collection' | 'singleton' = 'collection',
+): CapabilityDefinition {
   return {
     name,
     scope: 'system',
@@ -98,7 +104,10 @@ interface Harness {
  * The broker is never started, so there is nothing to stop in teardown —
  * no `afterEach` teardown is needed.
  */
-function createHarness(capNames: readonly string[], mode: 'collection' | 'singleton' = 'collection'): Harness {
+function createHarness(
+  capNames: readonly string[],
+  mode: 'collection' | 'singleton' = 'collection',
+): Harness {
   const registry = new CapabilityRegistry(makeLogger())
   for (const name of capNames) {
     registry.declareCapability(makeCapDef(name, mode))
@@ -248,8 +257,8 @@ describe('MoleculerService.applyNodeManifest — singleton local-first preferenc
 
   it('prefers the hub-local provider when the REMOTE one registered first', () => {
     const { driver, registry } = createSingletonHarness(['pipeline-executor'])
-    driver.onRegisterNode(singleton(REMOTE))   // agent first → would win under first-wins
-    driver.onRegisterNode(singleton(LOCAL))    // hub-local second
+    driver.onRegisterNode(singleton(REMOTE)) // agent first → would win under first-wins
+    driver.onRegisterNode(singleton(LOCAL)) // hub-local second
     // Active provider must be the hub-local key (bare addonId, no '@').
     expect(registry.getSingletonAddonId('pipeline-executor')).toBe('detection-pipeline')
     expect(registry.getSingletonAddonId('pipeline-executor')).not.toContain('@')
@@ -257,8 +266,8 @@ describe('MoleculerService.applyNodeManifest — singleton local-first preferenc
 
   it('keeps the hub-local provider active when a REMOTE one registers afterwards', () => {
     const { driver, registry } = createSingletonHarness(['pipeline-executor'])
-    driver.onRegisterNode(singleton(LOCAL))    // hub-local first
-    driver.onRegisterNode(singleton(REMOTE))   // agent second must NOT steal active
+    driver.onRegisterNode(singleton(LOCAL)) // hub-local first
+    driver.onRegisterNode(singleton(REMOTE)) // agent second must NOT steal active
     expect(registry.getSingletonAddonId('pipeline-executor')).toBe('detection-pipeline')
   })
 })

package/src/__tests__/native-cap-route.spec.ts

@@ -38,7 +38,10 @@ interface FakeHubLocalRegistry extends HubLocalChildDispatcher {
 function makeDeviceAwareHubLocalRegistry(
   caps: ReadonlyMap<string, ReadonlyMap<number | 'singleton', string>>,
 ): FakeHubLocalRegistry {
-  const callCapOnChildSpy = vi.fn(async (_childId: string, _input: unknown) => ({ ok: true, from: 'uds' }))
+  const callCapOnChildSpy = vi.fn(async (_childId: string, _input: unknown) => ({
+    ok: true,
+    from: 'uds',
+  }))
   return {
     resolveChildId: (capName: string, deviceId?: number): string | null => {
       const capMap = caps.get(capName)
@@ -79,8 +82,7 @@ function makeNativeAwareNodeAuthority(
       return nativeCaps.some((n) => n.nodeId === nodeId && n.capName === capName)
     },
 
-    nodeIsAgent: (nodeId: string): boolean =>
-      nodeId !== HUB_NODE_ID && !nodeId.includes('/'),
+    nodeIsAgent: (nodeId: string): boolean => nodeId !== HUB_NODE_ID && !nodeId.includes('/'),
 
     nodeOnline: (nodeId: string): boolean => onlineNodes.has(nodeId),
 
@@ -104,7 +106,9 @@ function makeNativeAwareNodeAuthority(
 
     isNativeCap: (nodeId: string, capName: string, deviceId?: number): boolean => {
       if (deviceId !== undefined) {
-        return nativeCaps.some((n) => n.nodeId === nodeId && n.capName === capName && n.deviceId === deviceId)
+        return nativeCaps.some(
+          (n) => n.nodeId === nodeId && n.capName === capName && n.deviceId === deviceId,
+        )
       }
       return nativeCaps.some((n) => n.nodeId === nodeId && n.capName === capName)
     },
@@ -119,15 +123,22 @@ describe('Task5 – device-scoped native cap on hub-local child', () => {
   it('resolves to hub-local-uds and calls callCapOnChild with {capName, method, args+deviceId, deviceId}', async () => {
     // ptz is a device-scoped native cap owned by hub child 'provider-reolink'
     const hubLocalCaps = makeDeviceAwareHubLocalRegistry(
-      new Map([
-        ['ptz', new Map([[7, 'provider-reolink']])],
-      ]),
+      new Map([['ptz', new Map([[7, 'provider-reolink']])]]),
     )
 
     const nativeCaps: NativeCapSpec[] = [
-      { nodeId: 'hub/provider-reolink', addonId: 'addon-provider-reolink', capName: 'ptz', deviceId: 7 },
+      {
+        nodeId: 'hub/provider-reolink',
+        addonId: 'addon-provider-reolink',
+        capName: 'ptz',
+        deviceId: 7,
+      },
     ]
-    const nodeAuthority = makeNativeAwareNodeAuthority(new Map(), new Set(['hub/provider-reolink']), nativeCaps)
+    const nodeAuthority = makeNativeAwareNodeAuthority(
+      new Map(),
+      new Set(['hub/provider-reolink']),
+      nativeCaps,
+    )
 
     const deps: CapRouteResolverDeps = {
       hubNodeId: HUB_NODE_ID,
@@ -149,7 +160,10 @@ describe('Task5 – device-scoped native cap on hub-local child', () => {
     expect(result).toEqual({ ok: true, from: 'uds' })
 
     expect(hubLocalCaps.callCapOnChildSpy).toHaveBeenCalledOnce()
-    const [calledChildId, calledInput] = hubLocalCaps.callCapOnChildSpy.mock.calls[0] as [string, unknown]
+    const [calledChildId, calledInput] = hubLocalCaps.callCapOnChildSpy.mock.calls[0] as [
+      string,
+      unknown,
+    ]
     expect(calledChildId).toBe('provider-reolink')
     expect(calledInput).toMatchObject({
       capName: 'ptz',
@@ -191,9 +205,7 @@ describe('Task5 – d9ba709 regression: singleton prefers hub-local over remote'
   it('singleton cap provided by both hub-local child AND remote node classifies to hub-local-uds (no nodeId given)', () => {
     // 'pipeline-executor' is on BOTH local child addon-detection-pipeline AND remote-agent-0
     const hubLocalCaps = makeDeviceAwareHubLocalRegistry(
-      new Map([
-        ['pipeline-executor', new Map([['singleton', 'addon-detection-pipeline']])],
-      ]),
+      new Map([['pipeline-executor', new Map([['singleton', 'addon-detection-pipeline']])]]),
     )
 
     const systemCaps = new Map([
@@ -307,7 +319,12 @@ describe('Task5 – remote native cap uses NATIVE_PROVIDER_SERVICE_INFIX in acti
 describe('Task5 – nodeKnowsCap includes native caps', () => {
   it('nodeKnowsCap returns true when the node has a native cap entry (even with no manifest cap)', () => {
     const nativeCaps: NativeCapSpec[] = [
-      { nodeId: 'hub/provider-reolink', addonId: 'addon-provider-reolink', capName: 'ptz', deviceId: 7 },
+      {
+        nodeId: 'hub/provider-reolink',
+        addonId: 'addon-provider-reolink',
+        capName: 'ptz',
+        deviceId: 7,
+      },
     ]
     const nodeAuthority = makeNativeAwareNodeAuthority(
       new Map(), // no system caps
@@ -338,14 +355,20 @@ describe('native-fallback – wrapper must not shadow the hub-local native child
   // snapshot has an in-hub wrapper AND a forked native child for device 7.
   const wrapperRef: InProcessProviderRef = { invoke: vi.fn(async () => ({ from: 'wrapper' })) }
 
-  function makeSnapshotResolver(): { resolver: CapRouteResolver; hubLocalCaps: FakeHubLocalRegistry } {
+  function makeSnapshotResolver(): {
+    resolver: CapRouteResolver
+    hubLocalCaps: FakeHubLocalRegistry
+  } {
     const hubLocalCaps = makeDeviceAwareHubLocalRegistry(
-      new Map([
-        ['snapshot', new Map([[7, 'provider-reolink']])],
-      ]),
+      new Map([['snapshot', new Map([[7, 'provider-reolink']])]]),
     )
     const nativeCaps: NativeCapSpec[] = [
-      { nodeId: 'hub/provider-reolink', addonId: 'addon-provider-reolink', capName: 'snapshot', deviceId: 7 },
+      {
+        nodeId: 'hub/provider-reolink',
+        addonId: 'addon-provider-reolink',
+        capName: 'snapshot',
+        deviceId: 7,
+      },
     ]
     const nodeAuthority = makeNativeAwareNodeAuthority(
       new Map(),

package/src/__tests__/oauth2-account-linking.spec.ts

@@ -17,7 +17,11 @@ import * as crypto from 'node:crypto'
 import { registerOauth2Routes } from '../api/oauth2/oauth2-routes.js'
 import { createOauthGrants } from '../../../../packages/core/src/builtins/local-auth/oauth-grants.js'
 import type { ISsoBridgeProvider } from '@camstack/types'
-import type { IOauthIntegrationProvider, IUserManagementProvider, TokenScope } from '@camstack/types'
+import type {
+  IOauthIntegrationProvider,
+  IUserManagementProvider,
+  TokenScope,
+} from '@camstack/types'
 import type { OauthSession } from '../../../../packages/core/src/builtins/local-auth/oauth-session-manager.js'
 import { SESSION_COOKIE } from '../auth/session-cookie.js'
 
@@ -59,7 +63,10 @@ function verifyHmacJwt(token: string): Record<string, unknown> | null {
   )
   if (sig !== expected) return null
   try {
-    const decoded = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as Record<string, unknown>
+    const decoded = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as Record<
+      string,
+      unknown
+    >
     if (typeof decoded['exp'] === 'number' && decoded['exp'] < Math.floor(Date.now() / 1000)) {
       return null
     }
@@ -92,7 +99,12 @@ function fakeSessionManager() {
 
   return {
     store,
-    async create(input: { userId: string; username: string; integrationId: string; scopes: TokenScope[] }): Promise<OauthSession> {
+    async create(input: {
+      userId: string
+      username: string
+      integrationId: string
+      scopes: TokenScope[]
+    }): Promise<OauthSession> {
       const now = Date.now()
       const session: OauthSession = {
         id: `session-${++seq}`,
@@ -139,7 +151,13 @@ const VALID_SESSION_TOKEN = 'valid-session-token-abc123'
 const ALEXA_DESCRIPTOR = {
   integrationId: 'export-alexa',
   displayName: 'Alexa Smart Home',
-  requestedScopes: [{ type: 'category' as const, target: 'device' as const, access: ['view', 'create'] as ('view' | 'create' | 'delete')[] }],
+  requestedScopes: [
+    {
+      type: 'category' as const,
+      target: 'device' as const,
+      access: ['view', 'create'] as ('view' | 'create' | 'delete')[],
+    },
+  ],
   allowedRedirectPrefixes: ['https://cb.example/'],
 }
 
@@ -204,7 +222,10 @@ function buildFakeRegistry(
 
 // ─── Test setup ───────────────────────────────────────────────────────────────
 
-function buildApp(grants: ReturnType<typeof createOauthGrants>, sessionManager: ReturnType<typeof fakeSessionManager>) {
+function buildApp(
+  grants: ReturnType<typeof createOauthGrants>,
+  sessionManager: ReturnType<typeof fakeSessionManager>,
+) {
   const fastify = Fastify({ logger: false })
   void fastify.register(cookie)
 
@@ -291,7 +312,11 @@ describe('OAuth2 account-linking flow', () => {
 
     expect(res.statusCode).toBe(302)
     const location = res.headers['location'] as string
-    expect(location).toMatch(new RegExp(`^${REDIRECT_URI.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\?code=.+&state=${STATE}`))
+    expect(location).toMatch(
+      new RegExp(
+        `^${REDIRECT_URI.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\?code=.+&state=${STATE}`,
+      ),
+    )
   })
 
   // ── Case 4 ──────────────────────────────────────────────────────────────────
@@ -336,7 +361,12 @@ describe('OAuth2 account-linking flow', () => {
     })
 
     expect(tokenRes.statusCode).toBe(200)
-    const json = tokenRes.json<{ access_token: string; refresh_token: string; expires_in: number; token_type: string }>()
+    const json = tokenRes.json<{
+      access_token: string
+      refresh_token: string
+      expires_in: number
+      token_type: string
+    }>()
     expect(json).toMatchObject({
       expires_in: 3600,
       token_type: 'Bearer',
@@ -550,7 +580,12 @@ describe('OAuth2 account-linking flow', () => {
     })
 
     expect(refreshRes.statusCode).toBe(200)
-    const refreshJson = refreshRes.json<{ access_token: string; refresh_token: string; expires_in: number; token_type: string }>()
+    const refreshJson = refreshRes.json<{
+      access_token: string
+      refresh_token: string
+      expires_in: number
+      token_type: string
+    }>()
     expect(refreshJson).toMatchObject({ expires_in: 3600, token_type: 'Bearer' })
     expect(typeof refreshJson.access_token).toBe('string')
     expect(refreshJson.access_token.length).toBeGreaterThan(0)
@@ -604,7 +639,11 @@ describe('OAuth2 account-linking flow', () => {
   describe('session registry lifecycle', () => {
     // Shared helper: run the full authorize → consent → exchange flow and
     // return the issued token pair plus the raw location URL.
-    async function doFullFlow(): Promise<{ accessToken: string; refreshToken: string; location: string }> {
+    async function doFullFlow(): Promise<{
+      accessToken: string
+      refreshToken: string
+      location: string
+    }> {
       const authorizeBody = new URLSearchParams({
         consent: 'allow',
         integration: 'export-alexa',
@@ -661,9 +700,7 @@ describe('OAuth2 account-linking flow', () => {
 
       // Scopes must contain the category/device entry declared in ALEXA_DESCRIPTOR.
       expect(Array.isArray(session.scopes)).toBe(true)
-      const deviceScope = session.scopes.find(
-        (s) => s.type === 'category' && s.target === 'device',
-      )
+      const deviceScope = session.scopes.find((s) => s.type === 'category' && s.target === 'device')
       expect(deviceScope).toBeDefined()
     })
 
@@ -692,7 +729,9 @@ describe('OAuth2 account-linking flow', () => {
       const sessionId = sessions[0]!.id
 
       // Revoke via the fake user-management method (same as the real addon does).
-      const revokeResult = await sessionManager.markRevoked(sessionId).then((ok) => ({ success: ok }))
+      const revokeResult = await sessionManager
+        .markRevoked(sessionId)
+        .then((ok) => ({ success: ok }))
       expect(revokeResult).toEqual({ success: true })
 
       // The session must now carry a non-null revokedAt.
@@ -729,7 +768,9 @@ describe('OAuth2 account-linking flow', () => {
 
     // ── Case e ────────────────────────────────────────────────────────────────
     it('e) revokeOauthSession with unknown id → {success: false}', async () => {
-      const result = await sessionManager.markRevoked('non-existent-session-id').then((ok) => ({ success: ok }))
+      const result = await sessionManager
+        .markRevoked('non-existent-session-id')
+        .then((ok) => ({ success: ok }))
       expect(result).toEqual({ success: false })
     })
   })
@@ -777,7 +818,8 @@ describe('integration-driven hubUrl claim (Phase A public-origin bridge)', () =>
     registerOauth2Routes(fastify, {
       getRegistry: () => reg as any,
       verifyToken: (token: string) => {
-        if (token === VALID_SESSION_TOKEN) return { userId: OPERATOR_USER_ID, username: OPERATOR_USERNAME }
+        if (token === VALID_SESSION_TOKEN)
+          return { userId: OPERATOR_USER_ID, username: OPERATOR_USERNAME }
         throw new Error('invalid token')
       },
       publicHubUrl: () => GLOBAL_FALLBACK,
@@ -785,7 +827,9 @@ describe('integration-driven hubUrl claim (Phase A public-origin bridge)', () =>
     return fastify
   }
 
-  async function issuedCodeHubUrl(app: ReturnType<typeof buildAppWithDescriptor>): Promise<unknown> {
+  async function issuedCodeHubUrl(
+    app: ReturnType<typeof buildAppWithDescriptor>,
+  ): Promise<unknown> {
     const body = new URLSearchParams({
       consent: 'allow',
       integration: 'export-alexa',
@@ -805,7 +849,9 @@ describe('integration-driven hubUrl claim (Phase A public-origin bridge)', () =>
     expect(res.statusCode).toBe(302)
     const loc = res.headers['location'] as string
     const code = decodeURIComponent(loc.match(/[?&]code=([^&]+)/)![1]!)
-    const payload = JSON.parse(Buffer.from(code.split('.')[1]!, 'base64url').toString('utf8')) as Record<string, unknown>
+    const payload = JSON.parse(
+      Buffer.from(code.split('.')[1]!, 'base64url').toString('utf8'),
+    ) as Record<string, unknown>
     return payload['hubUrl']
   }