@camstack/system 1.2.69 → 1.2.71

package/dist/{dist-D7wC-S4p.js → dist-I0WgqQQ-.js}

@@ -4148,6 +4148,24 @@ var ConvertResultSchema = zod.z.object({
 	artifacts: zod.z.array(ConvertArtifactSchema).readonly()
 });
 /**
+* 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));
+}
+/**
 * Error types for the safe expression engine. Two distinct classes so callers
 * can tell a compile-time (grammar) failure from a runtime (evaluation)
 * failure — both are non-fatal to the host: read paths degrade to "skip link".
@@ -13022,6 +13040,76 @@ var ScopedTokenSchema = zod.z.object({
 * Each provider returns a static descriptor; the core enumerates them
 * to validate the `integration=` query param and resolve the consent
 * label + the scopes baked into the issued token.
+*
+* ## Declaring one
+*
+* An OAuth client is integration-specific knowledge — who the client is, what
+* it may ask for, where it may be sent — so it is declared by the ADDON that
+* owns the integration, never by the kernel and never as a branch inside
+* `oauth2-routes.ts` ([D101](../../../../docs/decisions/adr-0101.md)). Three
+* steps, no others:
+*
+* 1. Add `{ "name": "oauth-integration" }` to the addon's `camstack.addons[]`
+*    manifest entry. This is also what tells the hub, at addon-LOAD time, that
+*    a descriptor is owed — see "the boot window" below.
+* 2. Return a provider from `onInitialize()`:
+*
+*    ```ts
+*    const provider: IOauthIntegrationProvider = {
+*      getDescriptor: async () => ({
+*        integrationId: 'my-thing',      // the `integration=` query param
+*        displayName: 'My Thing',
+*        requestedScopes: [ … ],         // see below
+*        allowedRedirectPrefixes: ['https://callback.example/'],
+*      }),
+*    }
+*    return [{ capability: oauthIntegrationCapability, provider }]
+*    ```
+*
+*    The descriptor must be **static** — it is read on the authorize path, so
+*    never put an await on network or disk behind it, and never register it
+*    behind one either (a provider is registered only once `onInitialize`
+*    RETURNS, so anything awaited before the return delays linking).
+* 3. Nothing else. There is no allow-list to join, no id to register with the
+*    core, and no per-integration branch anywhere: `/api/oauth2/authorize` and
+*    `/api/oauth2/integrations` are built from this collection alone.
+*
+* **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.
+*
+* 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
+* incomplete and an `integrationId` can be legitimately absent. The core does
+* not wait, poll or cache around this ([D3](../../../../docs/decisions/adr-0003.md)):
+* it compares the manifest declarers against the registered providers and
+* answers `503 temporarily_unavailable` (with `Retry-After` and the pending
+* addon ids) instead of `400 unknown integration`, and reports
+* `complete: false` on `GET /api/oauth2/integrations`. A client should retry
+* while the list is incomplete rather than conclude the hub cannot do OAuth.
 */
 var OauthIntegrationDescriptorSchema = zod.z.object({
 	/** Stable id used as the `integration=` query param, e.g. 'export-alexa'. */
@@ -13052,7 +13140,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",
@@ -17357,7 +17468,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",
@@ -17367,7 +17487,16 @@ var ssoBridgeCapability = {
 	methods: {
 		signBridgeToken: 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: method(zod.z.object({ token: zod.z.string() }), SsoBridgeClaimsSchema.nullable())
 	}
@@ -26163,7 +26292,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"
@@ -33617,12 +33751,6 @@ Object.defineProperty(exports, "normalizeUnit", {
 		return normalizeUnit;
 	}
 });
-Object.defineProperty(exports, "oauthIntegrationCapability", {
-	enumerable: true,
-	get: function() {
-		return oauthIntegrationCapability;
-	}
-});
 Object.defineProperty(exports, "objectInputDeclaresAddonId", {
 	enumerable: true,
 	get: function() {
@@ -33677,6 +33805,18 @@ Object.defineProperty(exports, "scopeKey", {
 		return scopeKey;
 	}
 });
+Object.defineProperty(exports, "scopesAllowAddon", {
+	enumerable: true,
+	get: function() {
+		return scopesAllowAddon;
+	}
+});
+Object.defineProperty(exports, "scopesAllowDeviceCap", {
+	enumerable: true,
+	get: function() {
+		return scopesAllowDeviceCap;
+	}
+});
 Object.defineProperty(exports, "scoreRuntimes", {
 	enumerable: true,
 	get: function() {