@camstack/server 1.2.83 → 1.2.84

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

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.redactAuthorizeQuery = redactAuthorizeQuery;
+exports.describeAuthorizeCall = describeAuthorizeCall;
 exports.validateAuthorizeQuery = validateAuthorizeQuery;
 exports.isRedirectUriAllowed = isRedirectUriAllowed;
 exports.summariseScopes = summariseScopes;
@@ -7,6 +9,64 @@ exports.registerOauth2Routes = registerOauth2Routes;
 const session_cookie_js_1 = require("../../auth/session-cookie.js");
 const consent_page_js_1 = require("./consent-page.js");
 const private_host_js_1 = require("./private-host.js");
+/**
+ * Query keys whose VALUE may be logged.
+ *
+ * Deliberately an allow-list, not a deny-list: a parameter this file has never
+ * heard of is redacted by default, so adding one cannot silently start
+ * publishing a secret. `state` is a per-attempt nonce the client binds its
+ * session to, `code_challenge` is public by design and `code_verifier`/`code`
+ * are outright credentials — all four are redacted under the one rule, because
+ * the diagnosis needs the KEY NAMES, not the values.
+ */
+const VALUE_SAFE_QUERY_KEYS = [
+    'response_type',
+    'integration',
+    'code_challenge_method',
+    'client_id',
+];
+const REDACTED = '<redacted>';
+/** Bound on the logged query and user-agent. A refusal must not be able to
+ *  write an unbounded caller-controlled string into the log. */
+const MAX_LOGGED_FIELD_LEN = 400;
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+/** Rebuild a query string with every non-allow-listed value replaced. */
+function redactAuthorizeQuery(rawQuery) {
+    if (rawQuery === '')
+        return '';
+    const parts = [];
+    for (const [key, value] of new URLSearchParams(rawQuery).entries()) {
+        parts.push(VALUE_SAFE_QUERY_KEYS.includes(key) ? `${key}=${value}` : `${key}=${REDACTED}`);
+    }
+    return truncate(parts.join('&'), MAX_LOGGED_FIELD_LEN);
+}
+/** Strip the query from a `Referer`, keeping origin + path. Returns `null` for
+ *  an absent or unparsable header rather than logging it raw. */
+function describeReferer(raw) {
+    if (raw === undefined || raw === '')
+        return null;
+    try {
+        const url = new URL(raw);
+        return `${url.origin}${url.pathname}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Everything the log is allowed to know about an inbound authorize call. */
+function describeAuthorizeCall(url, headers, hasSessionCookie) {
+    const q = url.indexOf('?');
+    const ua = headers['user-agent'];
+    return {
+        path: q === -1 ? url : url.slice(0, q),
+        query: q === -1 ? '' : redactAuthorizeQuery(url.slice(q + 1)),
+        referer: describeReferer(headers.referer),
+        userAgent: ua === undefined || ua === '' ? null : truncate(ua, MAX_LOGGED_FIELD_LEN),
+        hasSessionCookie,
+    };
+}
 /** Longest caller-supplied `integration` value echoed back in an error. */
 const MAX_ECHOED_INTEGRATION_LEN = 100;
 /**
@@ -65,15 +125,17 @@ function validateAuthorizeQuery(q, knownIntegrations, pendingAddons = []) {
     // arrived nor what would have been accepted.
     const detail = {
         received: describeReceivedIntegration(q.integration),
-        known_integrations: [...knownIntegrations.keys()],
-        ...(pendingAddons.length > 0 ? { pending_addons: pendingAddons } : {}),
+    };
+    const diagnostics = {
+        knownIntegrations: [...knownIntegrations.keys()],
+        pendingAddons,
     };
     const param = resolveIntegrationParam(q.integration);
     if (!param.ok) {
         const error = param.reason === 'missing'
             ? 'invalid_request — integration parameter missing'
             : 'invalid_request — integration parameter repeated with conflicting values';
-        return { ok: false, status: 400, error, detail };
+        return { ok: false, status: 400, error, detail, diagnostics };
     }
     const policy = knownIntegrations.get(param.value);
     if (!policy) {
@@ -89,10 +151,17 @@ function validateAuthorizeQuery(q, knownIntegrations, pendingAddons = []) {
                 status: 503,
                 error: 'temporarily_unavailable — integration not registered yet',
                 detail,
+                diagnostics,
                 retryAfterSec: INTEGRATION_PENDING_RETRY_AFTER_SEC,
             };
         }
-        return { ok: false, status: 400, error: 'invalid_request — unknown integration', detail };
+        return {
+            ok: false,
+            status: 400,
+            error: 'invalid_request — unknown integration',
+            detail,
+            diagnostics,
+        };
     }
     if (!q.redirect_uri)
         return { ok: false, status: 400, error: 'invalid_request — redirect_uri required' };
@@ -153,19 +222,23 @@ function summariseScopes(scopes) {
     }
     return scopes.map((s) => s.type).join(', ') || 'no permissions';
 }
-/** A refused `/authorize`. Logged at `warn` and echoed to the caller: both
- *  halves name the value that ARRIVED and the ids that would have worked, so
- *  neither the operator nor the log reader has to guess which of them is
- *  wrong. */
-function refuseAuthorize(reply, logger, method, refusal) {
+/**
+ * A refused `/authorize`. The two audiences get different things, on purpose.
+ *
+ * The LOG names the value that arrived next to the ids that would have worked
+ * and the addons still owed — that pairing is what turned "unknown
+ * integration" from a week-long outage into a diagnosis, and it must not be
+ * weakened. The RESPONSE carries only the caller's own echoed input; it tells
+ * a client nothing about what else this hub has installed.
+ */
+function refuseAuthorize(reply, logger, method, call, refusal) {
     logger.warn(`oauth2 authorize refused: ${refusal.error}`, {
         meta: {
             method,
+            ...call,
             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 ?? [],
+            knownIntegrations: refusal.diagnostics?.knownIntegrations ?? [],
+            pendingAddons: refusal.diagnostics?.pendingAddons ?? [],
         },
     });
     if (refusal.retryAfterSec !== undefined) {
@@ -173,6 +246,22 @@ function refuseAuthorize(reply, logger, method, refusal) {
     }
     return reply.status(refusal.status).send({ error: refusal.error, ...refusal.detail });
 }
+/**
+ * An authorize call turned away for want of a usable session.
+ *
+ * It is not a fault, and it is still logged: the browser bounce DEFERS the
+ * request through `/login?next=…`, and whatever the replay drops is dropped
+ * silently. That is exactly the branch CLAUDE.md requires to speak — with only
+ * refusals on the record, "arrived carrying `integration`, came back without
+ * it" is invisible and every refusal reads as a first arrival.
+ */
+function refuseUnauthenticated(request, reply, logger, call, reason) {
+    const redirected = (0, session_cookie_js_1.shouldRedirectToLogin)(request.method, request.headers.accept);
+    logger.info(redirected ? 'oauth2 authorize bounced to login' : 'oauth2 authorize refused: unauthenticated', { meta: { method: request.method, reason, redirected, ...call } });
+    if (redirected)
+        return reply.redirect((0, session_cookie_js_1.loginRedirectUrl)(request.url));
+    return reply.status(401).send({ error: 'unauthorized' });
+}
 /** Read integrationId → descriptor from every registered `oauth-integration`
  *  provider, plus the addons that still owe one. */
 async function readIntegrationRegistry(registry) {
@@ -214,21 +303,16 @@ function registerOauth2Routes(fastify, deps) {
     // per-path special-casing anywhere.
     fastify.get('/api/oauth2/authorize', async (request, reply) => {
         const cookie = request.cookies[session_cookie_js_1.SESSION_COOKIE];
+        const call = describeAuthorizeCall(request.url, request.headers, Boolean(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' });
+            return refuseUnauthenticated(request, reply, deps.logger, call, 'no-session-cookie');
         }
         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' });
+            return refuseUnauthenticated(request, reply, deps.logger, call, 'session-invalid');
         }
         const registry = deps.getRegistry();
         if (!registry) {
@@ -238,13 +322,14 @@ function registerOauth2Routes(fastify, deps) {
         const query = request.query;
         const v = validateAuthorizeQuery(query, descriptors, pendingAddons);
         if (!v.ok) {
-            return refuseAuthorize(reply, deps.logger, 'GET', v);
+            return refuseAuthorize(reply, deps.logger, 'GET', call, v);
         }
         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: {
                     method: 'GET',
+                    ...call,
                     integration: v.integration,
                     redirectUri: v.redirectUri,
                     allowedPrefixes: descriptor.allowedRedirectPrefixes,
@@ -312,21 +397,18 @@ function registerOauth2Routes(fastify, deps) {
     // ─── POST /api/oauth2/authorize ───────────────────────────────────────────
     fastify.post('/api/oauth2/authorize', async (request, reply) => {
         const cookie = request.cookies[session_cookie_js_1.SESSION_COOKIE];
+        // `query` is empty here by nature, not by loss: the consent POST carries its
+        // parameters as form fields. `method: POST` in the same line says so.
+        const call = describeAuthorizeCall(request.url, request.headers, Boolean(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' });
+            return refuseUnauthenticated(request, reply, deps.logger, call, 'no-session-cookie');
         }
         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' });
+            return refuseUnauthenticated(request, reply, deps.logger, call, 'session-invalid');
         }
         const registry = deps.getRegistry();
         if (!registry) {
@@ -346,13 +428,14 @@ function registerOauth2Routes(fastify, deps) {
         // and every one of them is attacker-editable.
         const v = validateAuthorizeQuery(formQuery, descriptors, pendingAddons);
         if (!v.ok) {
-            return refuseAuthorize(reply, deps.logger, 'POST', v);
+            return refuseAuthorize(reply, deps.logger, 'POST', call, v);
         }
         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: {
                     method: 'POST',
+                    ...call,
                     integration: v.integration,
                     redirectUri: v.redirectUri,
                     allowedPrefixes: descriptor.allowedRedirectPrefixes,
@@ -382,6 +465,12 @@ function registerOauth2Routes(fastify, deps) {
             // the hub-global fallback (which defaults to localhost in dev).
             hubUrl: descriptor.hubUrl ?? deps.publicHubUrl(),
             ...(v.codeChallenge !== '' ? { codeChallenge: v.codeChallenge } : {}),
+            // The integration declares its own refresh lifetime; omitting the field
+            // keeps the 30-day default. Baked in HERE, at consent, so the link the
+            // operator approved carries the lifetime they approved.
+            ...(descriptor.refreshTokenTtlSec !== undefined
+                ? { refreshTtlSec: descriptor.refreshTokenTtlSec }
+                : {}),
         });
         return reply.redirect(`${v.redirectUri}?code=${encodeURIComponent(code)}&state=${encodeURIComponent(v.state)}`);
     });

package/dist/api/trpc/cap-router-runtime.js

@@ -22,6 +22,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COLLECTION_ARRAY_METHODS = void 0;
 exports.aggregateCollectionCall = aggregateCollectionCall;
+exports.pinnedCollectionCall = pinnedCollectionCall;
 exports.createCapRouterPrimitives = createCapRouterPrimitives;
 exports.createCapRouterServices = createCapRouterServices;
 exports.buildRuntimeCapRouters = buildRuntimeCapRouters;
@@ -119,6 +120,69 @@ async function aggregateCollectionCall(reg, capName, method, args) {
     const out = await fn(args);
     return Array.isArray(out) ? out : null;
 }
+/**
+ * The `{ addonId }` PIN for a cap call arriving OUTSIDE the tRPC router — a
+ * forked addon's `ctx.api.<cap>.<method>` reaching the parent's
+ * `onUnownedCall`. The scalar twin of {@link aggregateCollectionCall}, and it
+ * exists for the same reason: the two paths answered differently and only the
+ * tRPC one was ever measured.
+ *
+ * `addonId` is not provider data on a system-scoped collection cap — the
+ * codegen INJECTS it as the `{nodeId?, addonId?}` selector on every method
+ * (`GetInputSchema` for `broker.getBrokerConfig` declares only `{ id }`), and
+ * `cap-router-builder.ts` routes the tRPC call by it. The child→parent path
+ * lifted only `nodeId` and `deviceId` out of a child's args, so the selector
+ * was DISCARDED IN SILENCE and the call landed on whichever provider registered
+ * first. Measured on the live hub 2026-08-09:
+ *
+ *     hub,   getBrokerConfig {id:'ha_001'}                       → null
+ *     hub,   getBrokerConfig {id:'ha_001', addonId:'provider-…'} → the config
+ *     addon, getBrokerConfig {id:'ha_001', addonId:'provider-…'} → null
+ *
+ * The third row is the bug: from an addon the pinned call returned exactly the
+ * UNPINNED answer — Homematic's `null` for a broker it does not own, which the
+ * Home Assistant export could not tell from "no such broker". It could not open
+ * a link, ever, and every write-up of the pin had measured only the first two
+ * rows.
+ *
+ * Mirrors the tRPC branch exactly, including what it does NOT do:
+ *   - ARRAY methods are never rerouted — their contract is the fan-out union
+ *     ({@link aggregateCollectionCall}), and a pin that turns a provider's
+ *     absence into a throw is what took `broker.list` from "fewer rows" to
+ *     `BAD_REQUEST` and the operator from "one instance" to "no instance".
+ *   - Only the EXPLICIT top-level selector routes. No nested recovery here:
+ *     that heuristic reads a domain payload, and this path has no schema.
+ *
+ * A pin naming a non-provider REFUSES with the valid ids spelled out rather
+ * than degrading to another provider's answer — the whole point of pinning.
+ *
+ * Returns a `{ value }` box, never the bare result: `getBrokerConfig` answers
+ * `null` legitimately, so a bare `null` could not be told from "not handled".
+ */
+async function pinnedCollectionCall(reg, capName, method, args) {
+    if (!reg)
+        return null;
+    if (reg.getDefinition(capName)?.mode !== 'collection')
+        return null;
+    if (exports.COLLECTION_ARRAY_METHODS.get(capName)?.includes(method) === true)
+        return null;
+    if (args === null || typeof args !== 'object' || Array.isArray(args))
+        return null;
+    const addonId = args['addonId'];
+    if (typeof addonId !== 'string' || addonId.length === 0)
+        return null;
+    const provider = reg.getProviderByAddonId(capName, addonId);
+    if (provider === null) {
+        const valid = reg.getProviderAddonIds(capName);
+        throw new Error(`Capability "${capName}" has no provider with addonId "${addonId}". ` +
+            `Registered: ${valid.length > 0 ? valid.join(', ') : '(none)'}`);
+    }
+    const fn = provider[method];
+    // Args pass through unchanged, exactly as the `nodeId` pin on this path
+    // already does: a provider destructures the fields it needs and ignores the
+    // selector. Stripping it here would diverge from that for no gain.
+    return { value: typeof fn === 'function' ? await fn(args) : undefined };
+}
 /**
  * Fan an array-returning method across every provider and flatten the
  * results — the runtime equivalent of `concatCollection` for the

package/dist/api/trpc/trpc-error-principal.js

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readCredentialIdentity = readCredentialIdentity;
+exports.describeTrpcPrincipal = describeTrpcPrincipal;
+/**
+ * Read the credential's self-description off verified claims.
+ *
+ * The claim set on the wire is WIDER than `TokenPayload` describes — an
+ * `oauth-access` token is an sso-bridge token and carries `kind`, `provider`
+ * and `sessionId` besides. Those are read structurally rather than by widening
+ * `TokenPayload`, which would invite every consumer to assume they are always
+ * there.
+ *
+ * Gated on `kind === 'sso-bridge'`: `provider` is a common enough field name
+ * that a future token type could carry one meaning something else entirely, and
+ * mislabelling a principal in a security log is worse than not labelling it.
+ */
+function readCredentialIdentity(claims) {
+    const kind = Reflect.get(claims, 'kind');
+    if (kind !== 'sso-bridge')
+        return {};
+    const provider = Reflect.get(claims, 'provider');
+    const sessionId = Reflect.get(claims, 'sessionId');
+    return {
+        ...(typeof provider === 'string' && provider !== '' ? { credential: provider } : {}),
+        ...(typeof sessionId === 'string' && sessionId !== '' ? { sessionId } : {}),
+    };
+}
+/**
+ * Render a principal for one log line.
+ *
+ * Shapes, in the order they are distinguished:
+ *
+ *   anonymous
+ *   apocaliss92 (admin)
+ *   share:ab12cd34 (share-view)
+ *   scoped:1a2b3c4d (scoped-token)
+ *   apocaliss92 (oauth-access session=910a6179-…)
+ *   apocaliss92 (session)
+ */
+function describeTrpcPrincipal(user) {
+    // Never blank: an empty field reads as a logging defect rather than as an
+    // unauthenticated request, and the two need different fixes.
+    if (!user)
+        return 'anonymous';
+    const name = user.username || user.id || 'unknown';
+    if (user.shareView)
+        return `${name} (share-view)`;
+    if (user.isAdmin)
+        return `${name} (admin)`;
+    if (user.credential) {
+        const session = user.oauthSessionId ? ` session=${user.oauthSessionId}` : '';
+        return `${name} (${user.credential}${session})`;
+    }
+    if (user.isScoped)
+        return `${name} (scoped-token)`;
+    return `${name} (session)`;
+}

package/dist/api/trpc/trpc.context.js

@@ -4,6 +4,7 @@ exports.createMeshTrpcContext = createMeshTrpcContext;
 exports.createTrpcContext = createTrpcContext;
 exports.createWsTrpcContext = createWsTrpcContext;
 const share_token_service_js_1 = require("../../core/auth/share-token.service.js");
+const trpc_error_principal_js_1 = require("./trpc-error-principal.js");
 /** Read `req.query` if present (Fastify-only) without losing type safety. */
 function readQuery(req) {
     if (!('query' in req))
@@ -127,6 +128,10 @@ async function resolveUser(token, authService, addonRegistry, shareTokens = null
         if (typeof payload.isAdmin !== 'boolean') {
             return null;
         }
+        // What the token says it IS. An `oauth-access` token is an account link,
+        // and until this was carried onto the principal a refusal of one was
+        // indistinguishable in the logs from a refusal of a browser session.
+        const credential = (0, trpc_error_principal_js_1.readCredentialIdentity)(payload);
         return {
             id: payload.userId ?? payload.keyId ?? 'unknown',
             username: payload.username ?? 'unknown',
@@ -141,6 +146,8 @@ async function resolveUser(token, authService, addonRegistry, shareTokens = null
             // Scopes are baked into the JWT at login; the middleware uses
             // them to gate every call until the user re-logs.
             ...(payload.scopes !== undefined ? { scopes: payload.scopes } : {}),
+            ...(credential.credential !== undefined ? { credential: credential.credential } : {}),
+            ...(credential.sessionId !== undefined ? { oauthSessionId: credential.sessionId } : {}),
         };
     }
     catch {

package/dist/auth/addon-route-jwt-gate.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gateAddonJwt = gateAddonJwt;
+/**
+ * The JWT half of the `/addon/:addonId/*` gate — shared by the HTTP data-plane
+ * branch and the addon-route branch so there is exactly ONE answer to "may this
+ * bearer reach this addon".
+ *
+ * Before this existed the two branches disagreed with themselves and with the
+ * `cst_` branch: a scoped token needed an `addon:<id>` grant, while ANY valid
+ * hub JWT passed on nothing but a signature check. Measured on the live hub
+ * 2026-08-09, that let an `oauth-access` token minted for the `export-alexa`
+ * account link drive `POST /addon/homeassistant-export/command` — PTZ, reboot,
+ * the per-camera switches and notification snooze. A 60-second authorization
+ * CODE and a 30-day refresh token passed the same way. See D103.
+ */
+const types_1 = require("@camstack/types");
+function readScopes(raw) {
+    return Array.isArray(raw) ? raw : [];
+}
+/**
+ * Decide, and REPORT. A refusal always returns its reason to the log — a branch
+ * that drops a request silently reads as "never happened", and this one drops
+ * requests an operator will be trying to explain.
+ *
+ * Order is deliberate. `Admin required` is answered before the scope check so
+ * an admin-only route keeps the response it already had; nothing that is not a
+ * session or an `oauth-access` token gets that far at all.
+ */
+function gateAddonJwt(input, logger) {
+    const principal = (0, types_1.classifyBearerPrincipal)(input.payload);
+    const isAdmin = input.payload.isAdmin === true;
+    if (principal.kind === 'not-a-credential') {
+        logger.warn('addon route: refused a bearer that is not an API credential', {
+            meta: { addonId: input.addonId, method: input.method, reason: principal.reason },
+        });
+        return { ok: false, status: 401, error: 'Invalid token' };
+    }
+    if (input.access === 'admin' && !isAdmin) {
+        logger.warn('addon route: refused a non-admin bearer on an admin route', {
+            meta: { addonId: input.addonId, method: input.method, principal: principal.kind },
+        });
+        return { ok: false, status: 403, error: 'Admin required' };
+    }
+    const verdict = (0, types_1.principalMayReachAddon)({
+        principal,
+        scopes: readScopes(input.payload.scopes),
+        isAdmin,
+        addonId: input.addonId,
+        method: input.method,
+    });
+    if (!verdict.allowed) {
+        logger.warn('addon route: refused an integration token outside its declared grant', {
+            meta: { addonId: input.addonId, method: input.method, reason: verdict.reason },
+        });
+        return { ok: false, status: 403, error: 'Token scope mismatch' };
+    }
+    return { ok: true };
+}

package/dist/core/moleculer/moleculer.service.js

@@ -297,6 +297,14 @@ class MoleculerService {
                 // how the Notification Center saw an empty `notification-output`
                 // catalog and dead-lettered every notification (2026-07-30).
                 callCollectionAggregate: (capName, method, args) => (0, cap_router_runtime_js_1.aggregateCollectionCall)(this.capabilityService.getRegistry(), capName, method, args),
+                // `{ addonId }` PIN for the same child→parent path — the scalar twin of
+                // the fan-out above, sharing this server's provider resolution so the
+                // two paths cannot disagree. Routing takes only `nodeId`/`deviceId`, so
+                // without this a forked addon's pin is discarded and the first
+                // registered provider answers for a resource it does not own: HA's
+                // export read Homematic's `null` for `ha_001` and never opened a link
+                // (2026-08-09).
+                callPinnedCollection: (capName, method, args) => (0, cap_router_runtime_js_1.pinnedCollectionCall)(this.capabilityService.getRegistry(), capName, method, args),
                 // Hub-core `$`-service discriminant for the general
                 // provider-not-yet-registered recovery. A resolver miss on a NON-core
                 // cap (any addon-provided system/singleton cap, e.g.

package/dist/main.js

@@ -80,11 +80,13 @@ const addon_widgets_service_1 = require("./core/addon-widgets/addon-widgets.serv
 const trpc_router_1 = require("./api/trpc/trpc.router");
 const core_cap_bridge_1 = require("./api/trpc/core-cap-bridge");
 const trpc_context_1 = require("./api/trpc/trpc.context");
+const trpc_error_principal_1 = require("./api/trpc/trpc-error-principal");
 const addon_upload_1 = require("./api/addon-upload");
 const server_upload_1 = require("./api/server-upload");
 const auth_whoami_1 = require("./api/auth-whoami");
 const system_2 = require("@camstack/system");
 const session_cookie_js_1 = require("./auth/session-cookie.js");
+const addon_route_jwt_gate_js_1 = require("./auth/addon-route-jwt-gate.js");
 const health_routes_1 = require("./api/health/health.routes");
 const spa_static_1 = require("./api/static/spa-static");
 const precompressed_asset_js_1 = require("./api/static/precompressed-asset.js");
@@ -461,10 +463,19 @@ async function bootstrap() {
             trpcOptions: {
                 router: appRouter,
                 createContext: ({ req }) => (0, trpc_context_1.createTrpcContext)(req, authService, addonRegistry, shareTokenService),
-                onError: ({ path: trpcPath, error, }) => {
+                onError: ({ path: trpcPath, error, ctx, }) => {
                     const trpcLogger = app.get(logging_service_1.LoggingService).createLogger('tRPC');
                     trpcLogger.warn('tRPC error', {
-                        meta: { code: error.code, path: trpcPath ?? '?', message: error.message },
+                        meta: {
+                            code: error.code,
+                            path: trpcPath ?? '?',
+                            // WHO was refused. A FORBIDDEN with no principal cannot be tied
+                            // to the integration that hit it, and an operator grepping for
+                            // the integration finds nothing — which reads as "the hub logged
+                            // nothing" (2026-08-09).
+                            principal: (0, trpc_error_principal_1.describeTrpcPrincipal)(ctx?.user),
+                            message: error.message,
+                        },
                     });
                     if (error.cause)
                         trpcLogger.warn('tRPC error cause', {
@@ -784,6 +795,10 @@ async function bootstrap() {
             reply.setCookie(c.name, c.value, c.options);
             return reply.redirect(next);
         });
+        // Every refusal on the addon gate is a request an operator will be asking
+        // about ("why did Home Assistant stop actuating?"). Its own scope so the
+        // reason is greppable rather than buried in the bootstrap logger.
+        const addonGateLogger = app.get(logging_service_1.LoggingService).createLogger('addon-route-auth');
         // Addon HTTP API route catch-all: /addon/:addonId/*
         // Only handles non-GET or routes that actually exist in the addon route registry.
         // GET requests that don't match an addon route are SPA pages — handled by the /* fallback.
@@ -832,15 +847,17 @@ async function bootstrap() {
                         }
                     }
                     else {
+                        let payload;
                         try {
-                            const payload = authService.verifyToken(token);
-                            if (access === 'admin' && !payload.isAdmin) {
-                                return reply.status(403).send({ error: 'Admin required' });
-                            }
+                            payload = authService.verifyToken(token);
                         }
                         catch {
                             return reply.status(401).send({ error: 'Invalid token' });
                         }
+                        const gate = (0, addon_route_jwt_gate_js_1.gateAddonJwt)({ payload, addonId, method, access }, addonGateLogger);
+                        if (!gate.ok) {
+                            return reply.status(gate.status).send({ error: gate.error });
+                        }
                     }
                 }
                 const qIdx = request.url.indexOf('?');
@@ -915,28 +932,32 @@ async function bootstrap() {
                     return match.route.handler(addonRequest, addonReply);
                 }
                 else {
+                    let payload;
                     try {
-                        const payload = authService.verifyToken(token);
-                        if (match.route.access === 'admin' && !payload.isAdmin) {
-                            return reply.status(403).send({ error: 'Admin required' });
-                        }
-                        const addonRequest = {
-                            params: match.params,
-                            query,
-                            body: request.body,
-                            headers,
-                            user: {
-                                id: payload.userId ?? 'unknown',
-                                username: payload.username ?? 'unknown',
-                                isAdmin: payload.isAdmin,
-                            },
-                        };
-                        const addonReply = buildAddonReply(reply);
-                        return match.route.handler(addonRequest, addonReply);
+                        payload = authService.verifyToken(token);
                     }
                     catch {
                         return reply.status(401).send({ error: 'Invalid token' });
                     }
+                    // NOTE: the handler call used to sit INSIDE this try, so a throw from
+                    // an addon's own route handler was reported as `401 Invalid token`.
+                    const gate = (0, addon_route_jwt_gate_js_1.gateAddonJwt)({ payload, addonId, method, access: match.route.access }, addonGateLogger);
+                    if (!gate.ok) {
+                        return reply.status(gate.status).send({ error: gate.error });
+                    }
+                    const addonRequest = {
+                        params: match.params,
+                        query,
+                        body: request.body,
+                        headers,
+                        user: {
+                            id: payload.userId ?? 'unknown',
+                            username: payload.username ?? 'unknown',
+                            isAdmin: payload.isAdmin,
+                        },
+                    };
+                    const addonReply = buildAddonReply(reply);
+                    return match.route.handler(addonRequest, addonReply);
                 }
             }
             // Public route — no auth required
@@ -997,10 +1018,15 @@ async function bootstrap() {
             wss,
             router: appRouter,
             createContext: (opts) => (0, trpc_context_1.createWsTrpcContext)(opts, authService, addonRegistry, shareTokenService),
-            onError: ({ path: trpcPath, error, }) => {
+            onError: ({ path: trpcPath, error, ctx, }) => {
                 const trpcLogger = app.get(logging_service_1.LoggingService).createLogger('tRPC:ws');
                 trpcLogger.warn('tRPC error', {
-                    meta: { code: error.code, path: trpcPath ?? '?', message: error.message },
+                    meta: {
+                        code: error.code,
+                        path: trpcPath ?? '?',
+                        principal: (0, trpc_error_principal_1.describeTrpcPrincipal)(ctx?.user),
+                        message: error.message,
+                    },
                 });
                 if (error.cause)
                     trpcLogger.warn('tRPC error cause', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/server",
-  "version": "1.2.83",
+  "version": "1.2.84",
   "private": false,
   "files": [
     "dist",
@@ -33,7 +33,7 @@
     ]
   },
   "dependencies": {
-    "@camstack/addon-admin-ui": "1.2.41",
+    "@camstack/addon-admin-ui": "1.2.42",
     "@camstack/addon-agent-ui": "1.2.10",
     "@camstack/addon-auth": "1.2.11",
     "@camstack/addon-decoder-nodeav": "1.2.9",
@@ -43,8 +43,8 @@
     "@camstack/addon-post-analysis": "1.2.56",
     "@camstack/sdk": "1.2.11",
     "@camstack/shm-ring": "1.1.9",
-    "@camstack/system": "1.2.70",
-    "@camstack/types": "1.2.54",
+    "@camstack/system": "1.2.71",
+    "@camstack/types": "1.2.55",
     "@camstack/ui-library": "1.2.38",
     "@fastify/compress": "^9.0.0",
     "@fastify/cookie": "^11.0.2",