@pellux/goodvibes-sdk 0.18.3 → 0.18.11

package/dist/platform/runtime/permissions/normalization/verdict.js

@@ -0,0 +1,269 @@
+/**
+ * Per-segment verdict evaluation for Shell AST normalization.
+ *
+ * Evaluates policy per AST segment, aggregates a final compound verdict,
+ * and produces structured denial output with per-segment reasons.
+ *
+ * Each segment verdict is a runtime contract: callers can inspect which
+ * segments were safe vs. unsafe and surface that information to the user.
+ *
+ * @module normalization/verdict
+ */
+import { collectCommandNodes, describeNode } from './ast.js';
+import { classifySegment } from './classifier.js';
+/**
+ * Default set of classifications permitted for exec commands.
+ *
+ * Destructive and escalation are excluded; they require explicit user approval.
+ * Network commands are allowed because connectivity restrictions are handled
+ * by network-scope rules in the evaluator, not at the exec layer.
+ */
+export const DEFAULT_ALLOWED_CLASSES = new Set([
+    'read',
+    'write',
+    'network',
+]);
+// ── Obfuscation detection ──────────────────────────────────────────────────────
+/**
+ * Patterns that indicate potential obfuscation or bypass attempts.
+ * Each entry provides a description and a predicate.
+ */
+const OBFUSCATION_CHECKS = [
+    {
+        /**
+         * NOTE: This check has a known false-positive risk on legitimate base64-like arguments
+         * (e.g. UUIDs, hashes, or long alphanumeric tokens). It requires both the base64
+         * character-set pattern AND 4-byte alignment, which reduces but does not eliminate
+         * false positives. Callers should surface the pattern description to the user so
+         * they can identify and allowlist benign cases.
+         */
+        description: 'base64-encoded argument (possible command injection)',
+        test: (_raw, args) => args.some((a) => /^[A-Za-z0-9+/]{16,}={0,2}$/.test(a) && a.length % 4 === 0),
+    },
+    {
+        description: 'hex-encoded argument (possible command injection)',
+        test: (_raw, args) => args.some((a) => /^(0x)?[0-9a-fA-F]{8,}$/.test(a)),
+    },
+    {
+        description: 'URL-encoded content in argument',
+        test: (_raw, args) => args.some((a) => /%[0-9a-fA-F]{2}/.test(a)),
+    },
+    {
+        description: 'variable expansion in critical position',
+        test: (raw) => /\$\{?[A-Z_]+\}?/.test(raw) && /rm|kill|dd|mkfs/.test(raw),
+    },
+    {
+        description: 'command substitution in argument (backtick or $())',
+        test: (raw) => /`[^`]+`/.test(raw) || /\$\([^)]+\)/.test(raw),
+    },
+    {
+        description: 'octal or unicode escape in path argument',
+        test: (_raw, args) => args.some((a) => /\\[0-7]{3}/.test(a) ||
+            /\\u[0-9a-fA-F]{4}/.test(a) ||
+            /\\x[0-9a-fA-F]{2}/.test(a)),
+    },
+    {
+        description: 'null-byte injection attempt',
+        test: (raw) => raw.includes('\0') || raw.includes('%00') || raw.includes('\\0'),
+    },
+    {
+        description: 'eval command detected',
+        test: (raw, args) => raw.trim().startsWith('eval') || args.includes('eval'),
+    },
+];
+/**
+ * Checks a command node for obfuscation patterns.
+ *
+ * @param node - The command node to check.
+ * @returns List of obfuscation pattern descriptions found.
+ */
+function detectObfuscation(node) {
+    const found = [];
+    for (const check of OBFUSCATION_CHECKS) {
+        if (check.test(node.raw, node.args, node.flags)) {
+            found.push(check.description);
+        }
+    }
+    return found;
+}
+// ── Policy evaluation ─────────────────────────────────────────────────────────
+/**
+ * Classification priority order (highest index = lowest risk).
+ * Used for comparing segment classifications.
+ */
+const CLASSIFICATION_PRIORITY = [
+    'destructive',
+    'escalation',
+    'network',
+    'write',
+    'read',
+];
+function classificationRank(c) {
+    const idx = CLASSIFICATION_PRIORITY.indexOf(c);
+    return idx === -1 ? 999 : idx;
+}
+function higherPriorityClassification(a, b) {
+    return classificationRank(a) <= classificationRank(b) ? a : b;
+}
+/**
+ * Default policies applied to each segment.
+ *
+ * Extend this list to add project-specific per-segment rules.
+ * First match wins (denial takes precedence).
+ */
+const DEFAULT_POLICIES = [
+    // Deny destructive commands unconditionally
+    (_, cls) => cls === 'destructive'
+        ? `segment classified as destructive — denied by policy`
+        : null,
+    // Deny escalation commands unconditionally
+    (_, cls) => cls === 'escalation'
+        ? `segment classified as escalation — denied by policy`
+        : null,
+    // Deny network commands by default (can be overridden by caller)
+    // NOTE: the exec integration layer overrides this based on feature flags
+    // so this policy only fires when no override is provided.
+    (_node, _cls) => null,
+];
+/**
+ * Evaluates a single CommandNode against the default policy.
+ *
+ * @param node           - The command node to evaluate.
+ * @param allowedClasses - Classification tiers to allow (defaults to read+write+network).
+ * @returns A SegmentVerdict for this node.
+ */
+export function evaluateSegmentNode(node, allowedClasses = DEFAULT_ALLOWED_CLASSES) {
+    // Build a minimal CommandSegment for the classifier
+    const seg = {
+        raw: node.raw,
+        tokens: node.tokens,
+        command: node.command,
+        args: node.args,
+        flags: node.flags,
+    };
+    const classification = classifySegment(seg);
+    const obfuscationPatterns = detectObfuscation(node);
+    const hasObfuscation = obfuscationPatterns.length > 0;
+    // Obfuscation always triggers denial
+    if (hasObfuscation) {
+        return {
+            raw: node.raw,
+            command: node.command,
+            classification,
+            allowed: false,
+            reason: `obfuscation detected: ${obfuscationPatterns.join('; ')}`,
+            hasObfuscation,
+            obfuscationPatterns,
+        };
+    }
+    // Check default policies
+    for (const policy of DEFAULT_POLICIES) {
+        const denial = policy(node, classification);
+        if (denial !== null) {
+            return {
+                raw: node.raw,
+                command: node.command,
+                classification,
+                allowed: false,
+                reason: denial,
+                hasObfuscation,
+                obfuscationPatterns,
+            };
+        }
+    }
+    // Check against caller-provided allowed classes
+    if (!allowedClasses.has(classification)) {
+        return {
+            raw: node.raw,
+            command: node.command,
+            classification,
+            allowed: false,
+            reason: `classification "${classification}" is not in the allowed set [${[...allowedClasses].join(', ')}]`,
+            hasObfuscation,
+            obfuscationPatterns,
+        };
+    }
+    return {
+        raw: node.raw,
+        command: node.command,
+        classification,
+        allowed: true,
+        reason: `classification "${classification}" is permitted`,
+        hasObfuscation,
+        obfuscationPatterns,
+    };
+}
+/**
+ * Builds a structured denial explanation from a list of segment verdicts.
+ *
+ * Includes the full per-segment breakdown for user-facing output.
+ *
+ * @param original - The original command string.
+ * @param verdicts - All segment verdicts.
+ * @returns A multi-line denial explanation string.
+ */
+export function buildDenialExplanation(original, verdicts) {
+    const denied = verdicts.filter((v) => !v.allowed);
+    const lines = [
+        `Command denied: "${original}"`,
+        ``,
+        `Segment analysis (${verdicts.length} segment${verdicts.length !== 1 ? 's' : ''}):`,
+    ];
+    for (const [i, v] of verdicts.entries()) {
+        const status = v.allowed ? '✓ allowed' : '✗ denied';
+        lines.push(`  [${i + 1}] ${status}  ${v.raw}`);
+        lines.push(`       classification: ${v.classification}`);
+        lines.push(`       reason: ${v.reason}`);
+        if (v.hasObfuscation) {
+            lines.push(`       obfuscation: ${v.obfuscationPatterns.join('; ')}`);
+        }
+    }
+    lines.push(``);
+    lines.push(`${denied.length} of ${verdicts.length} segment${verdicts.length !== 1 ? 's' : ''} denied.`);
+    return lines.join('\n');
+}
+/**
+ * Evaluates a ShellNode AST against policy and returns a CompoundVerdict.
+ *
+ * Safe segments are identified alongside unsafe ones. The compound command
+ * is denied if ANY segment is denied.
+ *
+ * @param original       - The original command string.
+ * @param ast            - The parsed ShellNode AST.
+ * @param allowedClasses - Classification tiers to allow per segment.
+ * @returns A CompoundVerdict with per-segment breakdown.
+ */
+export function evaluateCommandAST(original, ast, allowedClasses = DEFAULT_ALLOWED_CLASSES) {
+    const commandNodes = collectCommandNodes(ast);
+    // If AST has no command nodes (e.g. empty or pure subshell with no inner)
+    if (commandNodes.length === 0) {
+        // Conservative: deny empty/unparseable compound commands
+        const verdict = {
+            original,
+            allowed: false,
+            highestClassification: 'write',
+            segments: [],
+            denialExplanation: `Command denied: "${original}"\n\nNo parseable command segments found. Denied as a precaution.`,
+            hasObfuscation: false,
+        };
+        return verdict;
+    }
+    const segmentVerdicts = commandNodes.map((node) => evaluateSegmentNode(node, allowedClasses));
+    let highest = 'read';
+    for (const sv of segmentVerdicts) {
+        highest = higherPriorityClassification(highest, sv.classification);
+    }
+    const anyDenied = segmentVerdicts.some((v) => !v.allowed);
+    const hasObfuscation = segmentVerdicts.some((v) => v.hasObfuscation);
+    const compound = {
+        original,
+        allowed: !anyDenied,
+        highestClassification: highest,
+        segments: segmentVerdicts,
+        hasObfuscation,
+    };
+    if (anyDenied) {
+        compound.denialExplanation = buildDenialExplanation(original, segmentVerdicts);
+    }
+    return compound;
+}

package/dist/platform/runtime/permissions/policy-loader.d.ts

@@ -0,0 +1,142 @@
+/**
+ * GC-PERM-011 — Policy loader with signature validation.
+ *
+ * Wraps the raw policy bundle loading path with a signature validation
+ * step. In managed mode, bundles with invalid or missing signatures are
+ * rejected. In non-managed mode, unsigned bundles are allowed through
+ * with a `SignatureStatus` of `'unsigned'` for UI display.
+ *
+ * This module does NOT perform I/O itself — it accepts a pre-parsed
+ * `SignedPolicyBundle` so callers control the loading strategy.
+ */
+import type { PolicyRule } from './types.js';
+import type { PolicyBundleId, SignatureStatus, ProvenanceSource, SignedPolicyBundle } from './policy-signer.js';
+/**
+ * A policy bundle payload: the rules array and optional metadata.
+ */
+export interface PolicyBundlePayload {
+    /** Version tag for schema migration. */
+    version: number;
+    /** The ordered list of policy rules to register with the evaluator. */
+    rules: PolicyRule[];
+    /** Optional human-readable bundle description. */
+    description?: string;
+}
+/**
+ * Provenance record attached to every loaded policy bundle.
+ *
+ * Carried forward onto each `PermissionDecision` produced by an evaluator
+ * that was configured from this bundle.
+ */
+export interface BundleProvenance {
+    /** Stable identifier for the bundle instance. */
+    policyBundleId: PolicyBundleId;
+    /** Validation outcome for the bundle's signature. */
+    signatureStatus: SignatureStatus;
+    /** Where the bundle originated from. */
+    provenanceSource: ProvenanceSource;
+    /** ISO 8601 timestamp from the bundle, if present. */
+    issuedAt?: string;
+    /** Human-readable issuer label, if present in the bundle. */
+    issuer?: string;
+}
+/**
+ * Result returned by `loadPolicyBundle()`.
+ */
+export interface PolicyLoadResult {
+    /** Whether the bundle was successfully loaded and validated. */
+    ok: boolean;
+    /** The extracted policy rules (only populated when `ok` is true). */
+    rules?: PolicyRule[];
+    /** Provenance record for the bundle. */
+    provenance: BundleProvenance;
+    /** Human-readable explanation of why loading failed (when `ok` is false). */
+    error?: string;
+}
+/**
+ * PolicySignatureError — Thrown when a managed-mode bundle fails signature
+ * validation and the caller opts into strict error throwing.
+ *
+ * Managed mode MUST reject bundles with invalid or missing signatures.
+ */
+export declare class PolicySignatureError extends Error {
+    /** The bundle ID that failed validation. */
+    readonly bundleId: PolicyBundleId;
+    /** The validation outcome. */
+    readonly signatureStatus: SignatureStatus;
+    constructor(
+    /** The bundle ID that failed validation. */
+    bundleId: PolicyBundleId, 
+    /** The validation outcome. */
+    signatureStatus: SignatureStatus, message: string);
+}
+/**
+ * Options controlling how `loadPolicyBundle()` behaves.
+ */
+export interface PolicyLoaderOptions {
+    /**
+     * HMAC-SHA256 signing key (Buffer or hex string).
+     *
+     * Required when `managed` is true; optional otherwise. When absent,
+     * signature verification is skipped and status is set to `'skipped'`.
+     */
+    signingKey?: Buffer | string;
+    /**
+     * When true, the loader operates in managed mode:
+     *   - Bundles with `SignatureStatus` of `'invalid'` or `'missing'` are rejected.
+     *   - Bundles with `SignatureStatus` of `'unsigned'` are rejected.
+     *   - Only `'valid'` signatures are accepted.
+     *
+     * When false (default), unsigned bundles are permitted with status `'unsigned'`.
+     */
+    managed?: boolean;
+    /**
+     * Describes where the bundle was loaded from.
+     * Defaults to `'inline'` when not provided.
+     */
+    provenanceSource?: ProvenanceSource;
+    /**
+     * When true, `loadPolicyBundle()` throws a `PolicySignatureError` on
+     * rejection in managed mode instead of returning `{ ok: false }`.
+     *
+     * Defaults to false.
+     */
+    throwOnRejection?: boolean;
+}
+/**
+ * loadPolicyBundle — Validates and loads a signed policy bundle.
+ *
+ * Performs signature verification and returns the extracted rules with
+ * a full provenance record. In managed mode, bundles that are unsigned,
+ * missing a signature, or carry an invalid signature are rejected.
+ *
+ * In non-managed mode, unsigned bundles are accepted with status `'unsigned'`
+ * so the UI can display a warning.
+ *
+ * @param bundle  — The pre-parsed signed bundle object.
+ * @param options — Loader behaviour options.
+ *
+ * @example
+ * ```ts
+ * const result = loadPolicyBundle(bundle, {
+ *   signingKey: process.env['POLICY_SIGNING_KEY'],
+ *   managed: true,
+ *   provenanceSource: 'local-file',
+ * });
+ * if (!result.ok) {
+ *   throw new Error(`Policy load failed: ${result.error}`);
+ * }
+ * ```
+ */
+export declare function loadPolicyBundle(bundle: SignedPolicyBundle<PolicyBundlePayload>, options?: PolicyLoaderOptions): PolicyLoadResult;
+/**
+ * createUnsignedBundle — Convenience helper for non-managed/test usage.
+ *
+ * Creates a bare `SignedPolicyBundle` without a signature. The resulting
+ * bundle will be accepted in non-managed mode with status `'unsigned'`.
+ *
+ * @param bundleId — Unique identifier for this bundle.
+ * @param payload  — The policy payload.
+ */
+export declare function createUnsignedBundle(bundleId: PolicyBundleId, payload: PolicyBundlePayload): SignedPolicyBundle<PolicyBundlePayload>;
+//# sourceMappingURL=policy-loader.d.ts.map

package/dist/platform/runtime/permissions/policy-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-loader.d.ts","sourceRoot":"","sources":["../../../../src/platform/runtime/permissions/policy-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,oBAAoB,CAAC;AAK5B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,kDAAkD;IAClD,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iDAAiD;IACjD,cAAc,EAAE,cAAc,CAAC;IAC/B,qDAAqD;IACrD,eAAe,EAAE,eAAe,CAAC;IACjC,wCAAwC;IACxC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,EAAE,EAAE,OAAO,CAAC;IACZ,qEAAqE;IACrE,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,wCAAwC;IACxC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;;;GAKG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,4CAA4C;aAC5B,QAAQ,EAAE,cAAc;IACxC,8BAA8B;aACd,eAAe,EAAE,eAAe;;IAHhD,4CAA4C;IAC5B,QAAQ,EAAE,cAAc;IACxC,8BAA8B;IACd,eAAe,EAAE,eAAe,EAChD,OAAO,EAAE,MAAM;CAKlB;AAID;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE7B;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAEpC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC/C,OAAO,GAAE,mBAAwB,GAChC,gBAAgB,CA8DlB;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAAC,mBAAmB,CAAC,CAOzC"}

package/dist/platform/runtime/permissions/policy-loader.js

@@ -0,0 +1,124 @@
+/**
+ * GC-PERM-011 — Policy loader with signature validation.
+ *
+ * Wraps the raw policy bundle loading path with a signature validation
+ * step. In managed mode, bundles with invalid or missing signatures are
+ * rejected. In non-managed mode, unsigned bundles are allowed through
+ * with a `SignatureStatus` of `'unsigned'` for UI display.
+ *
+ * This module does NOT perform I/O itself — it accepts a pre-parsed
+ * `SignedPolicyBundle` so callers control the loading strategy.
+ */
+import { verifyBundle } from './policy-signer.js';
+// ── Error class ───────────────────────────────────────────────────────────────
+/**
+ * PolicySignatureError — Thrown when a managed-mode bundle fails signature
+ * validation and the caller opts into strict error throwing.
+ *
+ * Managed mode MUST reject bundles with invalid or missing signatures.
+ */
+export class PolicySignatureError extends Error {
+    bundleId;
+    signatureStatus;
+    constructor(
+    /** The bundle ID that failed validation. */
+    bundleId, 
+    /** The validation outcome. */
+    signatureStatus, message) {
+        super(message);
+        this.bundleId = bundleId;
+        this.signatureStatus = signatureStatus;
+        this.name = 'PolicySignatureError';
+    }
+}
+// ── Core loader ───────────────────────────────────────────────────────────────
+/**
+ * loadPolicyBundle — Validates and loads a signed policy bundle.
+ *
+ * Performs signature verification and returns the extracted rules with
+ * a full provenance record. In managed mode, bundles that are unsigned,
+ * missing a signature, or carry an invalid signature are rejected.
+ *
+ * In non-managed mode, unsigned bundles are accepted with status `'unsigned'`
+ * so the UI can display a warning.
+ *
+ * @param bundle  — The pre-parsed signed bundle object.
+ * @param options — Loader behaviour options.
+ *
+ * @example
+ * ```ts
+ * const result = loadPolicyBundle(bundle, {
+ *   signingKey: process.env['POLICY_SIGNING_KEY'],
+ *   managed: true,
+ *   provenanceSource: 'local-file',
+ * });
+ * if (!result.ok) {
+ *   throw new Error(`Policy load failed: ${result.error}`);
+ * }
+ * ```
+ */
+export function loadPolicyBundle(bundle, options = {}) {
+    const { signingKey, managed = false, provenanceSource = 'inline', throwOnRejection = false, } = options;
+    const baseProv = {
+        policyBundleId: bundle.bundleId,
+        signatureStatus: 'skipped',
+        provenanceSource,
+        issuedAt: bundle.issuedAt,
+        issuer: bundle.issuer,
+    };
+    // ── Signature validation ────────────────────────────────────────────────────
+    let signatureStatus;
+    if (!signingKey) {
+        // No key supplied — skip verification (permitted in non-managed mode)
+        signatureStatus = 'skipped';
+    }
+    else if (!bundle.signature) {
+        // Key supplied but bundle has no signature — unsigned in non-managed, rejected in managed
+        signatureStatus = 'unsigned';
+    }
+    else {
+        const result = verifyBundle(bundle, signingKey);
+        signatureStatus = result.status;
+    }
+    const provenance = { ...baseProv, signatureStatus };
+    // ── Managed-mode enforcement ────────────────────────────────────────────────
+    if (managed) {
+        const rejected = signatureStatus === 'invalid'
+            || signatureStatus === 'missing'
+            || signatureStatus === 'unsigned'
+            || signatureStatus === 'skipped'; // managed mode requires a key + valid sig
+        if (rejected) {
+            const msg = `Managed-mode policy rejection: bundle "${bundle.bundleId}" ` +
+                `has signatureStatus="${signatureStatus}". ` +
+                `Only bundles with a valid HMAC-SHA256 signature are accepted in managed mode.`;
+            if (throwOnRejection) {
+                throw new PolicySignatureError(bundle.bundleId, signatureStatus, msg);
+            }
+            return { ok: false, provenance, error: msg };
+        }
+    }
+    // ── Payload extraction ───────────────────────────────────────────────────────
+    const payload = bundle.payload;
+    return {
+        ok: true,
+        rules: payload.rules,
+        provenance,
+    };
+}
+/**
+ * createUnsignedBundle — Convenience helper for non-managed/test usage.
+ *
+ * Creates a bare `SignedPolicyBundle` without a signature. The resulting
+ * bundle will be accepted in non-managed mode with status `'unsigned'`.
+ *
+ * @param bundleId — Unique identifier for this bundle.
+ * @param payload  — The policy payload.
+ */
+export function createUnsignedBundle(bundleId, payload) {
+    return {
+        bundleId,
+        issuedAt: new Date().toISOString(),
+        payload,
+        // No signature field
+    };
+}