@clockworkdog/cogs-client 3.0.4 → 3.1.0

package/dist/index.d.ts

@@ -7,6 +7,8 @@ export { SurfaceManager } from './state-based/SurfaceManager';
 export { MediaPreloader } from './state-based/MediaPreloader';
 export { assetUrl, preloadUrl } from './utils/urls';
 export { getStateAtTime } from './utils/getStateAtTime';
+export { NetworkHostPattern } from './utils/NetworkHostPattern';
 export * from './types/CogsPluginManifest';
 export * as ManifestTypes from './types/ManifestTypes';
 export * from './DataStore';
+export { getPluginManifestErrors } from './utils/getPluginManifestErrors';

package/dist/index.js

@@ -5,6 +5,8 @@ export { SurfaceManager } from './state-based/SurfaceManager';
 export { MediaPreloader } from './state-based/MediaPreloader';
 export { assetUrl, preloadUrl } from './utils/urls';
 export { getStateAtTime } from './utils/getStateAtTime';
+export { NetworkHostPattern } from './utils/NetworkHostPattern';
 export * from './types/CogsPluginManifest';
 export * as ManifestTypes from './types/ManifestTypes';
 export * from './DataStore';
+export { getPluginManifestErrors } from './utils/getPluginManifestErrors';

package/dist/types/CogsPluginManifest.d.ts

@@ -41,6 +41,40 @@ export type PluginManifestStateJson = {
     writableFromCogs?: true;
     writableFromClient?: true;
 };
+export type PluginManifestNetworkAccessRuleJson = {
+    /**
+     * Host patterns this rule grants outbound network access to.
+     *
+     * Every pattern must include an explicit port.
+     *
+     * | Pattern | Meaning |
+     * | --- | --- |
+     * | `"localhost:8080"` | Port 8080 on `localhost` / `127.0.0.1` / `::1` |
+     * | `"private:443"` | Port 443 on any RFC 1918 private address range (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) |
+     * | `"api.vendor.com:443"` | An exact hostname and port |
+     * | `"*.vendor.com:443"` | A wildcard subdomain, exact port |
+     * | `"foo.example.com:*"` | Any port on an exact hostname |
+     * | `"[fd00::1]:443"` | An IPv6 literal, using bracket syntax |
+     * | `"*:*"` | Any host, any port |
+     *
+     * CIDR ranges (e.g. `"192.168.1.0/24:443"`) are not supported.
+     *
+     * Every port on `localhost` / `127.0.0.1` / `::1` is always implicitly reachable regardless of
+     * these rules, since plugins connect to the COGS server at `localhost:12095` — a `"localhost:*"`
+     * pattern here is never required.
+     */
+    hosts: string[];
+    /**
+     * Paths, relative to the root of the packaged `.cogsplugin` archive, of PEM-encoded CA
+     * certificates to trust for HTTPS connections to the hosts matched by `hosts`.
+     *
+     * Use this to reach local devices with vendor-issued certificates that aren't in the system CA
+     * store (e.g. a Philips Hue bridge). For matched hosts, the certificate chain is verified
+     * against these CAs instead of the system store; all other hosts continue to use the system
+     * store.
+     */
+    caCertificates?: string[];
+};
 /**
  * `cogs-plugin-manifest.json` is a JSON manifest file describing the content of a COGS plugin or COGS Media Master custom content.
  *
@@ -141,6 +175,28 @@ export interface CogsPluginManifestJson {
             };
         };
     };
+    /**
+     * Elevated permissions for this plugin.
+     *
+     * **Only applies to verified, packaged (`.cogsplugin`) plugins.** It is ignored for plugins
+     * loaded from a folder, to maintain compatibility with the existing folder-based plugin
+     * structure.
+     */
+    permissions?: {
+        network?: {
+            /**
+             * Rules granting this plugin outbound network access to specific hosts, optionally with
+             * a bundled CA certificate for hosts using vendor-issued (rather than publicly-trusted)
+             * TLS certificates.
+             *
+             * Requests to hosts not matched by any rule here are blocked. By default a plugin has no
+             * network access beyond the COGS server itself.
+             *
+             * Added in COGS 5.11.0
+             */
+            access?: PluginManifestNetworkAccessRuleJson[];
+        };
+    };
 }
 /**
  * A readonly version of `PluginManifestJson`

package/dist/utils/NetworkHostPattern.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A single host pattern from a `PluginManifestNetworkAccessRuleJson`'s `hosts` array
+ * (e.g. `"private:443"`, `"*.vendor.com:443"`).
+ */
+export declare class NetworkHostPattern {
+    private readonly host;
+    private readonly port;
+    /**
+     * @throws If `pattern` has no port (or `*`) component.
+     */
+    constructor(pattern: string);
+    /** Checks whether `host` and `port` are matched by this pattern. */
+    validate(host: string, port: number): boolean;
+    private matchesHost;
+}

package/dist/utils/NetworkHostPattern.js

@@ -0,0 +1,65 @@
+import { Address4, Address6 } from 'ip-address';
+/**
+ * A single host pattern from a `PluginManifestNetworkAccessRuleJson`'s `hosts` array
+ * (e.g. `"private:443"`, `"*.vendor.com:443"`).
+ */
+export class NetworkHostPattern {
+    host;
+    port;
+    /**
+     * @throws If `pattern` has no port (or `*`) component.
+     */
+    constructor(pattern) {
+        // Split on the last `:` rather than the first, since a bracketed IPv6 host (e.g. "[fd00::1]")
+        // contains colons of its own.
+        const lastColonIndex = pattern.lastIndexOf(':');
+        const host = pattern.slice(0, lastColonIndex);
+        const port = pattern.slice(lastColonIndex + 1);
+        if (lastColonIndex === -1 || !/^(\d+|\*)$/.test(port)) {
+            throw new Error(`Invalid host pattern "${pattern}": a port (or "*") is required`);
+        }
+        this.host = host;
+        this.port = port;
+    }
+    /** Checks whether `host` and `port` are matched by this pattern. */
+    validate(host, port) {
+        return this.matchesHost(host) && (this.port === '*' || Number(this.port) === port);
+    }
+    matchesHost(host) {
+        // Hostnames are case-insensitive; IP literals are unaffected by lowercasing.
+        const patternHost = this.host.toLowerCase();
+        host = host.toLowerCase();
+        if (patternHost === '*') {
+            return true;
+        }
+        if (patternHost === 'localhost') {
+            return host === 'localhost' || isLoopback(host);
+        }
+        if (patternHost === 'private') {
+            return isPrivateIpv4(host);
+        }
+        if (patternHost.startsWith('*.')) {
+            // The leading dot in the suffix guarantees a full-label boundary, so "*.vendor.com"
+            // matches "api.vendor.com" but not "vendor.com".
+            return host.endsWith(patternHost.slice(1));
+        }
+        return patternHost === host;
+    }
+}
+/**
+ * RFC 1918 private address ranges: `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`.
+ */
+function isPrivateIpv4(host) {
+    return Address4.isValid(host) && new Address4(host).isPrivate();
+}
+/**
+ * Loopback ranges: `127.0.0.0/8` (RFC 5735) and `::1` (RFC 4291).
+ */
+function isLoopback(host) {
+    // Only IPv6 literals are ever bracketed (e.g. "[::1]"); `Address6` doesn't accept the brackets itself.
+    if (host.startsWith('[') && host.endsWith(']')) {
+        const address = host.slice(1, -1);
+        return Address6.isValid(address) && new Address6(address).isLoopback();
+    }
+    return (Address4.isValid(host) && new Address4(host).isLoopback()) || (Address6.isValid(host) && new Address6(host).isLoopback());
+}

package/dist/utils/getPluginManifestErrors.d.ts

@@ -0,0 +1,6 @@
+import { CogsPluginManifestJson, CogsValueTypeOptionWithDefault } from '../types/CogsPluginManifest';
+import { z } from 'zod/v4';
+export declare const cogsValueTypeOptionWithDefaultSchema: (options: {
+    defaultRequired: boolean;
+}) => z.ZodType<CogsValueTypeOptionWithDefault>;
+export declare function getPluginManifestErrors(manifest: CogsPluginManifestJson): string[] | null;

package/dist/utils/getPluginManifestErrors.js

@@ -0,0 +1,167 @@
+import { z } from 'zod/v4';
+import semver from 'semver';
+import { NetworkHostPattern } from './NetworkHostPattern';
+const uniqueStringArray = z.array(z.string().min(1)).refine((items) => new Set(items).size === items.length, {
+    message: 'Array items must be unique',
+});
+const cogsValueTypeStringSchema = z.strictObject({
+    type: z.literal('string'),
+});
+const cogsValueTypeNumberSchema = z.strictObject({
+    type: z.literal('number'),
+    integer: z.literal(true).optional(),
+    min: z.number().optional(),
+    max: z.number().optional(),
+});
+const cogsValueTypeBooleanSchema = z.strictObject({
+    type: z.literal('boolean'),
+});
+const cogsValueTypeOptionSchema = z.strictObject({
+    type: z.literal('option'),
+    options: uniqueStringArray,
+});
+const pluginCogsValueTypeJsonSchema = z.union([
+    cogsValueTypeStringSchema,
+    cogsValueTypeNumberSchema,
+    cogsValueTypeBooleanSchema,
+    cogsValueTypeOptionSchema,
+]);
+const cogsValueTypeStringWithDefaultSchema = (options) => (options.defaultRequired
+    ? z.strictObject({ type: z.literal('string'), default: z.string() })
+    : z.strictObject({ type: z.literal('string'), default: z.string().optional() }));
+const cogsValueTypeNumberWithDefaultSchema = (options) => (options.defaultRequired
+    ? z.strictObject({
+        type: z.literal('number'),
+        integer: z.boolean().optional(),
+        min: z.number().optional(),
+        max: z.number().optional(),
+        default: z.number(),
+    })
+    : z.strictObject({
+        type: z.literal('number'),
+        integer: z.boolean().optional(),
+        min: z.number().optional(),
+        max: z.number().optional(),
+        default: z.number().optional(),
+    }));
+const cogsValueTypeBooleanWithDefaultSchema = (options) => (options.defaultRequired
+    ? z.strictObject({ type: z.literal('boolean'), default: z.boolean() })
+    : z.strictObject({ type: z.literal('boolean'), default: z.boolean().optional() }));
+export const cogsValueTypeOptionWithDefaultSchema = (options) => (options.defaultRequired
+    ? z.strictObject({
+        type: z.literal('option'),
+        options: uniqueStringArray.optional(),
+        default: z.string().min(1),
+    })
+    : z.strictObject({
+        type: z.literal('option'),
+        options: uniqueStringArray.optional(),
+        default: z.string().min(1).optional(),
+    }));
+const pluginCogsValueTypeWithDefaultJsonSchema = (options) => z.union([
+    cogsValueTypeStringWithDefaultSchema(options),
+    cogsValueTypeNumberWithDefaultSchema(options),
+    cogsValueTypeBooleanWithDefaultSchema(options),
+    cogsValueTypeOptionWithDefaultSchema(options),
+]);
+const pluginManifestConfigJsonSchema = z.strictObject({
+    name: z.string().min(1),
+    value: pluginCogsValueTypeWithDefaultJsonSchema({ defaultRequired: false }),
+});
+const pluginManifestEventJsonSchema = z.strictObject({
+    name: z.string().min(1),
+    value: pluginCogsValueTypeJsonSchema.optional(),
+});
+const pluginManifestStateJsonSchema = z.strictObject({
+    name: z.string().min(1),
+    value: pluginCogsValueTypeWithDefaultJsonSchema({ defaultRequired: true }),
+    writableFromCogs: z.literal(true).optional(),
+    writableFromClient: z.literal(true).optional(),
+});
+const validateNetworkHostPattern = (pattern) => {
+    try {
+        new NetworkHostPattern(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const cogsPluginManifestJsonSchema = z
+    .strictObject({
+    version: z.union([
+        z.templateLiteral([z.uint32()]),
+        z.templateLiteral([z.uint32(), z.literal('.'), z.uint32()]),
+        z.templateLiteral([z.uint32(), z.literal('.'), z.uint32(), z.literal('.'), z.uint32()]),
+    ]),
+    name: z.string(),
+    minCogsVersion: z.templateLiteral([z.uint32(), z.literal('.'), z.uint32(), z.literal('.'), z.uint32()]).optional(),
+    description: z.string().optional(),
+    icon: z.string().optional(),
+    indexPath: z.string().optional(),
+    window: z
+        .object({
+        width: z.number().gt(0).int(),
+        height: z.number().gt(0).int(),
+        visible: z.boolean().optional(),
+    })
+        .optional(),
+    config: z.array(pluginManifestConfigJsonSchema).optional(),
+    events: z
+        .object({
+        fromCogs: z.array(pluginManifestEventJsonSchema).optional(),
+        toCogs: z.array(pluginManifestEventJsonSchema).optional(),
+    })
+        .optional(),
+    state: z.array(pluginManifestStateJsonSchema).optional(),
+    media: z
+        .object({
+        audio: z.literal(true).optional(),
+        video: z.literal(true).optional(),
+        images: z.literal(true).optional(),
+    })
+        .optional(),
+    store: z
+        .object({
+        items: z
+            .record(z.string(), z.strictObject({
+            persistValue: z.boolean().optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+    permissions: z
+        .strictObject({
+        network: z
+            .strictObject({
+            access: z
+                .array(z.strictObject({
+                hosts: z.array(z.string().refine(validateNetworkHostPattern, { error: 'Invalid network host pattern' })).min(1),
+                caCertificate: z.string().optional(),
+            }))
+                .optional(),
+        })
+            .optional(),
+    })
+        .optional(),
+})
+    // Check that network access rules are only present if minCogsVersion is at least 5.11.0
+    .refine((manifest) => {
+    if (!manifest.permissions?.network?.access) {
+        return true;
+    }
+    if (manifest.minCogsVersion && semver.gte(manifest.minCogsVersion, '5.11.0')) {
+        return true;
+    }
+    return false;
+}, {
+    path: ['permissions', 'network', 'access'],
+    message: 'minCogsVersion must be at least 5.11.0',
+});
+const validate = cogsPluginManifestJsonSchema;
+export function getPluginManifestErrors(manifest) {
+    const result = validate.safeParse(manifest);
+    if (result.success)
+        return null;
+    return result.error.issues.map((issue) => `${issue.path.join('.') || 'root'}: ${issue.message}`);
+}

package/package.json

@@ -3,7 +3,7 @@
   "description": "Connect to COGS to build a custom Media Master",
   "author": "Clockwork Dog <info@clockwork.dog>",
   "homepage": "https://github.com/clockwork-dog/cogs-sdk/tree/main/packages/javascript",
-  "version": "3.0.4",
+  "version": "3.1.0",
   "keywords": [],
   "license": "MIT",
   "repository": {
@@ -37,8 +37,10 @@
     "cy:generate": "cypress run --e2e"
   },
   "dependencies": {
-    "@clockworkdog/timesync": "^3.0.4",
+    "@clockworkdog/timesync": "^3.1.0",
+    "ip-address": "^10.2.0",
     "reconnecting-websocket": "^4.4.0",
+    "semver": "^7.8.5",
     "zod": "^4.1.13"
   },
   "devDependencies": {
@@ -46,6 +48,7 @@
     "@eslint/js": "^9.17.0",
     "@types/jsdom": "^27",
     "@types/node": "^22.10.2",
+    "@types/semver": "^7",
     "cypress": "^14.5.4",
     "eslint": "^9.17.0",
     "eslint-config-prettier": "^9.1.0",