@auxiora/cloud 1.0.0

package/src/plans.ts

@@ -0,0 +1,84 @@
+import type { PlanDefinition, TenantPlan, TenantQuotas } from './types.js';
+
+const PLAN_DEFINITIONS: Record<TenantPlan, PlanDefinition> = {
+  free: {
+    plan: 'free',
+    name: 'Free',
+    priceMonthly: 0,
+    priceYearly: 0,
+    quotas: {
+      maxMessages: 100,
+      maxSessions: 3,
+      maxStorageMb: 50,
+      maxPlugins: 2,
+      maxBehaviors: 5,
+      maxChannels: 1,
+      maxAgents: 1,
+    },
+    features: ['Single channel', 'Basic vault', 'Community support'],
+  },
+  pro: {
+    plan: 'pro',
+    name: 'Pro',
+    priceMonthly: 19,
+    priceYearly: 190,
+    quotas: {
+      maxMessages: 5000,
+      maxSessions: 20,
+      maxStorageMb: 1024,
+      maxPlugins: 20,
+      maxBehaviors: 50,
+      maxChannels: 5,
+      maxAgents: 3,
+    },
+    features: ['Multi-channel', 'Cloud vault', 'Priority support', 'Custom behaviors'],
+  },
+  team: {
+    plan: 'team',
+    name: 'Team',
+    priceMonthly: 49,
+    priceYearly: 490,
+    quotas: {
+      maxMessages: 25000,
+      maxSessions: 100,
+      maxStorageMb: 5120,
+      maxPlugins: 50,
+      maxBehaviors: 200,
+      maxChannels: 20,
+      maxAgents: 10,
+    },
+    features: ['All Pro features', 'Team collaboration', 'Orchestration', 'Audit logs'],
+  },
+  enterprise: {
+    plan: 'enterprise',
+    name: 'Enterprise',
+    priceMonthly: 199,
+    priceYearly: 1990,
+    quotas: {
+      maxMessages: -1, // unlimited
+      maxSessions: -1,
+      maxStorageMb: -1,
+      maxPlugins: -1,
+      maxBehaviors: -1,
+      maxChannels: -1,
+      maxAgents: -1,
+    },
+    features: ['All Team features', 'Unlimited usage', 'SLA', 'Dedicated support', 'SSO'],
+  },
+};
+
+export function getPlanDefinition(plan: TenantPlan): PlanDefinition {
+  return PLAN_DEFINITIONS[plan];
+}
+
+export function getPlanQuotas(plan: TenantPlan): TenantQuotas {
+  return PLAN_DEFINITIONS[plan].quotas;
+}
+
+export function getAllPlans(): PlanDefinition[] {
+  return Object.values(PLAN_DEFINITIONS);
+}
+
+export function isValidPlan(plan: string): plan is TenantPlan {
+  return plan in PLAN_DEFINITIONS;
+}

package/src/quotas.ts

@@ -0,0 +1,103 @@
+import type { TenantQuotas, UsageRecord } from './types.js';
+import { QuotaExceededError } from './types.js';
+import { getPlanQuotas } from './plans.js';
+import type { TenantManager } from './tenant.js';
+
+export interface QuotaEnforcerOptions {
+  tenantManager: TenantManager;
+}
+
+/**
+ * QuotaEnforcer tracks usage against plan limits
+ * and throws QuotaExceededError when limits are breached.
+ */
+export class QuotaEnforcer {
+  private usage = new Map<string, Map<string, number>>();
+  private tenantManager: TenantManager;
+
+  constructor(options: QuotaEnforcerOptions) {
+    this.tenantManager = options.tenantManager;
+  }
+
+  /**
+   * Check whether a metric increment would exceed the quota.
+   * Throws QuotaExceededError if the limit would be breached.
+   */
+  async check(tenantId: string, metric: keyof TenantQuotas, increment = 1): Promise<void> {
+    const tenant = await this.tenantManager.get(tenantId);
+    const quotas = getPlanQuotas(tenant.plan);
+    const limit = quotas[metric];
+
+    // -1 means unlimited
+    if (limit === -1) return;
+
+    const current = this.getUsage(tenantId, metric);
+    if (current + increment > limit) {
+      throw new QuotaExceededError(metric, limit, current + increment);
+    }
+  }
+
+  /**
+   * Record usage for a metric.
+   */
+  record(tenantId: string, metric: string, value = 1): UsageRecord {
+    let tenantUsage = this.usage.get(tenantId);
+    if (!tenantUsage) {
+      tenantUsage = new Map();
+      this.usage.set(tenantId, tenantUsage);
+    }
+
+    const current = tenantUsage.get(metric) ?? 0;
+    tenantUsage.set(metric, current + value);
+
+    return {
+      tenantId,
+      metric,
+      value: current + value,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Get current usage for a specific metric.
+   */
+  getUsage(tenantId: string, metric: string): number {
+    return this.usage.get(tenantId)?.get(metric) ?? 0;
+  }
+
+  /**
+   * Get all usage for a tenant.
+   */
+  getAllUsage(tenantId: string): Record<string, number> {
+    const tenantUsage = this.usage.get(tenantId);
+    if (!tenantUsage) return {};
+
+    const result: Record<string, number> = {};
+    for (const [metric, value] of tenantUsage) {
+      result[metric] = value;
+    }
+    return result;
+  }
+
+  /**
+   * Reset usage for a tenant (e.g., at billing period start).
+   */
+  resetUsage(tenantId: string): void {
+    this.usage.delete(tenantId);
+  }
+
+  /**
+   * Get usage as a percentage of the quota limit.
+   */
+  async getUsagePercentage(tenantId: string, metric: keyof TenantQuotas): Promise<number> {
+    const tenant = await this.tenantManager.get(tenantId);
+    const quotas = getPlanQuotas(tenant.plan);
+    const limit = quotas[metric];
+
+    if (limit === -1) return 0;
+    if (limit === 0) return 100;
+
+    const current = this.getUsage(tenantId, metric);
+    return Math.round((current / limit) * 100);
+  }
+}

package/src/tenant.ts

@@ -0,0 +1,140 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as crypto from 'node:crypto';
+import type { Tenant, TenantPlan, CloudConfig } from './types.js';
+import { TenantNotFoundError } from './types.js';
+import { getPlanQuotas } from './plans.js';
+
+export interface TenantManagerOptions {
+  config: CloudConfig;
+}
+
+export class TenantManager {
+  private tenants = new Map<string, Tenant>();
+  private config: CloudConfig;
+
+  constructor(options: TenantManagerOptions) {
+    this.config = options.config;
+  }
+
+  async create(email: string, name: string, plan: TenantPlan = 'free'): Promise<Tenant> {
+    const id = `tenant-${crypto.randomUUID()}`;
+    const dataDir = path.join(this.config.baseDataDir, id);
+
+    await fs.mkdir(dataDir, { recursive: true });
+
+    const tenant: Tenant = {
+      id,
+      name,
+      email,
+      plan,
+      status: 'active',
+      dataDir,
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+
+    this.tenants.set(id, tenant);
+    await this.persistTenant(tenant);
+    return tenant;
+  }
+
+  async get(id: string): Promise<Tenant> {
+    const tenant = this.tenants.get(id);
+    if (!tenant) {
+      throw new TenantNotFoundError(id);
+    }
+    return tenant;
+  }
+
+  async getByEmail(email: string): Promise<Tenant | null> {
+    for (const tenant of this.tenants.values()) {
+      if (tenant.email === email) {
+        return tenant;
+      }
+    }
+    return null;
+  }
+
+  async update(id: string, updates: Partial<Pick<Tenant, 'name' | 'email' | 'plan'>>): Promise<Tenant> {
+    const tenant = await this.get(id);
+
+    if (updates.name !== undefined) tenant.name = updates.name;
+    if (updates.email !== undefined) tenant.email = updates.email;
+    if (updates.plan !== undefined) tenant.plan = updates.plan;
+    tenant.updatedAt = new Date().toISOString();
+
+    this.tenants.set(id, tenant);
+    await this.persistTenant(tenant);
+    return tenant;
+  }
+
+  async suspend(id: string, reason: string): Promise<Tenant> {
+    const tenant = await this.get(id);
+    tenant.status = 'suspended';
+    tenant.suspendedAt = new Date().toISOString();
+    tenant.suspendReason = reason;
+    tenant.updatedAt = new Date().toISOString();
+
+    this.tenants.set(id, tenant);
+    await this.persistTenant(tenant);
+    return tenant;
+  }
+
+  async reactivate(id: string): Promise<Tenant> {
+    const tenant = await this.get(id);
+    tenant.status = 'active';
+    tenant.suspendedAt = undefined;
+    tenant.suspendReason = undefined;
+    tenant.updatedAt = new Date().toISOString();
+
+    this.tenants.set(id, tenant);
+    await this.persistTenant(tenant);
+    return tenant;
+  }
+
+  async delete(id: string): Promise<boolean> {
+    const tenant = this.tenants.get(id);
+    if (!tenant) return false;
+
+    tenant.status = 'deleted';
+    tenant.updatedAt = new Date().toISOString();
+    this.tenants.set(id, tenant);
+    await this.persistTenant(tenant);
+    return true;
+  }
+
+  async list(): Promise<Tenant[]> {
+    return Array.from(this.tenants.values()).filter(t => t.status !== 'deleted');
+  }
+
+  getQuotas(plan: TenantPlan) {
+    return getPlanQuotas(plan);
+  }
+
+  private async persistTenant(tenant: Tenant): Promise<void> {
+    const tenantFile = path.join(tenant.dataDir, 'tenant.json');
+    await fs.mkdir(path.dirname(tenantFile), { recursive: true });
+    await fs.writeFile(tenantFile, JSON.stringify(tenant, null, 2), 'utf-8');
+  }
+
+  async loadFromDisk(): Promise<void> {
+    try {
+      const entries = await fs.readdir(this.config.baseDataDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && entry.name.startsWith('tenant-')) {
+          const tenantFile = path.join(this.config.baseDataDir, entry.name, 'tenant.json');
+          try {
+            const content = await fs.readFile(tenantFile, 'utf-8');
+            const tenant = JSON.parse(content) as Tenant;
+            this.tenants.set(tenant.id, tenant);
+          } catch {
+            // Skip corrupt tenant files
+          }
+        }
+      }
+    } catch {
+      // Base data dir doesn't exist yet
+    }
+  }
+}

package/src/types.ts

@@ -0,0 +1,114 @@
+/** Tenant plan tiers */
+export type TenantPlan = 'free' | 'pro' | 'team' | 'enterprise';
+
+/** Tenant status */
+export type TenantStatus = 'active' | 'suspended' | 'pending' | 'deleted';
+
+/** A cloud tenant */
+export interface Tenant {
+  id: string;
+  name: string;
+  email: string;
+  plan: TenantPlan;
+  status: TenantStatus;
+  stripeCustomerId?: string;
+  stripeSubscriptionId?: string;
+  dataDir: string;
+  createdAt: string;
+  updatedAt: string;
+  suspendedAt?: string;
+  suspendReason?: string;
+}
+
+/** Quota limits for a given plan */
+export interface TenantQuotas {
+  maxMessages: number;
+  maxSessions: number;
+  maxStorageMb: number;
+  maxPlugins: number;
+  maxBehaviors: number;
+  maxChannels: number;
+  maxAgents: number;
+}
+
+/** A single usage record */
+export interface UsageRecord {
+  tenantId: string;
+  metric: string;
+  value: number;
+  timestamp: string;
+}
+
+/** Billing information */
+export interface BillingInfo {
+  tenantId: string;
+  plan: TenantPlan;
+  stripeCustomerId?: string;
+  stripeSubscriptionId?: string;
+  currentPeriodStart?: string;
+  currentPeriodEnd?: string;
+  paymentMethodLast4?: string;
+  paymentMethodBrand?: string;
+}
+
+/** Cloud-specific configuration */
+export interface CloudConfig {
+  enabled: boolean;
+  baseDataDir: string;
+  jwtSecret: string;
+  stripeSecretKey?: string;
+  stripeWebhookSecret?: string;
+  domain: string;
+}
+
+/** Plan definition with pricing */
+export interface PlanDefinition {
+  plan: TenantPlan;
+  name: string;
+  priceMonthly: number;
+  priceYearly: number;
+  quotas: TenantQuotas;
+  features: string[];
+}
+
+/** Stripe SDK interface for dependency injection */
+export interface StripeClient {
+  createCustomer(email: string, name: string): Promise<{ id: string }>;
+  createSubscription(customerId: string, priceId: string): Promise<{ id: string; status: string }>;
+  cancelSubscription(subscriptionId: string): Promise<void>;
+  getInvoices(customerId: string): Promise<Array<{
+    id: string;
+    amount: number;
+    status: string;
+    created: string;
+  }>>;
+  createPaymentIntent(customerId: string, amount: number): Promise<{ clientSecret: string }>;
+}
+
+/** Quota exceeded error */
+export class QuotaExceededError extends Error {
+  constructor(
+    public readonly metric: string,
+    public readonly limit: number,
+    public readonly current: number,
+  ) {
+    super(`Quota exceeded for ${metric}: ${current}/${limit}`);
+    this.name = 'QuotaExceededError';
+  }
+}
+
+/** Tenant not found error */
+export class TenantNotFoundError extends Error {
+  constructor(tenantId: string) {
+    super(`Tenant not found: ${tenantId}`);
+    this.name = 'TenantNotFoundError';
+  }
+}
+
+/** Tenant suspended error */
+export class TenantSuspendedError extends Error {
+  constructor(tenantId: string) {
+    super(`Tenant is suspended: ${tenantId}`);
+    this.name = 'TenantSuspendedError';
+  }
+}

package/tests/billing.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { TenantManager } from '../src/tenant.js';
+import { BillingManager } from '../src/billing.js';
+import type { CloudConfig, StripeClient } from '../src/types.js';
+
+function makeConfig(baseDataDir: string): CloudConfig {
+  return {
+    enabled: true,
+    baseDataDir,
+    jwtSecret: 'test-secret-32-chars-long-enough!',
+    domain: 'test.auxiora.cloud',
+  };
+}
+
+function createMockStripe(): StripeClient {
+  return {
+    createCustomer: vi.fn().mockResolvedValue({ id: 'cus_test123' }),
+    createSubscription: vi.fn().mockResolvedValue({ id: 'sub_test123', status: 'active' }),
+    cancelSubscription: vi.fn().mockResolvedValue(undefined),
+    getInvoices: vi.fn().mockResolvedValue([
+      { id: 'inv_1', amount: 1900, status: 'paid', created: '2025-01-01T00:00:00Z' },
+    ]),
+    createPaymentIntent: vi.fn().mockResolvedValue({ clientSecret: 'pi_secret' }),
+  };
+}
+
+describe('BillingManager', () => {
+  let tenantManager: TenantManager;
+  let billing: BillingManager;
+  let mockStripe: StripeClient;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cloud-billing-'));
+    tenantManager = new TenantManager({ config: makeConfig(tmpDir) });
+    mockStripe = createMockStripe();
+    billing = new BillingManager({ tenantManager, stripe: mockStripe });
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('createCustomer', () => {
+    it('should create a Stripe customer', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      const customerId = await billing.createCustomer(tenant.id);
+      expect(customerId).toBe('cus_test123');
+      expect(mockStripe.createCustomer).toHaveBeenCalledWith('alice@test.com', 'Alice');
+    });
+
+    it('should throw if Stripe not configured', async () => {
+      const billingNoStripe = new BillingManager({ tenantManager });
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      await expect(billingNoStripe.createCustomer(tenant.id)).rejects.toThrow('Stripe not configured');
+    });
+  });
+
+  describe('createSubscription', () => {
+    it('should create a subscription', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      // Manually set stripeCustomerId
+      (tenant as any).stripeCustomerId = 'cus_test123';
+
+      const result = await billing.createSubscription(tenant.id, 'pro');
+      expect(result.subscriptionId).toBe('sub_test123');
+      expect(result.status).toBe('active');
+    });
+
+    it('should throw without customer ID', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      await expect(billing.createSubscription(tenant.id, 'pro')).rejects.toThrow('No Stripe customer ID');
+    });
+  });
+
+  describe('getBillingInfo', () => {
+    it('should return billing info', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice', 'pro');
+      const info = await billing.getBillingInfo(tenant.id);
+      expect(info.tenantId).toBe(tenant.id);
+      expect(info.plan).toBe('pro');
+    });
+  });
+
+  describe('getInvoices', () => {
+    it('should return invoices from Stripe', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      (tenant as any).stripeCustomerId = 'cus_test123';
+
+      const invoices = await billing.getInvoices(tenant.id);
+      expect(invoices).toHaveLength(1);
+      expect(invoices[0].id).toBe('inv_1');
+    });
+
+    it('should return empty for tenant without customer', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      const invoices = await billing.getInvoices(tenant.id);
+      expect(invoices).toHaveLength(0);
+    });
+  });
+
+  describe('handleWebhookEvent', () => {
+    it('should downgrade on subscription deleted', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice', 'pro');
+      (tenant as any).stripeCustomerId = 'cus_alice';
+
+      await billing.handleWebhookEvent('customer.subscription.deleted', { customer: 'cus_alice' });
+
+      const updated = await tenantManager.get(tenant.id);
+      expect(updated.plan).toBe('free');
+    });
+
+    it('should suspend on payment failed', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice', 'pro');
+      (tenant as any).stripeCustomerId = 'cus_alice';
+
+      await billing.handleWebhookEvent('invoice.payment_failed', { customer: 'cus_alice' });
+
+      const updated = await tenantManager.get(tenant.id);
+      expect(updated.status).toBe('suspended');
+    });
+  });
+});

package/tests/isolation.test.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { TenantManager } from '../src/tenant.js';
+import { TenantIsolation } from '../src/isolation.js';
+import { TenantNotFoundError, TenantSuspendedError } from '../src/types.js';
+import type { CloudConfig } from '../src/types.js';
+
+function makeConfig(baseDataDir: string): CloudConfig {
+  return {
+    enabled: true,
+    baseDataDir,
+    jwtSecret: 'test-secret-32-chars-long-enough!',
+    domain: 'test.auxiora.cloud',
+  };
+}
+
+describe('TenantIsolation', () => {
+  let tenantManager: TenantManager;
+  let isolation: TenantIsolation;
+  let tmpDir: string;
+  let config: CloudConfig;
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'cloud-isolation-'));
+    config = makeConfig(tmpDir);
+    tenantManager = new TenantManager({ config });
+    isolation = new TenantIsolation({ tenantManager, config });
+  });
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  });
+
+  describe('extractTenant', () => {
+    it('should extract tenant from JWT payload with tenantId', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      const context = await isolation.extractTenant({ tenantId: tenant.id });
+      expect(context.tenantId).toBe(tenant.id);
+      expect(context.tenant.email).toBe('alice@test.com');
+    });
+
+    it('should extract tenant from JWT payload with sub', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      const context = await isolation.extractTenant({ sub: tenant.id });
+      expect(context.tenantId).toBe(tenant.id);
+    });
+
+    it('should throw for missing tenant ID', async () => {
+      await expect(isolation.extractTenant({})).rejects.toThrow(TenantNotFoundError);
+    });
+
+    it('should throw for suspended tenant', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      await tenantManager.suspend(tenant.id, 'overdue');
+      await expect(isolation.extractTenant({ tenantId: tenant.id })).rejects.toThrow(TenantSuspendedError);
+    });
+
+    it('should throw for deleted tenant', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      await tenantManager.delete(tenant.id);
+      await expect(isolation.extractTenant({ tenantId: tenant.id })).rejects.toThrow(TenantNotFoundError);
+    });
+  });
+
+  describe('scopePath', () => {
+    it('should resolve paths within tenant dir', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      const scoped = isolation.scopePath(tenant, 'config/settings.json');
+      expect(scoped).toContain(tenant.id);
+      expect(scoped).toContain('config/settings.json');
+    });
+
+    it('should block path traversal', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      expect(() => isolation.scopePath(tenant, '../../etc/passwd')).toThrow('Path traversal');
+    });
+  });
+
+  describe('validateAccess', () => {
+    it('should allow access to own resources', async () => {
+      const tenant = await tenantManager.create('alice@test.com', 'Alice');
+      const context = await isolation.extractTenant({ tenantId: tenant.id });
+      expect(isolation.validateAccess(context, tenant.id)).toBe(true);
+    });
+
+    it('should deny access to other tenant resources', async () => {
+      const alice = await tenantManager.create('alice@test.com', 'Alice');
+      const bob = await tenantManager.create('bob@test.com', 'Bob');
+      const context = await isolation.extractTenant({ tenantId: alice.id });
+      expect(isolation.validateAccess(context, bob.id)).toBe(false);
+    });
+  });
+});