@creedspace/sdk 1.0.0

package/README.md

@@ -0,0 +1,195 @@
+# @creed-space/sdk
+
+Official TypeScript SDK for Creed Space - governance infrastructure for AI agents.
+
+## Installation
+
+```bash
+npm install @creed-space/sdk
+# or
+yarn add @creed-space/sdk
+# or
+pnpm add @creed-space/sdk
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from '@creed-space/sdk';
+
+const client = createClient({
+  apiKey: process.env.CREED_API_KEY!,
+});
+
+// Get a governance decision for a tool call
+const result = await client.decide({
+  toolName: 'send_email',
+  arguments: {
+    to: 'user@example.com',
+    subject: 'Hello',
+  },
+  onAllow: (decision) => {
+    console.log('Authorized:', decision.decisionToken);
+    // Execute the tool with the signed token
+  },
+  onDeny: (decision) => {
+    console.log('Denied:', decision.reasons);
+  },
+});
+```
+
+## Features
+
+- **Governance Decisions** - Get ALLOW/DENY decisions for tool calls
+- **Cryptographic Tokens** - Signed JWT tokens for authorization proof
+- **Callback Flow Control** - `onAllow`, `onDeny`, `onRequireHuman` callbacks
+- **Audit Trail** - Query tamper-evident hash-chain audit logs
+- **TypeScript Native** - Full type definitions included
+
+## API Reference
+
+### `createClient(options)`
+
+Create a new Creed Space client.
+
+```typescript
+const client = createClient({
+  apiKey: 'crd_live_...', // Required: Your API key
+  baseUrl: 'https://api.creed.space', // Optional: Custom API URL
+  timeoutMs: 30000, // Optional: Request timeout (default: 30s)
+  fetch: customFetch, // Optional: Custom fetch implementation
+});
+```
+
+### `client.decide(request)`
+
+Get a governance decision for a tool call.
+
+```typescript
+interface DecideRequest {
+  toolName: string; // Tool to execute
+  arguments: Record<string, unknown>; // Tool arguments
+  constitutionId?: string; // Constitution ID (default: 'default')
+  context?: {
+    tenantId?: string;
+    projectId?: string;
+    userId?: string;
+    sessionId?: string;
+  };
+  onAllow?: (decision: AllowDecision) => void | Promise<void>;
+  onDeny?: (decision: DenyDecision) => void | Promise<void>;
+  onRequireHuman?: (decision: RequireHumanDecision) => void | Promise<void>;
+}
+
+const result = await client.decide({
+  toolName: 'send_email',
+  arguments: { to: 'user@example.com' },
+  onAllow: async (decision) => {
+    // Execute the tool
+    await sendEmail(decision.decisionToken);
+  },
+});
+```
+
+### `client.authorize(request)`
+
+Verify a decision token before execution.
+
+```typescript
+const auth = await client.authorize({
+  decisionToken: result.decisionToken,
+  toolName: 'send_email', // Optional: verify tool name matches
+});
+
+if (auth.authorized) {
+  console.log('Token valid until:', auth.claims?.expiresAt);
+}
+```
+
+### `client.audit(request)`
+
+Query the audit trail for a run.
+
+```typescript
+const audit = await client.audit({
+  runId: 'run_123',
+  limit: 50,
+});
+
+console.log('Events:', audit.events);
+console.log('Integrity verified:', audit.integrity.verified);
+```
+
+### `client.status()`
+
+Get service status and feature availability.
+
+```typescript
+const status = await client.status();
+console.log('Service:', status.service);
+console.log('Features:', status.features);
+```
+
+## Utilities
+
+### `computeArgsHash(args)`
+
+Compute SHA-256 hash of arguments for verification.
+
+```typescript
+import { computeArgsHash } from '@creed-space/sdk';
+
+const hash = await computeArgsHash({ to: 'user@example.com' });
+// 'sha256:...'
+```
+
+### `isTokenExpired(token)`
+
+Check if a decision token is expired.
+
+```typescript
+import { isTokenExpired } from '@creed-space/sdk';
+
+if (isTokenExpired(token)) {
+  // Request a new decision
+}
+```
+
+## Error Handling
+
+```typescript
+import { createClient, CreedError } from '@creed-space/sdk';
+
+try {
+  await client.decide({ ... });
+} catch (error) {
+  if (error instanceof CreedError) {
+    console.error('Code:', error.code);
+    console.error('Status:', error.statusCode);
+  }
+}
+```
+
+Error codes:
+- `MISSING_API_KEY` - API key not provided
+- `REQUEST_FAILED` - API request failed
+- `NETWORK_ERROR` - Network connectivity issue
+- `TIMEOUT` - Request timed out
+
+## Decision Types
+
+| Decision | Status | Description |
+|----------|--------|-------------|
+| `ALLOW` | Active | Tool execution authorized |
+| `DENY` | Active | Tool execution blocked |
+| `REQUIRE_HUMAN` | Planned | Human review required |
+| `REQUIRE_STEPUP` | Planned | Step-up authentication required |
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.0+ (for type definitions)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,205 @@
+/**
+ * Creed Space SDK for TypeScript
+ *
+ * Provides governance infrastructure for AI agents with:
+ * - Tool call authorization with cryptographic proof
+ * - Callback-based flow control (onAllow, onDeny, onRequireHuman)
+ * - Hash-chain audit trails
+ *
+ * Design inspired by Superagent's clean SDK patterns.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@creed-space/sdk';
+ *
+ * const client = createClient({ apiKey: 'crd_live_...' });
+ *
+ * const result = await client.decide({
+ *   toolName: 'send_email',
+ *   arguments: { to: 'user@example.com', subject: 'Hello' },
+ *   onAllow: (decision) => {
+ *     console.log('Authorized:', decision.token);
+ *     // Execute the tool
+ *   },
+ *   onDeny: (decision) => {
+ *     console.log('Denied:', decision.reasons);
+ *   },
+ *   onRequireHuman: (decision) => {
+ *     // Feature planned - will trigger human review workflow
+ *     console.log('Human review required (planned feature)');
+ *   },
+ * });
+ * ```
+ */
+type DecisionType = 'ALLOW' | 'DENY' | 'REQUIRE_HUMAN';
+interface Risk {
+    score: number;
+    labels: string[];
+}
+interface DecideRequest {
+    /** Name of the tool to execute */
+    toolName: string;
+    /** Tool arguments */
+    arguments: Record<string, unknown>;
+    /** Constitution ID (default: 'default') */
+    constitutionId?: string;
+    /** Optional context */
+    context?: {
+        tenantId?: string;
+        projectId?: string;
+        userId?: string;
+        sessionId?: string;
+    };
+    /** Callback when tool is allowed */
+    onAllow?: (decision: AllowDecision) => void | Promise<void>;
+    /** Callback when tool is denied */
+    onDeny?: (decision: DenyDecision) => void | Promise<void>;
+    /** Callback when human review is required (planned feature) */
+    onRequireHuman?: (decision: RequireHumanDecision) => void | Promise<void>;
+}
+interface AllowDecision {
+    decision: 'ALLOW';
+    runId: string;
+    actionId: string;
+    toolCallId: string;
+    argsHash: string;
+    risk: Risk;
+    /** Signed JWT decision token */
+    decisionToken: string;
+    /** Token expiry */
+    expiresAt: string;
+}
+interface DenyDecision {
+    decision: 'DENY';
+    runId: string;
+    actionId: string;
+    toolCallId: string;
+    argsHash: string;
+    risk: Risk;
+    reasons: string[];
+    guidance: {
+        message: string;
+        suggestion?: string;
+    };
+}
+interface RequireHumanDecision {
+    decision: 'REQUIRE_HUMAN';
+    runId: string;
+    actionId: string;
+    toolCallId: string;
+    argsHash: string;
+    risk: Risk;
+    /** Review ID for tracking (planned) */
+    reviewId?: string;
+    /** Status - always 'planned' until feature is released */
+    featureStatus: 'planned';
+}
+type DecideResult = AllowDecision | DenyDecision | RequireHumanDecision;
+interface AuthorizeRequest {
+    /** The decision token to verify */
+    decisionToken: string;
+    /** Tool name (must match token) */
+    toolName?: string;
+    /** Args hash (must match token) */
+    argsHash?: string;
+}
+interface AuthorizeResult {
+    authorized: boolean;
+    claims?: {
+        actionId: string;
+        toolName: string;
+        toolCallId: string;
+        argsHash: string;
+        runId: string;
+        decision: string;
+        issuedAt: string;
+        expiresAt: string;
+    };
+    error?: string;
+    message: string;
+}
+interface AuditRequest {
+    /** Run ID to query */
+    runId: string;
+    /** Specific action ID (optional) */
+    actionId?: string;
+    /** Max events to return */
+    limit?: number;
+}
+interface AuditEvent {
+    seq: number;
+    type: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+    hash: string;
+}
+interface AuditResult {
+    runId: string;
+    actionId?: string;
+    eventCount: number;
+    events: AuditEvent[];
+    integrity: {
+        chain: string;
+        verified: boolean;
+    };
+}
+interface CreedClientOptions {
+    /** API key (crd_live_... or crd_test_...) */
+    apiKey: string;
+    /** Base URL (default: https://api.creed.space) */
+    baseUrl?: string;
+    /** Custom fetch implementation */
+    fetch?: typeof fetch;
+    /** Request timeout in ms (default: 30000) */
+    timeoutMs?: number;
+}
+interface CreedClient {
+    /** Get a governance decision for a tool call */
+    decide(request: DecideRequest): Promise<DecideResult>;
+    /** Verify a decision token before execution */
+    authorize(request: AuthorizeRequest): Promise<AuthorizeResult>;
+    /** Query the audit trail */
+    audit(request: AuditRequest): Promise<AuditResult>;
+    /** Get service status */
+    status(): Promise<StatusResult>;
+}
+interface StatusResult {
+    service: string;
+    version: string;
+    features: Record<string, {
+        status: string;
+        description: string;
+    }>;
+    decisionTypes: Record<string, string>;
+}
+declare class CreedError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+/**
+ * Create a Creed Space client.
+ *
+ * @param options - Client configuration
+ * @returns CreedClient instance
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   apiKey: process.env.CREED_API_KEY!,
+ *   baseUrl: 'https://api.creed.space',
+ * });
+ * ```
+ */
+declare function createClient(options: CreedClientOptions): CreedClient;
+/**
+ * Compute SHA-256 hash of arguments (for verification).
+ * Uses the same canonical JSON format as the server.
+ */
+declare function computeArgsHash(args: Record<string, unknown>): Promise<string>;
+/**
+ * Check if a decision token is expired (without verification).
+ */
+declare function isTokenExpired(token: string): boolean;
+
+export { type AllowDecision, type AuditEvent, type AuditRequest, type AuditResult, type AuthorizeRequest, type AuthorizeResult, type CreedClient, type CreedClientOptions, CreedError, type DecideRequest, type DecideResult, type DecisionType, type DenyDecision, type RequireHumanDecision, type Risk, type StatusResult, computeArgsHash, createClient, createClient as default, isTokenExpired };

package/dist/index.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Creed Space SDK for TypeScript
+ *
+ * Provides governance infrastructure for AI agents with:
+ * - Tool call authorization with cryptographic proof
+ * - Callback-based flow control (onAllow, onDeny, onRequireHuman)
+ * - Hash-chain audit trails
+ *
+ * Design inspired by Superagent's clean SDK patterns.
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@creed-space/sdk';
+ *
+ * const client = createClient({ apiKey: 'crd_live_...' });
+ *
+ * const result = await client.decide({
+ *   toolName: 'send_email',
+ *   arguments: { to: 'user@example.com', subject: 'Hello' },
+ *   onAllow: (decision) => {
+ *     console.log('Authorized:', decision.token);
+ *     // Execute the tool
+ *   },
+ *   onDeny: (decision) => {
+ *     console.log('Denied:', decision.reasons);
+ *   },
+ *   onRequireHuman: (decision) => {
+ *     // Feature planned - will trigger human review workflow
+ *     console.log('Human review required (planned feature)');
+ *   },
+ * });
+ * ```
+ */
+type DecisionType = 'ALLOW' | 'DENY' | 'REQUIRE_HUMAN';
+interface Risk {
+    score: number;
+    labels: string[];
+}
+interface DecideRequest {
+    /** Name of the tool to execute */
+    toolName: string;
+    /** Tool arguments */
+    arguments: Record<string, unknown>;
+    /** Constitution ID (default: 'default') */
+    constitutionId?: string;
+    /** Optional context */
+    context?: {
+        tenantId?: string;
+        projectId?: string;
+        userId?: string;
+        sessionId?: string;
+    };
+    /** Callback when tool is allowed */
+    onAllow?: (decision: AllowDecision) => void | Promise<void>;
+    /** Callback when tool is denied */
+    onDeny?: (decision: DenyDecision) => void | Promise<void>;
+    /** Callback when human review is required (planned feature) */
+    onRequireHuman?: (decision: RequireHumanDecision) => void | Promise<void>;
+}
+interface AllowDecision {
+    decision: 'ALLOW';
+    runId: string;
+    actionId: string;
+    toolCallId: string;
+    argsHash: string;
+    risk: Risk;
+    /** Signed JWT decision token */
+    decisionToken: string;
+    /** Token expiry */
+    expiresAt: string;
+}
+interface DenyDecision {
+    decision: 'DENY';
+    runId: string;
+    actionId: string;
+    toolCallId: string;
+    argsHash: string;
+    risk: Risk;
+    reasons: string[];
+    guidance: {
+        message: string;
+        suggestion?: string;
+    };
+}
+interface RequireHumanDecision {
+    decision: 'REQUIRE_HUMAN';
+    runId: string;
+    actionId: string;
+    toolCallId: string;
+    argsHash: string;
+    risk: Risk;
+    /** Review ID for tracking (planned) */
+    reviewId?: string;
+    /** Status - always 'planned' until feature is released */
+    featureStatus: 'planned';
+}
+type DecideResult = AllowDecision | DenyDecision | RequireHumanDecision;
+interface AuthorizeRequest {
+    /** The decision token to verify */
+    decisionToken: string;
+    /** Tool name (must match token) */
+    toolName?: string;
+    /** Args hash (must match token) */
+    argsHash?: string;
+}
+interface AuthorizeResult {
+    authorized: boolean;
+    claims?: {
+        actionId: string;
+        toolName: string;
+        toolCallId: string;
+        argsHash: string;
+        runId: string;
+        decision: string;
+        issuedAt: string;
+        expiresAt: string;
+    };
+    error?: string;
+    message: string;
+}
+interface AuditRequest {
+    /** Run ID to query */
+    runId: string;
+    /** Specific action ID (optional) */
+    actionId?: string;
+    /** Max events to return */
+    limit?: number;
+}
+interface AuditEvent {
+    seq: number;
+    type: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+    hash: string;
+}
+interface AuditResult {
+    runId: string;
+    actionId?: string;
+    eventCount: number;
+    events: AuditEvent[];
+    integrity: {
+        chain: string;
+        verified: boolean;
+    };
+}
+interface CreedClientOptions {
+    /** API key (crd_live_... or crd_test_...) */
+    apiKey: string;
+    /** Base URL (default: https://api.creed.space) */
+    baseUrl?: string;
+    /** Custom fetch implementation */
+    fetch?: typeof fetch;
+    /** Request timeout in ms (default: 30000) */
+    timeoutMs?: number;
+}
+interface CreedClient {
+    /** Get a governance decision for a tool call */
+    decide(request: DecideRequest): Promise<DecideResult>;
+    /** Verify a decision token before execution */
+    authorize(request: AuthorizeRequest): Promise<AuthorizeResult>;
+    /** Query the audit trail */
+    audit(request: AuditRequest): Promise<AuditResult>;
+    /** Get service status */
+    status(): Promise<StatusResult>;
+}
+interface StatusResult {
+    service: string;
+    version: string;
+    features: Record<string, {
+        status: string;
+        description: string;
+    }>;
+    decisionTypes: Record<string, string>;
+}
+declare class CreedError extends Error {
+    code: string;
+    statusCode?: number | undefined;
+    constructor(message: string, code: string, statusCode?: number | undefined);
+}
+/**
+ * Create a Creed Space client.
+ *
+ * @param options - Client configuration
+ * @returns CreedClient instance
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   apiKey: process.env.CREED_API_KEY!,
+ *   baseUrl: 'https://api.creed.space',
+ * });
+ * ```
+ */
+declare function createClient(options: CreedClientOptions): CreedClient;
+/**
+ * Compute SHA-256 hash of arguments (for verification).
+ * Uses the same canonical JSON format as the server.
+ */
+declare function computeArgsHash(args: Record<string, unknown>): Promise<string>;
+/**
+ * Check if a decision token is expired (without verification).
+ */
+declare function isTokenExpired(token: string): boolean;
+
+export { type AllowDecision, type AuditEvent, type AuditRequest, type AuditResult, type AuthorizeRequest, type AuthorizeResult, type CreedClient, type CreedClientOptions, CreedError, type DecideRequest, type DecideResult, type DecisionType, type DenyDecision, type RequireHumanDecision, type Risk, type StatusResult, computeArgsHash, createClient, createClient as default, isTokenExpired };