sandstream-kit 1.0.0

package/dist/approval.js

@@ -0,0 +1,148 @@
+import * as readline from "node:readline/promises";
+import { isNonInteractive } from "./environment.js";
+import { mergeGovernanceConfig, isDestructiveOperation } from "./governance.js";
+import { IdGenerators } from "./id-generator.js";
+/**
+ * Send approval request to webhook
+ */
+async function sendApprovalWebhook(request, webhookUrl) {
+    try {
+        const response = await fetch(webhookUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+                operation: request.operation,
+                environment: request.environment,
+                agent_id: request.agent_id,
+                reason: request.reason,
+                details: request.metadata,
+                timestamp: new Date().toISOString(),
+            }),
+        });
+        if (!response.ok) {
+            console.error(`Failed to send approval webhook: ${response.status} ${response.statusText}`);
+        }
+    }
+    catch (error) {
+        console.error("Failed to send approval webhook:", error);
+    }
+}
+/**
+ * Wait for approval via Remote API
+ */
+async function waitForRemoteApproval(approvalId, companyId, timeoutMs) {
+    const apiUrl = process.env.KIT_REMOTE_URL || "http://localhost:3199";
+    const url = `${apiUrl}/api/companies/${companyId}/approvals/${approvalId}`;
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeoutMs) {
+        try {
+            const response = await fetch(url);
+            if (response.ok) {
+                const data = await response.json();
+                if (data.status === "approved") {
+                    return { approved: true, approval_id: approvalId };
+                }
+                if (data.status === "denied") {
+                    return {
+                        approved: false,
+                        approval_id: approvalId,
+                        denied_reason: data.reason,
+                    };
+                }
+            }
+        }
+        catch (error) {
+            console.error("Error checking approval status:", error);
+        }
+        // Wait 2 seconds before checking again
+        await new Promise((resolve) => setTimeout(resolve, 2000));
+    }
+    return { approved: false, timeout: true };
+}
+/**
+ * Request human approval for an operation
+ */
+export async function requestApproval(config, request, companyId) {
+    const fullConfig = mergeGovernanceConfig(config);
+    // If approval is not configured, auto-approve
+    if (!fullConfig.approval) {
+        return true;
+    }
+    // Check if operation requires approval
+    const requiresApproval = isDestructiveOperation(fullConfig, request.operation) ||
+        (request.environment === "prod" && fullConfig.approval.production_writes);
+    if (!requiresApproval) {
+        return true;
+    }
+    // Display approval request
+    console.log("\n" + "=".repeat(80));
+    console.log("APPROVAL REQUIRED");
+    console.log("=".repeat(80));
+    console.log(`Operation: ${request.operation}`);
+    console.log(`Environment: ${request.environment}`);
+    console.log(`Reason: ${request.reason}`);
+    if (request.metadata && Object.keys(request.metadata).length > 0) {
+        console.log(`Metadata: ${JSON.stringify(request.metadata, null, 2)}`);
+    }
+    console.log("=".repeat(80));
+    // Send webhook notification if configured
+    const webhookUrl = process.env.KIT_APPROVAL_WEBHOOK;
+    if (webhookUrl) {
+        await sendApprovalWebhook(request, webhookUrl);
+    }
+    // If company ID is provided, use Remote API approval flow
+    if (companyId) {
+        const approvalId = IdGenerators.approval();
+        const timeout = fullConfig.approval.approval_timeout || 3600;
+        console.log(`\nWaiting for approval via Remote API (timeout: ${timeout}s)...`);
+        console.log(`Approval ID: ${approvalId}`);
+        const result = await waitForRemoteApproval(approvalId, companyId, timeout * 1000);
+        if (result.approved) {
+            console.log("✓ Operation approved");
+            return true;
+        }
+        if (result.timeout) {
+            console.log("✗ Approval timeout");
+            return false;
+        }
+        if (result.denied_reason) {
+            console.log(`✗ Operation denied: ${result.denied_reason}`);
+            return false;
+        }
+        return false;
+    }
+    // Non-interactive mode: skip CLI prompt and deny
+    if (isNonInteractive()) {
+        console.error("✗ Approval required but running in non-interactive mode — operation denied");
+        return false;
+    }
+    // Fall back to CLI approval
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await rl.question("\nDo you approve this operation? (yes/no): ");
+        rl.close();
+        return answer.toLowerCase().trim() === "yes";
+    }
+    catch (error) {
+        rl.close();
+        console.error("Failed to request approval:", error);
+        return false;
+    }
+}
+/**
+ * Check if an operation would require approval without actually requesting it
+ */
+export function wouldRequireApproval(config, operation, environment) {
+    const fullConfig = mergeGovernanceConfig(config);
+    if (!fullConfig.approval) {
+        return false;
+    }
+    return (isDestructiveOperation(fullConfig, operation) ||
+        (environment === "prod" && fullConfig.approval.production_writes === true));
+}
+//# sourceMappingURL=approval.js.map

package/dist/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"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"}

package/dist/audit-logging-model.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Audit Logging & Compliance — data models
+ * Comprehensive audit trail, activity tracking, change history, compliance reporting
+ */
+export type AuditAction = "create" | "read" | "update" | "delete" | "execute" | "approve" | "reject" | "export" | "import" | "login" | "logout";
+export type AuditResource = "team" | "member" | "role" | "permission" | "plugin" | "workflow" | "integration" | "settings" | "api_key" | "session";
+export type ComplianceStandard = "SOC2" | "GDPR" | "HIPAA" | "ISO27001" | "PCI-DSS";
+export type AuditSeverity = "low" | "medium" | "high" | "critical";
+export interface AuditEntry {
+    id: string;
+    action: AuditAction;
+    resource: AuditResource;
+    resource_id: string;
+    actor_id: string;
+    actor_name: string;
+    actor_ip?: string;
+    team_id?: string;
+    status: "success" | "failure";
+    status_code?: number;
+    changes?: {
+        field: string;
+        old_value: unknown;
+        new_value: unknown;
+    }[];
+    details: Record<string, unknown>;
+    severity: AuditSeverity;
+    timestamp: string;
+    created_at: string;
+}
+export interface UserActivity {
+    id: string;
+    user_id: string;
+    user_name: string;
+    team_id?: string;
+    action_count: number;
+    last_action_at: string;
+    first_action_at: string;
+    login_count: number;
+    last_login_at?: string;
+    unique_resources_accessed: number;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+export interface ChangeHistory {
+    id: string;
+    resource_id: string;
+    resource_type: AuditResource;
+    team_id?: string;
+    change_type: "created" | "updated" | "deleted";
+    previous_state?: Record<string, unknown>;
+    current_state: Record<string, unknown>;
+    changed_by: string;
+    changed_by_name: string;
+    reason?: string;
+    timestamp: string;
+    created_at: string;
+}
+export interface ComplianceReport {
+    id: string;
+    standard: ComplianceStandard;
+    period_start: string;
+    period_end: string;
+    team_id?: string;
+    total_audit_entries: number;
+    security_events: number;
+    failed_operations: number;
+    data_access_events: number;
+    deletion_events: number;
+    role_changes: number;
+    permission_changes: number;
+    compliance_score: number;
+    issues: ComplianceIssue[];
+    generated_at: string;
+    generated_by: string;
+    created_at: string;
+}
+export interface ComplianceIssue {
+    id: string;
+    severity: AuditSeverity;
+    type: string;
+    description: string;
+    resource_id?: string;
+    resource_type?: AuditResource;
+    actor_id?: string;
+    timestamp: string;
+    remediation?: string;
+}
+export interface AuditLog {
+    id: string;
+    team_id?: string;
+    action: AuditAction;
+    resource: AuditResource;
+    resource_id: string;
+    actor_id: string;
+    actor_name: string;
+    status: "success" | "failure";
+    severity: AuditSeverity;
+    details: Record<string, unknown>;
+    timestamp: string;
+    created_at: string;
+}
+export interface AuditQuery {
+    team_id?: string;
+    actor_id?: string;
+    resource?: AuditResource;
+    action?: AuditAction;
+    status?: "success" | "failure";
+    severity?: AuditSeverity;
+    start_date?: string;
+    end_date?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface AuditMetrics {
+    total_entries: number;
+    entries_last_24h: number;
+    entries_last_7d: number;
+    entries_last_30d: number;
+    unique_users: number;
+    unique_resources: number;
+    failed_operations_count: number;
+    critical_events_count: number;
+    average_actions_per_user: number;
+    most_common_action: string;
+    most_accessed_resource: string;
+}
+export interface DataExportRequest {
+    id: string;
+    user_id: string;
+    team_id?: string;
+    export_type: "full" | "filtered";
+    data_types: AuditResource[];
+    start_date?: string;
+    end_date?: string;
+    format: "json" | "csv" | "parquet";
+    status: "pending" | "processing" | "completed" | "failed";
+    download_url?: string;
+    expires_at?: string;
+    requested_at: string;
+    completed_at?: string;
+    created_at: string;
+}
+export interface SessionAudit {
+    id: string;
+    user_id: string;
+    session_id: string;
+    ip_address: string;
+    user_agent: string;
+    login_time: string;
+    logout_time?: string;
+    duration_minutes?: number;
+    actions_count: number;
+    last_activity_at: string;
+    is_active: boolean;
+    created_at: string;
+}

package/dist/audit-logging-model.js

@@ -0,0 +1,6 @@
+/**
+ * Audit Logging & Compliance — data models
+ * Comprehensive audit trail, activity tracking, change history, compliance reporting
+ */
+export {};
+//# sourceMappingURL=audit-logging-model.js.map

package/dist/audit-logging-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logging-model.js","sourceRoot":"","sources":["../src/audit-logging-model.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/audit-logging-service.d.ts

@@ -0,0 +1,89 @@
+import type { AuditEntry, UserActivity, ChangeHistory, ComplianceReport, AuditQuery, AuditMetrics, DataExportRequest, SessionAudit, AuditAction, AuditResource, AuditSeverity, ComplianceStandard } from "./audit-logging-model.js";
+/**
+ * Record audit entry
+ */
+export declare function recordAuditEntry(action: AuditAction, resource: AuditResource, resource_id: string, actor_id: string, actor_name: string, status?: "success" | "failure", details?: Record<string, unknown>, severity?: AuditSeverity, team_id?: string, actor_ip?: string): {
+    entry: AuditEntry;
+    error?: string;
+};
+/**
+ * Record change history
+ */
+export declare function recordChangeHistory(resource_id: string, resource_type: AuditResource, change_type: "created" | "updated" | "deleted", current_state: Record<string, unknown>, changed_by: string, changed_by_name: string, previous_state?: Record<string, unknown>, reason?: string, team_id?: string): {
+    history: ChangeHistory;
+    error?: string;
+};
+/**
+ * Query audit entries
+ */
+export declare function queryAuditEntries(query: AuditQuery): {
+    entries: AuditEntry[];
+    total: number;
+};
+/**
+ * Get user activity
+ */
+export declare function getUserActivity(user_id: string): {
+    activity: UserActivity | null;
+    error?: string;
+};
+/**
+ * List user activities
+ */
+export declare function listUserActivities(team_id?: string, limit?: number, offset?: number): {
+    activities: UserActivity[];
+    total: number;
+};
+/**
+ * Get change history for resource
+ */
+export declare function getChangeHistory(resource_id: string, limit?: number, offset?: number): {
+    history: ChangeHistory[];
+    total: number;
+};
+/**
+ * Generate compliance report
+ */
+export declare function generateComplianceReport(standard: ComplianceStandard, period_start: string, period_end: string, generated_by: string, team_id?: string): {
+    report: ComplianceReport;
+    error?: string;
+};
+/**
+ * List compliance reports
+ */
+export declare function listComplianceReports(team_id?: string, limit?: number, offset?: number): {
+    reports: ComplianceReport[];
+    total: number;
+};
+/**
+ * Request data export for compliance
+ */
+export declare function requestDataExport(user_id: string, format: "json" | "csv" | "parquet", data_types: AuditResource[], team_id?: string, start_date?: string, end_date?: string): {
+    request: DataExportRequest;
+    error?: string;
+};
+/**
+ * Get data export status
+ */
+export declare function getDataExportStatus(export_id: string): {
+    request: DataExportRequest | null;
+    error?: string;
+};
+/**
+ * Record session audit
+ */
+export declare function recordSessionAudit(user_id: string, session_id: string, ip_address: string, user_agent: string): {
+    session: SessionAudit;
+    error?: string;
+};
+/**
+ * End session audit
+ */
+export declare function endSessionAudit(session_id: string): {
+    success: boolean;
+    error?: string;
+};
+/**
+ * Get audit metrics
+ */
+export declare function getAuditMetrics(team_id?: string): AuditMetrics;