@tillstack/cli 0.2.0

package/dist/rules.js

@@ -0,0 +1,175 @@
+// Rules-as-code for TillShield's inline WAF.
+//
+// The dashboard is fine for one-off tweaks, but a security team wants its edge
+// rules in version control: reviewed in a PR, diffed, rolled back with `git
+// revert`, applied from CI. This module turns the server's rule set into a flat,
+// stable document and reconciles a desired document back onto the server.
+//
+// The natural key is the rule NAME (unique per org by convention). Apply matches
+// desired↔existing by name and produces a create / update / delete plan:
+//   • in file, not on server        → create
+//   • in both, content differs      → update (PATCH by id)
+//   • in both, content identical    → unchanged (no request)
+//   • on server, not in file        → delete  — ONLY with --prune
+//
+// `export` then immediate `apply` must be a no-op, so export and the diff share
+// one canonical form (canonicalRule). We are deliberately dependency-free — the
+// document is JSON, which is diffable, PR-reviewable and needs no parser.
+export const RULES_DOC_VERSION = 1;
+// Field order is fixed so a stringified rule is stable regardless of how the
+// server (or a hand-edited file) happened to order keys.
+const MATCH_KEYS = [
+    'ip_cidrs',
+    'paths',
+    'methods',
+    'countries',
+    'user_agent_regex',
+    'threat_intel',
+];
+function canonicalMatch(m) {
+    const out = {};
+    if (!m || typeof m !== 'object')
+        return out;
+    for (const k of MATCH_KEYS) {
+        const v = m[k];
+        if (v === undefined || v === null)
+            continue;
+        // Drop empty arrays / empty strings so "unset" and "set to nothing" match.
+        if (Array.isArray(v)) {
+            if (v.length > 0)
+                out[k] = v;
+        }
+        else if (typeof v === 'string') {
+            if (v.length > 0)
+                out[k] = v;
+        }
+        else {
+            ;
+            out[k] = v;
+        }
+    }
+    return out;
+}
+function canonicalRateLimit(r) {
+    if (!r || typeof r !== 'object')
+        return null;
+    if (typeof r.requests !== 'number' || typeof r.window_seconds !== 'number')
+        return null;
+    return { requests: r.requests, window_seconds: r.window_seconds, by: r.by ?? 'ip' };
+}
+/** Normalize any rule-shaped object (server row OR file entry) to canonical form. */
+export function canonicalRule(r) {
+    return {
+        name: String(r.name ?? '').trim(),
+        description: r.description ?? null,
+        project_id: r.project_id ?? null,
+        enabled: r.enabled !== false,
+        priority: typeof r.priority === 'number' ? r.priority : 100,
+        mode: (r.mode ?? 'block'),
+        match: canonicalMatch(r.match),
+        rate_limit: canonicalRateLimit(r.rate_limit),
+        response_status: typeof r.response_status === 'number' ? r.response_status : 403,
+        response_body: r.response_body ?? null,
+        escalate_to_incident: r.escalate_to_incident === true,
+    };
+}
+/** Deterministic JSON (keys sorted) so two canonical rules compare by value. */
+export function stableStringify(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(v) {
+    if (Array.isArray(v))
+        return v.map(sortKeys);
+    if (v && typeof v === 'object') {
+        const out = {};
+        for (const k of Object.keys(v).sort()) {
+            out[k] = sortKeys(v[k]);
+        }
+        return out;
+    }
+    return v;
+}
+/** Serialize the server's rules into an authored document. */
+export function toDoc(rules) {
+    return {
+        version: RULES_DOC_VERSION,
+        rules: rules.map(canonicalRule).sort((a, b) => a.priority - b.priority || a.name.localeCompare(b.name)),
+    };
+}
+/** Parse + validate a document read from disk. Throws with a human message. */
+export function parseDoc(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`rules file is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const rulesRaw = Array.isArray(parsed)
+        ? parsed
+        : parsed && typeof parsed === 'object' && Array.isArray(parsed.rules)
+            ? parsed.rules
+            : null;
+    if (!rulesRaw)
+        throw new Error('rules file must be a JSON array or an object with a "rules" array');
+    const seen = new Set();
+    const rules = [];
+    for (const [i, entry] of rulesRaw.entries()) {
+        if (!entry || typeof entry !== 'object')
+            throw new Error(`rules[${i}] is not an object`);
+        const rule = canonicalRule(entry);
+        if (!rule.name)
+            throw new Error(`rules[${i}] is missing a non-empty "name"`);
+        if (seen.has(rule.name))
+            throw new Error(`duplicate rule name "${rule.name}" — names are the unique key`);
+        seen.add(rule.name);
+        rules.push(rule);
+    }
+    return rules;
+}
+/** Diff desired (file) against existing (server) by name. */
+export function planApply(existing, desired, opts) {
+    const byName = new Map(existing.map((r) => [canonicalRule(r).name, r]));
+    const desiredNames = new Set(desired.map((r) => r.name));
+    const plan = { create: [], update: [], unchanged: [], del: [] };
+    for (const want of desired) {
+        const have = byName.get(want.name);
+        if (!have) {
+            plan.create.push(want);
+            continue;
+        }
+        const from = canonicalRule(have);
+        if (stableStringify(from) === stableStringify(want)) {
+            plan.unchanged.push(want);
+        }
+        else {
+            plan.update.push({ id: have.id, name: want.name, from, to: want });
+        }
+    }
+    if (opts.prune) {
+        for (const have of existing) {
+            const name = canonicalRule(have).name;
+            if (!desiredNames.has(name))
+                plan.del.push({ id: have.id, name });
+        }
+    }
+    return plan;
+}
+/** Strip a canonical rule down to the API's create/update body (drops nothing —
+ *  the API accepts every canonical field on both POST and PATCH). */
+export function toApiBody(r) {
+    return {
+        name: r.name,
+        description: r.description,
+        project_id: r.project_id,
+        enabled: r.enabled,
+        priority: r.priority,
+        mode: r.mode,
+        match: r.match,
+        rate_limit: r.rate_limit,
+        response_status: r.response_status,
+        response_body: r.response_body,
+        escalate_to_incident: r.escalate_to_incident,
+    };
+}
+//# sourceMappingURL=rules.js.map

package/dist/rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.js","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@tillstack/cli",
+  "version": "0.2.0",
+  "description": "TillDev command-line interface — manage TillPulse observability, TillShield edge WAF, TillGate and TillAuth from your terminal (source-map uploads, rules-as-code, and more).",
+  "license": "UNLICENSED",
+  "type": "module",
+  "bin": {
+    "tilldev": "./dist/index.js",
+    "tillpulse": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tillafrica/tilldev.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://tilldev.dev/docs/tilldev/cli",
+  "bugs": {
+    "url": "https://github.com/tillafrica/tilldev/issues"
+  },
+  "keywords": [
+    "tilldev",
+    "tillpulse",
+    "cli",
+    "observability",
+    "source-maps",
+    "tillshield",
+    "tillgate"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}