@camstack/server 1.2.82 → 1.2.83

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.82",
+  "version": "1.2.83",
   "private": false,
   "files": [
     "dist",
@@ -39,12 +39,12 @@
     "@camstack/addon-decoder-nodeav": "1.2.9",
     "@camstack/addon-notifiers": "1.2.13",
     "@camstack/addon-pipeline": "1.2.52",
-    "@camstack/addon-pipeline-orchestrator": "1.2.33",
+    "@camstack/addon-pipeline-orchestrator": "1.2.34",
     "@camstack/addon-post-analysis": "1.2.56",
     "@camstack/sdk": "1.2.11",
     "@camstack/shm-ring": "1.1.9",
-    "@camstack/system": "1.2.69",
-    "@camstack/types": "1.2.53",
+    "@camstack/system": "1.2.70",
+    "@camstack/types": "1.2.54",
     "@camstack/ui-library": "1.2.38",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",