@camstack/server 1.2.81 → 1.2.83

package/dist/api/core/cap-providers.js

@@ -68,10 +68,8 @@ exports.buildNodesProvider = buildNodesProvider;
 exports.buildIntegrationsProvider = buildIntegrationsProvider;
 exports.dispatchCustomAction = dispatchCustomAction;
 exports.buildAddonsProvider = buildAddonsProvider;
-const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const os = __importStar(require("node:os"));
-const node_util_1 = require("node:util");
 const system_1 = require("@camstack/system");
 const types_1 = require("@camstack/types");
 const server_1 = require("@trpc/server");
@@ -79,7 +77,6 @@ const integration_id_backfill_1 = require("../../boot/integration-id-backfill");
 const addon_package_service_js_1 = require("../../core/addon/addon-package.service.js");
 const lifecycle_runner_singleton_js_1 = require("../../core/lifecycle/lifecycle-runner.singleton.js");
 const collection_preference_js_1 = require("./collection-preference.js");
-const execFileAsync = (0, node_util_1.promisify)(node_child_process_1.execFile);
 // ── system ──────────────────────────────────────────────────────────
 function getRetention(registry) {
     return (registry?.getSingleton('analysis-data-persistence')?.retention ?? null);
@@ -569,6 +566,117 @@ function getDeviceProvider(ar, addonId) {
     const provider = ar.getCapabilityRegistry().getProviderByAddon('device-provider', addonId);
     return isDeviceProvider(provider) ? provider : null;
 }
+function isConnectionTestProvider(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof Reflect.get(value, 'testSettings') === 'function');
+}
+function getConnectionTestProvider(ar, addonId) {
+    const provider = ar.getCapabilityRegistry().getProviderByAddon('connection-test', addonId);
+    return isConnectionTestProvider(provider) ? provider : null;
+}
+function isBrokerProvider(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        typeof Reflect.get(value, 'testConnection') === 'function');
+}
+/**
+ * Does this addon declare a pre-creation test at all? Drives
+ * `getAvailableTypes().canTest`, so the wizard can say "this one cannot be
+ * tested" instead of offering a button that always answers the same nonsense.
+ *
+ * Broker-mode addons count: their connection identity is the broker, and the
+ * broker cap owns a real `testConnection`.
+ */
+function declaresConnectionTest(ar, addonId, mode) {
+    if (getConnectionTestProvider(ar, addonId) !== null)
+        return true;
+    if (mode !== 'broker')
+        return false;
+    return isBrokerProvider(ar.getCapabilityRegistry().getProviderByAddon('broker', addonId));
+}
+/**
+ * Run the DECLARED pre-creation test for `(addonId, settings)`.
+ *
+ * Never throws: a test that blows up is `inconclusive`, which is emphatically
+ * NOT `rejected`. A timeout must not read as a refusal — it would block a
+ * perfectly good create on a flaky network, and the operator would have no way
+ * to tell the two apart.
+ */
+async function runConnectionTest(ar, addonId, settings, logger) {
+    // 1. The provider's own declared test — the primary path.
+    const tester = getConnectionTestProvider(ar, addonId);
+    if (tester) {
+        try {
+            const outcome = await tester.testSettings({ settings });
+            if (outcome.outcome === 'validated') {
+                return {
+                    status: 'validated',
+                    testedBy: addonId,
+                    ...(outcome.latencyMs !== undefined ? { latencyMs: outcome.latencyMs } : {}),
+                    ...(outcome.detail !== undefined ? { detail: outcome.detail } : {}),
+                };
+            }
+            if (outcome.outcome === 'rejected') {
+                return { status: 'rejected', error: outcome.error, testedBy: addonId };
+            }
+            return { status: 'inconclusive', error: outcome.error, testedBy: addonId };
+        }
+        catch (err) {
+            logger.warn('connection test could not run', {
+                tags: { addonId },
+                meta: { phase: 'test', error: (0, types_1.errMsg)(err) },
+            });
+            return {
+                status: 'inconclusive',
+                error: `Connection test could not run: ${(0, types_1.errMsg)(err)}`,
+                testedBy: addonId,
+            };
+        }
+    }
+    // 2. Broker-backed integrations carry their connection identity as a
+    //    `brokerId`; the broker already owns the real semantic check (HA opens a
+    //    temporary WS handshake, MQTT pings the bridge). Reached because the
+    //    settings NAME a broker, not because nothing else matched.
+    const brokerId = settings['brokerId'];
+    if (typeof brokerId === 'string' && brokerId.length > 0) {
+        const brokerProvider = ar
+            .getCapabilityRegistry()
+            .getProviderByAddonId('broker', addonId);
+        if (!brokerProvider) {
+            return {
+                status: 'inconclusive',
+                error: `Broker provider for addon '${addonId}' is not available`,
+                testedBy: null,
+            };
+        }
+        try {
+            const result = await brokerProvider.testConnection({ id: brokerId });
+            return result.ok
+                ? { status: 'validated', latencyMs: result.latencyMs, testedBy: addonId }
+                : { status: 'rejected', error: result.error, testedBy: addonId };
+        }
+        catch (err) {
+            logger.warn('broker connection test could not run', {
+                tags: { addonId },
+                meta: { phase: 'test', brokerId, error: (0, types_1.errMsg)(err) },
+            });
+            return {
+                status: 'inconclusive',
+                error: `Broker test could not run: ${(0, types_1.errMsg)(err)}`,
+                testedBy: addonId,
+            };
+        }
+    }
+    // 3. Nothing declared. Say so plainly — this must never render as a pass,
+    //    and must never render as a failure we did not observe.
+    return {
+        status: 'unsupported',
+        error: `Integration '${addonId}' declares no connection test, ` +
+            `so these settings cannot be validated before it is created.`,
+        testedBy: null,
+    };
+}
 /**
  * Marker caps that flag an addon as a creatable integration type:
  *   - `device-provider` — classic providers (Reolink/ONVIF/Frigate)
@@ -621,6 +729,38 @@ function buildIntegrationsProvider(ar, eb, loggingService, capabilityRegistry) {
                     throw new Error(`Addon "${input.addonId}" is unique-instance and already has an integration (${existing[0].id})`);
                 }
             }
+            // ── the gate ────────────────────────────────────────────────────
+            //
+            // "Next" must validate and create ONLY on success. `rejected` is the one
+            // status that blocks: it means the remote was asked and said no. An
+            // `unsupported` (no test declared) or `inconclusive` (declared test could
+            // not complete) observed NOTHING about the credentials — refusing on
+            // those would make every integration lacking the hook uncreatable, and
+            // would fail a good create on a flaky network. They pass, and they SAY SO
+            // in the log: silence here would read as "validated".
+            const verdict = await runConnectionTest(ar, input.addonId, input.settings ?? {}, logger);
+            if (verdict.status === 'rejected') {
+                logger.warn('rejected — connection test refused the settings', {
+                    tags: { addonId: input.addonId },
+                    meta: { phase: 'create', status: verdict.status, testedBy: verdict.testedBy },
+                });
+                throw new server_1.TRPCError({
+                    code: 'BAD_REQUEST',
+                    message: verdict.error ?? `Connection test failed for '${input.addonId}'`,
+                });
+            }
+            if (verdict.status === 'validated') {
+                logger.info('connection test validated — proceeding', {
+                    tags: { addonId: input.addonId },
+                    meta: { phase: 'create', latencyMs: verdict.latencyMs },
+                });
+            }
+            else {
+                logger.warn('creating without validation — the settings were not validated', {
+                    tags: { addonId: input.addonId },
+                    meta: { phase: 'create', status: verdict.status, reason: verdict.error },
+                });
+            }
             const integration = await reg.createIntegration(payload);
             logger.info('persisted', {
                 tags: { integrationId: integration.id, addonId: integration.addonId },
@@ -911,6 +1051,7 @@ function buildIntegrationsProvider(ar, eb, loggingService, capabilityRegistry) {
                     kind,
                     brokerKind,
                     supportsLocationImport,
+                    canTest: declaresConnectionTest(ar, m.id, mode),
                     existingInstances: existing.map((i) => ({
                         id: i.id,
                         name: i.name,
@@ -920,63 +1061,24 @@ function buildIntegrationsProvider(ar, eb, loggingService, capabilityRegistry) {
             });
         },
         testConnection: async (input) => {
-            // Broker-backed integrations (Approach A) carry their connection
-            // identity as a `brokerId` in settings — testing is a broker
-            // concern now, so delegate to the addon's `broker` cap. The broker
-            // already owns the real semantic check (HA opens a temporary WS
-            // handshake; MQTT pings the bridge). We translate the broker's
-            // discriminated result (`{ok:true,latencyMs}|{ok:false,error}`) into
-            // the integrations `{success, error?}` output shape. Falls back to
-            // the default RTSP/ffprobe path below for legacy device-provider
-            // addons (Reolink/Frigate/ONVIF) that probe a stream URL.
-            const registry = ar.getCapabilityRegistry();
-            const brokerId = input.settings['brokerId'];
-            if (typeof brokerId === 'string' && brokerId.length > 0) {
-                const brokerProvider = registry.getProviderByAddonId('broker', input.addonId);
-                if (!brokerProvider) {
-                    return {
-                        success: false,
-                        error: `Broker provider for addon '${input.addonId}' is not available`,
-                    };
-                }
-                try {
-                    const result = await brokerProvider.testConnection({ id: brokerId });
-                    return result.ok ? { success: true } : { success: false, error: result.error };
-                }
-                catch (err) {
-                    return { success: false, error: (0, types_1.errMsg)(err) };
-                }
-            }
-            // Default — RTSP/Frigate/ONVIF legacy path: probe the stream URL.
-            const url = String(input.settings['main_stream_url'] ?? input.settings['url'] ?? '').trim();
-            if (!url)
-                return { success: false, error: 'No stream URL provided' };
-            try {
-                const { stdout } = await execFileAsync('ffprobe', [
-                    '-v',
-                    'error',
-                    '-rtsp_transport',
-                    'tcp',
-                    '-timeout',
-                    '3000000',
-                    '-show_entries',
-                    'stream=codec_name,width,height',
-                    '-of',
-                    'json',
-                    url,
-                ], { timeout: 5000 });
-                const parsed = (0, types_1.asJsonObject)(JSON.parse(stdout));
-                const streams = (0, types_1.asJsonArray)(parsed?.streams);
-                return streams.length > 0
-                    ? { success: true }
-                    : { success: false, error: 'No streams found at URL' };
-            }
-            catch (err) {
-                return {
-                    success: false,
-                    error: `Connection failed: ${(0, types_1.errMsg)(err)}`,
-                };
-            }
+            // The Test button. Routes to the DECLARED test (see `runConnectionTest`)
+            // and reports the tri-state verbatim: `success` is true ONLY for
+            // `validated`, so a test that never ran can never render as a tick — and
+            // `status` lets the UI show "could not be validated" in its own colour
+            // instead of a red failure nobody observed.
+            const verdict = await runConnectionTest(ar, input.addonId, input.settings, logger);
+            logger.info('connection test', {
+                tags: { addonId: input.addonId },
+                meta: { phase: 'test', status: verdict.status, testedBy: verdict.testedBy },
+            });
+            return {
+                success: verdict.status === 'validated',
+                status: verdict.status,
+                testedBy: verdict.testedBy,
+                ...(verdict.error !== undefined ? { error: verdict.error } : {}),
+                ...(verdict.latencyMs !== undefined ? { latencyMs: verdict.latencyMs } : {}),
+                ...(verdict.detail !== undefined ? { detail: verdict.detail } : {}),
+            };
         },
     };
 }

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

@@ -9,6 +9,15 @@ const consent_page_js_1 = require("./consent-page.js");
 const private_host_js_1 = require("./private-host.js");
 /** Longest caller-supplied `integration` value echoed back in an error. */
 const MAX_ECHOED_INTEGRATION_LEN = 100;
+/**
+ * `Retry-After` on a refusal caused by an addon that has not registered yet.
+ *
+ * A forked addon's runner spawns, loads and initialises in seconds. This is
+ * advice to the CLIENT and nothing more — the hub never sleeps, never polls
+ * and never queues the request ([D3](../../../../../docs/decisions/adr-0003.md));
+ * it answers immediately with what is true right now.
+ */
+const INTEGRATION_PENDING_RETRY_AFTER_SEC = 5;
 /** Render the received `integration` for a human, bounded. */
 function describeReceivedIntegration(raw) {
     if (raw === undefined)
@@ -48,15 +57,16 @@ function resolveIntegrationParam(raw) {
  *  NOT checked — that pair is verified only at the Lambda boundary, and a
  *  PUBLIC client (`requiresPkce`) has no secret to check it against at all;
  *  the S256 challenge is what binds the code to its requester instead. */
-function validateAuthorizeQuery(q, knownIntegrations) {
+function validateAuthorizeQuery(q, knownIntegrations, pendingAddons = []) {
     if (q.response_type !== 'code')
         return { ok: false, status: 400, error: 'unsupported_response_type' };
-    // Three distinct client faults used to collapse into one opaque string.
+    // Four distinct faults used to collapse into one opaque string.
     // Alexa linking was down for a day because the message named neither what
     // arrived nor what would have been accepted.
     const detail = {
         received: describeReceivedIntegration(q.integration),
         known_integrations: [...knownIntegrations.keys()],
+        ...(pendingAddons.length > 0 ? { pending_addons: pendingAddons } : {}),
     };
     const param = resolveIntegrationParam(q.integration);
     if (!param.ok) {
@@ -67,6 +77,21 @@ function validateAuthorizeQuery(q, knownIntegrations) {
     }
     const policy = knownIntegrations.get(param.value);
     if (!policy) {
+        // The fourth fault, and the one moving every descriptor into an addon made
+        // likelier: the id is absent because the addon that owns it has not
+        // registered yet. `invalid_request` means "your request is wrong, do not
+        // repeat it" — during boot that is a lie, and it is the lie that sends a
+        // client to its degraded fallback and leaves it there. `temporarily_
+        // unavailable` is RFC 6749 §4.1.2.1 and says the opposite.
+        if (pendingAddons.length > 0) {
+            return {
+                ok: false,
+                status: 503,
+                error: 'temporarily_unavailable — integration not registered yet',
+                detail,
+                retryAfterSec: INTEGRATION_PENDING_RETRY_AFTER_SEC,
+            };
+        }
         return { ok: false, status: 400, error: 'invalid_request — unknown integration', detail };
     }
     if (!q.redirect_uri)
@@ -138,19 +163,29 @@ function refuseAuthorize(reply, logger, method, refusal) {
             method,
             received: refusal.detail?.received ?? null,
             knownIntegrations: refusal.detail?.known_integrations ?? [],
+            // Without this, a refusal during the boot window is byte-identical in
+            // Loki to one against a hub that has been up for a week.
+            pendingAddons: refusal.detail?.pending_addons ?? [],
         },
     });
+    if (refusal.retryAfterSec !== undefined) {
+        void reply.header('Retry-After', String(refusal.retryAfterSec));
+    }
     return reply.status(refusal.status).send({ error: refusal.error, ...refusal.detail });
 }
-/** Build a map of integrationId → descriptor from all registered oauth-integration providers. */
-async function buildIntegrationMap(registry) {
+/** Read integrationId → descriptor from every registered `oauth-integration`
+ *  provider, plus the addons that still owe one. */
+async function readIntegrationRegistry(registry) {
     const entries = registry.getCollectionEntries('oauth-integration');
-    const descriptorMap = new Map();
+    const descriptors = new Map();
     for (const [, provider] of entries) {
         const descriptor = await provider.getDescriptor();
-        descriptorMap.set(descriptor.integrationId, descriptor);
+        descriptors.set(descriptor.integrationId, descriptor);
     }
-    return descriptorMap;
+    const pendingAddons = registry
+        .getManifestDeclarers('oauth-integration')
+        .filter((addonId) => !registry.hasProvider('oauth-integration', addonId));
+    return { descriptors, pendingAddons };
 }
 /** Parse an application/x-www-form-urlencoded body string into a plain object. */
 function parseFormBody(raw) {
@@ -199,13 +234,13 @@ function registerOauth2Routes(fastify, deps) {
         if (!registry) {
             return reply.status(503).send({ error: 'service_unavailable' });
         }
-        const descriptorMap = await buildIntegrationMap(registry);
+        const { descriptors, pendingAddons } = await readIntegrationRegistry(registry);
         const query = request.query;
-        const v = validateAuthorizeQuery(query, descriptorMap);
+        const v = validateAuthorizeQuery(query, descriptors, pendingAddons);
         if (!v.ok) {
             return refuseAuthorize(reply, deps.logger, 'GET', v);
         }
-        const descriptor = descriptorMap.get(v.integration);
+        const descriptor = descriptors.get(v.integration);
         if (!isRedirectUriAllowed(v.redirectUri, descriptor.allowedRedirectPrefixes, descriptor.allowedPrivateHostPaths ?? [])) {
             deps.logger.warn('oauth2 authorize refused: redirect_uri not allowed', {
                 meta: {
@@ -247,18 +282,31 @@ function registerOauth2Routes(fastify, deps) {
     // from one that is refusing it, or the client dead-ends on a 400 with no way
     // to fall back. Unauthenticated (so is /token) and it discloses only which
     // integrations are installed.
+    //
+    // `complete` exists because absence-means-old-hub is a STICKY verdict: a
+    // client that probes 200ms after a restart sees a short list, concludes the
+    // hub cannot do OAuth, and settles into its password fallback for good. The
+    // flag says whether the list is final; a client SHOULD re-probe while it is
+    // false rather than downgrade. The pending addon IDS are deliberately not
+    // here — this route needs no token, and "not final yet" is the entire signal
+    // a client can act on. They are on the session-gated /authorize refusal,
+    // where a human is reading them as a diagnosis.
     fastify.get('/api/oauth2/integrations', async (_request, reply) => {
         const registry = deps.getRegistry();
         if (!registry) {
             return reply.status(503).send({ error: 'service_unavailable' });
         }
-        const descriptorMap = await buildIntegrationMap(registry);
+        const { descriptors, pendingAddons } = await readIntegrationRegistry(registry);
+        if (pendingAddons.length > 0) {
+            void reply.header('Retry-After', String(INTEGRATION_PENDING_RETRY_AFTER_SEC));
+        }
         return reply.send({
-            integrations: [...descriptorMap.values()].map((d) => ({
+            integrations: [...descriptors.values()].map((d) => ({
                 integrationId: d.integrationId,
                 displayName: d.displayName,
                 requiresPkce: d.requiresPkce === true,
             })),
+            complete: pendingAddons.length === 0,
         });
     });
     // ─── POST /api/oauth2/authorize ───────────────────────────────────────────
@@ -284,7 +332,7 @@ function registerOauth2Routes(fastify, deps) {
         if (!registry) {
             return reply.status(503).send({ error: 'service_unavailable' });
         }
-        const descriptorMap = await buildIntegrationMap(registry);
+        const { descriptors, pendingAddons } = await readIntegrationRegistry(registry);
         const body = request.body;
         const formQuery = {
             response_type: body.response_type,
@@ -296,11 +344,11 @@ function registerOauth2Routes(fastify, deps) {
         };
         // Re-validated, not trusted: the hidden fields came back from a browser
         // and every one of them is attacker-editable.
-        const v = validateAuthorizeQuery(formQuery, descriptorMap);
+        const v = validateAuthorizeQuery(formQuery, descriptors, pendingAddons);
         if (!v.ok) {
             return refuseAuthorize(reply, deps.logger, 'POST', v);
         }
-        const descriptor = descriptorMap.get(v.integration);
+        const descriptor = descriptors.get(v.integration);
         if (!isRedirectUriAllowed(v.redirectUri, descriptor.allowedRedirectPrefixes, descriptor.allowedPrivateHostPaths ?? [])) {
             deps.logger.warn('oauth2 authorize refused: redirect_uri not allowed', {
                 meta: {

package/dist/api/trpc/generated-cap-mounts.js

@@ -2,7 +2,7 @@
 // AUTO-GENERATED by scripts/generate-cap-mounts.ts — DO NOT EDIT
 // Re-run: npx tsx scripts/generate-cap-mounts.ts
 //
-// Mounted: 144    Skipped (legacy): 3
+// Mounted: 145    Skipped (legacy): 3
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.LEGACY_SHAPE_SKIP = void 0;
 exports.mountAllCaps = mountAllCaps;
@@ -111,6 +111,15 @@ function mountAllCaps(services) {
         carbonMonoxide: (0, generated_cap_routers_js_1.createCapRouter_carbonMonoxide)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'carbon-monoxide'), remoteCapProxy),
         climateControl: (0, generated_cap_routers_js_1.createCapRouter_climateControl)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'climate-control'), remoteCapProxy),
         color: (0, generated_cap_routers_js_1.createCapRouter_color)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'color'), remoteCapProxy),
+        connectionTest: (0, generated_cap_routers_js_1.createCapRouter_connectionTest)((_ctx, addonId) => {
+            if (!reg)
+                return null;
+            if (addonId !== undefined) {
+                return reg.getProviderByAddonId('connection-test', addonId);
+            }
+            const entries = reg.getCollectionEntries('connection-test');
+            return entries[0]?.[1] ?? null;
+        }, remoteCapProxy),
         connectivity: (0, generated_cap_routers_js_1.createCapRouter_connectivity)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'connectivity'), remoteCapProxy),
         consumables: (0, generated_cap_routers_js_1.createCapRouter_consumables)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'consumables'), remoteCapProxy),
         contact: (0, generated_cap_routers_js_1.createCapRouter_contact)((_ctx) => (0, cap_mount_helpers_js_1.requireDeviceScoped)(reg, 'contact'), remoteCapProxy),