@camstack/server 0.1.5 → 0.1.7

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

@@ -49,12 +49,17 @@ interface RegisterNodeDriver {
   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. */
+function createSingletonHarness(capNames: readonly string[]): Harness {
+  return createHarness(capNames, 'singleton')
+}
+
 /** A minimal real `CapabilityDefinition` so `getDefinition`/`expandCapMethods` resolve. */
-function makeCapDef(name: string): CapabilityDefinition {
+function makeCapDef(name: string, mode: 'collection' | 'singleton' = 'collection'): CapabilityDefinition {
   return {
     name,
     scope: 'system',
-    mode: 'collection',
+    mode,
     methods: {
       ping: {
         input: z.object({}),
@@ -93,10 +98,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[]): 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))
+    registry.declareCapability(makeCapDef(name, mode))
   }
   // Boot-complete state — `getAllProviders` returns [] until `ready()`.
   registry.ready()
@@ -227,3 +232,33 @@ describe('MoleculerService.applyNodeManifest — re-handshake idempotency', () =
     expect(harness.driver.createCapabilityProxy('cap-alpha', 'hub/reolink')).not.toBeNull()
   })
 })
+
+describe('MoleculerService.applyNodeManifest — singleton local-first preference (UDS regression)', () => {
+  // A `placement: 'any-node'` singleton (e.g. `pipeline-executor`) can register
+  // on BOTH the hub-local forked child AND a remote agent. The hub must resolve
+  // its OWN local provider (reachable over UDS) — never the agent's proxy, whose
+  // callFn routes over Moleculer to a UDS-only agent runner that no longer hosts
+  // the service ("not found on <agent>"). First-registered-wins picked the agent.
+  const LOCAL = 'hub/detection-pipeline'
+  const REMOTE = 'dev-agent-0/detection-pipeline'
+  const singleton: (nodeId: string) => RegisterNodeParams = (nodeId) => ({
+    nodeId,
+    addons: [{ addonId: 'detection-pipeline', capabilities: ['pipeline-executor'] }],
+  })
+
+  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
+    // 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('@')
+  })
+
+  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
+    expect(registry.getSingletonAddonId('pipeline-executor')).toBe('detection-pipeline')
+  })
+})

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

@@ -0,0 +1,404 @@
+/**
+ * Task 5 — TDD tests: device-scoped native cap routing through CapRouteResolver.
+ *
+ * Covers:
+ *  1. A device-scoped native cap on a HUB-LOCAL child resolves to hub-local-uds
+ *     and dispatches via callCapOnChild with {capName, method, args:{...deviceId}, deviceId}.
+ *  2. d9ba709 regression guard: a singleton cap on BOTH a hub-local child AND a remote
+ *     node, resolved WITHOUT explicit nodeId, classifies to hub-local (not remote).
+ *  3. A remote device-scoped native cap builds the ${addonId}.native-provider.${cap}.${method}
+ *     action (NATIVE_PROVIDER_SERVICE_INFIX).
+ *  4. nodeKnowsCap returns true for native caps (not just manifest caps).
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { CapRouteResolver, NATIVE_PROVIDER_SERVICE_INFIX } from '@camstack/kernel'
+import type {
+  NodeCapAuthority,
+  HubLocalChildDispatcher,
+  CapRouteResolverDeps,
+  InProcessProviderRef,
+} from '@camstack/kernel'
+import { CapRouteError } from '@camstack/kernel'
+
+const HUB_NODE_ID = 'hub'
+
+// ---------------------------------------------------------------------------
+// Fake HubLocalChildDispatcher with deviceId-aware resolveChildId
+// ---------------------------------------------------------------------------
+
+interface FakeHubLocalRegistry extends HubLocalChildDispatcher {
+  readonly callCapOnChildSpy: ReturnType<typeof vi.fn>
+}
+
+/**
+ * Build a fake registry that supports device-scoped cap resolution.
+ * The caps map is {capName → {deviceId? → childId}} or {capName → childId} for singletons.
+ */
+function makeDeviceAwareHubLocalRegistry(
+  caps: ReadonlyMap<string, ReadonlyMap<number | 'singleton', string>>,
+): FakeHubLocalRegistry {
+  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)
+      if (capMap === undefined) return null
+      if (deviceId !== undefined) {
+        const deviceSpecific = capMap.get(deviceId)
+        if (deviceSpecific !== undefined) return deviceSpecific
+      }
+      return capMap.get('singleton') ?? null
+    },
+    callCapOnChild: callCapOnChildSpy,
+    callCapOnChildSpy,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Fake NodeCapAuthority with native-cap awareness
+// ---------------------------------------------------------------------------
+
+interface NativeCapSpec {
+  readonly nodeId: string
+  readonly addonId: string
+  readonly capName: string
+  readonly deviceId: number
+}
+
+function makeNativeAwareNodeAuthority(
+  systemCaps: ReadonlyMap<string, { addonId: string; nodeId: string }>,
+  onlineNodes: ReadonlySet<string>,
+  nativeCaps: readonly NativeCapSpec[],
+): NodeCapAuthority {
+  return {
+    nodeKnowsCap: (nodeId: string, capName: string): boolean => {
+      // Check system (manifest) caps
+      const sys = systemCaps.get(capName)
+      if (sys !== undefined && sys.nodeId === nodeId) return true
+      // Check native caps (any deviceId for this node+capName)
+      return nativeCaps.some((n) => n.nodeId === nodeId && n.capName === capName)
+    },
+
+    nodeIsAgent: (nodeId: string): boolean =>
+      nodeId !== HUB_NODE_ID && !nodeId.includes('/'),
+
+    nodeOnline: (nodeId: string): boolean => onlineNodes.has(nodeId),
+
+    listNodeIds: (): readonly string[] => {
+      const ids = new Set<string>()
+      for (const spec of systemCaps.values()) ids.add(spec.nodeId)
+      for (const n of nativeCaps) ids.add(n.nodeId)
+      return [...ids]
+    },
+
+    getAddonId: (nodeId: string, capName: string): string | null => {
+      // Check system (manifest) caps
+      const sys = systemCaps.get(capName)
+      if (sys !== undefined && sys.nodeId === nodeId) return sys.addonId
+      // Check native caps
+      const nat = nativeCaps.find((n) => n.nodeId === nodeId && n.capName === capName)
+      return nat?.addonId ?? null
+    },
+
+    getAgentChildId: (_agentNodeId: string, _capName: string): string | null => null,
+
+    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)
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: device-scoped native cap on hub-local child → hub-local-uds dispatch
+// ---------------------------------------------------------------------------
+
+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']])],
+      ]),
+    )
+
+    const nativeCaps: NativeCapSpec[] = [
+      { nodeId: 'hub/provider-reolink', addonId: 'addon-provider-reolink', capName: 'ptz', deviceId: 7 },
+    ]
+    const nodeAuthority = makeNativeAwareNodeAuthority(new Map(), new Set(['hub/provider-reolink']), nativeCaps)
+
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker: { call: vi.fn(), waitForServices: vi.fn() },
+      hubLocalRegistry: hubLocalCaps,
+      nodeAuthority,
+      inProcessProviders: () => null,
+    }
+
+    const resolver = new CapRouteResolver(deps)
+
+    // Resolve with deviceId = 7 so the snapshot uses the device-aware accessor
+    const route = resolver.resolveCapRoute('ptz', { nodeId: HUB_NODE_ID, deviceId: 7 })
+    expect(route.kind).toBe('hub-local-uds')
+    if (route.kind !== 'hub-local-uds') return
+    expect(route.childId).toBe('provider-reolink')
+
+    const result = await resolver.dispatch(route, 'move', { pan: 10, deviceId: 7 })
+    expect(result).toEqual({ ok: true, from: 'uds' })
+
+    expect(hubLocalCaps.callCapOnChildSpy).toHaveBeenCalledOnce()
+    const [calledChildId, calledInput] = hubLocalCaps.callCapOnChildSpy.mock.calls[0] as [string, unknown]
+    expect(calledChildId).toBe('provider-reolink')
+    expect(calledInput).toMatchObject({
+      capName: 'ptz',
+      method: 'move',
+      args: { pan: 10, deviceId: 7 },
+      deviceId: 7,
+    })
+  })
+
+  it('resolving ptz WITHOUT deviceId does NOT match the device-scoped child (no spurious route)', () => {
+    // When no deviceId hint is given, the singleton fallback fires — no deviceId-less descriptor exists
+    const hubLocalCaps = makeDeviceAwareHubLocalRegistry(
+      new Map([
+        ['ptz', new Map([[7, 'provider-reolink']])],
+        // No 'singleton' entry for ptz — ptz is strictly device-scoped
+      ]),
+    )
+    const nodeAuthority = makeNativeAwareNodeAuthority(new Map(), new Set(), [])
+
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker: { call: vi.fn(), waitForServices: vi.fn() },
+      hubLocalRegistry: hubLocalCaps,
+      nodeAuthority,
+      inProcessProviders: () => null,
+    }
+
+    const resolver = new CapRouteResolver(deps)
+    // Without deviceId, no hub-local-uds route → CapRouteError
+    expect(() => resolver.resolveCapRoute('ptz', { nodeId: HUB_NODE_ID })).toThrow(CapRouteError)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Test 2: d9ba709 regression guard — hub-local singleton beats remote
+// ---------------------------------------------------------------------------
+
+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']])],
+      ]),
+    )
+
+    const systemCaps = new Map([
+      ['pipeline-executor', { addonId: 'addon-detection-pipeline', nodeId: 'remote-agent-0' }],
+    ])
+    const nodeAuthority = makeNativeAwareNodeAuthority(
+      systemCaps,
+      new Set(['hub/addon-detection-pipeline', 'remote-agent-0']),
+      [],
+    )
+
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker: { call: vi.fn(), waitForServices: vi.fn() },
+      hubLocalRegistry: hubLocalCaps,
+      nodeAuthority,
+      inProcessProviders: () => null,
+    }
+
+    const resolver = new CapRouteResolver(deps)
+    // Singleton resolution (no nodeId) — must prefer hub-local-uds
+    const route = resolver.resolveCapRoute('pipeline-executor', {})
+    expect(route.kind).toBe('hub-local-uds')
+    if (route.kind === 'hub-local-uds') {
+      expect(route.childId).toBe('addon-detection-pipeline')
+    }
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Test 3: remote device-scoped native cap uses NATIVE_PROVIDER_SERVICE_INFIX
+// (Remote-moleculer path: non-agent remote node hosting a native device cap,
+//  e.g. a secondary hub or a directly-wired remote runner)
+// ---------------------------------------------------------------------------
+
+describe('Task5 – remote native cap uses NATIVE_PROVIDER_SERVICE_INFIX in action name', () => {
+  it('dispatches remote native cap (on non-agent remote node) with action ${addonId}.native-provider.${cap}.${method}', async () => {
+    const callSpy = vi.fn(async () => ({ ok: true }))
+    const broker = { call: callSpy, waitForServices: vi.fn(async () => {}) }
+
+    // ptz is provided by a REMOTE non-agent node (contains '/' so nodeIsAgent=false)
+    const remoteNodeId = 'hub-secondary/provider-reolink'
+    const nativeCaps: NativeCapSpec[] = [
+      { nodeId: remoteNodeId, addonId: 'addon-provider-reolink', capName: 'ptz', deviceId: 7 },
+    ]
+    const nodeAuthority = makeNativeAwareNodeAuthority(
+      new Map(),
+      new Set([remoteNodeId]),
+      nativeCaps,
+    )
+
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker,
+      hubLocalRegistry: null,
+      nodeAuthority,
+      inProcessProviders: () => null,
+    }
+
+    const resolver = new CapRouteResolver(deps)
+    const route = resolver.resolveCapRoute('ptz', { nodeId: remoteNodeId, deviceId: 7 })
+    expect(route.kind).toBe('remote-moleculer')
+
+    await resolver.dispatch(route, 'move', { pan: 10, deviceId: 7 })
+
+    expect(callSpy).toHaveBeenCalledOnce()
+    const [action, , opts] = callSpy.mock.calls[0] as [string, unknown, { nodeID?: string }]
+    expect(action).toBe(`addon-provider-reolink${NATIVE_PROVIDER_SERVICE_INFIX}.ptz.move`)
+    expect((opts as { nodeID?: string }).nodeID).toBe(remoteNodeId)
+  })
+
+  it('non-native remote cap still uses plain ${addonId}.${cap}.${method} action', async () => {
+    const callSpy = vi.fn(async () => ({ ok: true }))
+    const broker = { call: callSpy, waitForServices: vi.fn(async () => {}) }
+
+    const remoteNodeId = 'hub-secondary/addon-analytics-suite'
+    const systemCaps = new Map([
+      ['analytics', { addonId: 'addon-analytics-suite', nodeId: remoteNodeId }],
+    ])
+    const nodeAuthority = makeNativeAwareNodeAuthority(
+      systemCaps,
+      new Set([remoteNodeId]),
+      [], // no native caps
+    )
+
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker,
+      hubLocalRegistry: null,
+      nodeAuthority,
+      inProcessProviders: () => null,
+    }
+
+    const resolver = new CapRouteResolver(deps)
+    const route = resolver.resolveCapRoute('analytics', { nodeId: remoteNodeId })
+    expect(route.kind).toBe('remote-moleculer')
+
+    await resolver.dispatch(route, 'getReport', { period: 'day' })
+
+    const [action] = callSpy.mock.calls[0] as [string]
+    expect(action).toBe('addon-analytics-suite.analytics.getReport')
+    // Must NOT have the native infix
+    expect(action).not.toContain(NATIVE_PROVIDER_SERVICE_INFIX)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Test 4: nodeKnowsCap returns true for native caps (not just manifest)
+// ---------------------------------------------------------------------------
+
+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 },
+    ]
+    const nodeAuthority = makeNativeAwareNodeAuthority(
+      new Map(), // no system caps
+      new Set(['hub/provider-reolink']),
+      nativeCaps,
+    )
+
+    expect(nodeAuthority.nodeKnowsCap('hub/provider-reolink', 'ptz')).toBe(true)
+    expect(nodeAuthority.nodeKnowsCap('hub/provider-reolink', 'stream-broker')).toBe(false)
+    expect(nodeAuthority.nodeKnowsCap('other-node', 'ptz')).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Test 5: native-fallback regression — an in-hub WRAPPER must not shadow the
+// hub-local-uds NATIVE child for the same cap name.
+//
+// Reproduces the snapshot bug: the `snapshot` cap has an in-hub wrapper
+// (SnapshotAddon, registered as a system singleton, so inProcessProviders
+// returns a ref) AND a per-device native provider in a forked vendor child
+// (provider-reolink). `resolveCapRoute` gives Priority 1 to hub-in-process,
+// so it returns the WRAPPER route — never reaching the hub-local-uds native.
+// The setNativeFallback resolver wants the NATIVE child specifically; it must
+// use `resolveHubLocalUdsRoute`, which skips the in-process branch.
+// ---------------------------------------------------------------------------
+
+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 } {
+    const hubLocalCaps = makeDeviceAwareHubLocalRegistry(
+      new Map([
+        ['snapshot', new Map([[7, 'provider-reolink']])],
+      ]),
+    )
+    const nativeCaps: NativeCapSpec[] = [
+      { nodeId: 'hub/provider-reolink', addonId: 'addon-provider-reolink', capName: 'snapshot', deviceId: 7 },
+    ]
+    const nodeAuthority = makeNativeAwareNodeAuthority(
+      new Map(),
+      new Set(['hub/provider-reolink']),
+      nativeCaps,
+    )
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker: { call: vi.fn(), waitForServices: vi.fn() },
+      hubLocalRegistry: hubLocalCaps,
+      nodeAuthority,
+      // The wrapper occupies the in-hub slot for 'snapshot'.
+      inProcessProviders: (cap: string): InProcessProviderRef | null =>
+        cap === 'snapshot' ? wrapperRef : null,
+    }
+    return { resolver: new CapRouteResolver(deps), hubLocalCaps }
+  }
+
+  it('documents the shadow: resolveCapRoute picks the in-hub wrapper (hub-in-process)', () => {
+    const { resolver } = makeSnapshotResolver()
+    const route = resolver.resolveCapRoute('snapshot', { nodeId: HUB_NODE_ID, deviceId: 7 })
+    // The wrapper shadows the native — this is the existing (correct for the
+    // generic dispatch path) behaviour the native fallback must NOT rely on.
+    expect(route.kind).toBe('hub-in-process')
+  })
+
+  it('resolveHubLocalUdsRoute returns the native child route, bypassing the wrapper shadow', () => {
+    const { resolver } = makeSnapshotResolver()
+    const route = resolver.resolveHubLocalUdsRoute('snapshot', 7)
+    expect(route).not.toBeNull()
+    expect(route?.kind).toBe('hub-local-uds')
+    expect(route?.childId).toBe('provider-reolink')
+  })
+
+  it('resolveHubLocalUdsRoute returns null when no hub-local child owns the cap (lets fallback try remote)', () => {
+    const { resolver } = makeSnapshotResolver()
+    // device 999 has no hub-local native child
+    expect(resolver.resolveHubLocalUdsRoute('snapshot', 999)).toBeNull()
+    // a cap with neither wrapper nor hub-local child
+    expect(resolver.resolveHubLocalUdsRoute('nonexistent', 7)).toBeNull()
+  })
+
+  it('dispatching the resolved hub-local-uds route reaches the native child (not the wrapper)', async () => {
+    const { resolver, hubLocalCaps } = makeSnapshotResolver()
+    const route = resolver.resolveHubLocalUdsRoute('snapshot', 7)
+    expect(route).not.toBeNull()
+    if (route === null) return
+    const result = await resolver.dispatch(route, 'getSnapshot', { deviceId: 7 })
+    expect(result).toEqual({ ok: true, from: 'uds' })
+    expect(hubLocalCaps.callCapOnChildSpy).toHaveBeenCalledOnce()
+    const [childId] = hubLocalCaps.callCapOnChildSpy.mock.calls[0] as [string]
+    expect(childId).toBe('provider-reolink')
+    // The wrapper's invoke must NOT have been called.
+    expect(wrapperRef.invoke).not.toHaveBeenCalled()
+  })
+})

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

@@ -734,3 +734,88 @@ describe('OAuth2 account-linking flow', () => {
     })
   })
 })
+
+// ─── Phase A: integration-driven hubUrl claim ───────────────────────────────
+//
+// The OAuth code/token JWT carries a `hubUrl` claim the cloud Lambda routes
+// back on. A forked exporter addon (which can't set the hub's env) declares its
+// operator-selected external-access endpoint on the oauth-integration
+// descriptor; the authorize route must prefer it over the hub-global
+// publicHubUrl() (which is localhost in dev — the cause of "linking fails after
+// consent").
+
+describe('integration-driven hubUrl claim (Phase A public-origin bridge)', () => {
+  const GLOBAL_FALLBACK = 'https://hub-global.example'
+
+  function buildAppWithDescriptor(descriptorHubUrl?: string) {
+    const sm = fakeSessionManager()
+    const g = createOauthGrants(realSsoBridge, sm as any)
+    const fastify = Fastify({ logger: false })
+    void fastify.register(cookie)
+
+    const descriptor = descriptorHubUrl
+      ? { ...ALEXA_DESCRIPTOR, hubUrl: descriptorHubUrl }
+      : { ...ALEXA_DESCRIPTOR }
+    const alexaProvider: IOauthIntegrationProvider = { getDescriptor: async () => descriptor }
+
+    const userMgmt: IUserManagementProvider = {
+      ...({} as IUserManagementProvider),
+      oauthIssueCode: g.oauthIssueCode.bind(g),
+      oauthExchangeCode: g.oauthExchangeCode.bind(g),
+      oauthRefresh: g.oauthRefresh.bind(g),
+      oauthVerifyAccessToken: g.oauthVerifyAccessToken.bind(g),
+      listOauthSessions: async () => [],
+      revokeOauthSession: async () => ({ success: true }),
+    }
+
+    const reg = {
+      getCollectionEntries: (cap: string) =>
+        cap === 'oauth-integration' ? [['export-alexa-addon', alexaProvider]] : [],
+      getSingleton: (cap: string) => (cap === 'user-management' ? userMgmt : null),
+    }
+
+    registerOauth2Routes(fastify, {
+      getRegistry: () => reg as any,
+      verifyToken: (token: string) => {
+        if (token === VALID_SESSION_TOKEN) return { userId: OPERATOR_USER_ID, username: OPERATOR_USERNAME }
+        throw new Error('invalid token')
+      },
+      publicHubUrl: () => GLOBAL_FALLBACK,
+    })
+    return fastify
+  }
+
+  async function issuedCodeHubUrl(app: ReturnType<typeof buildAppWithDescriptor>): Promise<unknown> {
+    const body = new URLSearchParams({
+      consent: 'allow',
+      integration: 'export-alexa',
+      redirect_uri: REDIRECT_URI,
+      state: STATE,
+      response_type: 'code',
+    }).toString()
+    const res = await app.inject({
+      method: 'POST',
+      url: '/api/oauth2/authorize',
+      headers: {
+        'content-type': 'application/x-www-form-urlencoded',
+        cookie: `${SESSION_COOKIE}=${VALID_SESSION_TOKEN}`,
+      },
+      body,
+    })
+    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>
+    return payload['hubUrl']
+  }
+
+  it('bakes the integration descriptor hubUrl into the issued code', async () => {
+    const app = buildAppWithDescriptor('https://tunnel.example.test')
+    expect(await issuedCodeHubUrl(app)).toBe('https://tunnel.example.test')
+  })
+
+  it('falls back to publicHubUrl() when the descriptor has no hubUrl', async () => {
+    const app = buildAppWithDescriptor()
+    expect(await issuedCodeHubUrl(app)).toBe(GLOBAL_FALLBACK)
+  })
+})