@creedspace/sdk 1.0.0

package/src/index.ts

@@ -0,0 +1,364 @@
+/**
+ * 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)');
+ *   },
+ * });
+ * ```
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type DecisionType = 'ALLOW' | 'DENY' | 'REQUIRE_HUMAN';
+
+export interface Risk {
+  score: number;
+  labels: string[];
+}
+
+export 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>;
+}
+
+export interface AllowDecision {
+  decision: 'ALLOW';
+  runId: string;
+  actionId: string;
+  toolCallId: string;
+  argsHash: string;
+  risk: Risk;
+  /** Signed JWT decision token */
+  decisionToken: string;
+  /** Token expiry */
+  expiresAt: string;
+}
+
+export interface DenyDecision {
+  decision: 'DENY';
+  runId: string;
+  actionId: string;
+  toolCallId: string;
+  argsHash: string;
+  risk: Risk;
+  reasons: string[];
+  guidance: {
+    message: string;
+    suggestion?: string;
+  };
+}
+
+export 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';
+}
+
+export type DecideResult = AllowDecision | DenyDecision | RequireHumanDecision;
+
+export interface AuthorizeRequest {
+  /** The decision token to verify */
+  decisionToken: string;
+  /** Tool name (must match token) */
+  toolName?: string;
+  /** Args hash (must match token) */
+  argsHash?: string;
+}
+
+export 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;
+}
+
+export interface AuditRequest {
+  /** Run ID to query */
+  runId: string;
+  /** Specific action ID (optional) */
+  actionId?: string;
+  /** Max events to return */
+  limit?: number;
+}
+
+export interface AuditEvent {
+  seq: number;
+  type: string;
+  timestamp: string;
+  data: Record<string, unknown>;
+  hash: string;
+}
+
+export interface AuditResult {
+  runId: string;
+  actionId?: string;
+  eventCount: number;
+  events: AuditEvent[];
+  integrity: {
+    chain: string;
+    verified: boolean;
+  };
+}
+
+export 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;
+}
+
+export 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>;
+}
+
+export interface StatusResult {
+  service: string;
+  version: string;
+  features: Record<string, { status: string; description: string }>;
+  decisionTypes: Record<string, string>;
+}
+
+// ============================================================================
+// Errors
+// ============================================================================
+
+export class CreedError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode?: number
+  ) {
+    super(message);
+    this.name = 'CreedError';
+  }
+}
+
+// ============================================================================
+// Client Implementation
+// ============================================================================
+
+/**
+ * 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',
+ * });
+ * ```
+ */
+export function createClient(options: CreedClientOptions): CreedClient {
+  const {
+    apiKey,
+    baseUrl = 'https://api.creed.space',
+    fetch: customFetch = fetch,
+    timeoutMs = 30000,
+  } = options;
+
+  if (!apiKey) {
+    throw new CreedError('API key is required', 'MISSING_API_KEY');
+  }
+
+  async function request<T>(
+    endpoint: string,
+    method: string,
+    body?: Record<string, unknown>
+  ): Promise<T> {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+
+    try {
+      const response = await customFetch(`${baseUrl}${endpoint}`, {
+        method,
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${apiKey}`,
+          'X-Creed-SDK': 'typescript/1.0.0',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const errorBody = await response.text();
+        throw new CreedError(
+          errorBody || `Request failed with status ${response.status}`,
+          'REQUEST_FAILED',
+          response.status
+        );
+      }
+
+      return response.json();
+    } catch (error) {
+      if (error instanceof CreedError) throw error;
+      if ((error as Error).name === 'AbortError') {
+        throw new CreedError('Request timed out', 'TIMEOUT');
+      }
+      throw new CreedError((error as Error).message, 'NETWORK_ERROR');
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  return {
+    async decide(req: DecideRequest): Promise<DecideResult> {
+      const response = await request<DecideResult>('/v1/decide', 'POST', {
+        tool_name: req.toolName,
+        arguments: req.arguments,
+        constitution_id: req.constitutionId || 'default',
+        context: req.context || {},
+      });
+
+      // Invoke appropriate callback
+      if (response.decision === 'ALLOW' && req.onAllow) {
+        await req.onAllow(response as AllowDecision);
+      } else if (response.decision === 'DENY' && req.onDeny) {
+        await req.onDeny(response as DenyDecision);
+      } else if (response.decision === 'REQUIRE_HUMAN' && req.onRequireHuman) {
+        // Note: REQUIRE_HUMAN is a planned feature
+        const humanDecision: RequireHumanDecision = {
+          ...(response as RequireHumanDecision),
+          featureStatus: 'planned',
+        };
+        await req.onRequireHuman(humanDecision);
+      }
+
+      return response;
+    },
+
+    async authorize(req: AuthorizeRequest): Promise<AuthorizeResult> {
+      return request<AuthorizeResult>('/v1/authorize', 'POST', {
+        decision_token: req.decisionToken,
+        tool_name: req.toolName,
+        args_hash: req.argsHash,
+      });
+    },
+
+    async audit(req: AuditRequest): Promise<AuditResult> {
+      return request<AuditResult>('/v1/audit', 'POST', {
+        run_id: req.runId,
+        action_id: req.actionId,
+        limit: req.limit || 50,
+      });
+    },
+
+    async status(): Promise<StatusResult> {
+      return request<StatusResult>('/v1/status', 'GET');
+    },
+  };
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Compute SHA-256 hash of arguments (for verification).
+ * Uses the same canonical JSON format as the server.
+ */
+export async function computeArgsHash(
+  args: Record<string, unknown>
+): Promise<string> {
+  // Canonical JSON: sorted keys, no whitespace
+  const canonical = JSON.stringify(args, Object.keys(args).sort());
+  const encoder = new TextEncoder();
+  const data = encoder.encode(canonical);
+  const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+  const hashArray = Array.from(new Uint8Array(hashBuffer));
+  return 'sha256:' + hashArray.map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+/**
+ * Check if a decision token is expired (without verification).
+ */
+export function isTokenExpired(token: string): boolean {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return true;
+    const payload = JSON.parse(atob(parts[1]));
+    return payload.exp * 1000 < Date.now();
+  } catch {
+    return true;
+  }
+}
+
+// ============================================================================
+// Re-exports for convenience
+// ============================================================================
+
+export default createClient;