@coffeerunhobby/mcp-ha-connect 2.3.1 → 2.4.0

package/README.md

@@ -160,7 +160,7 @@ Known limit: cancellations and answers are kept in memory. After a restart, some
 | `listCalendars` | List all calendar entities |
 | `getCalendarEvents` | Get events from one or all calendars |
 
-### Omada Network Tools (36)
+### Omada Network Tools (49)
 
 #### Site Tools
 
@@ -217,6 +217,19 @@ Known limit: cancellations and answers are kept in memory. After a restart, some
 | `omada_setMacGroupEntry` | Add a MAC to a MAC group, or rename its entry (needs `CONFIGURE`) |
 | `omada_removeMacGroupEntry` | Remove a MAC from a MAC group (needs `CONFIGURE`) |
 
+#### Access Control (schedules, groups, gateway ACLs)
+
+Lets the controller enforce a schedule itself (e.g. a curfew) instead of a daily block/unblock loop. All writes need `CONFIGURE`.
+
+| Tool | Description |
+|------|-------------|
+| `omada_listAccessControl` | Time ranges (readable windows), IP groups and gateway ACL rules with names and schedules (graph mode: `omada_read` `/profiles/time-range`, `/profiles/ip-groups`, `/network/acls/gateway`) |
+| `omada_createTimeRange` / `omada_updateTimeRange` / `omada_deleteTimeRange` | Weekly schedules in quarter hours, e.g. `{days:["mon","tue"], start:"14:30", end:"19:00"}`; `invertWindows` turns allowed hours into the blocked ones. Delete is refused while a rule uses it |
+| `omada_createGroup` / `omada_deleteGroup` | IP groups (ACL sources/destinations) and MAC groups (SSID allow/deny lists); delete is refused for built-in groups and groups in use |
+| `omada_setDhcpReservation` / `omada_removeDhcpReservation` | Fixed IP for a device (so an ACL can match it); refuses an address reserved for another device |
+| `omada_createGatewayAcl` / `omada_updateGatewayAcl` / `omada_deleteGatewayAcl` / `omada_moveGatewayAcl` | Gateway (router) LAN-to-internet rules: allow/deny a source (IP group, LAN network or SSID), optionally only during a time range; covers wired and Wi-Fi |
+| `omada_setSsidMacFilter` | Turn an SSID's MAC filter on (MAC group as allow or deny list) or off; reports and refuses to disconnect connected clients unless `allowLockout`; `dryRun` previews |
+
 #### Security Tools
 
 | Tool | Description |

package/dist/omadaClient/accessControl.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Controller-side access control: time-range profiles, IP/MAC group profiles,
+ * DHCP reservations, gateway ACL rules and the SSID MAC filter. These let a
+ * schedule (e.g. a curfew) be enforced by the controller itself instead of a
+ * daily block/unblock loop.
+ *
+ * Omada's create endpoints return no id, so new objects are found again by
+ * their (required unique) name or description. Deletes refuse objects that are
+ * still in use, and the SSID MAC filter refuses to lock out connected clients
+ * unless told to.
+ */
+import type { ClientOperations } from './client.js';
+import type { MacGroupOperations } from './macGroups.js';
+import type { NetworkOperations } from './network.js';
+import type { RequestHandler } from './request.js';
+import type { SiteOperations } from './site.js';
+import { type TimeRangeEntry } from './timeRange.js';
+export declare const IP_GROUP_TYPE = 0;
+/** All protocols, in Omada's ACL protocol numbering. */
+export declare const ALL_PROTOCOLS = 256;
+declare const SOURCE_TYPES: {
+    readonly network: 0;
+    readonly ipGroup: 1;
+    readonly ssid: 4;
+};
+declare const DESTINATION_TYPES: {
+    readonly network: 0;
+    readonly ipGroup: 1;
+};
+export type AclSourceType = keyof typeof SOURCE_TYPES;
+export type AclDestinationType = keyof typeof DESTINATION_TYPES;
+export interface TimeRangeProfile {
+    profileId: string;
+    name: string;
+    dayMode?: number;
+    timeList?: TimeRangeEntry[];
+    [field: string]: unknown;
+}
+export interface IpGroup {
+    groupId: string;
+    name: string;
+    buildIn?: boolean;
+    ipList?: Array<{
+        ip: string;
+        mask: number;
+        description?: string;
+    }>;
+    [field: string]: unknown;
+}
+export interface DhcpReservation {
+    netId: string;
+    mac: string;
+    ip?: string;
+    description?: string;
+    status?: boolean;
+    options?: unknown[];
+    [field: string]: unknown;
+}
+export interface GatewayAcl {
+    id: string;
+    index?: number;
+    description: string;
+    status: boolean;
+    policy: number;
+    protocols: number[];
+    sourceType: number;
+    sourceIds: string[];
+    destinationType: number;
+    destinationIds?: string[];
+    syslog?: boolean;
+    direction?: {
+        lanToWan: boolean;
+        lanToLan: boolean;
+        wanInIds: string[];
+        vpnInIds: string[];
+    };
+    stateMode?: number;
+    states?: unknown;
+    timeRangeId?: string;
+    [field: string]: unknown;
+}
+export interface GatewayAclInput {
+    description: string;
+    policy: 'allow' | 'deny';
+    source: {
+        type: AclSourceType;
+        ids: string[];
+    };
+    /** Default: the built-in IP group IPGroup_Any (everything). */
+    destination?: {
+        type: AclDestinationType;
+        ids: string[];
+    };
+    protocols?: number[];
+    /** Time-range profile (id or name) during which the rule applies; omitted = always. */
+    timeRange?: string;
+    enabled?: boolean;
+}
+export interface GatewayAclChanges {
+    description?: string;
+    policy?: 'allow' | 'deny';
+    source?: {
+        type: AclSourceType;
+        ids: string[];
+    };
+    destination?: {
+        type: AclDestinationType;
+        ids: string[];
+    };
+    protocols?: number[];
+    /** Profile id or name; null removes the schedule (rule always applies). */
+    timeRange?: string | null;
+    enabled?: boolean;
+}
+export interface SsidMacFilterChange {
+    ssid: string;
+    ssidId: string;
+    before: {
+        enabled: boolean;
+        policy?: 'allow' | 'deny';
+        group?: string;
+    };
+    after: {
+        enabled: boolean;
+        policy?: 'allow' | 'deny';
+        group?: string;
+    };
+    /** Currently connected clients of this SSID the new setting would cut off. */
+    wouldLockOut: Array<{
+        mac: string;
+        name?: string;
+    }>;
+    applied: boolean;
+}
+export declare class AccessControlOperations {
+    private readonly request;
+    private readonly site;
+    private readonly buildPath;
+    private readonly network;
+    private readonly macGroups;
+    private readonly clients;
+    constructor(request: RequestHandler, site: SiteOperations, buildPath: (path: string) => string, network: NetworkOperations, macGroups: MacGroupOperations, clients: ClientOperations);
+    createTimeRange(...a: Parameters<AccessControlOperations['createTimeRangeUnlocked']>): Promise<{
+        profileId: string;
+        name: string;
+        windows: string[];
+    }>;
+    updateTimeRange(...a: Parameters<AccessControlOperations['updateTimeRangeUnlocked']>): Promise<{
+        profileId: string;
+        name: string;
+        before: string[];
+        after: string[];
+    }>;
+    deleteTimeRange(...a: Parameters<AccessControlOperations['deleteTimeRangeUnlocked']>): Promise<{
+        profileId: string;
+        name: string;
+        deleted: boolean;
+    }>;
+    createGroup(...a: Parameters<AccessControlOperations['createGroupUnlocked']>): Promise<{
+        groupId: string;
+        name: string;
+        type: "mac" | "ip";
+        entries: {
+            ip: string;
+            mask: number;
+        }[] | {
+            name: string;
+            macAddress: string;
+        }[] | undefined;
+    }>;
+    deleteGroup(...a: Parameters<AccessControlOperations['deleteGroupUnlocked']>): Promise<{
+        groupId: string;
+        name: string;
+        type: "mac" | "ip";
+        deleted: boolean;
+    }>;
+    setDhcpReservation(...a: Parameters<AccessControlOperations['setDhcpReservationUnlocked']>): Promise<{
+        mac: string;
+        ip: string;
+        network: string;
+        action: "unchanged";
+    } | {
+        note: string;
+        previousIp?: string | undefined;
+        mac: string;
+        ip: string;
+        network: string;
+        action: "updated" | "created";
+    }>;
+    removeDhcpReservation(...a: Parameters<AccessControlOperations['removeDhcpReservationUnlocked']>): Promise<{
+        mac: string;
+        action: "not-present";
+        ip?: undefined;
+    } | {
+        mac: string;
+        ip: string | undefined;
+        action: "removed";
+    }>;
+    createGatewayAcl(...a: Parameters<AccessControlOperations['createGatewayAclUnlocked']>): Promise<{
+        id: string;
+        position: number | undefined;
+        description: string;
+        enabled: boolean;
+        policy: string;
+        source: string;
+        destination: string;
+        schedule: string | {
+            profileId: string;
+            name: string | undefined;
+            windows: string[] | undefined;
+        };
+    }>;
+    updateGatewayAcl(...a: Parameters<AccessControlOperations['updateGatewayAclUnlocked']>): Promise<{
+        id: string;
+        position: number | undefined;
+        description: string;
+        enabled: boolean;
+        policy: string;
+        source: string;
+        destination: string;
+        schedule: string | {
+            profileId: string;
+            name: string | undefined;
+            windows: string[] | undefined;
+        };
+    }>;
+    deleteGatewayAcl(...a: Parameters<AccessControlOperations['deleteGatewayAclUnlocked']>): Promise<{
+        id: string;
+        description: string;
+        deleted: boolean;
+    }>;
+    moveGatewayAcl(...a: Parameters<AccessControlOperations['moveGatewayAclUnlocked']>): Promise<{
+        order: string[];
+    }>;
+    setSsidMacFilter(...a: Parameters<AccessControlOperations['setSsidMacFilterUnlocked']>): Promise<SsidMacFilterChange>;
+    private locked;
+    private sitePath;
+    private send;
+    listTimeRanges(siteId?: string): Promise<Array<TimeRangeProfile & {
+        windows: string[];
+    }>>;
+    private createTimeRangeUnlocked;
+    private updateTimeRangeUnlocked;
+    private deleteTimeRangeUnlocked;
+    /** What references a time range: gateway and switch ACL rules, SSID WLAN schedules. */
+    private timeRangeUsers;
+    private resolveTimeRange;
+    listIpGroups(siteId?: string): Promise<IpGroup[]>;
+    /** Create an IP group (addresses as "a.b.c.d" or "a.b.c.d/n") or a MAC group. */
+    private createGroupUnlocked;
+    private deleteGroupUnlocked;
+    listDhcpReservations(siteId?: string): Promise<DhcpReservation[]>;
+    /** Reserve `ip` for a MAC (create or change). The LAN network is the one whose subnet holds the IP. */
+    private setDhcpReservationUnlocked;
+    private removeDhcpReservationUnlocked;
+    listGatewayAcls(siteId?: string): Promise<GatewayAcl[]>;
+    private createGatewayAclUnlocked;
+    private updateGatewayAclUnlocked;
+    private deleteGatewayAclUnlocked;
+    /** Move a rule to `position` (1 = evaluated first); the others keep their order. */
+    private moveGatewayAclUnlocked;
+    /** A rule with names instead of ids, for responses. */
+    describeAcl(acl: GatewayAcl, siteId?: string): Promise<{
+        id: string;
+        position: number | undefined;
+        description: string;
+        enabled: boolean;
+        policy: string;
+        source: string;
+        destination: string;
+        schedule: string | {
+            profileId: string;
+            name: string | undefined;
+            windows: string[] | undefined;
+        };
+    }>;
+    private resolveEndpoints;
+    /** Ids or names of IP groups, LAN networks or SSIDs -> ids. */
+    private resolveIds;
+    private endpointNames;
+    private timeRangeId;
+    private listSsidFilters;
+    /**
+     * Turn an SSID's MAC filter on (allow or deny list = a MAC group) or off.
+     * Reports which connected clients of that SSID the new setting would cut off,
+     * and refuses to apply then unless `allowLockout` is set. dryRun only reports.
+     */
+    private setSsidMacFilterUnlocked;
+}
+export {};