ruvnet/ruflo · error · SecurityPackageMissingError

ruflo auth needs the '@claude-flow/security' package, which

Error message

ruflo auth needs the '@claude-flow/security' package, which isn't installed (it's an optional dependency — install/reinstall failed or was skipped for this platform). Try: npm install @claude-flow/security. Underlying error: ${cause instanceof Error ? cause.message : String(cause)}

What it means

SecurityPackageMissingError is the user-facing error thrown by loadSecurityOAuth() when it cannot produce a usable @claude-flow/security module for ANY reason — whether the package is absent (ERR_MODULE_NOT_FOUND) or loaded but malformed (error 161, which is caught and rewrapped here). Per ADR-306, @claude-flow/security is an optionalDependency because ruflo auth is the only capability that genuinely requires it; local/offline ruflo commands work without it. The error message embeds the underlying cause and gives the install command.

Source

Thrown at v3/@claude-flow/cli/src/auth/security-bridge.ts:75

    );
    this.name = 'SecurityPackageMissingError';
  }
}

let cached: SecurityOAuthModule | null = null;

/** Loads `@claude-flow/security`'s OAuth surface, throwing a clear error if it's absent. */
export async function loadSecurityOAuth(): Promise<SecurityOAuthModule> {
  if (cached) return cached;
  try {
    const mod = (await import('@claude-flow/security')) as unknown as SecurityOAuthModule;
    if (!mod.authorizeUrl || !mod.createKeychainAdapter) {
      throw new Error('module loaded but is missing expected OAuth exports');
    }
    cached = mod;
    return mod;
  } catch (e) {
    throw new SecurityPackageMissingError(e);
  }
}

View on GitHub (pinned to 6b01dc5a68)

Solutions

Run `npm install @claude-flow/security` in the package where @claude-flow/cli is installed
If install used --omit=optional, re-run without that flag or add @claude-flow/security to direct `dependencies` so it is never skipped
For Docker/CI, change the install line to not skip optional dependencies, or explicitly add the package to dependencies
Verify platform support — check the security package's `os` and `cpu` fields in its package.json if install silently skips for your platform

Example fix

// before: optional dependency skipped
// Dockerfile: RUN npm ci --omit=optional

// after:
// Dockerfile: RUN npm ci
// or add to package.json dependencies:
//   "@claude-flow/security": "^latest"

Defensive patterns

Strategy: try-catch

Validate before calling

// Check at startup whether the optional security package is resolvable
import { existsSync } from 'node:fs';
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
function isSecurityPackageInstalled(): boolean {
  try {
    require.resolve('@claude-flow/security');
    return true;
  } catch {
    return false;
  }
}

Try / catch

import { loadSecurityOAuth, SecurityPackageMissingError } from '@claude-flow/cli/auth/security-bridge';

try {
  await loadSecurityOAuth();
} catch (e) {
  if (e instanceof SecurityPackageMissingError) {
    // User-facing message already includes the install command.
    // For local-only commands, you can degrade gracefully; for auth commands,
    // print the message and exit.
    console.error(e.message);
    process.exit(1);
  }
  throw e;
}

Prevention

Do not install with --omit=optional in environments that need ruflo auth
Add @claude-flow/security to direct dependencies if your workflow always needs auth, so it is never treated as optional
In Dockerfiles, run `npm ci` without --omit=optional, or explicitly install the package afterward

When it happens

Trigger: Any ruflo auth subcommand (login, status with refresh, token-stdin) or any code path calling loadSecurityOAuth() when @claude-flow/security is not resolvable from the CLI package's node_modules, OR when the inner export-check (error 161) fires and is caught.

Common situations: Install was run with --omit=optional or --no-optional; a Docker/CI image built with npm ci --omit=optional; the security package's platform-specific native dependency failed to build so npm skipped it; npm prune removed it; a monorepo did not hoist the optional dep to the CLI package's depth.

Related errors

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/d2a6fc2992420c0b. Report an issue: GitHub.