claude-flow 3.48.0 → 3.49.0

package/v3/@claude-flow/cli/dist/src/plugins/trust-policy.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Plugin install trust policy (#3557).
+ *
+ * `plugins install --verify` used to be parsed and never read, and a plugin's
+ * declared `trustLevel`/`permissions` were neither recorded nor enforced.
+ * These pure helpers decide what an install may register.
+ */
+/**
+ * Permissions a plugin may declare and still have its hooks and commands
+ * registered without `--trust`. Anything else (filesystem, network, shell,
+ * secrets, config, privileged, …) needs an explicit `--trust`.
+ */
+export declare const DEFAULT_PLUGIN_PERMISSIONS: readonly string[];
+/** Trust levels that are withheld unless the user passes `--trust`. */
+export declare const UNTRUSTED_TRUST_LEVELS: readonly string[];
+/** Registry trust levels that the registry itself vouches for. */
+export declare const REGISTRY_VOUCHED_TRUST_LEVELS: readonly string[];
+export interface DeclaredTrust {
+    trustLevel?: string;
+    permissions: string[];
+}
+export interface TrustDecision {
+    /** Hooks and commands may be registered. */
+    allowed: boolean;
+    /** Verification was skipped with `--no-verify`. */
+    verificationSkipped: boolean;
+    /** Why registration was withheld (empty when allowed). */
+    reasons: string[];
+    /** Declared permissions outside {@link DEFAULT_PLUGIN_PERMISSIONS}. */
+    excessPermissions: string[];
+}
+export interface TrustOptions {
+    /** `--verify` (default true). */
+    verify: boolean;
+    /** `--trust` (default false). */
+    trust: boolean;
+    /** Trust level from a registry entry, when the plugin was found there. */
+    registryTrustLevel?: string;
+}
+/**
+ * Read the trust declaration from a plugin's package.json. The `claude-flow`
+ * block wins; top-level fields are accepted as a fallback.
+ */
+export declare function readDeclaredTrust(pkg: Record<string, unknown>): DeclaredTrust;
+/** Decide whether an install may register the plugin's hooks and commands. */
+export declare function evaluatePluginTrust(declared: DeclaredTrust, opts: TrustOptions): TrustDecision;
+/**
+ * Whether npm may run the package's lifecycle scripts (preinstall/install/
+ * postinstall, and those of its dependencies). Scripts execute before the
+ * package's own trust declaration can be read, so only an explicit `--trust`
+ * or a registry-vouched entry allows them; everything else installs with
+ * `--ignore-scripts`.
+ */
+export declare function shouldRunInstallScripts(opts: {
+    trust?: boolean;
+    registryTrustLevel?: string;
+}): boolean;
+/** A registry checksum we can actually verify: `sha256:` + 64 hex chars. */
+export declare function parseSha256Checksum(checksum: unknown): string | null;
+export declare function sha256Hex(data: Buffer): string;
+//# sourceMappingURL=trust-policy.d.ts.map

package/v3/@claude-flow/cli/dist/src/plugins/trust-policy.js

@@ -0,0 +1,84 @@
+/**
+ * Plugin install trust policy (#3557).
+ *
+ * `plugins install --verify` used to be parsed and never read, and a plugin's
+ * declared `trustLevel`/`permissions` were neither recorded nor enforced.
+ * These pure helpers decide what an install may register.
+ */
+import { createHash } from 'crypto';
+/**
+ * Permissions a plugin may declare and still have its hooks and commands
+ * registered without `--trust`. Anything else (filesystem, network, shell,
+ * secrets, config, privileged, …) needs an explicit `--trust`.
+ */
+export const DEFAULT_PLUGIN_PERMISSIONS = Object.freeze(['memory:read']);
+/** Trust levels that are withheld unless the user passes `--trust`. */
+export const UNTRUSTED_TRUST_LEVELS = Object.freeze(['untrusted', 'unverified']);
+/** Registry trust levels that the registry itself vouches for. */
+export const REGISTRY_VOUCHED_TRUST_LEVELS = Object.freeze(['official', 'verified']);
+function asStringList(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === 'string' && v.trim() !== '').map((v) => v.trim());
+}
+/**
+ * Read the trust declaration from a plugin's package.json. The `claude-flow`
+ * block wins; top-level fields are accepted as a fallback.
+ */
+export function readDeclaredTrust(pkg) {
+    const block = (pkg['claude-flow'] && typeof pkg['claude-flow'] === 'object'
+        ? pkg['claude-flow']
+        : {});
+    const trustLevel = typeof block.trustLevel === 'string'
+        ? block.trustLevel
+        : typeof pkg.trustLevel === 'string' ? pkg.trustLevel : undefined;
+    const permissions = asStringList(block.permissions).length > 0
+        ? asStringList(block.permissions)
+        : asStringList(pkg.permissions);
+    return { trustLevel, permissions };
+}
+/** Decide whether an install may register the plugin's hooks and commands. */
+export function evaluatePluginTrust(declared, opts) {
+    const excessPermissions = declared.permissions.filter((p) => !DEFAULT_PLUGIN_PERMISSIONS.includes(p));
+    if (!opts.verify) {
+        return { allowed: true, verificationSkipped: true, reasons: [], excessPermissions };
+    }
+    const reasons = [];
+    const registryVouched = opts.registryTrustLevel !== undefined
+        && REGISTRY_VOUCHED_TRUST_LEVELS.includes(opts.registryTrustLevel);
+    if (!registryVouched) {
+        if (declared.trustLevel && UNTRUSTED_TRUST_LEVELS.includes(declared.trustLevel)) {
+            reasons.push(`declares trustLevel "${declared.trustLevel}"`);
+        }
+        if (excessPermissions.length > 0) {
+            reasons.push(`declares permissions beyond the default set (${DEFAULT_PLUGIN_PERMISSIONS.join(', ')}): ${excessPermissions.join(', ')}`);
+        }
+    }
+    if (reasons.length > 0 && !opts.trust) {
+        return { allowed: false, verificationSkipped: false, reasons, excessPermissions };
+    }
+    return { allowed: true, verificationSkipped: false, reasons: [], excessPermissions };
+}
+/**
+ * Whether npm may run the package's lifecycle scripts (preinstall/install/
+ * postinstall, and those of its dependencies). Scripts execute before the
+ * package's own trust declaration can be read, so only an explicit `--trust`
+ * or a registry-vouched entry allows them; everything else installs with
+ * `--ignore-scripts`.
+ */
+export function shouldRunInstallScripts(opts) {
+    if (opts.trust === true)
+        return true;
+    return opts.registryTrustLevel !== undefined && REGISTRY_VOUCHED_TRUST_LEVELS.includes(opts.registryTrustLevel);
+}
+/** A registry checksum we can actually verify: `sha256:` + 64 hex chars. */
+export function parseSha256Checksum(checksum) {
+    if (typeof checksum !== 'string')
+        return null;
+    const m = /^sha256:([0-9a-f]{64})$/i.exec(checksum.trim());
+    return m ? m[1].toLowerCase() : null;
+}
+export function sha256Hex(data) {
+    return createHash('sha256').update(data).digest('hex');
+}
+//# sourceMappingURL=trust-policy.js.map

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.d.ts

@@ -17,6 +17,12 @@ export declare function issuePolicyApproval(approval: Omit<PolicyApproval, 'uses
     issuedAt?: number;
 }, projectRoot?: string, approvalIssuerVerifier?: (issuer: string) => boolean): Promise<PolicyApproval>;
 export declare function revokePolicyApproval(id: string, projectRoot?: string): Promise<boolean>;
+/**
+ * Read-only verification (#3568). It must not run inside
+ * `withPolicyTransaction`, whose own post-operation check throws a generic
+ * `policy-ledger-verification-failed` and hides which check failed. The only
+ * write is persisting an anchor established for a pre-anchor ledger.
+ */
 export declare function verifyPolicyLedger(projectRoot?: string): Promise<ReturnType<AgenticPolicyEngine['verifyLedger']>>;
 export declare function authorizeMcpTool(toolName: string, input: Record<string, unknown>, context?: Record<string, unknown>, attributes?: Readonly<{
     actionType?: string;

package/v3/@claude-flow/cli/dist/src/services/policy-runtime.js

@@ -338,9 +338,12 @@ export async function withPolicyTransaction(projectRoot, operation, options = {}
             approvalIssuerVerifier: options.approvalIssuerVerifier,
         });
         const result = await operation(engine);
-        const nextState = engine.exportState();
+        // Verify before exporting: verification establishes the ledger anchor
+        // (#3568) on state written before the anchor existed, and that anchor
+        // must be part of what is persisted.
         if (!engine.verifyLedger().valid)
             throw new Error('policy-ledger-verification-failed');
+        const nextState = engine.exportState();
         await writePolicyState(projectRoot, target.state, nextState);
         return result;
     }
@@ -393,8 +396,30 @@ export async function issuePolicyApproval(approval, projectRoot = process.cwd(),
 export async function revokePolicyApproval(id, projectRoot = process.cwd()) {
     return withPolicyTransaction(projectRoot, (engine) => engine.revokeApproval(id));
 }
+/**
+ * Read-only verification (#3568). It must not run inside
+ * `withPolicyTransaction`, whose own post-operation check throws a generic
+ * `policy-ledger-verification-failed` and hides which check failed. The only
+ * write is persisting an anchor established for a pre-anchor ledger.
+ */
 export async function verifyPolicyLedger(projectRoot = process.cwd()) {
-    return withPolicyTransaction(projectRoot, (engine) => engine.verifyLedger());
+    const target = paths(projectRoot);
+    mkdirSync(target.dir, { recursive: true, mode: 0o700 });
+    const release = await acquireLock(target.lock);
+    try {
+        const engine = AgenticPolicyEngine.fromState(loadPolicyState(projectRoot), {
+            signingKey: process.env.CLAUDE_FLOW_POLICY_SIGNING_KEY,
+            keyId: process.env.CLAUDE_FLOW_POLICY_KEY_ID,
+        });
+        const result = engine.verifyLedger();
+        if (result.anchor === 'established-now') {
+            await writePolicyState(projectRoot, target.state, engine.exportState());
+        }
+        return result;
+    }
+    finally {
+        release();
+    }
 }
 /**
  * Resolve the caller identity for `authorizeMcpTool`.

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.48.0",
+  "version": "3.49.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -103,7 +103,7 @@
     "@claude-flow/mcp": "3.0.0",
     "@claude-flow/neural": "3.0.0",
     "@claude-flow/plugin-agent-federation": "1.0.0",
-    "@claude-flow/security": "3.0.0",
+    "@claude-flow/security": "3.0.1",
     "@claude-flow/shared": "3.0.0",
     "@iarna/toml": "^2.2.5",
     "@noble/ed25519": "2.3.0",