stagent 0.8.0 → 0.9.0

package/src/lib/sync/cloud-sync.ts

@@ -0,0 +1,237 @@
+/**
+ * Cloud Sync — encrypted SQLite backup and restore via Supabase Storage.
+ *
+ * Encryption: AES-256-GCM with HKDF-derived keys.
+ * Envelope: [4B version][32B salt][12B IV][N bytes ciphertext][16B auth tag]
+ *
+ * V1: Full-database export (no incremental). Manual backup/restore only.
+ */
+
+import { createHash, createCipheriv, createDecipheriv, randomBytes } from "crypto";
+import { readFileSync, writeFileSync, existsSync, copyFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { getStagentDataDir } from "@/lib/utils/stagent-paths";
+import { getSupabaseClient } from "@/lib/cloud/supabase-client";
+import { sqlite } from "@/lib/db";
+
+const SYNC_VERSION = Buffer.from([0, 0, 0, 1]); // Version 1
+const BUCKET_NAME = "stagent-sync";
+
+export interface SyncResult {
+  success: boolean;
+  blobPath?: string;
+  sizeBytes?: number;
+  error?: string;
+}
+
+/**
+ * Derive an AES-256 key from userId using HKDF-like construction.
+ * Uses SHA-256 HMAC with a fixed info string and random salt.
+ */
+function deriveKey(userId: string, salt: Buffer): Buffer {
+  const hmac = createHash("sha256");
+  hmac.update(salt);
+  hmac.update(userId);
+  hmac.update("stagent-sync-v1");
+  return Buffer.from(hmac.digest());
+}
+
+/**
+ * Encrypt data using AES-256-GCM.
+ * Returns envelope: [4B version][32B salt][12B IV][ciphertext + 16B auth tag]
+ */
+function encrypt(data: Buffer, userId: string): Buffer {
+  const salt = randomBytes(32);
+  const iv = randomBytes(12);
+  const key = deriveKey(userId, salt);
+
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  return Buffer.concat([SYNC_VERSION, salt, iv, encrypted, authTag]);
+}
+
+/**
+ * Decrypt an envelope back to raw data.
+ */
+function decrypt(envelope: Buffer, userId: string): Buffer {
+  // Parse envelope
+  const version = envelope.subarray(0, 4);
+  if (!version.equals(SYNC_VERSION)) {
+    throw new Error(`Unsupported sync version: ${version.toString("hex")}`);
+  }
+
+  const salt = envelope.subarray(4, 36);
+  const iv = envelope.subarray(36, 48);
+  const authTag = envelope.subarray(envelope.length - 16);
+  const ciphertext = envelope.subarray(48, envelope.length - 16);
+
+  const key = deriveKey(userId, salt);
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(authTag);
+
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+/**
+ * Export the SQLite database, encrypt it, and upload to Supabase Storage.
+ */
+export async function exportAndUpload(
+  userId: string,
+  deviceId: string,
+  accessToken?: string
+): Promise<SyncResult> {
+  let supabase = getSupabaseClient();
+  if (!supabase) return { success: false, error: "Cloud not configured" };
+
+  // If an access token is provided, create an authenticated client for Storage RLS
+  if (accessToken) {
+    const { createClient } = await import("@supabase/supabase-js");
+    const url = process.env.NEXT_PUBLIC_SUPABASE_URL || "https://yznantjbmacbllhcyzwc.supabase.co";
+    const anonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY || "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6Inl6bmFudGpibWFjYmxsaGN5endjIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzI1MDg1ODMsImV4cCI6MjA4ODA4NDU4M30.i-P7MXpR1_emBjhUkzbFeSX7fgjgPDv90_wkqF7sW3Y";
+    supabase = createClient(url, anonKey, {
+      global: { headers: { Authorization: `Bearer ${accessToken}` } },
+      auth: { persistSession: false },
+    });
+  }
+
+  try {
+    // 1. Create a consistent backup using better-sqlite3 .backup()
+    const tempPath = join(tmpdir(), `stagent-export-${Date.now()}.db`);
+    await sqlite.backup(tempPath);
+
+    // 2. Read and encrypt
+    const dbBuffer = readFileSync(tempPath);
+    const encrypted = encrypt(dbBuffer, userId);
+
+    // 3. Upload to Supabase Storage
+    const blobPath = `${userId}/${deviceId}/${Date.now()}.enc`;
+    const { error: uploadError } = await supabase.storage
+      .from(BUCKET_NAME)
+      .upload(blobPath, encrypted, {
+        contentType: "application/octet-stream",
+        upsert: false,
+      });
+
+    if (uploadError) {
+      return { success: false, error: uploadError.message };
+    }
+
+    // 4. Record sync session
+    await supabase.from("sync_sessions").insert({
+      user_id: userId,
+      device_name: deviceId,
+      device_id: deviceId,
+      blob_path: blobPath,
+      blob_size_bytes: encrypted.length,
+      sync_type: "backup",
+      status: "completed",
+    });
+
+    // Clean up temp file
+    try { require("fs").unlinkSync(tempPath); } catch { /* ignore */ }
+
+    return { success: true, blobPath, sizeBytes: encrypted.length };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : "Export failed" };
+  }
+}
+
+/**
+ * Download the latest snapshot and restore it.
+ * Always creates a safety backup before restoring.
+ */
+export async function downloadAndRestore(userId: string): Promise<SyncResult> {
+  const supabase = getSupabaseClient();
+  if (!supabase) return { success: false, error: "Cloud not configured" };
+
+  try {
+    // 1. Find the latest snapshot
+    const { data: sessions, error: listError } = await supabase
+      .from("sync_sessions")
+      .select("blob_path, blob_size_bytes")
+      .eq("user_id", userId)
+      .eq("sync_type", "backup")
+      .eq("status", "completed")
+      .order("created_at", { ascending: false })
+      .limit(1);
+
+    if (listError || !sessions?.length) {
+      return { success: false, error: "No backup found" };
+    }
+
+    const { blob_path } = sessions[0];
+
+    // 2. Download encrypted snapshot
+    const { data: blob, error: downloadError } = await supabase.storage
+      .from(BUCKET_NAME)
+      .download(blob_path);
+
+    if (downloadError || !blob) {
+      return { success: false, error: downloadError?.message ?? "Download failed" };
+    }
+
+    const encrypted = Buffer.from(await blob.arrayBuffer());
+
+    // 3. Decrypt
+    const decrypted = decrypt(encrypted, userId);
+
+    // 4. Create safety backup of current DB
+    const dataDir = getStagentDataDir();
+    const safetyPath = join(dataDir, `stagent-safety-${Date.now()}.db`);
+    const dbPath = join(dataDir, "stagent.db");
+    if (existsSync(dbPath)) {
+      copyFileSync(dbPath, safetyPath);
+    }
+
+    // 5. Write restored DB to temp location and validate
+    const tempRestore = join(tmpdir(), `stagent-restore-${Date.now()}.db`);
+    writeFileSync(tempRestore, decrypted);
+
+    // Basic validation: check it's a valid SQLite file
+    const header = decrypted.subarray(0, 16).toString("ascii");
+    if (!header.startsWith("SQLite format 3")) {
+      return { success: false, error: "Decrypted data is not a valid SQLite database" };
+    }
+
+    // 6. Replace current DB (requires app restart)
+    copyFileSync(tempRestore, dbPath);
+
+    // Clean up
+    try { require("fs").unlinkSync(tempRestore); } catch { /* ignore */ }
+
+    // Record restore session
+    await supabase.from("sync_sessions").insert({
+      user_id: userId,
+      device_name: "restore",
+      device_id: "restore",
+      blob_path,
+      blob_size_bytes: decrypted.length,
+      sync_type: "restore",
+      status: "completed",
+    });
+
+    return { success: true, sizeBytes: decrypted.length };
+  } catch (err) {
+    return { success: false, error: err instanceof Error ? err.message : "Restore failed" };
+  }
+}
+
+/**
+ * List recent sync sessions for the user.
+ */
+export async function listSyncSessions(userId: string) {
+  const supabase = getSupabaseClient();
+  if (!supabase) return [];
+
+  const { data } = await supabase
+    .from("sync_sessions")
+    .select("*")
+    .eq("user_id", userId)
+    .order("created_at", { ascending: false })
+    .limit(20);
+
+  return data ?? [];
+}

package/src/lib/telemetry/conversion-events.ts

@@ -0,0 +1,73 @@
+/**
+ * Conversion funnel tracking — lightweight, anonymous event tracking
+ * for Community→Premium conversion optimization.
+ *
+ * Events: banner_impression, banner_click, checkout_started,
+ * checkout_completed, limit_hit
+ *
+ * Fire-and-forget — never blocks user actions. No PII.
+ * No-op if Supabase is not configured.
+ */
+
+import { isCloudConfigured } from "@/lib/cloud/supabase-client";
+import { getSettingSync, setSetting } from "@/lib/settings/helpers";
+
+const SESSION_KEY = "conversion.sessionId";
+
+export type ConversionEventType =
+  | "banner_impression"
+  | "banner_click"
+  | "checkout_started"
+  | "checkout_completed"
+  | "limit_hit";
+
+/**
+ * Get or create an anonymous session ID for conversion tracking.
+ * Stored in settings, not tied to any user identity.
+ */
+function getSessionId(): string {
+  let id = getSettingSync(SESSION_KEY);
+  if (!id) {
+    id = crypto.randomUUID();
+    setSetting(SESSION_KEY, id).catch(() => {});
+  }
+  return id;
+}
+
+/**
+ * Track a conversion funnel event. Fire-and-forget.
+ *
+ * @param eventType - The event type
+ * @param source - Where the event originated (e.g., "memory_banner", "schedule_gate")
+ * @param metadata - Optional additional context
+ */
+export function trackConversionEvent(
+  eventType: ConversionEventType,
+  source?: string,
+  metadata?: Record<string, unknown>
+): void {
+  if (!isCloudConfigured()) return;
+
+  const sessionId = getSessionId();
+  const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const anonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+
+  if (!supabaseUrl || !anonKey) return;
+
+  // Fire-and-forget — don't await, don't block
+  fetch(`${supabaseUrl}/functions/v1/conversion-ingest`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${anonKey}`,
+    },
+    body: JSON.stringify({
+      eventType,
+      sessionId,
+      source: source ?? null,
+      metadata: metadata ?? null,
+    }),
+  }).catch(() => {
+    // Silently ignore — conversion tracking is non-critical
+  });
+}

package/src/lib/telemetry/queue.ts

@@ -0,0 +1,122 @@
+/**
+ * Telemetry batch queue — opt-in anonymized usage data.
+ *
+ * Events are queued in the settings table as a JSON array,
+ * flushed every 5 minutes to the Supabase telemetry-ingest Edge Function.
+ * Capped at 200 events to prevent unbounded growth.
+ *
+ * EXPLICITLY ABSENT from events: taskId, projectId, taskTitle,
+ * description, result, userId, email (no PII).
+ */
+
+import { getSettingSync, setSetting } from "@/lib/settings/helpers";
+import { SETTINGS_KEYS } from "@/lib/constants/settings";
+import { isCloudConfigured } from "@/lib/cloud/supabase-client";
+
+const MAX_BATCH_SIZE = 200;
+const FLUSH_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+export interface TelemetryEvent {
+  runtimeId: string;
+  providerId: string;
+  modelId: string;
+  profileDomain?: string;
+  workflowPattern?: string;
+  activityType: string;
+  outcomeStatus?: string;
+  tokenCount?: number;
+  costMicros?: number;
+  durationMs?: number;
+  stepCount?: number;
+}
+
+/**
+ * Check if telemetry is opt-in enabled.
+ */
+export function isTelemetryEnabled(): boolean {
+  return getSettingSync(SETTINGS_KEYS.TELEMETRY_ENABLED) === "true";
+}
+
+/**
+ * Get or create the anonymous runtime ID.
+ */
+export function getRuntimeId(): string {
+  let id = getSettingSync(SETTINGS_KEYS.TELEMETRY_RUNTIME_ID);
+  if (!id) {
+    id = crypto.randomUUID();
+    setSetting(SETTINGS_KEYS.TELEMETRY_RUNTIME_ID, id).catch(() => {});
+  }
+  return id;
+}
+
+/**
+ * Queue a telemetry event for batch flush.
+ * No-op if telemetry is disabled.
+ */
+export function queueTelemetryEvent(event: TelemetryEvent): void {
+  if (!isTelemetryEnabled()) return;
+
+  const batch = loadBatch();
+  if (batch.length >= MAX_BATCH_SIZE) {
+    // Drop oldest events when at capacity
+    batch.shift();
+  }
+  batch.push(event);
+  saveBatch(batch);
+}
+
+/**
+ * Flush the batch to the cloud telemetry endpoint.
+ * Called on an interval from instrumentation.ts.
+ */
+export async function flushTelemetryBatch(): Promise<void> {
+  if (!isTelemetryEnabled() || !isCloudConfigured()) return;
+
+  const batch = loadBatch();
+  if (batch.length === 0) return;
+
+  const supabaseUrl = process.env.NEXT_PUBLIC_SUPABASE_URL!;
+  const anonKey = process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!;
+
+  try {
+    const res = await fetch(`${supabaseUrl}/functions/v1/telemetry-ingest`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${anonKey}`,
+      },
+      body: JSON.stringify({ events: batch }),
+    });
+
+    if (res.ok) {
+      // Clear the batch on successful flush
+      saveBatch([]);
+    }
+  } catch {
+    // Network failure — retain batch for next flush
+  }
+}
+
+/**
+ * Start the periodic flush timer. Call from instrumentation.ts.
+ */
+export function startTelemetryFlush(): void {
+  // Flush once on startup
+  flushTelemetryBatch().catch(() => {});
+  // Then every 5 minutes
+  setInterval(() => flushTelemetryBatch().catch(() => {}), FLUSH_INTERVAL_MS);
+}
+
+function loadBatch(): TelemetryEvent[] {
+  try {
+    const raw = getSettingSync(SETTINGS_KEYS.TELEMETRY_BATCH);
+    if (!raw) return [];
+    return JSON.parse(raw) as TelemetryEvent[];
+  } catch {
+    return [];
+  }
+}
+
+function saveBatch(batch: TelemetryEvent[]): void {
+  setSetting(SETTINGS_KEYS.TELEMETRY_BATCH, JSON.stringify(batch)).catch(() => {});
+}

package/src/lib/usage/ledger.ts

@@ -248,6 +248,24 @@ export async function recordUsageLedgerEntry(input: UsageLedgerWriteInput) {
   } as const;
 
   await db.insert(usageLedger).values(row);
+
+  // Queue telemetry event (opt-in, fire-and-forget)
+  try {
+    const { queueTelemetryEvent } = await import("@/lib/telemetry/queue");
+    queueTelemetryEvent({
+      runtimeId: input.runtimeId,
+      providerId: input.providerId,
+      modelId: input.modelId ?? "unknown",
+      activityType: input.activityType,
+      outcomeStatus: status,
+      tokenCount: normalizedTotalTokens ?? undefined,
+      costMicros: resolvedCostMicros ?? undefined,
+      durationMs: input.finishedAt.getTime() - input.startedAt.getTime(),
+    });
+  } catch {
+    // Telemetry is non-critical
+  }
+
   return row;
 }
 

package/src/lib/validators/license.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { TIERS } from "@/lib/license/tier-limits";
+
+export const activateLicenseSchema = z.object({
+  key: z
+    .string()
+    .min(1, "License key is required")
+    .regex(
+      /^STAG-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}-[A-HJ-NP-Z2-9]{4}$/,
+      "Invalid license key format (expected STAG-XXXX-XXXX-XXXX-XXXX)"
+    )
+    .optional(),
+  email: z.string().email("Invalid email address").optional(),
+  tier: z.enum(TIERS).optional(),
+  token: z.string().optional(),
+});
+
+export type ActivateLicenseInput = z.infer<typeof activateLicenseSchema>;
+
+export const licenseStatusSchema = z.object({
+  tier: z.enum(TIERS),
+  status: z.enum(["active", "inactive", "grace"]),
+  email: z.string().nullable(),
+  activatedAt: z.string().nullable(),
+  expiresAt: z.string().nullable(),
+  lastValidatedAt: z.string().nullable(),
+  gracePeriodExpiresAt: z.string().nullable(),
+  isPremium: z.boolean(),
+  features: z.record(z.string(), z.boolean()),
+  limits: z.record(z.string(), z.number()),
+});
+
+export type LicenseStatusResponse = z.infer<typeof licenseStatusSchema>;

package/tsconfig.json

@@ -39,6 +39,7 @@
     "node_modules",
     "vitest.config*.ts",
     "src/**/__tests__/**",
-    "src/__tests__/**"
+    "src/__tests__/**",
+    "supabase/**"
   ]
 }