@vasperacapital/vaspera-shared 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,122 @@
+type SubscriptionTier = 'free' | 'starter' | 'pro' | 'enterprise';
+type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'trialing' | 'incomplete';
+interface UserProfile {
+    id: string;
+    email: string;
+    fullName: string | null;
+    avatarUrl: string | null;
+    subscriptionTier: SubscriptionTier;
+    subscriptionStatus: SubscriptionStatus;
+    stripeCustomerId: string | null;
+    stripeSubscriptionId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+interface ApiKey {
+    id: string;
+    userId: string;
+    name: string;
+    keyPrefix: string;
+    lastUsedAt: string | null;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+interface ApiKeyWithSecret extends Omit<ApiKey, 'revokedAt'> {
+    key: string;
+}
+interface UsageEvent {
+    id: string;
+    userId: string;
+    apiKeyId: string | null;
+    toolName: string;
+    tokensUsed: number;
+    latencyMs: number | null;
+    success: boolean;
+    errorCode: string | null;
+    requestId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+}
+interface UsageSummary {
+    period: {
+        start: string;
+        end: string;
+    };
+    summary: {
+        totalToolCalls: number;
+        totalTokensUsed: number;
+        quotaUsed: number;
+        quotaLimit: number;
+        quotaPercentage: number;
+    };
+    byTool: Array<{
+        tool: string;
+        calls: number;
+        tokensUsed: number;
+        avgLatencyMs: number;
+    }>;
+}
+declare const QUOTA_LIMITS: Record<SubscriptionTier, number>;
+declare const RATE_LIMITS: Record<SubscriptionTier, {
+    perMinute: number;
+    perDay: number;
+}>;
+type IntegrationProvider = 'jira' | 'linear' | 'github' | 'gitlab' | 'asana';
+interface IntegrationToken {
+    id: string;
+    userId: string;
+    provider: IntegrationProvider;
+    tokenType: string;
+    expiresAt: string | null;
+    scopes: string[] | null;
+    providerUserId: string | null;
+    providerEmail: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+interface IntegrationStatus {
+    provider: IntegrationProvider;
+    connected: boolean;
+    connectedAt?: string;
+    providerEmail?: string;
+    scopes?: string[];
+    metadata?: Record<string, unknown>;
+}
+type McpToolName = 'synthesize_requirements' | 'review_prd' | 'explode_backlog' | 'generate_architecture' | 'sync_to_tracker' | 'infer_prd_from_code' | 'reverse_engineer_user_flows' | 'generate_test_specs' | 'explain_codebase' | 'validate_implementation' | 'suggest_refactors' | 'generate_api_docs' | 'dependency_audit' | 'estimate_migration';
+interface McpToolResult<T = unknown> {
+    content: Array<{
+        type: 'text' | 'image' | 'resource';
+        text?: string;
+        data?: string;
+        mimeType?: string;
+    }>;
+    data?: T;
+    tokensUsed?: number;
+    isError?: boolean;
+}
+interface ApiSuccessResponse<T> {
+    success: true;
+    data: T;
+    meta?: {
+        requestId: string;
+        timestamp: string;
+    };
+}
+interface ApiErrorResponse {
+    success: false;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+        docUrl?: string;
+    };
+    meta?: {
+        requestId: string;
+        timestamp: string;
+    };
+}
+type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;
+
+export { type ApiErrorResponse, type ApiKey, type ApiKeyWithSecret, type ApiResponse, type ApiSuccessResponse, type IntegrationProvider, type IntegrationStatus, type IntegrationToken, type McpToolName, type McpToolResult, QUOTA_LIMITS, RATE_LIMITS, type SubscriptionStatus, type SubscriptionTier, type UsageEvent, type UsageSummary, type UserProfile };

package/dist/types/index.js

@@ -0,0 +1,45 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types/index.ts
+var types_exports = {};
+__export(types_exports, {
+  QUOTA_LIMITS: () => QUOTA_LIMITS,
+  RATE_LIMITS: () => RATE_LIMITS
+});
+module.exports = __toCommonJS(types_exports);
+var QUOTA_LIMITS = {
+  free: 5,
+  starter: 100,
+  pro: 500,
+  enterprise: 999999
+  // Effectively unlimited
+};
+var RATE_LIMITS = {
+  free: { perMinute: 10, perDay: 100 },
+  starter: { perMinute: 30, perDay: 1e3 },
+  pro: { perMinute: 60, perDay: 5e3 },
+  enterprise: { perMinute: 120, perDay: 999999 }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  QUOTA_LIMITS,
+  RATE_LIMITS
+});
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["// Subscription Types\nexport type SubscriptionTier = 'free' | 'starter' | 'pro' | 'enterprise';\nexport type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'trialing' | 'incomplete';\n\n// User Profile\nexport interface UserProfile {\n  id: string;\n  email: string;\n  fullName: string | null;\n  avatarUrl: string | null;\n  subscriptionTier: SubscriptionTier;\n  subscriptionStatus: SubscriptionStatus;\n  stripeCustomerId: string | null;\n  stripeSubscriptionId: string | null;\n  createdAt: string;\n  updatedAt: string;\n}\n\n// API Key\nexport interface ApiKey {\n  id: string;\n  userId: string;\n  name: string;\n  keyPrefix: string;\n  lastUsedAt: string | null;\n  expiresAt: string | null;\n  revokedAt: string | null;\n  createdAt: string;\n}\n\nexport interface ApiKeyWithSecret extends Omit<ApiKey, 'revokedAt'> {\n  key: string; // Full key (only shown once)\n}\n\n// Usage\nexport interface UsageEvent {\n  id: string;\n  userId: string;\n  apiKeyId: string | null;\n  toolName: string;\n  tokensUsed: number;\n  latencyMs: number | null;\n  success: boolean;\n  errorCode: string | null;\n  requestId: string | null;\n  metadata: Record<string, unknown>;\n  createdAt: string;\n}\n\nexport interface UsageSummary {\n  period: {\n    start: string;\n    end: string;\n  };\n  summary: {\n    totalToolCalls: number;\n    totalTokensUsed: number;\n    quotaUsed: number;\n    quotaLimit: number;\n    quotaPercentage: number;\n  };\n  byTool: Array<{\n    tool: string;\n    calls: number;\n    tokensUsed: number;\n    avgLatencyMs: number;\n  }>;\n}\n\n// Quota Limits by Tier\nexport const QUOTA_LIMITS: Record<SubscriptionTier, number> = {\n  free: 5,\n  starter: 100,\n  pro: 500,\n  enterprise: 999999, // Effectively unlimited\n};\n\nexport const RATE_LIMITS: Record<SubscriptionTier, { perMinute: number; perDay: number }> = {\n  free: { perMinute: 10, perDay: 100 },\n  starter: { perMinute: 30, perDay: 1000 },\n  pro: { perMinute: 60, perDay: 5000 },\n  enterprise: { perMinute: 120, perDay: 999999 },\n};\n\n// Integration Types\nexport type IntegrationProvider = 'jira' | 'linear' | 'github' | 'gitlab' | 'asana';\n\nexport interface IntegrationToken {\n  id: string;\n  userId: string;\n  provider: IntegrationProvider;\n  tokenType: string;\n  expiresAt: string | null;\n  scopes: string[] | null;\n  providerUserId: string | null;\n  providerEmail: string | null;\n  metadata: Record<string, unknown>;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport interface IntegrationStatus {\n  provider: IntegrationProvider;\n  connected: boolean;\n  connectedAt?: string;\n  providerEmail?: string;\n  scopes?: string[];\n  metadata?: Record<string, unknown>;\n}\n\n// MCP Tool Types\nexport type McpToolName =\n  | 'synthesize_requirements'\n  | 'review_prd'\n  | 'explode_backlog'\n  | 'generate_architecture'\n  | 'sync_to_tracker'\n  | 'infer_prd_from_code'\n  | 'reverse_engineer_user_flows'\n  | 'generate_test_specs'\n  | 'explain_codebase'\n  | 'validate_implementation'\n  | 'suggest_refactors'\n  | 'generate_api_docs'\n  | 'dependency_audit'\n  | 'estimate_migration';\n\nexport interface McpToolResult<T = unknown> {\n  content: Array<{\n    type: 'text' | 'image' | 'resource';\n    text?: string;\n    data?: string;\n    mimeType?: string;\n  }>;\n  data?: T;\n  tokensUsed?: number;\n  isError?: boolean;\n}\n\n// API Response Types\nexport interface ApiSuccessResponse<T> {\n  success: true;\n  data: T;\n  meta?: {\n    requestId: string;\n    timestamp: string;\n  };\n}\n\nexport interface ApiErrorResponse {\n  success: false;\n  error: {\n    code: string;\n    message: string;\n    details?: Record<string, unknown>;\n    docUrl?: string;\n  };\n  meta?: {\n    requestId: string;\n    timestamp: string;\n  };\n}\n\nexport type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAsEO,IAAM,eAAiD;AAAA,EAC5D,MAAM;AAAA,EACN,SAAS;AAAA,EACT,KAAK;AAAA,EACL,YAAY;AAAA;AACd;AAEO,IAAM,cAA+E;AAAA,EAC1F,MAAM,EAAE,WAAW,IAAI,QAAQ,IAAI;AAAA,EACnC,SAAS,EAAE,WAAW,IAAI,QAAQ,IAAK;AAAA,EACvC,KAAK,EAAE,WAAW,IAAI,QAAQ,IAAK;AAAA,EACnC,YAAY,EAAE,WAAW,KAAK,QAAQ,OAAO;AAC/C;","names":[]}

package/dist/types/index.mjs

@@ -0,0 +1,19 @@
+// src/types/index.ts
+var QUOTA_LIMITS = {
+  free: 5,
+  starter: 100,
+  pro: 500,
+  enterprise: 999999
+  // Effectively unlimited
+};
+var RATE_LIMITS = {
+  free: { perMinute: 10, perDay: 100 },
+  starter: { perMinute: 30, perDay: 1e3 },
+  pro: { perMinute: 60, perDay: 5e3 },
+  enterprise: { perMinute: 120, perDay: 999999 }
+};
+export {
+  QUOTA_LIMITS,
+  RATE_LIMITS
+};
+//# sourceMappingURL=index.mjs.map

package/dist/types/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/index.ts"],"sourcesContent":["// Subscription Types\nexport type SubscriptionTier = 'free' | 'starter' | 'pro' | 'enterprise';\nexport type SubscriptionStatus = 'active' | 'canceled' | 'past_due' | 'trialing' | 'incomplete';\n\n// User Profile\nexport interface UserProfile {\n  id: string;\n  email: string;\n  fullName: string | null;\n  avatarUrl: string | null;\n  subscriptionTier: SubscriptionTier;\n  subscriptionStatus: SubscriptionStatus;\n  stripeCustomerId: string | null;\n  stripeSubscriptionId: string | null;\n  createdAt: string;\n  updatedAt: string;\n}\n\n// API Key\nexport interface ApiKey {\n  id: string;\n  userId: string;\n  name: string;\n  keyPrefix: string;\n  lastUsedAt: string | null;\n  expiresAt: string | null;\n  revokedAt: string | null;\n  createdAt: string;\n}\n\nexport interface ApiKeyWithSecret extends Omit<ApiKey, 'revokedAt'> {\n  key: string; // Full key (only shown once)\n}\n\n// Usage\nexport interface UsageEvent {\n  id: string;\n  userId: string;\n  apiKeyId: string | null;\n  toolName: string;\n  tokensUsed: number;\n  latencyMs: number | null;\n  success: boolean;\n  errorCode: string | null;\n  requestId: string | null;\n  metadata: Record<string, unknown>;\n  createdAt: string;\n}\n\nexport interface UsageSummary {\n  period: {\n    start: string;\n    end: string;\n  };\n  summary: {\n    totalToolCalls: number;\n    totalTokensUsed: number;\n    quotaUsed: number;\n    quotaLimit: number;\n    quotaPercentage: number;\n  };\n  byTool: Array<{\n    tool: string;\n    calls: number;\n    tokensUsed: number;\n    avgLatencyMs: number;\n  }>;\n}\n\n// Quota Limits by Tier\nexport const QUOTA_LIMITS: Record<SubscriptionTier, number> = {\n  free: 5,\n  starter: 100,\n  pro: 500,\n  enterprise: 999999, // Effectively unlimited\n};\n\nexport const RATE_LIMITS: Record<SubscriptionTier, { perMinute: number; perDay: number }> = {\n  free: { perMinute: 10, perDay: 100 },\n  starter: { perMinute: 30, perDay: 1000 },\n  pro: { perMinute: 60, perDay: 5000 },\n  enterprise: { perMinute: 120, perDay: 999999 },\n};\n\n// Integration Types\nexport type IntegrationProvider = 'jira' | 'linear' | 'github' | 'gitlab' | 'asana';\n\nexport interface IntegrationToken {\n  id: string;\n  userId: string;\n  provider: IntegrationProvider;\n  tokenType: string;\n  expiresAt: string | null;\n  scopes: string[] | null;\n  providerUserId: string | null;\n  providerEmail: string | null;\n  metadata: Record<string, unknown>;\n  createdAt: string;\n  updatedAt: string;\n}\n\nexport interface IntegrationStatus {\n  provider: IntegrationProvider;\n  connected: boolean;\n  connectedAt?: string;\n  providerEmail?: string;\n  scopes?: string[];\n  metadata?: Record<string, unknown>;\n}\n\n// MCP Tool Types\nexport type McpToolName =\n  | 'synthesize_requirements'\n  | 'review_prd'\n  | 'explode_backlog'\n  | 'generate_architecture'\n  | 'sync_to_tracker'\n  | 'infer_prd_from_code'\n  | 'reverse_engineer_user_flows'\n  | 'generate_test_specs'\n  | 'explain_codebase'\n  | 'validate_implementation'\n  | 'suggest_refactors'\n  | 'generate_api_docs'\n  | 'dependency_audit'\n  | 'estimate_migration';\n\nexport interface McpToolResult<T = unknown> {\n  content: Array<{\n    type: 'text' | 'image' | 'resource';\n    text?: string;\n    data?: string;\n    mimeType?: string;\n  }>;\n  data?: T;\n  tokensUsed?: number;\n  isError?: boolean;\n}\n\n// API Response Types\nexport interface ApiSuccessResponse<T> {\n  success: true;\n  data: T;\n  meta?: {\n    requestId: string;\n    timestamp: string;\n  };\n}\n\nexport interface ApiErrorResponse {\n  success: false;\n  error: {\n    code: string;\n    message: string;\n    details?: Record<string, unknown>;\n    docUrl?: string;\n  };\n  meta?: {\n    requestId: string;\n    timestamp: string;\n  };\n}\n\nexport type ApiResponse<T> = ApiSuccessResponse<T> | ApiErrorResponse;\n"],"mappings":";AAsEO,IAAM,eAAiD;AAAA,EAC5D,MAAM;AAAA,EACN,SAAS;AAAA,EACT,KAAK;AAAA,EACL,YAAY;AAAA;AACd;AAEO,IAAM,cAA+E;AAAA,EAC1F,MAAM,EAAE,WAAW,IAAI,QAAQ,IAAI;AAAA,EACnC,SAAS,EAAE,WAAW,IAAI,QAAQ,IAAK;AAAA,EACvC,KAAK,EAAE,WAAW,IAAI,QAAQ,IAAK;AAAA,EACnC,YAAY,EAAE,WAAW,KAAK,QAAQ,OAAO;AAC/C;","names":[]}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@vasperacapital/vaspera-shared",
+  "version": "0.1.0",
+  "description": "Shared utilities for VasperaPM - API key generation, encryption, error handling",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rcolkitt/VasperaPM"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.mjs",
+      "require": "./dist/errors/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.mjs",
+      "require": "./dist/types/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@vaspera/tsconfig": "workspace:*",
+    "tsup": "^8.3.0",
+    "typescript": "^5"
+  }
+}

package/src/__tests__/api-key.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import {
+  generateApiKey,
+  hashApiKey,
+  isValidApiKeyFormat,
+  extractKeyPrefix,
+  isTestKey,
+  maskApiKey,
+} from '../utils/api-key.js';
+
+describe('API Key Utilities', () => {
+  describe('generateApiKey', () => {
+    it('should generate a live key by default', () => {
+      const result = generateApiKey();
+
+      expect(result.key).toMatch(/^vpm_live_[a-zA-Z0-9_-]{32}$/);
+      expect(result.keyPrefix).toBe(result.key.slice(0, 16));
+      expect(result.keyHash).toBeDefined();
+      expect(result.keyHash).toHaveLength(64); // SHA-256 hex
+    });
+
+    it('should generate a live key when specified', () => {
+      const result = generateApiKey('live');
+
+      expect(result.key).toMatch(/^vpm_live_[a-zA-Z0-9_-]{32}$/);
+      expect(result.key.startsWith('vpm_live_')).toBe(true);
+    });
+
+    it('should generate a test key when specified', () => {
+      const result = generateApiKey('test');
+
+      expect(result.key).toMatch(/^vpm_test_[a-zA-Z0-9_-]{32}$/);
+      expect(result.key.startsWith('vpm_test_')).toBe(true);
+    });
+
+    it('should generate unique keys each time', () => {
+      const key1 = generateApiKey();
+      const key2 = generateApiKey();
+
+      expect(key1.key).not.toBe(key2.key);
+      expect(key1.keyHash).not.toBe(key2.keyHash);
+    });
+
+    it('should generate consistent hash for the same key', () => {
+      const { key } = generateApiKey();
+      const hash1 = hashApiKey(key);
+      const hash2 = hashApiKey(key);
+
+      expect(hash1).toBe(hash2);
+    });
+  });
+
+  describe('hashApiKey', () => {
+    it('should return a SHA-256 hex hash', () => {
+      const hash = hashApiKey('vpm_live_test1234567890abcdefghij');
+
+      expect(hash).toHaveLength(64);
+      expect(hash).toMatch(/^[a-f0-9]{64}$/);
+    });
+
+    it('should return different hashes for different keys', () => {
+      const hash1 = hashApiKey('vpm_live_key1aaaaaaaaaaaaaaaaaaaaa');
+      const hash2 = hashApiKey('vpm_live_key2bbbbbbbbbbbbbbbbbbbbb');
+
+      expect(hash1).not.toBe(hash2);
+    });
+  });
+
+  describe('isValidApiKeyFormat', () => {
+    it('should validate correct live key format', () => {
+      expect(isValidApiKeyFormat('vpm_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).toBe(true);
+      expect(isValidApiKeyFormat('vpm_live_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef')).toBe(true);
+      expect(isValidApiKeyFormat('vpm_live_0123456789-_0123456789-_01234567')).toBe(true);
+    });
+
+    it('should validate correct test key format', () => {
+      expect(isValidApiKeyFormat('vpm_test_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).toBe(true);
+      expect(isValidApiKeyFormat('vpm_test_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef')).toBe(true);
+    });
+
+    it('should reject invalid prefixes', () => {
+      expect(isValidApiKeyFormat('vpm_prod_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).toBe(false);
+      expect(isValidApiKeyFormat('xxx_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).toBe(false);
+      expect(isValidApiKeyFormat('aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).toBe(false);
+    });
+
+    it('should reject keys with wrong length', () => {
+      expect(isValidApiKeyFormat('vpm_live_short')).toBe(false);
+      expect(isValidApiKeyFormat('vpm_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaextralong')).toBe(false);
+    });
+
+    it('should reject keys with invalid characters', () => {
+      expect(isValidApiKeyFormat('vpm_live_aaaaaaaaaaaaaaaa!@#$aaaaaaaaaaaaa')).toBe(false);
+    });
+  });
+
+  describe('extractKeyPrefix', () => {
+    it('should extract first 16 characters', () => {
+      const key = 'vpm_live_abcdefghijklmnopqrstuvwxyz012345';
+      expect(extractKeyPrefix(key)).toBe('vpm_live_abcdefg');
+    });
+  });
+
+  describe('isTestKey', () => {
+    it('should return true for test keys', () => {
+      expect(isTestKey('vpm_test_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).toBe(true);
+    });
+
+    it('should return false for live keys', () => {
+      expect(isTestKey('vpm_live_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa')).toBe(false);
+    });
+  });
+
+  describe('maskApiKey', () => {
+    it('should mask middle portion of key', () => {
+      const key = 'vpm_live_abcdefghijklmnopqrstuvwxyz012345';
+      const masked = maskApiKey(key);
+
+      expect(masked).toBe('vpm_live_abcdefg...2345');
+      expect(masked).toContain('...');
+      expect(masked.startsWith('vpm_live_')).toBe(true);
+    });
+
+    it('should return short keys unchanged', () => {
+      const shortKey = 'short_key';
+      expect(maskApiKey(shortKey)).toBe(shortKey);
+    });
+  });
+});

package/src/__tests__/encryption.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import {
+  encrypt,
+  decrypt,
+  generateEncryptionSecret,
+} from '../utils/encryption.js';
+
+describe('Encryption Utilities', () => {
+  describe('generateEncryptionSecret', () => {
+    it('should generate a 64-character hex string', () => {
+      const secret = generateEncryptionSecret();
+
+      expect(secret).toHaveLength(64);
+      expect(secret).toMatch(/^[a-f0-9]{64}$/);
+    });
+
+    it('should generate unique secrets each time', () => {
+      const secret1 = generateEncryptionSecret();
+      const secret2 = generateEncryptionSecret();
+
+      expect(secret1).not.toBe(secret2);
+    });
+  });
+
+  describe('encrypt and decrypt', () => {
+    it('should encrypt and decrypt text correctly', async () => {
+      const secret = generateEncryptionSecret();
+      const plaintext = 'Hello, World!';
+
+      const encrypted = await encrypt(plaintext, secret);
+      const decrypted = await decrypt(encrypted, secret);
+
+      expect(decrypted).toBe(plaintext);
+    });
+
+    it('should produce different ciphertext for same plaintext', async () => {
+      const secret = generateEncryptionSecret();
+      const plaintext = 'Same text twice';
+
+      const encrypted1 = await encrypt(plaintext, secret);
+      const encrypted2 = await encrypt(plaintext, secret);
+
+      // Due to random salt/IV, encryptions should be different
+      expect(encrypted1).not.toBe(encrypted2);
+
+      // But both should decrypt to same plaintext
+      expect(await decrypt(encrypted1, secret)).toBe(plaintext);
+      expect(await decrypt(encrypted2, secret)).toBe(plaintext);
+    });
+
+    it('should encrypt/decrypt unicode text', async () => {
+      const secret = generateEncryptionSecret();
+      const plaintext = '你好世界! 🚀 Привет мир!';
+
+      const encrypted = await encrypt(plaintext, secret);
+      const decrypted = await decrypt(encrypted, secret);
+
+      expect(decrypted).toBe(plaintext);
+    });
+
+    it('should encrypt/decrypt long text', async () => {
+      const secret = generateEncryptionSecret();
+      const plaintext = 'A'.repeat(10000);
+
+      const encrypted = await encrypt(plaintext, secret);
+      const decrypted = await decrypt(encrypted, secret);
+
+      expect(decrypted).toBe(plaintext);
+    });
+
+    it('should encrypt/decrypt empty string', async () => {
+      const secret = generateEncryptionSecret();
+      const plaintext = '';
+
+      const encrypted = await encrypt(plaintext, secret);
+      const decrypted = await decrypt(encrypted, secret);
+
+      expect(decrypted).toBe(plaintext);
+    });
+
+    it('should produce encrypted text in correct format', async () => {
+      const secret = generateEncryptionSecret();
+      const encrypted = await encrypt('test', secret);
+
+      // Format: salt:iv:tag:ciphertext (all base64)
+      const parts = encrypted.split(':');
+      expect(parts).toHaveLength(4);
+
+      // Each part should be valid base64
+      parts.forEach(part => {
+        expect(() => Buffer.from(part, 'base64')).not.toThrow();
+      });
+    });
+
+    it('should fail decryption with wrong secret', async () => {
+      const secret1 = generateEncryptionSecret();
+      const secret2 = generateEncryptionSecret();
+      const plaintext = 'Secret message';
+
+      const encrypted = await encrypt(plaintext, secret1);
+
+      await expect(decrypt(encrypted, secret2)).rejects.toThrow();
+    });
+
+    it('should fail decryption with invalid format', async () => {
+      const secret = generateEncryptionSecret();
+
+      await expect(decrypt('not:enough:parts', secret)).rejects.toThrow(
+        'Invalid encrypted text format'
+      );
+
+      await expect(decrypt('single', secret)).rejects.toThrow(
+        'Invalid encrypted text format'
+      );
+    });
+
+    it('should fail decryption with tampered ciphertext', async () => {
+      const secret = generateEncryptionSecret();
+      const encrypted = await encrypt('test', secret);
+
+      // Tamper with the ciphertext part
+      const parts = encrypted.split(':');
+      parts[3] = 'AAAA' + parts[3]!.slice(4); // Modify ciphertext
+      const tampered = parts.join(':');
+
+      await expect(decrypt(tampered, secret)).rejects.toThrow();
+    });
+  });
+});