Sector8 TypeScript SDK

TypeScript SDK for Sector8 decisioning, telemetry, and MCP guard integration.

Sector8 is an execution-boundary security platform for AI systems. The production Guard Module is live at https://sdkapi.sector8.ai.

What this package is for

Use @sector8/sdk when you want to:

• connect a Node.js or TypeScript application to Sector8
• send telemetry and security events to the Sector8 backend
• bootstrap the Sector8 MCP guard path in a project

This package should stay thin. The paid wedge is the live decision service, not a large client-side framework.

Installation

npm install @sector8/sdk

Runtime defaults

• Production API: https://sdkapi.sector8.ai
• Auth headers: x-api-key, x-client-id
• Primary contract: POST /api/v1/evaluate
• Supporting telemetry: POST /api/v1/telemetry

Quick start

import sector8 from '@sector8/sdk';

const client = sector8.setup({
  apiKey: process.env.SECTOR8_API_KEY,
  clientId: process.env.SECTOR8_CLIENT_ID || '1'
});

await client.logLLMCall({
  provider: 'openai',
  model: 'gpt-4o',
  tokens: 150,
  cost: 0.003,
  latency_ms: 800,
  prompt: 'Summarize this contract.',
  completion: 'Here is the summary...'
});

Protect an action before execution:

const decision = await client.evaluate({
  tool_name: 'bash',
  arguments: { command: 'git status' },
  caller_id: 'developer-1',
  role: 'developer',
  session_id: 'customer-onboarding-1'
});

if (decision.outcome === 'ALLOW') {
  await runTheAction();
} else {
  auditLog(decision.reason_code, decision.decision_trace_id);
}

A policy DENY is returned as a normal decision artifact. Authentication, scope, validation, transport, and malformed-response failures throw SDK errors. Never execute an action unless decision.outcome === 'ALLOW'.

Secure host configuration

The SDK uses https://sdkapi.sector8.ai by default and treats endpoint as the preferred configuration field. The legacy baseUrl alias is still accepted for compatibility.

• plain HTTP is rejected by default
• arbitrary remote hosts other than sdkapi.sector8.ai are rejected by default
• endpoint values with /api/... paths, query strings, or fragments are rejected by default
• local or mock testing requires explicit opt-in

const client = sector8.setup({
  apiKey: process.env.SECTOR8_API_KEY!,
  endpoint: 'http://localhost:9876',
  unsafeEndpoint: true
});

Use unsafeEndpoint: true only for deliberate local or test use. The older allowUnsafeBaseUrl: true option remains available as a compatibility alias.

Staging endpoints such as https://stgsdkapi.sector8.ai are intentionally treated as non-production hosts by the SDK. Use unsafeEndpoint: true when running controlled staging tests, and never combine that setting with production credentials.

Verification flow

Use the same proof pattern everywhere:

1. health check succeeds
2. one allow-path request succeeds
3. one deny-path request returns the expected reason code

Core client methods

• logLLMCall(...)
• alertThreat(...)
• logIncident(...)
• testConnection()

Links

• Repository: https://github.com/sector8-ai/sector8-sdk-typescript
• Production API: https://sdkapi.sector8.ai
• Dashboard: https://app.sector8.ai
• Maintainer release process: RELEASING.md

Verify a new customer connection

import { Sector8Client, verifyOnboarding } from '@sector8/sdk';

const endpoint = process.env.SECTOR8_ENDPOINT || 'https://sdkapi.sector8.ai';
const client = new Sector8Client({
  apiKey: process.env.SECTOR8_API_KEY!,
  clientId: process.env.SECTOR8_CLIENT_ID!,
  endpoint,
  unsafeEndpoint: process.env.SECTOR8_UNSAFE_ENDPOINT === 'true'
});
process.exitCode = await verifyOnboarding(client);

The verifier submits safe simulated actions only. It confirms one ALLOW, one DENY, and the canonical decision artifact fields without printing credentials or request payloads.

After setting SECTOR8_API_KEY, SECTOR8_CLIENT_ID, and optionally SECTOR8_ENDPOINT, run npm run verify:onboarding for the packaged verifier. Set SECTOR8_UNSAFE_ENDPOINT=true only for deliberate staging/local use. Never use production credentials with an unsafe endpoint or share one-time reveal keys.

Verifier exit codes:

• 0: onboarding contract verified
• 2: Gate connectivity or verifier startup failure
• 3: credentials rejected or API key lacks evaluate scope
• 4: Gate returned an invalid or unexpected decision artifact