@camstack/server 1.0.0 → 1.0.1

package/dist/api/core/settings-backend.router.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSettingsBackendRouter = createSettingsBackendRouter;
+/**
+ * Settings backend router — tRPC proxy for ISettingsBackend operations.
+ *
+ * Exposes the core collection-based operations (get, set, query, insert,
+ * update, delete, count, isEmpty) so forked worker addons can use
+ * context.settingsBackend via tRPC instead of requiring in-process access
+ * to the SQLite database.
+ *
+ * Introduced for Task 11 — TrpcSettingsBackend for forked workers.
+ */
+const zod_1 = require("zod");
+const trpc_middleware_js_1 = require("../trpc/trpc.middleware.js");
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+const CollectionKeySchema = zod_1.z.object({
+    collection: zod_1.z.string(),
+    key: zod_1.z.string(),
+});
+const SetValueSchema = zod_1.z.object({
+    collection: zod_1.z.string(),
+    key: zod_1.z.string(),
+    value: zod_1.z.unknown(),
+});
+const QueryFilterSchema = zod_1.z
+    .object({
+    where: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
+    whereIn: zod_1.z.record(zod_1.z.string(), zod_1.z.array(zod_1.z.unknown())).optional(),
+    whereBetween: zod_1.z.record(zod_1.z.string(), zod_1.z.tuple([zod_1.z.unknown(), zod_1.z.unknown()])).optional(),
+    orderBy: zod_1.z
+        .object({
+        field: zod_1.z.string(),
+        direction: zod_1.z.enum(['asc', 'desc']),
+    })
+        .optional(),
+    limit: zod_1.z.number().optional(),
+    offset: zod_1.z.number().optional(),
+})
+    .optional();
+const QueryInputSchema = zod_1.z.object({
+    collection: zod_1.z.string(),
+    filter: QueryFilterSchema,
+});
+const InsertInputSchema = zod_1.z.object({
+    collection: zod_1.z.string(),
+    record: zod_1.z.object({
+        id: zod_1.z.string(),
+        data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+    }),
+});
+const UpdateInputSchema = zod_1.z.object({
+    collection: zod_1.z.string(),
+    id: zod_1.z.string(),
+    data: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()),
+});
+const CountInputSchema = zod_1.z.object({
+    collection: zod_1.z.string(),
+    filter: QueryFilterSchema,
+});
+const IsEmptyInputSchema = zod_1.z.object({
+    collection: zod_1.z.string(),
+});
+// ---------------------------------------------------------------------------
+// Router factory
+// ---------------------------------------------------------------------------
+function createSettingsBackendRouter(getBackend) {
+    const requireBackend = () => {
+        const backend = getBackend();
+        if (!backend) {
+            throw new Error('Settings backend not available — settings-store addon may not be initialized yet');
+        }
+        return backend;
+    };
+    return (0, trpc_middleware_js_1.trpcRouter)({
+        get: trpc_middleware_js_1.protectedProcedure.input(CollectionKeySchema).query(async ({ input }) => {
+            const result = await requireBackend().get(input);
+            return { value: result };
+        }),
+        set: trpc_middleware_js_1.protectedProcedure.input(SetValueSchema).mutation(async ({ input }) => {
+            await requireBackend().set({
+                collection: input.collection,
+                key: input.key,
+                value: input.value,
+            });
+            return { success: true };
+        }),
+        query: trpc_middleware_js_1.protectedProcedure.input(QueryInputSchema).query(async ({ input }) => {
+            const records = await requireBackend().query({
+                collection: input.collection,
+                filter: input.filter ?? undefined,
+            });
+            return { records: records.map((r) => ({ id: r.id, data: r.data })) };
+        }),
+        insert: trpc_middleware_js_1.protectedProcedure.input(InsertInputSchema).mutation(async ({ input }) => {
+            await requireBackend().insert(input);
+            return { success: true };
+        }),
+        update: trpc_middleware_js_1.protectedProcedure.input(UpdateInputSchema).mutation(async ({ input }) => {
+            await requireBackend().update(input);
+            return { success: true };
+        }),
+        delete: trpc_middleware_js_1.protectedProcedure.input(CollectionKeySchema).mutation(async ({ input }) => {
+            await requireBackend().delete(input);
+            return { success: true };
+        }),
+        count: trpc_middleware_js_1.protectedProcedure.input(CountInputSchema).query(async ({ input }) => {
+            const result = await requireBackend().count({
+                collection: input.collection,
+                filter: input.filter ?? undefined,
+            });
+            return { count: result };
+        }),
+        isEmpty: trpc_middleware_js_1.protectedProcedure.input(IsEmptyInputSchema).query(async ({ input }) => {
+            const result = await requireBackend().isEmpty(input);
+            return { empty: result };
+        }),
+    });
+}

package/dist/api/core/stream-probe.router.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStreamProbeRouter = createStreamProbeRouter;
+/**
+ * Stream probe router — fixed core API (not a capability).
+ *
+ * Thin wrapper over `StreamProbeService` (backend REAL_LOGIC: ffprobe +
+ * HTTP probes + 1h cache). Not pluggable: there is exactly one stream
+ * probe implementation shipping with the server.
+ *
+ * Previously these endpoints lived under `streaming.probeStream` — moved
+ * here as part of eliminating the `streaming` aggregator capability.
+ */
+const zod_1 = require("zod");
+const types_1 = require("@camstack/types");
+const trpc_middleware_js_1 = require("../trpc/trpc.middleware.js");
+const ProbedStreamSchema = zod_1.z.object({
+    width: zod_1.z.number().optional(),
+    height: zod_1.z.number().optional(),
+    codec: zod_1.z.string().optional(),
+    fps: zod_1.z.number().optional(),
+    bitrateKbps: zod_1.z.number().optional(),
+    quality: zod_1.z.enum(['high', 'mid', 'low']),
+});
+const FieldProbeResultSchema = zod_1.z.object({
+    status: zod_1.z.enum(['ok', 'error']),
+    labels: zod_1.z.array(zod_1.z.string()).optional(),
+    error: zod_1.z.string().optional(),
+});
+function createStreamProbeRouter(sp) {
+    return (0, trpc_middleware_js_1.trpcRouter)({
+        probe: trpc_middleware_js_1.adminProcedure
+            .input(zod_1.z.object({ url: zod_1.z.string(), force: zod_1.z.boolean().optional() }))
+            .output(ProbedStreamSchema)
+            .mutation(async ({ input }) => {
+            if (!sp)
+                throw new Error('StreamProbeService not available');
+            const metadata = await sp.probe(input.url, { force: input.force });
+            return { ...metadata, quality: (0, types_1.classifyStream)(metadata) };
+        }),
+        /**
+         * Generic field probe — decides stream vs HTTP reachability based on
+         * the field key (keys starting with `stream` trigger ffprobe;
+         * everything else falls back to an HTTP GET that aborts at headers).
+         * Wraps `StreamProbeService.probeField` — used by device providers
+         * that need the kernel's probe without re-implementing ffprobe /
+         * HTTP fetch in every addon.
+         */
+        probeField: trpc_middleware_js_1.adminProcedure
+            .input(zod_1.z.object({ key: zod_1.z.string(), value: zod_1.z.unknown() }))
+            .output(FieldProbeResultSchema)
+            .mutation(async ({ input }) => {
+            if (!sp)
+                throw new Error('StreamProbeService not available');
+            return sp.probeField(input.key, input.value);
+        }),
+    });
+}

package/dist/api/core/system-events.router.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSystemEventsRouter = createSystemEventsRouter;
+/**
+ * System events router — fixed core API (not a capability).
+ *
+ * Exposes recent-events query and live subscribe over the `EventBusService`.
+ * Supports hierarchical filtering via EventFilter: agentId → addonId → deviceId.
+ * All filters are applied server-side by the SystemEventBus — the client
+ * only receives matching events.
+ */
+const zod_1 = require("zod");
+const trpc_middleware_js_1 = require("../trpc/trpc.middleware.js");
+function serialize(e) {
+    return {
+        id: e.id,
+        timestamp: new Date(e.timestamp).toISOString(),
+        source: {
+            type: e.source.type,
+            id: e.source.id,
+            ...(e.source.nodeId ? { nodeId: e.source.nodeId } : {}),
+            ...(e.source.addonId ? { addonId: e.source.addonId } : {}),
+            ...(e.source.deviceId !== undefined ? { deviceId: e.source.deviceId } : {}),
+        },
+        category: e.category,
+        data: e.data,
+    };
+}
+/**
+ * Source / agent / addon / device fields shared by query + subscribe.
+ * Category handling is split (asymmetric): see the per-method schemas
+ * below.
+ */
+const ScopeFieldsSchema = zod_1.z.object({
+    /** Legacy source filter (exact type+id match). */
+    source: zod_1.z
+        .object({
+        type: zod_1.z.string(),
+        id: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]),
+    })
+        .optional(),
+    /** Agent/node filter (prefix match: 'hub' matches 'hub/pipeline'). */
+    agentId: zod_1.z.string().optional(),
+    /** Addon filter. Matches source.addonId or source.id when type='addon'. */
+    addonId: zod_1.z.string().optional(),
+    /** Device filter. Matches source.deviceId or source.id when type='device'. */
+    deviceId: zod_1.z.number().optional(),
+});
+/**
+ * `getRecent` accepts a category array so the UI can drive a
+ * server-side whitelist when reading the historical buffer. Without
+ * this, getRecent returns the last `limit` events of any category and
+ * a noisy category (per-frame metrics) can displace relevant events
+ * (provider.motion, detection.result) out of the window — which was
+ * the symptom of "no events visible after page refresh".
+ *
+ * The underlying ring-buffer filter
+ * (`addon-context-factory.ts:getRecent`) already iterates the
+ * `category` field as `string | string[]`.
+ */
+const GetRecentInputSchema = ScopeFieldsSchema.extend({
+    category: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).optional(),
+    limit: zod_1.z.number().int().min(1).max(500).optional(),
+});
+/**
+ * `subscribe` keeps category as a single string. The bus's
+ * `extractCategoryPattern` keys handlers by a single pattern; passing
+ * an array would silently route only the first category. UIs that
+ * need multi-category live filtering must subscribe by deviceId
+ * (single-category-per-call or wildcard) and narrow client-side.
+ */
+const SubscribeInputSchema = ScopeFieldsSchema.extend({
+    category: zod_1.z.string().optional(),
+});
+function createSystemEventsRouter(eb) {
+    return (0, trpc_middleware_js_1.trpcRouter)({
+        getRecent: trpc_middleware_js_1.protectedProcedure.input(GetRecentInputSchema).query(({ input }) => {
+            return eb
+                .getRecent({
+                ...(input.source ? { source: input.source } : {}),
+                ...(input.agentId ? { agentId: input.agentId } : {}),
+                ...(input.addonId ? { addonId: input.addonId } : {}),
+                ...(input.deviceId !== undefined ? { deviceId: input.deviceId } : {}),
+                ...(input.category ? { category: input.category } : {}),
+            }, input.limit)
+                .map(serialize);
+        }),
+        subscribe: trpc_middleware_js_1.protectedProcedure.input(SubscribeInputSchema).subscription(({ input }) => {
+            return (0, trpc_middleware_js_1.iterableSubscription)((push) => {
+                return eb.subscribe({
+                    ...(input.source ? { source: input.source } : {}),
+                    ...(input.agentId ? { agentId: input.agentId } : {}),
+                    ...(input.addonId ? { addonId: input.addonId } : {}),
+                    ...(input.deviceId !== undefined ? { deviceId: input.deviceId } : {}),
+                    ...(input.category ? { category: input.category } : {}),
+                }, (event) => push(serialize(event)));
+            });
+        }),
+    });
+}

package/dist/api/health/health.routes.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerHealthRoutes = registerHealthRoutes;
+const AGENT_HEALTH_TIMEOUT_MS = 3_000;
+function nowIso() {
+    return new Date().toISOString();
+}
+async function buildHubHealth(deps, proc = process) {
+    const nodes = await deps.agentRegistry.listNodes();
+    const remote = nodes.filter((n) => !n.isHub);
+    const online = remote.filter((n) => n.isOnline !== false).length;
+    const total = remote.length;
+    const memUsage = proc.memoryUsage();
+    const totalMem = memUsage.heapTotal + memUsage.external + memUsage.arrayBuffers;
+    const memoryPercent = totalMem > 0 ? Math.round((memUsage.heapUsed / totalMem) * 100) : 0;
+    return {
+        ok: true,
+        nodeId: 'hub',
+        version: deps.hubVersion,
+        uptimeSeconds: Math.round(proc.uptime()),
+        pid: proc.pid,
+        agents: { total, online, offline: total - online },
+        cpuPercent: 0,
+        memoryPercent,
+        checkedAt: nowIso(),
+    };
+}
+async function fetchAgentHealth(deps, nodeId) {
+    try {
+        const result = (await deps.moleculer.broker.call('$agent.health', {}, { nodeID: nodeId, timeout: AGENT_HEALTH_TIMEOUT_MS }));
+        return result;
+    }
+    catch (err) {
+        return {
+            ok: false,
+            nodeId,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function registerHealthRoutes(fastify, deps) {
+    fastify.get('/health', async () => buildHubHealth(deps));
+    fastify.get('/health/agents', async () => {
+        const nodes = await deps.agentRegistry.listNodes();
+        return {
+            agents: nodes.filter((n) => !n.isHub && n.isOnline !== false).map((n) => n.info.id),
+        };
+    });
+    fastify.get('/health/agents/:nodeId', async (req, reply) => {
+        const { nodeId } = req.params;
+        if (!nodeId) {
+            return reply.status(400).send({ ok: false, error: 'nodeId required' });
+        }
+        const result = await fetchAgentHealth(deps, nodeId);
+        if (!result.ok) {
+            return reply.status(503).send(result);
+        }
+        return result;
+    });
+    fastify.get('/health/cluster', async () => {
+        const hub = await buildHubHealth(deps);
+        const nodes = await deps.agentRegistry.listNodes();
+        const remote = nodes.filter((n) => !n.isHub && n.isOnline !== false);
+        const agents = await Promise.all(remote.map((n) => fetchAgentHealth(deps, n.info.id)));
+        const ok = hub.ok && agents.every((a) => a.ok);
+        return { ok, hub, agents, checkedAt: nowIso() };
+    });
+}

package/{src/api/oauth2/consent-page.ts → dist/api/oauth2/consent-page.js}

@@ -1,25 +1,16 @@
-function escapeHtml(s: string): string {
-  return s.replace(
-    /[&<>"']/g,
-    (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]!,
-  )
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderConsentPage = renderConsentPage;
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
 }
-
-interface ConsentPageInput {
-  displayName: string
-  username: string
-  scopeSummary: string
-  /** Hidden form fields replayed on POST. */
-  hidden: Record<string, string>
-}
-
 /** Allow/Deny consent screen. Submitting POSTs to the same path with the
  *  hidden query fields + `consent=allow|deny`. */
-export function renderConsentPage(input: ConsentPageInput): string {
-  const hidden = Object.entries(input.hidden)
-    .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`)
-    .join('\n      ')
-  return `<!doctype html>
+function renderConsentPage(input) {
+    const hidden = Object.entries(input.hidden)
+        .map(([k, v]) => `<input type="hidden" name="${escapeHtml(k)}" value="${escapeHtml(v)}">`)
+        .join('\n      ');
+    return `<!doctype html>
 <html lang="en"><head><meta charset="utf-8">
 <title>CamStack · Authorize ${escapeHtml(input.displayName)}</title>
 <style>
@@ -39,5 +30,5 @@ export function renderConsentPage(input: ConsentPageInput): string {
       <button class="deny" name="consent" value="deny" type="submit">Deny</button>
     </form>
   </div>
-</body></html>`
+</body></html>`;
 }

package/dist/api/oauth2/oauth2-routes.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAuthorizeQuery = validateAuthorizeQuery;
+exports.isRedirectUriAllowed = isRedirectUriAllowed;
+exports.summariseScopes = summariseScopes;
+exports.registerOauth2Routes = registerOauth2Routes;
+const consent_page_js_1 = require("./consent-page.js");
+const session_cookie_js_1 = require("../../auth/session-cookie.js");
+/** Validate the inbound authorize query. `client_id` is intentionally
+ *  NOT checked — that pair is verified only at the Lambda boundary. */
+function validateAuthorizeQuery(q, knownIntegrations) {
+    if (q.response_type !== 'code')
+        return { ok: false, status: 400, error: 'unsupported_response_type' };
+    if (!q.integration || !knownIntegrations.has(q.integration))
+        return { ok: false, status: 400, error: 'invalid_request — unknown integration' };
+    if (!q.redirect_uri)
+        return { ok: false, status: 400, error: 'invalid_request — redirect_uri required' };
+    if (!q.state)
+        return { ok: false, status: 400, error: 'invalid_request — state required' };
+    return { ok: true, integration: q.integration, redirectUri: q.redirect_uri, state: q.state };
+}
+/** True if `redirectUri` starts with one of the integration's allowed prefixes. */
+function isRedirectUriAllowed(redirectUri, allowedPrefixes) {
+    return allowedPrefixes.some((p) => redirectUri.startsWith(p));
+}
+/** One-line human summary of a scope list for the consent screen. */
+function summariseScopes(scopes) {
+    if (scopes.some((s) => s.type === 'category' && s.target === 'device')) {
+        return 'view and control all your cameras and devices';
+    }
+    return scopes.map((s) => s.type).join(', ') || 'no permissions';
+}
+/** Build a map of integrationId → descriptor from all registered oauth-integration providers. */
+async function buildIntegrationMap(registry) {
+    const entries = registry.getCollectionEntries('oauth-integration');
+    const descriptorMap = new Map();
+    for (const [, provider] of entries) {
+        const descriptor = await provider.getDescriptor();
+        descriptorMap.set(descriptor.integrationId, descriptor);
+    }
+    const knownSet = new Set(descriptorMap.keys());
+    return { descriptorMap, knownSet };
+}
+/** Parse an application/x-www-form-urlencoded body string into a plain object. */
+function parseFormBody(raw) {
+    const params = new URLSearchParams(raw);
+    const result = {};
+    for (const [key, value] of params.entries()) {
+        result[key] = value;
+    }
+    return result;
+}
+function registerOauth2Routes(fastify, deps) {
+    // Register a content-type parser for application/x-www-form-urlencoded so that
+    // consent POST and token POST can read form bodies. @fastify/formbody is not in
+    // the project's dependencies; we use URLSearchParams (Node built-in) instead.
+    fastify.addContentTypeParser('application/x-www-form-urlencoded', { parseAs: 'string' }, (_req, body, done) => {
+        try {
+            done(null, parseFormBody(body));
+        }
+        catch (err) {
+            done(err, undefined);
+        }
+    });
+    // ─── GET /api/oauth2/authorize ────────────────────────────────────────────
+    // Mounted under /api/* so it is naturally excluded from the SPA catch-all,
+    // the PWA service-worker navigate fallback, and the Vite dev proxy — no
+    // per-path special-casing anywhere.
+    fastify.get('/api/oauth2/authorize', async (request, reply) => {
+        const cookie = request.cookies[session_cookie_js_1.SESSION_COOKIE];
+        if (!cookie) {
+            if ((0, session_cookie_js_1.shouldRedirectToLogin)(request.method, request.headers.accept)) {
+                return reply.redirect((0, session_cookie_js_1.loginRedirectUrl)(request.url));
+            }
+            return reply.status(401).send({ error: 'unauthorized' });
+        }
+        let tokenInfo;
+        try {
+            tokenInfo = deps.verifyToken(cookie);
+        }
+        catch {
+            if ((0, session_cookie_js_1.shouldRedirectToLogin)(request.method, request.headers.accept)) {
+                return reply.redirect((0, session_cookie_js_1.loginRedirectUrl)(request.url));
+            }
+            return reply.status(401).send({ error: 'unauthorized' });
+        }
+        const registry = deps.getRegistry();
+        if (!registry) {
+            return reply.status(503).send({ error: 'service_unavailable' });
+        }
+        const { descriptorMap, knownSet } = await buildIntegrationMap(registry);
+        const query = request.query;
+        const v = validateAuthorizeQuery(query, knownSet);
+        if (!v.ok) {
+            return reply.status(v.status).send({ error: v.error });
+        }
+        const descriptor = descriptorMap.get(v.integration);
+        if (!isRedirectUriAllowed(v.redirectUri, descriptor.allowedRedirectPrefixes)) {
+            return reply
+                .status(400)
+                .send({ error: 'invalid_request — redirect_uri not allowed for this integration' });
+        }
+        const html = (0, consent_page_js_1.renderConsentPage)({
+            displayName: descriptor.displayName,
+            username: tokenInfo.username ?? '',
+            scopeSummary: summariseScopes(descriptor.requestedScopes),
+            hidden: {
+                integration: v.integration,
+                redirect_uri: v.redirectUri,
+                state: v.state,
+                response_type: 'code',
+            },
+        });
+        return reply.type('text/html').send(html);
+    });
+    // ─── POST /api/oauth2/authorize ───────────────────────────────────────────
+    fastify.post('/api/oauth2/authorize', async (request, reply) => {
+        const cookie = request.cookies[session_cookie_js_1.SESSION_COOKIE];
+        if (!cookie) {
+            if ((0, session_cookie_js_1.shouldRedirectToLogin)(request.method, request.headers.accept)) {
+                return reply.redirect((0, session_cookie_js_1.loginRedirectUrl)(request.url));
+            }
+            return reply.status(401).send({ error: 'unauthorized' });
+        }
+        let tokenInfo;
+        try {
+            tokenInfo = deps.verifyToken(cookie);
+        }
+        catch {
+            if ((0, session_cookie_js_1.shouldRedirectToLogin)(request.method, request.headers.accept)) {
+                return reply.redirect((0, session_cookie_js_1.loginRedirectUrl)(request.url));
+            }
+            return reply.status(401).send({ error: 'unauthorized' });
+        }
+        const registry = deps.getRegistry();
+        if (!registry) {
+            return reply.status(503).send({ error: 'service_unavailable' });
+        }
+        const { descriptorMap, knownSet } = await buildIntegrationMap(registry);
+        const body = request.body;
+        const formQuery = {
+            response_type: body.response_type,
+            integration: body.integration,
+            redirect_uri: body.redirect_uri,
+            state: body.state,
+        };
+        const v = validateAuthorizeQuery(formQuery, knownSet);
+        if (!v.ok) {
+            return reply.status(v.status).send({ error: v.error });
+        }
+        const descriptor = descriptorMap.get(v.integration);
+        if (!isRedirectUriAllowed(v.redirectUri, descriptor.allowedRedirectPrefixes)) {
+            return reply
+                .status(400)
+                .send({ error: 'invalid_request — redirect_uri not allowed for this integration' });
+        }
+        if (body.consent !== 'allow') {
+            return reply.redirect(`${v.redirectUri}?error=access_denied&state=${encodeURIComponent(v.state)}`);
+        }
+        const userMgmt = registry.getSingleton('user-management');
+        if (!userMgmt) {
+            return reply.status(503).send({ error: 'service_unavailable' });
+        }
+        const { code } = await userMgmt.oauthIssueCode({
+            integrationId: v.integration,
+            userId: tokenInfo.userId ?? '',
+            username: tokenInfo.username ?? '',
+            scopes: descriptor.requestedScopes,
+            redirectUri: v.redirectUri,
+            // Prefer the integration's own public origin (e.g. the operator-selected
+            // external-access endpoint surfaced by a forked exporter addon) so the
+            // claim the cloud Lambda routes back on is the reachable public URL, not
+            // the hub-global fallback (which defaults to localhost in dev).
+            hubUrl: descriptor.hubUrl ?? deps.publicHubUrl(),
+        });
+        return reply.redirect(`${v.redirectUri}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(v.state)}`);
+    });
+    // ─── POST /api/oauth2/token ───────────────────────────────────────────────
+    // No session gate — called by Alexa/Lambda directly.
+    fastify.post('/api/oauth2/token', async (request, reply) => {
+        const registry = deps.getRegistry();
+        if (!registry) {
+            return reply.status(503).send({ error: 'service_unavailable' });
+        }
+        const userMgmt = registry.getSingleton('user-management');
+        if (!userMgmt) {
+            return reply.status(503).send({ error: 'service_unavailable' });
+        }
+        const body = request.body;
+        let tokenResult;
+        if (body.grant_type === 'authorization_code') {
+            if (!body.code || !body.redirect_uri) {
+                return reply.status(400).send({ error: 'invalid_request' });
+            }
+            tokenResult = await userMgmt.oauthExchangeCode({
+                code: body.code,
+                redirectUri: body.redirect_uri,
+            });
+        }
+        else if (body.grant_type === 'refresh_token') {
+            if (!body.refresh_token) {
+                return reply.status(400).send({ error: 'invalid_request' });
+            }
+            tokenResult = await userMgmt.oauthRefresh({ refreshToken: body.refresh_token });
+        }
+        else {
+            return reply.status(400).send({ error: 'unsupported_grant_type' });
+        }
+        if (tokenResult === null) {
+            return reply.status(400).send({ error: 'invalid_grant' });
+        }
+        return reply.send({
+            access_token: tokenResult.accessToken,
+            refresh_token: tokenResult.refreshToken,
+            expires_in: tokenResult.expiresIn,
+            token_type: 'Bearer',
+        });
+    });
+}