Copy one universal prompt into Claude Code, Codex, Cursor, Windsurf, or Copilot Chat. It detects the framework and verifies the setup end to end.
SecureNow enables the full app protection set by default in v8+.
Works with Claude Code, Codex, Cursor, Windsurf, and Copilot Chat. If you already ran npm i securenow, it will verify and upgrade if needed.
You are working in an existing JavaScript or TypeScript app. Set up SecureNow end-to-end for the framework/runtime already used by this repo. Treat this as a real onboarding, not just a package install.
Primary goals:
- Use the latest published SecureNow npm package. Require securenow@8.24.0 or newer: 8.0.0 introduced split admin/runtime credentials and runtime-authenticated ingestion, and the Next.js, Nuxt, PM2 cluster and SECURENOW_CREDENTIALS setups below need 8.24.0.
- By default, enable tracing, logs, POST request body capture, multipart metadata capture, and the SecureNow firewall.
- If I explicitly ask for firewall-only mode, keep the same install/login/verification gates, but use firewall-only preload and do not add tracing, logging, or OTel instrumentation.
- The firewall must protect the selected SecureNow app, use SecureNow's own blocklist/allowlist/IPDB data, and respect that app's SecureNow AI IPDB confidence threshold. Do not add custom IP reputation providers or custom auto-blocking.
- Do not confuse IP Allowlist with Trusted IPs. IP Allowlist is restrictive deny-by-default: when any allowlist entry exists for an app/environment, only listed IPs can reach it and all other IPs are blocked. Use Trusted IPs for known-safe monitors, office/VPN traffic, or false-positive suppression. Only use allowlist after explicit human approval to lock the app/environment to known IPs.
Safety rules:
- Do not print full API keys, JWTs, tokens, or local SecureNow credential files (.securenow/admin.json, .securenow/runtime.json, legacy .securenow/credentials.json, or .securenow/credentials.*.json). Mask secrets.
- Do not commit secrets. Ignore only local SecureNow credential files (.securenow/admin.json, .securenow/runtime.json, .securenow/credentials.json, and .securenow/credentials.*.json); keep the .securenow/ directory itself trackable for repo-owned docs/templates.
- Do not manually browse to a SecureNow auth URL. Always start auth with npx securenow login so the CLI generates the required callback and state.
- If the browser says "Missing callback parameter", you opened the wrong URL: rerun npx securenow login from the project root.
- Do not skip login, app selection, firewall connection, or verification unless I explicitly say to.
- Preserve existing middleware, proxy, instrumentation, Docker, PM2, and start scripts.
- Do not add SecureNow runtime defaults to .env, PM2 env, Docker env, or shared process env. The SDK reads .securenow/runtime.json locally and generated runtime credential files in production. The only environment variables it reads are SECURENOW_CREDENTIALS (runtime credentials for hosts that cannot mount a file) and SECURENOW_DISABLED=1 (turns the SDK off, e.g. in tests); SECURENOW_APPID, SECURENOW_INSTANCE, SECURENOW_API_KEY and the other old SECURENOW_* variables are ignored.
Runbook:
1. Identify the project root, package manager, framework, start/build/test scripts, process manager files, Docker files, and existing middleware/proxy/instrumentation.
2. Install or upgrade SecureNow with the detected package manager, using securenow@latest. Verify the actual installed version with:
node -p "require('./node_modules/securenow/package.json').version"
npx securenow version
Stop and fix the install if either is below 8.24.0 or npx still resolves an older local package.
3. Read the installed package surface before editing files: node_modules/securenow/package.json, README/NPM_README, SKILL-API, SKILL-CLI, docs/MCP-GUIDE.md if present, npx securenow help, and relevant subcommand help for login/init/firewall/doctor/env/test-span/log/mcp.
4. Mandatory auth/runtime gate:
- Run npx securenow whoami from the project root.
- If admin auth is missing, run npx securenow admin login from the project root and wait for the browser flow.
- If runtime app config is missing, run npx securenow app connect from the project root and wait for the browser flow.
- After the CLI exits, rerun npx securenow whoami.
- Do not proceed to app edits or verification until whoami shows the required lane(s). SDK setup needs runtime app config; admin/global MCP operations need admin auth.
5. Validate project-local credentials without exposing secrets:
- Confirm .securenow/runtime.json exists for SDK runtime setup, or legacy .securenow/credentials.json exists for old installs.
- Confirm the runtime file has SecureNow's default config/explanations block.
- Confirm the runtime file has an app key/name/instance and a runtime API key. The app key only routes telemetry; the runtime API key is required to authenticate telemetry ingestion and firewall sync.
- Confirm .securenow/admin.json exists only when admin CLI/MCP auth is needed.
- Confirm .securenow/admin.json, .securenow/runtime.json, legacy .securenow/credentials.json, and any .securenow/credentials.*.json runtime files are ignored by git, without ignoring the entire .securenow/ directory.
6. Run npx securenow init. It detects the framework, writes the Next.js instrumentation file and next.config changes, prints the start-script change for plain Node, gitignores the credential files, and warns about a PM2 ecosystem file that uses a bare -r. If it fails, upgrade to securenow@latest and retry. Do not silently ignore init failures.
7. Configure the least invasive framework-specific integration (help: npx securenow help init; full guide: node_modules/securenow/SKILL-API.md):
- Plain Node servers (Express, Fastify, NestJS, Koa, Hapi, Hono with @hono/node-server, Polka, Feathers, h3, raw node:http): preload securenow/register in the existing start command: node -r securenow/register <entry>. The same flag works for CommonJS, ESM and TypeScript (node -r securenow/register --import tsx src/index.ts). Alternatives: NODE_OPTIONS="-r securenow/register", npx securenow run <entry>, or require('securenow/register') as the first line of a CommonJS entry.
- PM2: node_args: ['-r', require.resolve('securenow/register')] in ecosystem.config.cjs (fork or cluster). Never a bare '-r securenow/register' in PM2: cluster workers resolve it from the daemon's folder and crash-loop.
- Docker: CMD ["node", "-r", "securenow/register", "<entry>"] with WORKDIR set to the app folder.
- Next.js 15 and 16: keep the instrumentation file npx securenow init writes (it imports securenow/nextjs and securenow/nextjs-auto-capture inside if (process.env.NEXT_RUNTIME === 'nodejs') with a try/catch) and its next.config changes: serverExternalPackages: ['securenow'] plus outputFileTracingIncludes: { '/*': ['./node_modules/securenow/**/*'] }. Next.js 14: experimental.instrumentationHook, experimental.serverComponentsExternalPackages and experimental.outputFileTracingIncludes instead. Works with next start and output: 'standalone' (put .securenow/credentials.json next to the standalone server.js). Preserve existing instrumentation, proxy.js and middleware.js code. The Edge runtime is not instrumented.
- Nuxt 3/4: modules: ['securenow/nuxt'] in nuxt.config, no securenow options block (settings live in .securenow/runtime.json). Alternative: node -r securenow/register .output/server/index.mjs.
- Vite: browser telemetry is not sent to SecureNow. Instrument the Node process that serves the app: node -r securenow/register-vite node_modules/vite/bin/vite.js preview, or -r securenow/register for a Vite SSR server. Say that the firewall only protects a server runtime.
- Bun 1.3: bun --preload securenow/register <entry> for apps served through node:http. Bun.serve, Deno, Cloudflare Workers and other edge runtimes are not supported.
- Firewall-only: node -r securenow/firewall-only <entry>, or npx securenow run --firewall-only <entry>. Do not add OTel, tracing or logging in this mode.
- App-level features, when the app has authentication: send auth events with track() from securenow/events (auth.login.failure, auth.login.success, auth.otp.verify.failure, auth.password_reset.requested, ...) at the real login/OTP/reset code paths, and enable session revocation with "sessions": { "guard": true, "capture": true } under config in .securenow/runtime.json (add the app's session cookie names to sessions.cookieNames if they are not the defaults). Ask before changing auth code.
8. Do not create or require a .env file for local development or production. The SDK reads defaults from .securenow/runtime.json, with legacy .securenow/credentials.json and generated runtime credential files still supported:
- config.logging.enabled: true
- config.capture.body: true
- config.capture.multipart: true
- config.firewall.failMode: "open"
- config.capture.maxBodySize: 10240
- config.logging.redact: true (credential fields and secret shapes in exported log lines become [REDACTED])
Firewall enforcement is the per-app toggle in SecureNow (npx securenow firewall enable --app <appKey>), not a local setting.
For production, run npx securenow credentials runtime --env production, store the resulting JSON as a deployment secret file, and mount/copy it to <app-root>/.securenow/credentials.json or <app-root>/.securenow/credentials.production.json. Hosts that cannot mount a file (Vercel, Railway, Render, Heroku, Fly): npx securenow credentials runtime --env production --format env prints SECURENOW_CREDENTIALS=<base64>; store it as a secret environment variable. No other SECURENOW_* variable is read (SECURENOW_DISABLED=1 turns the SDK off, for tests). Vercel, AWS Lambda and other serverless platforms are not tested end to end: say so, and do not promise firewall blocking there.
Do not proceed with telemetry verification if the runtime API key is missing; run npx securenow app connect or npx securenow api-key create first. The v8 ingestion gateway rejects app-key-only telemetry.
Local credentials should use config.runtime.deploymentEnvironment="local". Production runtime credentials should use "production". The app key stays the same; traces, logs, firewall status, forensics, and CLI/MCP queries are scoped by environment.
9. Verify firewall and threshold:
- Run npx securenow firewall apps and npx securenow firewall status.
- Confirm the selected app is present, firewallEnabled is true, and the SecureNow AI IPDB confidence threshold is visible.
- If firewallEnabled is false, run the documented per-app enable command, for example npx securenow firewall enable --app <appKey>, then verify again.
10. End-to-end proof:
- Run npx securenow doctor.
- Run npx securenow env and confirm loggingEnabled, captureBody, captureMultipart, and firewallEnabled resolve true from credentials/defaults, unless I explicitly requested firewall-only.
- If available and not in firewall-only mode, send telemetry:
npx securenow test-span securenow.onboarding
npx securenow log send "SecureNow onboarding test" --level info
- Run the repo build/test command if available.
- For MCP-capable clients, optionally smoke-test npx securenow mcp with the securenow_auth_status tool.
Final response:
- List every changed file.
- Summarize installed SecureNow version and linked app name/key, masking secrets.
- Show verification commands and pass/fail result.
- Mention skipped checks and why.
- Provide exact command(s) to start the protected app.You do not normally edit these by hand. The SDK reads only two environment variables; npx securenow login writes the app, runtime API key, and SDK defaults to project-local runtime credentials. Shown here for production/CI file-backed deployment.
# Runtime credentials written by `npx securenow login` # or `npx securenow app connect` to .securenow/runtime.json: # app key/name, ingest gateway routing, runtime API key, and SDK defaults. # The runtime API key is required for telemetry ingestion and firewall sync. # Admin/control-plane CLI and MCP auth lives separately in .securenow/admin.json. # For production/CI, mount/copy the runtime credentials file generated with: # npx securenow credentials runtime --env production # Hosts that cannot mount a file: store the SECURENOW_CREDENTIALS value printed by # npx securenow credentials runtime --env production --format env # The SDK reads only SECURENOW_CREDENTIALS and SECURENOW_DISABLED=1 from the # environment; older SECURENOW_* variables are ignored. # # Default-on settings live in .securenow/runtime.json: # config.logging.enabled=true # config.logging.redact=true (8.25.0+: secrets in exported log lines become [REDACTED]) # config.capture.body=true # config.capture.multipart=true # config.firewall.failMode="open" # # The firewall runs once the runtime API key is present. Turn it on or off per app # and environment in the dashboard or with # npx securenow firewall enable|disable --app <key> --env production # (config.firewall.enabled is ignored by the SDK).