@eldrin-project/eldrin-app-core 0.0.4 → 0.0.5

package/README.md

@@ -2,17 +2,33 @@
 
 [![npm version](https://img.shields.io/npm/v/@eldrin-project/eldrin-app-core.svg)](https://www.npmjs.com/package/@eldrin-project/eldrin-app-core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
 
-Standard library for building Eldrin marketplace apps. Provides database migrations, React hooks for D1 database access, single-spa lifecycle management, and CLI tools for releasing to the Eldrin marketplace.
+Framework-agnostic core library for building Eldrin marketplace apps on Cloudflare Workers with D1 databases.
 
-## Features
+## Overview
 
-- **Zero-config migrations** - SQL migrations run automatically during app bootstrap
-- **Type-safe database access** - React hooks with full TypeScript support
-- **Single-spa compatible** - Seamless integration with micro-frontend architecture
-- **Cloudflare Workers ready** - Built for D1 databases and Workers runtime
-- **CLI tools included** - Release and submit apps to the Eldrin marketplace
+This package is the **foundation layer** of the Eldrin ecosystem:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Your App                                │
+├─────────────────────────────────────────────────────────────┤
+│              Framework Adapter (choose one)                 │
+│  • @eldrin-project/eldrin-app-angular                       │
+│  • @eldrin-project/eldrin-app-react                         │
+│  • @eldrin-project/eldrin-app-vue                           │
+├─────────────────────────────────────────────────────────────┤
+│              @eldrin-project/eldrin-app-core                │
+│  • Database migrations with checksum verification           │
+│  • JWT authentication & permission checking                 │
+│  • Permission middleware for API routes                     │
+│  • Event system for inter-app communication                 │
+│  • Vite plugin for build-time SQL loading                   │
+│  • CLI tools for marketplace release/submission             │
+├─────────────────────────────────────────────────────────────┤
+│              Cloudflare Workers + D1 Database               │
+└─────────────────────────────────────────────────────────────┘
+```
 
 ## Installation
 
@@ -20,142 +36,244 @@ Standard library for building Eldrin marketplace apps. Provides database migrati
 npm install @eldrin-project/eldrin-app-core
 ```
 
-## Quick Start
+## Features
+
+### 1. Database Migrations
 
-### 1. Create your app entry point
+Run SQL migrations against Cloudflare D1 with automatic tracking, checksum verification, and rollback support.
 
-```tsx
-// src/index.tsx
-import { createApp } from '@eldrin-project/eldrin-app-core';
-import migrations from 'virtual:eldrin/migrations';
-import App from './App';
+```typescript
+import { runMigrations, getMigrationStatus } from '@eldrin-project/eldrin-app-core';
 
-export const { bootstrap, mount, unmount } = createApp({
-  name: 'my-app',
-  root: App,
-  migrations,
+// Run pending migrations
+const result = await runMigrations(db, {
+  migrations: [
+    { name: '20250101120000-create-users.sql', content: 'CREATE TABLE users...' },
+    { name: '20250102100000-add-email.sql', content: 'ALTER TABLE users...' },
+  ],
+  onLog: (msg, level) => console.log(`[${level}] ${msg}`),
 });
-```
 
-### 2. Configure Vite
+if (result.success) {
+  console.log(`Executed ${result.executed} migrations`);
+} else {
+  console.error(`Failed at ${result.error?.migration}: ${result.error?.message}`);
+}
 
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite';
-import { eldrinPlugin } from '@eldrin-project/eldrin-app-core/vite';
+// Check migration status
+const status = await getMigrationStatus(db, migrations);
+console.log('Pending:', status.pending);
+console.log('Executed:', status.executed.length);
+```
 
-export default defineConfig({
-  plugins: [
-    eldrinPlugin({
-      migrationsDir: './migrations',
-      seedsDir: './seeds',
-    }),
-  ],
-});
+**Migration file naming:** `YYYYMMDDHHMMSS-description.sql`
+
+Migrations are tracked in `_eldrin_migrations` table with SHA-256 checksums to detect tampering.
+
+### 2. Authentication & Authorization
+
+Verify JWT tokens and check permissions in your Cloudflare Worker:
+
+```typescript
+import {
+  verifyJWT,
+  requireJWTAuth,
+  requireJWTPermission,
+  hasPermission,
+  isPlatformAdmin,
+} from '@eldrin-project/eldrin-app-core';
+
+export default {
+  async fetch(request: Request, env: Env) {
+    // Option 1: Manual verification
+    const result = await verifyJWT(request, {
+      secret: env.JWT_SECRET,
+      appId: 'my-app',
+    });
+
+    if (!result.success) {
+      return Response.json({ error: result.error }, { status: 401 });
+    }
+
+    const { auth } = result;
+    console.log('User:', auth.email);
+    console.log('Permissions:', auth.permissions);
+
+    // Option 2: Require auth (returns Response on failure)
+    const auth = await requireJWTAuth(request, {
+      secret: env.JWT_SECRET,
+      appId: 'my-app',
+    });
+
+    if (auth instanceof Response) return auth; // 401
+
+    // Option 3: Require specific permission
+    const auth = await requireJWTPermission(
+      request,
+      { secret: env.JWT_SECRET, appId: 'my-app' },
+      'invoices',
+      'write'
+    );
+
+    if (auth instanceof Response) return auth; // 401 or 403
+
+    // Check permissions manually
+    if (hasPermission(auth, 'invoices', 'delete')) {
+      // User can delete invoices
+    }
+
+    if (isPlatformAdmin(auth)) {
+      // User is platform admin (has all permissions)
+    }
+  },
+};
 ```
 
-### 3. Add TypeScript support for virtual modules
+### 3. Permission Middleware
 
-```ts
-// src/vite-env.d.ts
-/// <reference types="@eldrin-project/eldrin-app-core/vite-env" />
-```
+Manifest-driven middleware that automatically enforces route permissions:
 
-### 4. Use the database in components
+```typescript
+import { createPermissionMiddleware } from '@eldrin-project/eldrin-app-core';
+import manifest from './eldrin-app.manifest.json';
 
-```tsx
-import { useDatabase } from '@eldrin-project/eldrin-app-core';
+const middleware = createPermissionMiddleware<Env>({
+  manifest,
+  getSecret: (env) => env.JWT_SECRET,
+  cors: {
+    allowOrigin: '*',
+    allowMethods: 'GET, POST, PUT, DELETE, OPTIONS',
+    allowHeaders: 'Content-Type, Authorization',
+  },
+});
 
-function InvoiceList() {
-  const db = useDatabase();
-  const [invoices, setInvoices] = useState([]);
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const result = await middleware.handle(request, env);
 
-  useEffect(() => {
-    if (!db) return;
-    db.prepare('SELECT * FROM invoices ORDER BY created_at DESC')
-      .all()
-      .then(({ results }) => setInvoices(results));
-  }, [db]);
+    // Rejected request (401, 403, or CORS preflight)
+    if (result.response) {
+      return result.response;
+    }
 
-  return <ul>{invoices.map(inv => <li key={inv.id}>{inv.name}</li>)}</ul>;
+    // Authorized - access auth context and route params
+    const { auth, url, params } = result;
+    console.log('User:', auth.email);
+    console.log('Route params:', params); // e.g., { id: '123' }
+
+    // Handle the request...
+  },
+};
+```
+
+**Manifest API configuration:**
+
+```json
+{
+  "id": "my-app",
+  "developer_id": "acme",
+  "api": {
+    "defaultPolicy": "deny",
+    "publicRoutes": ["/api/health"],
+    "routes": [
+      { "method": "GET", "path": "/api/items", "permission": "items:read" },
+      { "method": "POST", "path": "/api/items", "permission": "items:write" },
+      { "method": "GET", "path": "/api/items/:id", "permission": "items:read" },
+      { "method": "DELETE", "path": "/api/items/:id", "permission": "items:delete" }
+    ]
+  }
 }
 ```
 
-## Migrations
+### 4. Event System
 
-Create SQL migration files in your `migrations/` directory:
+Publish/subscribe events for inter-app communication:
 
-```
-migrations/
-├── 20250101120000-create-invoices.sql
-├── 20250101120000-create-invoices.rollback.sql
-└── 20250102100000-add-status-column.sql
-```
+```typescript
+import { createEventClient } from '@eldrin-project/eldrin-app-core';
 
-Migration filenames must follow the pattern: `YYYYMMDDHHMMSS-description.sql`
+export default {
+  async fetch(request: Request, env: Env) {
+    const events = createEventClient(env, 'invoicing');
 
-Migrations run automatically during the app bootstrap phase. The system tracks executed migrations in the `_eldrin_migrations` table with SHA-256 checksums to detect tampering.
+    // Emit an event
+    await events.emit('invoice.created', {
+      invoiceId: 'inv_123',
+      customerId: 'cust_456',
+      total: 1500,
+    });
 
-### Migration Hooks
+    // Poll for events (in a scheduled worker)
+    const pending = await events.poll({ limit: 10 });
 
-```tsx
-export const { bootstrap, mount, unmount } = createApp({
-  name: 'my-app',
-  root: App,
-  migrations,
-  onMigrationsComplete: (result) => {
-    console.log(`Executed ${result.executed} migrations`);
-  },
-  onMigrationError: (error) => {
-    console.error('Migration failed:', error);
+    for (const delivery of pending.events) {
+      try {
+        await processEvent(delivery.event);
+        await events.ack(delivery.id);
+      } catch (error) {
+        await events.nack(delivery.id, error.message);
+      }
+    }
   },
-});
+};
 ```
 
-## API Reference
-
-### createApp(options)
+**Declare events in manifest:**
 
-Creates a single-spa compatible app lifecycle.
+```json
+{
+  "events": {
+    "emits": ["invoice.created", "invoice.paid"],
+    "subscribes": ["payment.received", "customer.updated"]
+  }
+}
+```
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `string` | Unique app identifier |
-| `root` | `React.ComponentType` | Root React component |
-| `migrations` | `MigrationFile[]` | Migration files (from virtual module) |
-| `onMigrationsComplete` | `(result) => void` | Called after successful migrations |
-| `onMigrationError` | `(error) => void` | Called if migrations fail |
+### 5. Vite Plugin
 
-### useDatabase()
+Load SQL migrations at build time (Workers have no filesystem access at runtime):
 
-React hook that returns the D1 database instance or `null`.
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { eldrinPlugin } from '@eldrin-project/eldrin-app-core/vite';
 
-```tsx
-const db = useDatabase();
+export default defineConfig({
+  plugins: [
+    eldrinPlugin({
+      migrationsDir: './migrations',
+      seedsDir: './seeds',
+    }),
+  ],
+});
 ```
 
-### useDatabaseContext()
-
-React hook that returns the full database context including migration status.
-
-```tsx
-const { db, migrationsComplete, migrationResult } = useDatabaseContext();
+```typescript
+// Add type declarations
+// src/vite-env.d.ts
+/// <reference types="@eldrin-project/eldrin-app-core/vite-env" />
 ```
 
-### useMigrationsComplete()
+```typescript
+// Import migrations in your code
+import migrations from 'virtual:eldrin/migrations';
+import seeds from 'virtual:eldrin/seeds';
+```
 
-React hook that returns `true` when migrations have finished.
+## Package Exports
 
-```tsx
-const ready = useMigrationsComplete();
-if (!ready) return <Loading />;
-```
+| Export | Environment | Description |
+|--------|-------------|-------------|
+| `@eldrin-project/eldrin-app-core` | Browser/Worker | Main exports (migrations, auth, events, middleware) |
+| `@eldrin-project/eldrin-app-core/node` | Node.js only | Marketplace utilities (generateMigrationManifest) |
+| `@eldrin-project/eldrin-app-core/vite` | Node.js only | Vite plugin for loading SQL files |
+| `@eldrin-project/eldrin-app-core/vite-env` | Types only | TypeScript declarations for virtual modules |
 
 ## CLI Tools
 
 ### eldrin-release
 
-Prepares your app for marketplace submission.
+Prepares your app for marketplace submission:
 
 ```bash
 npx eldrin-release [options]
@@ -168,18 +286,25 @@ Options:
   -o, --output <path>    Output directory
 ```
 
-Creates a release package at `dist/release/{developerId}/{appId}/v{version}/` containing:
-- `eldrin-app.manifest.json` - App metadata
-- `bundle.js` - Built app bundle
-- `deploy-bundle.json` - Worker + client assets (if applicable)
-- `migrations/` - Migration files with checksums
+Creates a release package at `dist/release/{developerId}/{appId}/v{version}/`:
+
+```
+dist/release/acme/invoicing/
+├── migrations/                    # Shared across versions
+│   ├── index.json                 # Manifest with checksums
+│   └── *.sql                      # Migration files
+└── v1.0.0/
+    ├── eldrin-app.manifest.json   # App metadata
+    ├── bundle.js                  # Worker bundle
+    └── deploy-bundle.json         # Worker + client assets
+```
 
 ### eldrin-submit
 
-Submits a release to the Eldrin marketplace.
+Submits a release to the Eldrin marketplace:
 
 ```bash
-npx eldrin-submit -d ./dist/release/eldrin.io/my-app/v1.0.0
+npx eldrin-submit -d ./dist/release/acme/invoicing/v1.0.0
 
 Options:
   -d, --release-dir <dir>  Release directory to submit
@@ -188,7 +313,7 @@ Options:
   --dry-run                Preview without submitting
 ```
 
-Environment variables:
+**Environment variables:**
 - `ELDRIN_API_KEY` - Your developer API key
 - `ELDRIN_DEVELOPER_ID` - Your developer ID
 - `ELDRIN_MARKETPLACE_URL` - Marketplace URL (default: https://eldrin.io)
@@ -199,11 +324,11 @@ Create `.eldrinrc.json` in your project root:
 
 ```json
 {
-  "developerId": "your-developer-id",
+  "developerId": "acme",
   "marketplaceUrl": "https://eldrin.io",
-  "manifestPath": "./eldrin-app.manifest.json",
+  "manifestPath": "./public/eldrin-app.manifest.json",
   "migrationsDir": "./migrations",
-  "buildCommand": "npm run build:lib",
+  "buildCommand": "npm run build",
   "clientDir": "dist/client",
   "workerEntry": "dist/worker/index.js"
 }
@@ -215,34 +340,99 @@ Create `eldrin-app.manifest.json`:
 
 ```json
 {
-  "id": "my-app",
-  "name": "My App",
+  "id": "invoicing",
+  "name": "Invoicing App",
   "version": "1.0.0",
-  "description": "Description of my app",
-  "developer": {
-    "id": "your-developer-id",
-    "name": "Your Name"
+  "description": "Create and manage invoices",
+  "developer_id": "acme",
+  "permissions": [
+    { "resource": "invoices", "actions": ["read", "write", "delete"] },
+    { "resource": "customers", "actions": ["read"] }
+  ],
+  "groups": [
+    {
+      "id": "admin",
+      "name": "Invoice Admin",
+      "permissions": ["invoices:*", "customers:read"]
+    },
+    {
+      "id": "viewer",
+      "name": "Viewer",
+      "permissions": ["invoices:read", "customers:read"]
+    }
+  ],
+  "events": {
+    "emits": ["invoice.created", "invoice.paid"],
+    "subscribes": ["payment.received"]
   },
-  "entry": "bundle.js"
+  "api": {
+    "defaultPolicy": "deny",
+    "publicRoutes": ["/api/health"],
+    "routes": [
+      { "method": "GET", "path": "/api/invoices", "permission": "invoices:read" },
+      { "method": "POST", "path": "/api/invoices", "permission": "invoices:write" }
+    ]
+  }
 }
 ```
 
-## Requirements
+## Framework Adapters
 
-- Node.js 18.0.0 or later
-- React 18.x or 19.x
-- Vite 6.x or 7.x
+This core package is framework-agnostic. Use these adapters for framework-specific integrations:
 
-## Contributing
+| Framework | Package | Features |
+|-----------|---------|----------|
+| Angular | `@eldrin-project/eldrin-app-angular` | InjectionTokens, providers, single-spa lifecycle |
+| React | `@eldrin-project/eldrin-app-react` | Hooks (useDatabase), Context, single-spa lifecycle |
+| Vue | `@eldrin-project/eldrin-app-vue` | Composables, provide/inject, single-spa lifecycle |
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## API Reference
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+### Migrations
+
+| Function | Description |
+|----------|-------------|
+| `runMigrations(db, options)` | Execute pending migrations |
+| `getMigrationStatus(db, migrations)` | Get pending/executed/orphaned migrations |
+| `rollbackMigrations(db, options)` | Rollback migrations (with .rollback.sql files) |
+| `calculateChecksum(content)` | Calculate SHA-256 checksum of migration content |
+| `verifyChecksum(content, checksum)` | Verify content matches stored checksum |
+
+### Auth
+
+| Function | Description |
+|----------|-------------|
+| `verifyJWT(request, options)` | Verify JWT and extract auth context |
+| `getAuthContextFromJWT(request, options)` | Get auth context (JWT or proxy headers) |
+| `requireJWTAuth(request, options)` | Require valid JWT (returns Response on failure) |
+| `requireJWTPermission(request, options, resource, action)` | Require specific permission |
+| `hasPermission(auth, resource, action)` | Check if auth has permission |
+| `isPlatformAdmin(auth)` | Check if auth is platform admin |
+
+### Middleware
+
+| Function | Description |
+|----------|-------------|
+| `createPermissionMiddleware(config)` | Create manifest-driven permission middleware |
+| `compileRoutes(routes, prefix)` | Pre-compile route patterns for matching |
+| `matchRoute(method, path, routes)` | Match request against compiled routes |
+
+### Events
+
+| Class/Function | Description |
+|----------------|-------------|
+| `EldrinEventClient` | Client for pub/sub event communication |
+| `createEventClient(env, appId)` | Create event client from worker env |
+| `client.emit(type, payload)` | Emit an event |
+| `client.poll(options)` | Poll for pending events |
+| `client.ack(deliveryId)` | Acknowledge successful processing |
+| `client.nack(deliveryId, error)` | Negative acknowledge (retry later) |
+
+## Requirements
+
+- Node.js 18.0.0 or later
+- Vite 6.x or 7.x (optional, for Vite plugin)
 
 ## License
 
-MIT - see [LICENSE](LICENSE) for details.
+MIT

package/dist/index.cjs

@@ -1,9 +1,5 @@
 'use strict';
 
-var promises = require('fs/promises');
-var fs = require('fs');
-var path = require('path');
-
 // src/migrations/checksum.ts
 var CHECKSUM_PREFIX = "sha256:";
 async function calculateChecksum(content, options = {}) {
@@ -371,75 +367,6 @@ async function rollbackMigrations(db, options) {
     };
   }
 }
-async function readMigrationFiles(dir) {
-  if (!fs.existsSync(dir)) {
-    return [];
-  }
-  const files = await promises.readdir(dir);
-  const sqlFiles = files.filter((f) => isValidMigrationFilename(f)).sort();
-  const migrations = [];
-  for (const file of sqlFiles) {
-    const content = await promises.readFile(path.resolve(dir, file), "utf-8");
-    migrations.push({
-      name: path.basename(file),
-      content
-    });
-  }
-  return migrations;
-}
-async function generateMigrationManifest(options) {
-  const { migrationsDir, database } = options;
-  const files = await readMigrationFiles(migrationsDir);
-  const migrations = await Promise.all(
-    files.map(async (file) => {
-      const timestamp = extractTimestamp(file.name);
-      const checksum = await calculatePrefixedChecksum(file.content);
-      return {
-        id: timestamp || file.name.replace(".sql", ""),
-        file: file.name,
-        checksum
-      };
-    })
-  );
-  return {
-    manifest: {
-      database,
-      migrations
-    },
-    files
-  };
-}
-async function validateMigrationManifest(manifest, files) {
-  const errors = [];
-  for (const entry of manifest.migrations) {
-    const file = files.find((f) => f.name === entry.file);
-    if (!file) {
-      errors.push(`Missing file: ${entry.file}`);
-      continue;
-    }
-    const actualChecksum = await calculatePrefixedChecksum(file.content);
-    if (actualChecksum !== entry.checksum) {
-      errors.push(
-        `Checksum mismatch for ${entry.file}: expected ${entry.checksum}, got ${actualChecksum}`
-      );
-    }
-    const timestamp = extractTimestamp(file.name);
-    if (timestamp !== entry.id) {
-      errors.push(
-        `ID mismatch for ${entry.file}: expected ${timestamp}, got ${entry.id}`
-      );
-    }
-  }
-  for (const file of files) {
-    if (!manifest.migrations.some((m) => m.file === file.name)) {
-      errors.push(`File not in manifest: ${file.name}`);
-    }
-  }
-  return {
-    valid: errors.length === 0,
-    errors
-  };
-}
 
 // src/events/client.ts
 var EldrinEventClient = class {
@@ -1052,7 +979,6 @@ exports.compileRoutes = compileRoutes;
 exports.createEventClient = createEventClient;
 exports.createPermissionMiddleware = createPermissionMiddleware;
 exports.extractTimestamp = extractTimestamp;
-exports.generateMigrationManifest = generateMigrationManifest;
 exports.getAuthContext = getAuthContext;
 exports.getAuthContextFromJWT = getAuthContextFromJWT;
 exports.getMigrationStatus = getMigrationStatus;
@@ -1073,7 +999,6 @@ exports.requireJWTPermission = requireJWTPermission;
 exports.requirePermission = requirePermission;
 exports.rollbackMigrations = rollbackMigrations;
 exports.runMigrations = runMigrations;
-exports.validateMigrationManifest = validateMigrationManifest;
 exports.verifyChecksum = verifyChecksum;
 exports.verifyJWT = verifyJWT;
 //# sourceMappingURL=index.cjs.map