@camstack/types 1.2.54 → 1.2.56

package/dist/addon.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_event_category = require("./event-category-BE4PDZ_3.js");
-const require_sleep = require("./sleep-DfF6vKCf.js");
+const require_event_category = require("./event-category-DxZbWydC.js");
+const require_sleep = require("./sleep-EX1-qUVR.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
 //#region src/generated/collection-array-methods.ts
 /**

package/dist/addon.mjs

@@ -1,5 +1,5 @@
-import { t as EventCategory } from "./event-category-41fKf-q9.mjs";
-import { C as DeviceType, F as readNodePin, L as ReadinessRegistry, O as expandCapMethods, P as nodePin, R as ReadinessTimeoutError, V as scopeKey, a as asJsonObject, d as DEVICE_SCOPED_CAPS, f as isDeviceScopedCap, gt as normalizeAddonInitResult, ht as BaseAddon, mt as DisposerChain, p as createDeviceProxy, pt as DATAPLANE_SECRET_HEADER, s as asString, t as sleep, u as parseJsonUnknown, v as deviceOpsCapability, w as adminUiCapability, y as viewerUiCapability, yt as emitReadiness } from "./sleep-CT4lN1ij.mjs";
+import { t as EventCategory } from "./event-category-Cv9dO26A.mjs";
+import { C as DeviceType, F as readNodePin, L as ReadinessRegistry, O as expandCapMethods, P as nodePin, R as ReadinessTimeoutError, V as scopeKey, a as asJsonObject, d as DEVICE_SCOPED_CAPS, f as isDeviceScopedCap, gt as normalizeAddonInitResult, ht as BaseAddon, mt as DisposerChain, p as createDeviceProxy, pt as DATAPLANE_SECRET_HEADER, s as asString, t as sleep, u as parseJsonUnknown, v as deviceOpsCapability, w as adminUiCapability, y as viewerUiCapability, yt as emitReadiness } from "./sleep-CeuvKr4N.mjs";
 import { t as errMsg } from "./err-msg-IQTHeDzc.mjs";
 //#region src/generated/collection-array-methods.ts
 /**

package/dist/auth/principal-scope.d.ts

@@ -0,0 +1,123 @@
+/**
+ * The one place a bearer principal is classified and matched against a
+ * `TokenScope` set. Pure — no I/O, no registry, no logger — so the kernel,
+ * `server/backend` and any ADDON can share it. It lives in `@camstack/types`
+ * for exactly that reason: `scopesAllowDeviceCap` used to live in
+ * `@camstack/system`, which addons may not import, so `addon-export-alexa`
+ * hand-copied it into `directive-router.ts` and said so in a comment twice.
+ * One vector, one derivation.
+ *
+ * ── What this exists to stop ────────────────────────────────────────────
+ *
+ * Measured on the live hub, 2026-08-09: an `oauth-access` token minted for the
+ * `export-alexa` account link was accepted on
+ * `POST /addon/homeassistant-export/command` — a route that actuates PTZ,
+ * reboot, the per-camera switches and notification snooze. The addon-route gate
+ * verified the JWT signature and checked `isAdmin` for `access: 'admin'` routes
+ * and nothing else, so every `access: 'authenticated'` route in the product was
+ * reachable by ANY valid hub JWT, including one issued to a different
+ * integration, a 60-second single-use authorization CODE, and a 30-day refresh
+ * token. See D103.
+ */
+import type { MethodAccess, TokenScope } from '../schemas/auth-records.js';
+/**
+ * The access flavour an HTTP verb asks for. `GET`/`HEAD` read; anything that
+ * can change state is at least `create`.
+ *
+ * An UNRECOGNISED verb resolves to `delete`, the most privileged flavour, so a
+ * method nobody thought about fails closed. The inverse default — treating the
+ * unknown as `view` — is how a gate quietly stops gating.
+ */
+export declare function methodAccessForHttpMethod(method: string): MethodAccess;
+/**
+ * True if the scope set grants `access` on device-scoped capabilities.
+ * A `category:device` grant covers every device cap (the broad grant).
+ */
+export declare function scopesAllowDeviceCap(scopes: readonly TokenScope[], access: MethodAccess): boolean;
+/**
+ * True if the scope set names this addon with at least `access`.
+ *
+ * Deliberately NOT satisfied by `category:device`: a grant over per-camera
+ * capabilities says nothing about an addon's own HTTP surface, and conflating
+ * the two is precisely the confusion that let an Alexa token drive Home
+ * Assistant's command route.
+ */
+export declare function scopesAllowAddon(scopes: readonly TokenScope[], addonId: string, access: MethodAccess): boolean;
+/**
+ * What a verified JWT actually IS. Every one of these verifies under the same
+ * hub secret — that is the whole trap. `jwt.verify` succeeding means "we minted
+ * this", never "this is an API credential".
+ */
+export type BearerPrincipal = 
+/** An ordinary user session from `auth.login`. Governed by the user's own scopes. */
+{
+    readonly kind: 'session';
+}
+/** An account-linking token issued to an integration. Governed by the grant. */
+ | {
+    readonly kind: 'integration';
+    readonly provider: 'oauth-access';
+}
+/** Minted for one hand-off step and never meant to authenticate an API call. */
+ | {
+    readonly kind: 'not-a-credential';
+    readonly reason: string;
+};
+/**
+ * The narrow shape read off a verified JWT payload. Every field optional: the
+ * payload arrives as whatever was signed, and a missing discriminator must
+ * classify, never throw.
+ */
+export interface BearerPayloadShape {
+    readonly kind?: unknown;
+    readonly provider?: unknown;
+    readonly userId?: unknown;
+    readonly isAdmin?: unknown;
+    readonly scopes?: unknown;
+}
+/**
+ * Classify a VERIFIED JWT payload.
+ *
+ * A session JWT carries no `kind`. Everything else in this system tags itself:
+ * `kind: 'sso-bridge'` for the OAuth/SSO family (discriminated further by
+ * `provider`), `kind: 'totp-challenge'` for login leg 1. Only `oauth-access` is
+ * an API credential; a code lives in a browser redirect URL and a refresh token
+ * belongs to `/token`.
+ */
+export declare function classifyBearerPrincipal(payload: BearerPayloadShape): BearerPrincipal;
+export interface PrincipalAddonReachInput {
+    readonly principal: BearerPrincipal;
+    readonly scopes: readonly TokenScope[];
+    readonly isAdmin: boolean;
+    readonly addonId: string;
+    /** The HTTP verb of the request being gated. */
+    readonly method: string;
+}
+/**
+ * The verdict, with the reason carried so the refusal can be LOGGED. A branch
+ * that drops a request silently reads as "never happened".
+ */
+export type PrincipalAddonReachVerdict = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+/**
+ * May this principal reach `/addon/<addonId>/…` on an `authenticated` route or
+ * data-plane endpoint?
+ *
+ * Three principals, three answers:
+ *
+ *  - **session** — unchanged. A user session is governed by the route's own
+ *    `access` (`authenticated` / `admin`), exactly as before. Tightening HERE
+ *    would lock every non-admin viewer out of recorder playback, snapshot media
+ *    and the stream-broker embed, which is a worse outcome than the hole.
+ *  - **integration** — must hold `addon:<addonId>` at the verb's access. This is
+ *    the same rule the `cst_` scoped-token branch has always applied; the JWT
+ *    branch simply never applied it, and closing that divergence IS the fix.
+ *    `isAdmin` is ignored: an integration token is minted `isAdmin: false` and a
+ *    token claiming otherwise must not talk its way past the grant.
+ *  - **not-a-credential** — refused unconditionally.
+ */
+export declare function principalMayReachAddon(input: PrincipalAddonReachInput): PrincipalAddonReachVerdict;

package/dist/capabilities/index.d.ts

@@ -74,7 +74,7 @@ export { AddBrokerInputSchema, BrokerConnectionDetailsSchema, BrokerInfoSchema,
 export type { NetworkAccessStatus, NetworkEndpoint } from './network-access.cap.js';
 export { NetworkAccessStatusSchema, NetworkEndpointSchema, networkAccessCapability, } from './network-access.cap.js';
 export { type Attachment, type AttachmentMediaType, AttachmentMediaTypeSchema, AttachmentSchema, type DiscoveredTarget, DiscoveredTargetSchema, type INotificationOutputProvider, type NotificationAction, type NotificationActionIcon, NotificationActionIconSchema, NotificationActionSchema, type NotificationFormat, NotificationFormatSchema, NotificationSchema, notificationOutputCapability, type RenderedAs, RenderedAsSchema, type SendResult, SendResultSchema, type Target, type TargetKind, type TargetKindCaps, TargetKindCapsSchema, type TargetKindLevel, TargetKindLevelSchema, TargetKindSchema, TargetSchema, type TestResult, TestResultSchema, } from './notification-output.cap.js';
-export { type INotificationRulesProvider, NC_CONDITION_CATALOG, NC_HISTORY_LIMIT_DEFAULT, NC_HISTORY_LIMIT_MAX, NC_MAX_PER_TRACK_IMMEDIATE, NC_SNOOZE_MAX_MINUTES, type NcAlarmConfig, NcAlarmConfigSchema, type NcAlarmModeCoverage, NcAlarmModeCoverageSchema, type NcAlarmSettings, type NcAlarmSettingsPatch, NcAlarmSettingsPatchSchema, NcAlarmSettingsSchema, type NcConditionDescriptor, NcConditionDescriptorSchema, type NcConditions, NcConditionsSchema, type NcCrossing, NcCrossingSchema, type NcDelivery, NcDeliverySchema, type NcDeviceStateCondition, NcDeviceStateConditionSchema, type NcHistoryEntry, NcHistoryEntrySchema, type NcHistoryFilter, NcHistoryFilterSchema, type NcHistoryRecordKind, NcHistoryRecordKindSchema, type NcHistoryStatus, NcHistoryStatusSchema, type NcHistorySubject, NcHistorySubjectSchema, type NcMediaFrame, NcMediaFrameSchema, type NcMediaPolicy, NcMediaPolicySchema, type NcOccupancyCondition, NcOccupancyConditionSchema, type NcPlateMatcher, NcPlateMatcherSchema, type NcRule, type NcRuleAction, NcRuleActionSchema, type NcRuleActionSequence, NcRuleActionSequenceSchema, type NcRuleActions, NcRuleActionsSchema, type NcRuleInput, NcRuleInputSchema, type NcRuleNotificationButton, NcRuleNotificationButtonSchema, type NcRulePatch, NcRulePatchSchema, NcRuleSchema, type NcRuleTarget, NcRuleTargetSchema, type NcSchedule, NcScheduleSchema, type NcScheduleWindow, NcScheduleWindowSchema, type NcSnooze, type NcSnoozeInput, NcSnoozeInputSchema, NcSnoozeSchema, type NcSnoozeScope, NcSnoozeScopeSchema, type NcSnoozeSuppressed, NcSnoozeSuppressedSchema, type NcTestResult, NcTestResultSchema, type NcThrottle, type NcThrottleGranularity, NcThrottleGranularitySchema, NcThrottleSchema, type NcZoneCondition, NcZoneConditionSchema, notificationRulesCapability, } from './notification-rules.cap.js';
+export { type INotificationRulesProvider, NC_CONDITION_CATALOG, NC_HISTORY_LIMIT_DEFAULT, NC_HISTORY_LIMIT_MAX, NC_MAX_PER_TRACK_IMMEDIATE, NC_SNOOZE_MAX_MINUTES, type NcAlarmConfig, NcAlarmConfigSchema, type NcAlarmModeCoverage, NcAlarmModeCoverageSchema, type NcAlarmSettings, type NcAlarmSettingsPatch, NcAlarmSettingsPatchSchema, NcAlarmSettingsSchema, type NcConditionDescriptor, NcConditionDescriptorSchema, type NcConditions, NcConditionsSchema, type NcCrossing, NcCrossingSchema, type NcDelivery, NcDeliverySchema, type NcDeviceStateCondition, NcDeviceStateConditionSchema, type NcHistoryEntry, NcHistoryEntrySchema, type NcHistoryFilter, NcHistoryFilterSchema, type NcHistoryRecordKind, NcHistoryRecordKindSchema, type NcHistoryStatus, NcHistoryStatusSchema, type NcHistorySubject, NcHistorySubjectSchema, type NcMediaFrame, NcMediaFrameSchema, type NcMediaPolicy, NcMediaPolicySchema, type NcOccupancyCondition, NcOccupancyConditionSchema, type NcPlateMatcher, NcPlateMatcherSchema, type NcRule, type NcRuleAction, NcRuleActionSchema, type NcRuleActionSequence, NcRuleActionSequenceSchema, type NcRuleActions, NcRuleActionsSchema, type NcRuleInput, NcRuleInputSchema, type NcRuleNotificationButton, NcRuleNotificationButtonSchema, type NcRulePatch, NcRulePatchSchema, NcRuleSchema, type NcRuleTarget, NcRuleTargetSchema, type NcSchedule, NcScheduleSchema, type NcScheduleWindow, NcScheduleWindowSchema, type NcSystemEventCondition, NcSystemEventConditionSchema, type NcSystemEventKind, NcSystemEventKindSchema, type NcSnooze, type NcSnoozeInput, NcSnoozeInputSchema, NcSnoozeSchema, type NcSnoozeScope, NcSnoozeScopeSchema, type NcSnoozeSuppressed, NcSnoozeSuppressedSchema, type NcTestResult, NcTestResultSchema, type NcThrottle, type NcThrottleGranularity, NcThrottleGranularitySchema, NcThrottleSchema, type NcZoneCondition, NcZoneConditionSchema, notificationRulesCapability, } from './notification-rules.cap.js';
 export { type IOauthIntegrationProvider, type OauthIntegrationDescriptor, OauthIntegrationDescriptorSchema, oauthIntegrationCapability, } from './oauth-integration.cap.js';
 export { type AudioEvent, AudioEventSchema, type DetectionSource, DetectionSourceSchema, type EventKind, type EventKindCategory, EventKindCategorySchema, type EventKindDescriptor, EventKindDescriptorSchema, type EventKindIcon, EventKindIconSchema, EventKindSchema, type EventKindsForDevice, EventKindsForDeviceSchema, type EventPruneCounts, type EventStoreDeviceFootprint, type EventStoreFootprint, type IPipelineAnalyticsProvider, type KeyEvent, KeyEventSchema, type LabelAttribution, LabelAttributionSchema, type LabelTier, LabelTierSchema, type MediaFile, type MediaFileInfo, MediaFileInfoSchema, type MediaFileKind, MediaFileSchema, type MotionEvent, MotionEventSchema, type ObjectEvent, ObjectEventSchema, pipelineAnalyticsCapability, type RecentTracksPage, RecentTracksPageSchema, type RecentTracksQuery, RecentTracksQueryInput, type RetrainAnnotation, type RetrainAnnotationDraft, RetrainAnnotationDraftSchema, RetrainAnnotationKindSchema, RetrainAnnotationSchema, RetrainAnnotationSourceSchema, type RetrainAssistResult, RetrainAssistResultSchema, RetrainAssistSubjectSchema, RetrainCopyRefusalSchema, type RetrainFrame, type RetrainFrameCandidate, RetrainFrameCandidateSchema, type RetrainFrameList, RetrainFrameListSchema, RetrainFrameSchema, type RetrainFrameSelection, RetrainFrameSelectionSchema, type RetrainMacroClass, RetrainMacroClassSchema, type RetrainStatus, RetrainStatusSchema, type RetrainTrack, RetrainTrackSchema, type RetrainTransitionResult, RetrainTransitionResultSchema, type ScoredObjectEvent, ScoredObjectEventSchema, type SensorEvent, SensorEventSchema, type Track, type TrackCascadeCounts, TrackCascadeCountsSchema, type TrackEnvelope, TrackEnvelopeSchema, TrackedDetectionSchema, type TrackFlags, type TrackFlagsPatch, TrackFlagsPatchSchema, TrackFlagsSchema, type TrackProjection, TrackProjectionSchema, TrackSchema, type TrackSource, TrackSourceSchema, type TrackState, TrackStateSchema, type TrackZoneFilter, TrackZoneFilterSchema, type TrainingExportDeviceTotals, TrainingExportDeviceTotalsSchema, type TrainingExportSummary, TrainingExportSummarySchema, type ZoneCrossing, type ZoneCrossingDirection, ZoneCrossingDirectionSchema, ZoneCrossingSchema, } from './pipeline-analytics.cap.js';
 export type { NativeCropRef, PipelineStepInputOutput, PipelineValidationIssue, PipelineValidationResult, } from './pipeline-executor.cap.js';