@securecode/sdk

@securecode/sdk

The official Node.js SDK for SecureCodeHQ — the secrets vault for developers who build with Claude Code.

Install

npm install @securecode/sdk

Quick Start

Set your API key and start using secrets:

export SECURECODE_API_KEY=sc_your_key_here

import { getSecret } from '@securecode/sdk';

const stripeKey = await getSecret('STRIPE_SECRET_KEY');
const dbUrl = await getSecret('DATABASE_URL');

Load All Secrets at Once

Inject all your secrets into process.env with a single API call:

import { loadEnv } from '@securecode/sdk';

await loadEnv();
// Now use process.env.STRIPE_SECRET_KEY, process.env.DATABASE_URL, etc.

Options:

await loadEnv({
  tags: { env: 'production', project: 'acme' }, // filter by tags
  override: true, // overwrite existing env vars (default: false)
});

CLI Tools

Migrate from .env files

Scan and import your .env files into SecureCodeHQ:

npx securecode migrate                        # scan all .env* files
npx securecode migrate .env.production        # import specific file
npx securecode migrate --tags "project:acme"  # apply tags
npx securecode migrate --ttl 720 -y           # 30-day TTL, skip confirm

Run with secrets injected

Load secrets into process.env and run your command:

npx securecode-run node server.js
npx securecode-run -- npm start
npx securecode-run --tags "env:production" node app.js

Full Client

For more control, create a client instance:

import { SecureCodeClient } from '@securecode/sdk';

const client = new SecureCodeClient({
  apiKey: 'sc_your_key_here',
});

// Get a secret value (inject mode by default — value written to local file, AI never sees it)
const value = await client.getSecret('OPENAI_API_KEY');

// Get a secret with tags to disambiguate
const prodKey = await client.getSecret('DB_URL', { env: 'production' });

// Reveal mode — value returned to caller (audited as conscious action)
const revealed = await client.getSecret('DB_URL', undefined, undefined, { reveal: true });

// List all secrets (metadata only, no values)
const secrets = await client.listSecrets();

// Filter by tags
const prodSecrets = await client.listSecrets({
  tags: { env: 'production', project: 'acme' },
});

// Create a secret with tags and TTL
await client.createSecret({
  name: 'NEW_API_KEY',
  value: 'sk-...',
  description: 'OpenAI production key',
  tags: { env: 'production', project: 'acme' },
  ttlHours: 720, // expires in 30 days
});

// Update a secret
await client.updateSecret('NEW_API_KEY', {
  value: 'sk-new-value...',
  tags: { env: 'production', rotated: 'true' },
});

// Renew an expired secret
await client.renewSecret('EXPIRED_KEY', 48); // 48 hours

// Delete a secret
await client.deleteSecret('OLD_KEY');

// Import from .env content
await client.importEnv('KEY1=val1\nKEY2=val2', {
  tags: { env: 'staging' },
  filename: '.env.staging',
});

// Export all secrets as .env format
const envContent = await client.exportEnv({ format: 'env' });

Onboarding API

The SDK includes methods for the guided onboarding flow (used by the MCP server):

// Start an onboarding session — returns URLs for signup and import popups
const session = await client.startOnboarding({ source: 'mcp', agentName: 'claude-code' });
console.log(session.signupUrl);  // https://securecodehq.com/onboarding/{token}/signup
console.log(session.importUrl);  // https://securecodehq.com/onboarding/{token}/import
console.log(session.expiresAt);  // Token expires in 30 minutes

// Poll session status
const status = await client.getOnboardingStatus(session.token);
console.log(status.step);              // 1 | 2 | 3
console.log(status.signupCompleted);   // boolean
console.log(status.importCompleted);   // boolean
console.log(status.migrationInstructions); // LLM-ready text (step 3 only)

MCP Access Rules

When an MCP rule blocks access, the SDK throws McpRuleBlockedError with rule metadata:

import { SecureCodeClient, McpRuleBlockedError } from '@securecode/sdk';

const client = new SecureCodeClient({ apiKey: 'sc_...' });

try {
  const value = await client.getSecret('STRIPE_LIVE_KEY');
} catch (err) {
  if (err instanceof McpRuleBlockedError) {
    console.log(err.ruleAction);  // 'block_always' | 'require_confirmation' | ...
    console.log(err.ruleName);    // 'Block production secrets'
    console.log(err.ruleId);      // Rule ID for acknowledgement

    // For require_confirmation rules, acknowledge and retry:
    if (err.ruleAction === 'require_confirmation') {
      const value = await client.getSecret('STRIPE_LIVE_KEY', undefined, err.ruleId);
    }
  }
}

// List active rules (read-only)
const rules = await client.getActiveRules();

Session Lock

Control when Claude Code can access your secrets:

// Wake session with scoped access
await client.wakeSession({
  scope: [{ project: 'acme', env: 'staging' }],
  autoSleepMinutes: 60,
});

// Check session status
const status = await client.getSessionStatus();
console.log(status.status); // 'active' | 'sleeping'
console.log(status.timeRemainingMinutes);

// Lock session when done
await client.sleepSession();

API Key

Get your API key from the SecureCodeHQ dashboard under Settings > API Keys.

Requirements

• Node.js >= 18

License

MIT