palaryn 0.1.0 → 0.3.2

package/src/storage/interfaces.ts

@@ -0,0 +1,287 @@
+import { BudgetState } from '../types/budget';
+import { AuditEvent, EventType } from '../types/events';
+import { PolicyPack } from '../types/policy';
+import {
+  User,
+  OAuthAccount,
+  OAuthProvider,
+  Workspace,
+  WorkspaceMember,
+  Session,
+  UserApiKey,
+} from '../types/user';
+import { Subscription } from '../types/subscription';
+
+import { ToolResult } from '../types/tool-result';
+
+/**
+ * Record stored by the ApprovalStore. Mirrors the shape created by ApprovalManager.
+ */
+export interface ApprovalRecord {
+  approval_id: string;
+  tool_call_id: string;
+  task_id: string;
+  workspace_id: string;
+  actor_id: string;
+  requesting_api_key_id?: string;
+  tool_name: string;
+  tool_capability: string;
+  args_summary: string;
+  scope: string;
+  reason: string;
+  token_hash: string;
+  status: 'pending' | 'approved' | 'denied' | 'expired';
+  created_at: string;
+  expires_at: string;
+  resolved_at?: string;
+  resolved_by?: string;
+  denial_reason?: string;
+}
+
+/**
+ * Storage interface for budget state.
+ * Implementations: InMemoryBudgetStore, PostgresBudgetStore, RedisBudgetStore
+ */
+export interface BudgetStore {
+  getTaskState(taskId: string): BudgetState | undefined;
+  setTaskState(taskId: string, state: BudgetState): void;
+
+  getCounter(key: string): number;
+  incrementCounter(key: string, amount: number): void;
+
+  getRetryCount(toolCallId: string): number;
+  incrementRetryCount(toolCallId: string): number;
+
+  /** Enumerate all task states (for BudgetManager hydration). */
+  getAllTaskStates?(): Map<string, BudgetState>;
+  /** Enumerate all counters (for BudgetManager hydration). */
+  getAllCounters?(): Map<string, number>;
+  /** Enumerate all retry counts (for BudgetManager hydration). */
+  getAllRetryCounts?(): Map<string, number>;
+
+  /** Wait for all pending async writes to complete. */
+  flush?(): Promise<void>;
+
+  reset(): void;
+}
+
+/**
+ * Storage interface for audit events.
+ * Implementations: InMemoryAuditStore, PostgresAuditStore, RedisAuditStore
+ */
+export interface AuditStore {
+  append(event: AuditEvent): void;
+  getByTaskId(taskId: string): AuditEvent[];
+  getByToolCallId(toolCallId: string): AuditEvent[];
+  getByEventType(eventType: EventType): AuditEvent[];
+  getAll(): AuditEvent[];
+  deleteByTaskId(taskId: string): void;
+  deleteBySessionId(sessionId: string): void;
+  clear(): void;
+}
+
+/**
+ * Storage interface for approval records.
+ * Implementations: InMemoryApprovalStore, PostgresApprovalStore, RedisApprovalStore
+ */
+export interface ApprovalStore {
+  save(approvalId: string, approval: ApprovalRecord): void;
+  getById(approvalId: string): ApprovalRecord | undefined;
+  /** Look up an approval by token hash (SHA-256 hex digest). */
+  getByToken(tokenHash: string): ApprovalRecord | undefined;
+  getByToolCallId(toolCallId: string): ApprovalRecord | undefined;
+  /** Find an approved approval for the given task + actor + tool combination. */
+  findApproved?(taskId: string, actorId: string, toolName: string, capability: string): ApprovalRecord | undefined;
+  findPending(workspaceId?: string): ApprovalRecord[];
+  /** Index a token hash to an approval ID for reverse lookup. */
+  indexToken(tokenHash: string, approvalId: string): void;
+  /**
+   * Atomically update an approval only if its current status matches expectedStatus.
+   * Returns true if the update succeeded, false if the status had already changed.
+   * Used to prevent race conditions where two concurrent callers both approve/deny.
+   */
+  compareAndSetStatus?(approvalId: string, expectedStatus: string, approval: ApprovalRecord): boolean | Promise<boolean>;
+  /** Wait for all pending async writes to complete. */
+  flush?(): Promise<void>;
+  clear(): void;
+}
+
+/**
+ * Storage interface for idempotency deduplication.
+ * Stores tool_call_id -> ToolResult mappings for dedup.
+ */
+export interface IdempotencyStore {
+  get(toolCallId: string): ToolResult | undefined | Promise<ToolResult | undefined>;
+  set(toolCallId: string, result: ToolResult, ttlMs: number): void;
+  has(toolCallId: string): boolean | Promise<boolean>;
+  /** Wait for all pending async writes to complete. */
+  flush?(): Promise<void>;
+  clear(): void;
+}
+
+/**
+ * Storage interface for rate limiting.
+ */
+export interface RateLimitStore {
+  /**
+   * Record a hit and check if the rate limit is exceeded.
+   * @param key - Rate limit key (e.g., "actor:agent-001" or "workspace:ws-001")
+   * @param windowMs - Time window in milliseconds
+   * @param maxRequests - Maximum requests allowed in the window
+   * @returns { allowed: boolean, current: number, limit: number, resetAt: number }
+   */
+  hit(key: string, windowMs: number, maxRequests: number): {
+    allowed: boolean;
+    current: number;
+    limit: number;
+    resetAt: number;
+  };
+  /** Bulk-hydrate local cache from persistent backend (e.g. Redis). */
+  hydrateAll?(): Promise<void>;
+  reset(): void;
+}
+
+// ---------------------------------------------------------------------------
+// SaaS Store Interfaces
+// ---------------------------------------------------------------------------
+
+/**
+ * Storage interface for user accounts.
+ */
+export interface UserStore {
+  create(user: User): void;
+  getById(id: string): User | undefined;
+  getByEmail(email: string): User | undefined;
+  update(id: string, updates: Partial<Pick<User, 'display_name' | 'avatar_url' | 'password_hash' | 'status' | 'onboarding_completed' | 'updated_at'>>): User | undefined;
+  delete(id: string): boolean;
+  list(): User[];
+}
+
+/**
+ * Storage interface for OAuth accounts (provider links).
+ */
+export interface OAuthAccountStore {
+  create(account: OAuthAccount): void;
+  getById(id: string): OAuthAccount | undefined;
+  getByProvider(provider: OAuthProvider, providerUserId: string): OAuthAccount | undefined;
+  getByUserId(userId: string): OAuthAccount[];
+  update(id: string, updates: Partial<Pick<OAuthAccount, 'access_token_encrypted' | 'refresh_token_encrypted' | 'token_expires_at' | 'updated_at'>>): OAuthAccount | undefined;
+  delete(id: string): boolean;
+}
+
+/**
+ * Storage interface for workspaces.
+ */
+export interface WorkspaceStore {
+  create(workspace: Workspace): void;
+  getById(id: string): Workspace | undefined;
+  getBySlug(slug: string): Workspace | undefined;
+  getByOwner(userId: string): Workspace[];
+  update(id: string, updates: Partial<Pick<Workspace, 'name' | 'slug' | 'plan' | 'settings' | 'updated_at'>>): Workspace | undefined;
+  delete(id: string): boolean;
+  list(): Workspace[];
+}
+
+/**
+ * Storage interface for workspace membership.
+ */
+export interface WorkspaceMemberStore {
+  create(member: WorkspaceMember): void;
+  getById(id: string): WorkspaceMember | undefined;
+  getByWorkspace(workspaceId: string): WorkspaceMember[];
+  getByUser(userId: string): WorkspaceMember[];
+  getByWorkspaceAndUser(workspaceId: string, userId: string): WorkspaceMember | undefined;
+  update(id: string, updates: Partial<Pick<WorkspaceMember, 'role'>>): WorkspaceMember | undefined;
+  delete(id: string): boolean;
+}
+
+/**
+ * Storage interface for sessions.
+ */
+export interface SessionStore {
+  create(session: Session): void;
+  getById(id: string): Session | undefined;
+  getByUserId(userId: string): Session[];
+  update(id: string, updates: Partial<Pick<Session, 'workspace_id' | 'last_active_at'>>): Session | undefined;
+  delete(id: string): boolean;
+  deleteExpired(): number;
+  deleteByUserId(userId: string): number;
+}
+
+/**
+ * Storage interface for user-generated API keys.
+ */
+export interface UserApiKeyStore {
+  create(apiKey: UserApiKey): void;
+  getById(id: string): UserApiKey | undefined;
+  getByKeyHash(keyHash: string): UserApiKey | undefined;
+  /** Verify a raw token against all stored keys (supports salted and unsalted hashes) */
+  verifyToken?(token: string): UserApiKey | undefined;
+  getByWorkspace(workspaceId: string): UserApiKey[];
+  getByUser(userId: string): UserApiKey[];
+  update(id: string, updates: Partial<Pick<UserApiKey, 'name' | 'roles' | 'tags' | 'revoked' | 'last_used_at'>>): UserApiKey | undefined;
+  delete(id: string): boolean;
+}
+
+/**
+ * Storage interface for subscriptions (Stripe billing).
+ */
+export interface SubscriptionStore {
+  create(subscription: Subscription): void;
+  getById(id: string): Subscription | undefined;
+  getByWorkspace(workspaceId: string): Subscription | undefined;
+  getByStripeCustomerId(customerId: string): Subscription | undefined;
+  getByStripeSubscriptionId(subscriptionId: string): Subscription | undefined;
+  update(id: string, updates: Partial<Subscription>): Subscription | undefined;
+  delete(id: string): boolean;
+  list(): Subscription[];
+}
+
+/**
+ * Storage interface for workspace policy packs.
+ */
+export interface PolicyStore {
+  getByWorkspaceId(workspaceId: string): PolicyPack | undefined;
+  set(workspaceId: string, policy: PolicyPack): void;
+  delete(workspaceId: string): boolean;
+  list(): Map<string, PolicyPack>;
+  clear(): void;
+}
+
+// ---------------------------------------------------------------------------
+// Per-Workspace Rate Limit & Budget Configuration
+// ---------------------------------------------------------------------------
+
+export interface WorkspaceRateLimitConfig {
+  actor_max_per_window?: number;
+  workspace_max_per_window?: number;
+  window_ms?: number;
+}
+
+export interface WorkspaceBudgetConfig {
+  task_budget_usd?: number;
+  user_daily_budget_usd?: number;
+  user_monthly_budget_usd?: number;
+  workspace_daily_budget_usd?: number;
+  workspace_monthly_budget_usd?: number;
+  max_steps_per_task?: number;
+  max_retries_per_call?: number;
+  max_wall_clock_ms?: number;
+  token_pricing?: Record<string, import('../types/budget').TokenPricing>;
+}
+
+export interface RateLimitConfigStore {
+  getByWorkspaceId(workspaceId: string): WorkspaceRateLimitConfig | undefined;
+  set(workspaceId: string, config: WorkspaceRateLimitConfig): void;
+  delete(workspaceId: string): boolean;
+  list(): Map<string, WorkspaceRateLimitConfig>;
+  clear(): void;
+}
+
+export interface BudgetConfigStore {
+  getByWorkspaceId(workspaceId: string): WorkspaceBudgetConfig | undefined;
+  set(workspaceId: string, config: WorkspaceBudgetConfig): void;
+  delete(workspaceId: string): boolean;
+  list(): Map<string, WorkspaceBudgetConfig>;
+  clear(): void;
+}