@camstack/types 1.2.54 → 1.2.56

package/dist/index.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_canonical_hash = require("./canonical-hash-DNV8S5ET.js");
 const require_enums = require("./enums.js");
 const require_err_msg = require("./err-msg-COpsHMw2.js");
@@ -2469,6 +2469,102 @@ var ConvertResultSchema = zod.z.object({
 	artifacts: zod.z.array(ConvertArtifactSchema).readonly()
 });
 //#endregion
+//#region src/auth/principal-scope.ts
+/**
+* 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.
+*/
+function methodAccessForHttpMethod(method) {
+	switch (method.toUpperCase()) {
+		case "GET":
+		case "HEAD":
+		case "OPTIONS": return "view";
+		case "POST":
+		case "PUT":
+		case "PATCH": return "create";
+		default: return "delete";
+	}
+}
+/**
+* True if the scope set grants `access` on device-scoped capabilities.
+* A `category:device` grant covers every device cap (the broad grant).
+*/
+function scopesAllowDeviceCap(scopes, access) {
+	return scopes.some((s) => s.type === "category" && s.target === "device" && s.access.includes(access));
+}
+/**
+* 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.
+*/
+function scopesAllowAddon(scopes, addonId, access) {
+	return scopes.some((s) => s.type === "addon" && s.target === addonId && s.access.includes(access));
+}
+/**
+* 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`.
+*/
+function classifyBearerPrincipal(payload) {
+	const kind = payload.kind;
+	if (kind === void 0) return { kind: "session" };
+	if (kind !== "sso-bridge") return {
+		kind: "not-a-credential",
+		reason: `bridge token kind=${String(kind)}`
+	};
+	const provider = payload.provider;
+	if (provider === "oauth-access") return {
+		kind: "integration",
+		provider: "oauth-access"
+	};
+	return {
+		kind: "not-a-credential",
+		reason: `bridge token provider=${String(provider)}`
+	};
+}
+/**
+* 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.
+*/
+function principalMayReachAddon(input) {
+	const { principal } = input;
+	if (principal.kind === "not-a-credential") return {
+		allowed: false,
+		reason: principal.reason
+	};
+	if (principal.kind === "session") return { allowed: true };
+	const access = methodAccessForHttpMethod(input.method);
+	if (scopesAllowAddon(input.scopes, input.addonId, access)) return { allowed: true };
+	return {
+		allowed: false,
+		reason: `integration token holds no addon:${input.addonId}[${access}] grant`
+	};
+}
+//#endregion
 //#region src/expression/errors.ts
 /**
 * Error types for the safe expression engine. Two distinct classes so callers
@@ -11563,9 +11659,36 @@ var NcDeliverySchema = zod.z.enum([
 	"immediate",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
+]);
+/**
+* Stable Notification Center vocabulary over infrastructure/liveness events.
+* Bus categories are normalized into these intent-level kinds so rules do not
+* depend on a provider's raw event name or payload shape.
+*/
+var NcSystemEventKindSchema = zod.z.enum([
+	"camera-online",
+	"camera-offline",
+	"stream-online",
+	"stream-offline",
+	"node-online",
+	"node-offline",
+	"addon-update-available",
+	"server-update-available"
 ]);
 /**
+* One coherent system-event condition. `kinds` is the required opt-in safety
+* gate; the remaining lists are optional narrowing filters relevant to the
+* selected kinds.
+*/
+var NcSystemEventConditionSchema = zod.z.object({
+	kinds: zod.z.array(NcSystemEventKindSchema).min(1),
+	deviceIds: zod.z.array(zod.z.number().int()).min(1).optional(),
+	nodeIds: zod.z.array(zod.z.string().min(1)).min(1).optional(),
+	packageNames: zod.z.array(zod.z.string().min(1)).min(1).optional()
+});
+/**
 * `maxPerTrack` for `immediate` rules is FIXED at 1 (D-3): a single track
 * fires an immediate rule at most once, enforced durably by the outbox
 * unique key `(ruleId, trackId, targetId)`. Not a rule field in P1.
@@ -11888,6 +12011,8 @@ var NcConditionsSchema = zod.z.object({
 		"picked-up",
 		"both"
 	]).optional(),
+	/** Infrastructure/liveness/update event matcher (`system-event` delivery). */
+	systemEvent: NcSystemEventConditionSchema.optional(),
 	/**
 	* PERSONAL-RULE custom zones (viewer-drawn). Inline normalized polygons
 	* (MaskShape vocabulary). A record passes when its bbox overlaps ANY
@@ -12107,7 +12232,8 @@ var NcTestResultSchema = zod.z.object({
 		"object-event",
 		"track",
 		"device-event",
-		"package-event"
+		"package-event",
+		"system-event"
 	]),
 	deviceId: zod.z.number(),
 	timestamp: zod.z.number(),
@@ -12129,7 +12255,8 @@ var NcConditionDescriptorSchema = zod.z.object({
 		"schedule",
 		"device",
 		"package",
-		"occupancy"
+		"occupancy",
+		"system"
 	]),
 	label: zod.z.string(),
 	/** Editor widget the UI renders — never hardcode per-condition forms. */
@@ -12147,7 +12274,8 @@ var NcConditionDescriptorSchema = zod.z.object({
 		"crossingSelect",
 		"polygonDraw",
 		"occupancy",
-		"deviceState"
+		"deviceState",
+		"systemEvent"
 	]),
 	operator: zod.z.enum([
 		"in",
@@ -12189,6 +12317,50 @@ var NcConditionDescriptorSchema = zod.z.object({
 * rule editors render from the catalog, not hardcoded forms (spec §4.2).
 */
 var NC_CONDITION_CATALOG = [
+	{
+		id: "systemEvent",
+		group: "system",
+		label: "System event",
+		valueType: "systemEvent",
+		options: [
+			{
+				value: "camera-online",
+				label: "Camera online"
+			},
+			{
+				value: "camera-offline",
+				label: "Camera offline"
+			},
+			{
+				value: "stream-online",
+				label: "Stream online"
+			},
+			{
+				value: "stream-offline",
+				label: "Stream offline"
+			},
+			{
+				value: "node-online",
+				label: "Node online"
+			},
+			{
+				value: "node-offline",
+				label: "Node offline"
+			},
+			{
+				value: "addon-update-available",
+				label: "Addon update available"
+			},
+			{
+				value: "server-update-available",
+				label: "Server update available"
+			}
+		],
+		operator: "in",
+		appliesTo: ["system-event"],
+		phase: "P1",
+		description: "Infrastructure and update events. Optionally narrow camera/stream events by device, node events by node id, and addon updates by package name."
+	},
 	{
 		id: "devices",
 		group: "scope",
@@ -12503,7 +12675,8 @@ var NC_CONDITION_CATALOG = [
 			"immediate",
 			"track-end",
 			"device-event",
-			"package-event"
+			"package-event",
+			"system-event"
 		],
 		phase: "P1",
 		description: "Weekly activation windows (invertible); absent = always active."
@@ -12531,7 +12704,8 @@ var NcHistoryRecordKindSchema = zod.z.enum([
 	"object-event",
 	"track-end",
 	"device-event",
-	"package-event"
+	"package-event",
+	"system-event"
 ]);
 /** Subject summary frozen on the row at fire time (survives rule/record edits). */
 var NcHistorySubjectSchema = zod.z.object({
@@ -12539,7 +12713,14 @@ var NcHistorySubjectSchema = zod.z.object({
 	label: zod.z.string().optional(),
 	confidence: zod.z.number().optional(),
 	zones: zod.z.array(zod.z.string()),
-	timestamp: zod.z.number()
+	timestamp: zod.z.number(),
+	systemEvent: zod.z.object({
+		kind: NcSystemEventKindSchema,
+		subject: zod.z.string(),
+		title: zod.z.string(),
+		body: zod.z.string(),
+		data: zod.z.record(zod.z.string(), zod.z.unknown())
+	}).optional()
 });
 /**
 * One delivery-history row. This is a read-only VIEW over the durable
@@ -13046,21 +13227,32 @@ var ScopedTokenSchema = zod.z.object({
 *    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
 *    `/api/oauth2/integrations` are built from this collection alone.
 *
-* **Scopes.** `requestedScopes` is baked into every token this integration is
-* ever issued and the operator consents to it once. Derive it from the tRPC
-* paths the client calls **with that token**, against `METHOD_ACCESS_MAP`, and
-* prefer a narrow `capability:` scope to a `category:` one unless the client
-* genuinely needs a whole family. A category scope grants every future member
+* **Scopes. `requestedScopes` has exactly ONE meaning: what the integration
+* NEEDS to function.** Not a blast radius, not a conservative
+* under-declaration, not a description of some other path the addon happens to
+* have. Derive it from what the client actually calls **with this token** —
+* every tRPC path against `METHOD_ACCESS_MAP`, plus an `addon:` grant for every
+* addon HTTP route it posts to — and write the call that justifies each entry
+* next to it. Two integrations once used this field to mean two different
+* things; the operator ruled there is one meaning, and any third integration
+* inherits it (2026-08-09).
+*
+* This is not documentation, it is the ENFORCEMENT INPUT. Since
+* [D103](../../../../docs/decisions/adr-0103.md) the `/addon/:addonId/*` gate
+* checks an integration token's grant before letting it reach an
+* `access: 'authenticated'` route, so an **under-declaration is an integration
+* that stops working** — a missing `addon:` entry means `403 Token scope
+* mismatch` on every control the client tries to actuate. Widen the descriptor
+* honestly rather than weakening a check to make a route pass.
+*
+* Prefer a narrow `capability:` scope to a `category:` one unless the client
+* genuinely needs a whole family; a category scope grants every future member
 * of that category too. `category:system [create]` has been rejected once and
 * should stay rejected: it hands `addons.installPackage` to an integration.
 *
-* What it does NOT cover: calls the ADDON makes over `ctx.api`, which run as
-* the addon and are not scope-checked. Alexa's descriptor is narrower than
-* Home Assistant's for exactly that reason — its Lambda posts directives and
-* the addon does the work, while the Home Assistant component calls tRPC
-* directly with the token. So `requestedScopes` describes the blast radius of
-* the GRANT, not the reach of the integration; do not widen one to describe the
-* other.
+* Calls the ADDON itself makes over `ctx.api` run as the addon and are not
+* scope-checked, so they are not what this field describes — but reaching the
+* addon's route in the first place IS, and that is the entry to declare.
 *
 * **The boot window.** An addon registers its provider after its runner forks
 * and initialises, so between hub start and that moment this collection is
@@ -13101,7 +13293,30 @@ var OauthIntegrationDescriptorSchema = zod.z.object({
 	*  present, /api/oauth2/authorize bakes THIS into the code instead of the
 	*  hub-global `publicHubUrl()`, so a forked exporter addon (which can't set
 	*  the hub's env) drives the claim that its cloud Lambda routes back on. */
-	hubUrl: zod.z.string().optional()
+	hubUrl: zod.z.string().optional(),
+	/**
+	* How long a REFRESH token issued for this integration lives — seconds, or
+	* `'never'` for a token minted with no `exp` claim at all. Omit to keep the
+	* 30-day default, which is what every link used before this field existed.
+	*
+	* Declared here for the same reason `requestedScopes` is: the integration
+	* knows what it needs. Amazon's account linking and a Home Assistant config
+	* entry are both meant to survive indefinitely, and re-linking is a manual
+	* user action, so a 30-day expiry silently unlinks a working integration.
+	*
+	* **The security posture, stated so it is owned deliberately.** A refresh
+	* token that never expires is permanent access if it leaks. What bounds it is
+	* revocation, not time: `oauthRefresh` re-reads the session on every use and
+	* returns `null` once `revokedAt` is set, as does `oauthVerifyAccessToken`.
+	* The one gap is the ACCESS token — it is a plain signed JWT that nothing
+	* re-checks against the session on the `/trpc` and `/addon/*` paths, so
+	* revoking a link takes effect there only after its remaining hour. That hour
+	* is why the access TTL is not configurable.
+	*
+	* The value is baked into the authorization code at `/authorize` and travels
+	* on the tokens, so editing this field changes FUTURE links only.
+	*/
+	refreshTokenTtlSec: zod.z.union([zod.z.number().int().positive(), zod.z.literal("never")]).optional()
 });
 var oauthIntegrationCapability = {
 	name: "oauth-integration",
@@ -17616,7 +17831,16 @@ var SsoBridgeClaimsSchema = zod.z.object({
 	codeChallenge: zod.z.string().optional(),
 	/** OAuth session registry id — set on `oauth-access`/`oauth-refresh`
 	*  tokens so the verify path can check the session is not revoked. */
-	sessionId: zod.z.string().optional()
+	sessionId: zod.z.string().optional(),
+	/**
+	* The refresh lifetime this LINK was created with, in seconds, or `'never'`.
+	* Baked into the code at `/authorize` from the integration's descriptor and
+	* carried forward so `oauthRefresh` re-mints with the same lifetime. It rides
+	* on the token rather than being re-read from the descriptor on purpose:
+	* editing a descriptor must not retroactively extend or shorten a link the
+	* operator already consented to.
+	*/
+	refreshTtl: zod.z.union([zod.z.number().int().positive(), zod.z.literal("never")]).optional()
 });
 var ssoBridgeCapability = {
 	name: "sso-bridge",
@@ -17626,7 +17850,16 @@ var ssoBridgeCapability = {
 	methods: {
 		signBridgeToken: require_sleep.method(zod.z.object({
 			claims: SsoBridgeClaimsSchema,
-			ttlSec: zod.z.number().int().positive().optional()
+			/**
+			* Seconds, or `'never'` for a token minted with NO `exp` claim.
+			*
+			* `'never'` is a literal rather than `undefined`/`0` because omitting
+			* this field already means "the 5-minute SSO hand-off default", and
+			* `jwt.sign` THROWS on `{ expiresIn: undefined }` — a "no expiry" that
+			* went through the numeric path would fail at mint time and break
+			* linking rather than produce an eternal token.
+			*/
+			ttlSec: zod.z.union([zod.z.number().int().positive(), zod.z.literal("never")]).optional()
 		}), zod.z.object({ token: zod.z.string() })),
 		verifyBridgeToken: require_sleep.method(zod.z.object({ token: zod.z.string() }), SsoBridgeClaimsSchema.nullable())
 	}
@@ -26708,7 +26941,12 @@ var userManagementCapability = {
 			hubUrl: zod.z.string(),
 			/** PKCE (RFC 7636) S256 challenge. Baked into the signed code; a code
 			*  that carries one can ONLY be exchanged with the matching verifier. */
-			codeChallenge: zod.z.string().optional()
+			codeChallenge: zod.z.string().optional(),
+			/** The integration's declared refresh lifetime — seconds, or `'never'`.
+			*  From `OauthIntegrationDescriptor.refreshTokenTtlSec`. Baked into the
+			*  code so the link carries its own lifetime; omit for the 30-day
+			*  default. */
+			refreshTtlSec: zod.z.union([zod.z.number().int().positive(), zod.z.literal("never")]).optional()
 		}), zod.z.object({ code: zod.z.string() }), {
 			kind: "mutation",
 			access: "create"
@@ -40130,6 +40368,8 @@ exports.NcSnoozeInputSchema = NcSnoozeInputSchema;
 exports.NcSnoozeSchema = NcSnoozeSchema;
 exports.NcSnoozeScopeSchema = NcSnoozeScopeSchema;
 exports.NcSnoozeSuppressedSchema = NcSnoozeSuppressedSchema;
+exports.NcSystemEventConditionSchema = NcSystemEventConditionSchema;
+exports.NcSystemEventKindSchema = NcSystemEventKindSchema;
 exports.NcTaxonomyEntrySchema = NcTaxonomyEntrySchema;
 exports.NcTaxonomySchema = NcTaxonomySchema;
 exports.NcTestResultSchema = NcTestResultSchema;
@@ -40501,6 +40741,7 @@ exports.canConvertUnit = canConvertUnit;
 exports.canonicalEgressPlan = canonicalEgressPlan;
 exports.carbonMonoxideCapability = carbonMonoxideCapability;
 exports.cellsToRects = cellsToRects;
+exports.classifyBearerPrincipal = classifyBearerPrincipal;
 exports.classifyStream = classifyStream;
 exports.classifyStreams = classifyStreams;
 exports.climateControlCapability = climateControlCapability;
@@ -40647,6 +40888,7 @@ exports.mediaPlayerCapability = mediaPlayerCapability;
 exports.mergeSourceInfo = mergeSourceInfo;
 exports.meshNetworkCapability = meshNetworkCapability;
 exports.method = require_sleep.method;
+exports.methodAccessForHttpMethod = methodAccessForHttpMethod;
 exports.metricsProviderCapability = metricsProviderCapability;
 exports.modelConvertCapability = modelConvertCapability;
 exports.modelDistributorCapability = modelDistributorCapability;
@@ -40695,6 +40937,7 @@ exports.powerMeterCapability = powerMeterCapability;
 exports.prepareNotification = prepareNotification;
 exports.presenceCapability = presenceCapability;
 exports.pressureSensorCapability = pressureSensorCapability;
+exports.principalMayReachAddon = principalMayReachAddon;
 exports.privacyMaskCapability = privacyMaskCapability;
 exports.procedureAuthKey = procedureAuthKey;
 exports.ptzAutotrackCapability = ptzAutotrackCapability;
@@ -40730,6 +40973,8 @@ exports.runInferenceStep = runInferenceStep;
 exports.runtimeDevices = runtimeDevices;
 exports.sceneMonitorCapability = sceneMonitorCapability;
 exports.scopeKey = require_sleep.scopeKey;
+exports.scopesAllowAddon = scopesAllowAddon;
+exports.scopesAllowDeviceCap = scopesAllowDeviceCap;
 exports.scoreRuntimes = scoreRuntimes;
 exports.scriptRunnerCapability = scriptRunnerCapability;
 exports.selectAssignedProfileSlots = require_sleep.selectAssignedProfileSlots;