@camstack/types 1.2.67 → 1.2.69

package/dist/schemas/access-roles.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The two questions the operator-facing Access panel asks, as pure logic.
+ *
+ *   1. WHAT can this user do?      → an {@link AccessRoleId}
+ *   2. On WHICH devices?           → a {@link DeviceSelector} + `includeLinked`
+ *
+ * and the composition of those two answers into the `TokenScope[]` the v3
+ * enforcement matcher actually reads.
+ *
+ * Why this is not a {@link SCOPE_PRESETS} entry: a preset is a frozen list of
+ * rows an operator drops into the raw picker. A ROLE is only half a grant set
+ * — its device row carries the selector chosen in question 2 — so it cannot be
+ * pre-baked. The two coexist: `SCOPE_PRESETS` fills the Advanced picker,
+ * `ACCESS_ROLES` drives the simple panel.
+ *
+ * The one rule that makes the pairing work: a role NEVER emits a
+ * `category:device` row. That row is unrestricted device reach
+ * (`hasUnrestrictedDeviceReach` in `device-selector.ts` / `scope-access.ts`)
+ * and would silently discard the operator's device choice — the panel would
+ * show "3 cameras" over a grant that reaches all of them. The device row is
+ * always `{type:'device', selector}` so question 2 is load-bearing; a
+ * selector of `{kind:'all'}` is the deliberate way to say "everything", and
+ * the matcher treats it as the same unrestricted reach.
+ *
+ * The `category:system` row is what makes a role USEFUL: recordings, the
+ * events feed, faces and playback manifests live on system-scope caps, so a
+ * device grant alone reaches almost nothing a viewer wants. It is safe at
+ * these tiers because (a) admin-tier methods are refused by the auth gate
+ * regardless of scope, and (b) every system-scope method that NAMES a device
+ * is cut back to the role's own device set by the F1 #3 device-reference gate.
+ *
+ * Lives in `@camstack/types` next to `device-selector.ts` for the same reason
+ * that file does: the admin UI composes these and the backend resolves them,
+ * and a hand-copied second derivation drifts (D103).
+ */
+import type { DeviceSelector, MethodAccess, TokenScope } from './auth-records.js';
+/** The three answers to "what can this user do". */
+export type AccessRoleId = 'viewer' | 'operator' | 'manager';
+export interface AccessRoleSpec {
+    readonly id: AccessRoleId;
+    /** Radio-button label. */
+    readonly label: string;
+    /** One sentence saying what the role can do — shown under the label. */
+    readonly description: string;
+    /** Access flavours carried by the role's `device` grant. */
+    readonly deviceAccess: readonly MethodAccess[];
+    /** Access flavours carried by the role's `category:system` grant. */
+    readonly systemAccess: readonly MethodAccess[];
+}
+/**
+ * Ordered widest-last — the panel renders them top to bottom and the operator
+ * reads the list as an escalation.
+ */
+export declare const ACCESS_ROLES: readonly AccessRoleSpec[];
+/** Look a role up by id. Throws on an unknown id — the union makes that
+ *  unreachable from typed callers, and a silent fallback would grant the
+ *  wrong thing. */
+export declare function roleSpec(id: AccessRoleId): AccessRoleSpec;
+/** A complete answer to both panel questions. */
+export interface AccessRoleAssignment {
+    readonly roleId: AccessRoleId;
+    readonly selector: DeviceSelector;
+    /**
+     * Whether a grant on a parent device covers its accessory children.
+     * ALWAYS written explicitly — see {@link buildRoleScopes}.
+     */
+    readonly includeLinked: boolean;
+}
+/**
+ * Compose an assignment into the grants the matcher reads.
+ *
+ * `includeLinked` is written explicitly in BOTH directions on purpose. Absent,
+ * the matcher derives it from the access flavour (`view` inherits, `create` /
+ * `delete` do not), so an omitted `false` would silently re-grant the
+ * accessories the operator just excluded, and the panel would be lying about
+ * its own toggle.
+ */
+export declare function buildRoleScopes(assignment: AccessRoleAssignment): TokenScope[];
+/**
+ * Recover the assignment behind a grant set, or `null` when the grants are
+ * not something this panel authored.
+ *
+ * `null` is not an error — it is the "Advanced" case, and the panel MUST show
+ * it as such rather than defaulting the radio to a role the user does not
+ * have. Silently rendering an unrecognised grant set as "View" would make the
+ * next save a downgrade nobody asked for.
+ *
+ * Strict by design: exactly the two rows `buildRoleScopes` writes, an
+ * explicit `includeLinked`, and device/system access that agree on a single
+ * role. Anything else belongs in the raw editor.
+ */
+export declare function detectAccessRole(scopes: readonly TokenScope[]): AccessRoleAssignment | null;

package/dist/schemas/auth-records.d.ts

@@ -10,6 +10,7 @@
  * keeps the original name for backward compatibility.
  */
 import { z } from 'zod';
+import { DeviceType } from '../device/device-type.js';
 /**
  * Auth model (v2 — 2026-05-12 caps-only):
  *
@@ -37,7 +38,62 @@ export declare const CapScopeSchema: z.ZodEnum<{
     device: "device";
 }>;
 export type CapScope = z.infer<typeof CapScopeSchema>;
-export declare const TokenScopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+/**
+ * DeviceSelector (scope model v3 — 2026-08-12).
+ *
+ * A `device` grant no longer carries a frozen list of deviceIds. It carries
+ * a SELECTOR the matcher resolves against the live fleet, so the grant can be
+ * DYNAMIC: a `types:['camera']` selector automatically covers a camera added
+ * AFTER the grant was minted — no re-grant, no re-login.
+ *
+ *   - `all`       — every device in the deployment. The broad viewer/operator
+ *     lever without a `category` grant (a `category` grant also covers device
+ *     caps that carry no deviceId; `all` is specifically the device set).
+ *   - `ids`       — an explicit deviceId list. This is what a v2 `device:[…]`
+ *     grant migrates to (see {@link TokenScopeSchema}); STATIC — a new camera
+ *     is NOT covered until the grant is edited.
+ *   - `types`     — every device of a `DeviceType` (e.g. every `camera`).
+ *     DYNAMIC. A device that changes type, or a new device of the type,
+ *     re-resolves on the next request.
+ *   - `locations` — every device whose operator-assigned `location` label is
+ *     in the set (e.g. "Garden", "Front door"). DYNAMIC. A device with a
+ *     null/unset location matches NO `locations` selector.
+ */
+export declare const DeviceSelectorSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"all">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"ids">;
+    ids: z.ZodArray<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"types">;
+    types: z.ZodArray<z.ZodEnum<typeof DeviceType>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"locations">;
+    locations: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "kind">;
+export type DeviceSelector = z.infer<typeof DeviceSelectorSchema>;
+declare const DeviceTokenScopeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"device">;
+    selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"all">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"ids">;
+        ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"types">;
+        types: z.ZodArray<z.ZodEnum<typeof DeviceType>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"locations">;
+        locations: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "kind">;
+    access: z.ZodArray<z.ZodEnum<{
+        view: "view";
+        create: "create";
+        delete: "delete";
+    }>>;
+    includeLinked: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const TokenScopeSchema: z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"category">;
     target: z.ZodEnum<{
         system: "system";
@@ -66,14 +122,28 @@ export declare const TokenScopeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"device">;
-    targets: z.ZodArray<z.ZodString>;
+    selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"all">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"ids">;
+        ids: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"types">;
+        types: z.ZodArray<z.ZodEnum<typeof DeviceType>>;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"locations">;
+        locations: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "kind">;
     access: z.ZodArray<z.ZodEnum<{
         view: "view";
         create: "create";
         delete: "delete";
     }>>;
-}, z.core.$strip>], "type">;
+    includeLinked: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>], "type">>;
 export type TokenScope = z.infer<typeof TokenScopeSchema>;
+/** The `device`-typed member of {@link TokenScope}, narrowed for matchers. */
+export type DeviceTokenScope = z.infer<typeof DeviceTokenScopeSchema>;
 export declare const UserRecordSchema: z.ZodObject<{
     id: z.ZodString;
     username: z.ZodString;
@@ -81,7 +151,7 @@ export declare const UserRecordSchema: z.ZodObject<{
     isAdmin: z.ZodDefault<z.ZodBoolean>;
     allowedProviders: z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>;
     allowedDevices: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodLiteral<"*">, z.ZodArray<z.ZodString>]>>;
-    scopes: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    scopes: z.ZodDefault<z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"category">;
         target: z.ZodEnum<{
             system: "system";
@@ -110,13 +180,25 @@ export declare const UserRecordSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"device">;
-        targets: z.ZodArray<z.ZodString>;
+        selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"all">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"ids">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"types">;
+            types: z.ZodArray<z.ZodEnum<typeof DeviceType>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"locations">;
+            locations: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>], "kind">;
         access: z.ZodArray<z.ZodEnum<{
             view: "view";
             create: "create";
             delete: "delete";
         }>>;
-    }, z.core.$strip>], "type">>>;
+        includeLinked: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>], "type">>>>;
     createdAt: z.ZodNumber;
     updatedAt: z.ZodNumber;
 }, z.core.$strip>;
@@ -139,7 +221,7 @@ export declare const ScopedTokenSchema: z.ZodObject<{
     name: z.ZodString;
     tokenHash: z.ZodString;
     tokenPrefix: z.ZodString;
-    scopes: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    scopes: z.ZodArray<z.ZodPreprocess<z.ZodDiscriminatedUnion<[z.ZodObject<{
         type: z.ZodLiteral<"category">;
         target: z.ZodEnum<{
             system: "system";
@@ -168,15 +250,28 @@ export declare const ScopedTokenSchema: z.ZodObject<{
         }>>;
     }, z.core.$strip>, z.ZodObject<{
         type: z.ZodLiteral<"device">;
-        targets: z.ZodArray<z.ZodString>;
+        selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"all">;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"ids">;
+            ids: z.ZodArray<z.ZodNumber>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"types">;
+            types: z.ZodArray<z.ZodEnum<typeof DeviceType>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"locations">;
+            locations: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>], "kind">;
         access: z.ZodArray<z.ZodEnum<{
             view: "view";
             create: "create";
             delete: "delete";
         }>>;
-    }, z.core.$strip>], "type">>;
+        includeLinked: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>], "type">>>;
     expiresAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     lastUsedAt: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     createdAt: z.ZodNumber;
 }, z.core.$strip>;
 export type ScopedToken = z.infer<typeof ScopedTokenSchema>;
+export {};

package/dist/schemas/device-selector.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Pure DeviceSelector semantics — scope model v3 (2026-08-12).
+ *
+ * One derivation of "does this grant cover this device", reused by:
+ *   - the enforcement matcher (`server/backend/.../scope-access.ts`), per
+ *     request, against a single deviceId + its ancestors;
+ *   - response projection + `auth.me`, against the WHOLE fleet, to compute
+ *     the viewable device set and the effective-scope summary the UI reads.
+ *
+ * Lives in `@camstack/types` (framework, train-bound) because BOTH the
+ * backend enforcement path and any addon/UI need the same rule — the F0.x
+ * lesson that a hand-copied scope check drifts (D103).
+ *
+ * No I/O, no registry — the fleet + parentage are passed in.
+ */
+import type { DeviceSelector, DeviceTokenScope, MethodAccess, TokenScope } from './auth-records.js';
+/** The minimal device shape selectors resolve against. */
+export interface DeviceMetaLike {
+    readonly id: number;
+    /** `DeviceType` string value (e.g. `'camera'`). */
+    readonly type: string;
+    /** Operator-assigned location label; `null` when unset. */
+    readonly location: string | null;
+    readonly parentDeviceId: number | null;
+}
+/**
+ * Does `selector` cover `device` DIRECTLY (no inheritance)? Inheritance is
+ * layered on by the resolver/matcher, which tests this against a device's
+ * ancestors too.
+ */
+export declare function deviceSelectorMatches(selector: DeviceSelector, device: DeviceMetaLike): boolean;
+/** Whether inheritance applies for a grant at `access` (view inherits, others
+ *  don't, unless the grant overrides via `includeLinked`). */
+export declare function scopeInherits(scope: DeviceTokenScope, access: MethodAccess): boolean;
+/**
+ * Resolve the set of deviceIds the caller may reach at `access`, expanded
+ * against the live `fleet`. A `category:device` grant returns the whole
+ * fleet. Device selectors are matched per device — directly, or (when the
+ * grant inherits) against an ancestor, so a parent grant covers its
+ * accessories.
+ */
+export declare function resolveViewableDeviceIds(scopes: readonly TokenScope[], fleet: readonly DeviceMetaLike[], access: MethodAccess): Set<number>;
+/**
+ * Normalise a raw scope array read off a JWT payload or a stored record into
+ * validated v3 `TokenScope`s, migrating any v2 `device:targets` grant on the
+ * way (via {@link TokenScopeSchema}'s preprocess). Applied at the request
+ * boundary (`resolveUser`) so the enforcement matcher only ever sees v3.
+ *
+ * Per-ITEM parse (not whole-array) so a single malformed scope is dropped
+ * without discarding the caller's valid grants — losing a good grant reads as
+ * a lockout, and a lockout reads as broken. A non-array input yields `[]`
+ * (fail closed).
+ */
+export declare function normalizeTokenScopes(raw: unknown): TokenScope[];
+/** A capability/addon grant flattened for the UI. */
+export interface ScopeGrantSummary {
+    readonly name: string;
+    readonly access: readonly MethodAccess[];
+}
+/** Per-access device reach — a COUNT and the "everything" flag, never the id
+ *  list (the UI hides surfaces from counts; it never needs the ids). */
+export interface DeviceReachSummary {
+    readonly all: boolean;
+    readonly deviceCount: number;
+}
+/**
+ * The resolved, effective scope the caller actually has — what `auth.me`
+ * returns so the viewer (F3/F4) can HIDE out-of-scope surfaces. Selectors are
+ * expanded to counts/flags against the live fleet, never to raw id lists.
+ */
+export interface EffectiveScope {
+    readonly isAdmin: boolean;
+    /** true iff every device is viewable (admin, `category:device[view]`, or a
+     *  device grant with an `all` selector). */
+    readonly allDevicesViewable: boolean;
+    /** How many devices the caller may VIEW right now. */
+    readonly viewableDeviceCount: number;
+    /** Device reach per access flavour. */
+    readonly device: Readonly<Record<MethodAccess, DeviceReachSummary>>;
+    /** `category:system` access flavours held. */
+    readonly system: readonly MethodAccess[];
+    /** `capability:<name>` grants. */
+    readonly capabilities: readonly ScopeGrantSummary[];
+    /** `addon:<id>` grants. */
+    readonly addons: readonly ScopeGrantSummary[];
+}
+/** Build the {@link EffectiveScope} for a caller from their scopes + the fleet. */
+export declare function summarizeEffectiveScope(scopes: readonly TokenScope[], fleet: readonly DeviceMetaLike[], isAdmin: boolean): EffectiveScope;

package/dist/{sleep-CSgK0rNX.mjs → sleep-CwERnGrD.mjs}

@@ -2901,6 +2901,7 @@ function createDeviceProxy(api, binding, opts) {
 			humiditySensor: createSliceHandle(stateSource, binding.deviceId, "humidity-sensor"),
 			image: createSliceHandle(stateSource, binding.deviceId, "image"),
 			imageSettings: createSliceHandle(stateSource, binding.deviceId, "image-settings"),
+			intercom: createSliceHandle(stateSource, binding.deviceId, "intercom"),
 			lawnMowerControl: createSliceHandle(stateSource, binding.deviceId, "lawn-mower-control"),
 			lockControl: createSliceHandle(stateSource, binding.deviceId, "lock-control"),
 			mediaPlayer: createSliceHandle(stateSource, binding.deviceId, "media-player"),

package/dist/{sleep-Dh1EJSqF.js → sleep-YuacOD41.js}

@@ -2901,6 +2901,7 @@ function createDeviceProxy(api, binding, opts) {
 			humiditySensor: createSliceHandle(stateSource, binding.deviceId, "humidity-sensor"),
 			image: createSliceHandle(stateSource, binding.deviceId, "image"),
 			imageSettings: createSliceHandle(stateSource, binding.deviceId, "image-settings"),
+			intercom: createSliceHandle(stateSource, binding.deviceId, "intercom"),
 			lawnMowerControl: createSliceHandle(stateSource, binding.deviceId, "lawn-mower-control"),
 			lockControl: createSliceHandle(stateSource, binding.deviceId, "lock-control"),
 			mediaPlayer: createSliceHandle(stateSource, binding.deviceId, "media-player"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.67",
+  "version": "1.2.69",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",