Merge pull request #15 from wataruoguchi/crypto-shredding

Add the crypto shredding feature

Author: wataruoguchi

.devcontainer/Dockerfile

@@ -1,4 +1,4 @@
-FROM mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm
+FROM mcr.microsoft.com/devcontainers/javascript-node:24-trixie
 
 RUN apt-get update \
     && apt-get install -y pgcli ack mkcert \

.devcontainer/devcontainer.json

@@ -1,7 +1,7 @@
 // For format details, see https://aka.ms/devcontainer.json. For config options, see the
 // README at: https://github.com/devcontainers/templates/tree/main/src/javascript-node-postgres
 {
-  "name": "Node.js & PostgreSQL",
+  "name": "Emmett Libs",
   "dockerComposeFile": "docker-compose.yml",
   "service": "app",
   "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}",

.github/workflows/ci.yml

@@ -10,11 +10,17 @@ on:
 
 jobs:
   quality:
-    name: Quality Checks
+    name: Quality Checks - ${{ matrix.package }}
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        package:
+          - emmett-event-store-kysely
+          - emmett-crypto-shredding
+          - emmett-crypto-shredding-kysely
     defaults:
       run:
-        working-directory: ./packages/emmett-event-store-kysely
+        working-directory: ./packages/${{ matrix.package }}
 
     steps:
       - name: Checkout code
@@ -27,7 +33,7 @@ jobs:
         with:
           node-version: '20'
           cache: 'npm'
-          cache-dependency-path: './packages/emmett-event-store-kysely/package-lock.json'
+          cache-dependency-path: './packages/${{ matrix.package }}/package-lock.json'
 
       - name: Install dependencies
         run: npm ci
@@ -39,17 +45,23 @@ jobs:
         run: npm run build
 
   release:
-    name: Release
+    name: Release - ${{ matrix.package }}
     runs-on: ubuntu-latest
     needs: quality
     if: github.ref == 'refs/heads/main'
+    strategy:
+      matrix:
+        package:
+          - emmett-event-store-kysely
+          - emmett-crypto-shredding
+          - emmett-crypto-shredding-kysely
     permissions:
       contents: write
       issues: write
       pull-requests: write
     defaults:
       run:
-        working-directory: ./packages/emmett-event-store-kysely
+        working-directory: ./packages/${{ matrix.package }}
 
     steps:
       - name: Checkout code
@@ -64,7 +76,7 @@ jobs:
           node-version: '20'
           registry-url: 'https://registry.npmjs.org'
           cache: 'npm'
-          cache-dependency-path: './packages/emmett-event-store-kysely/package-lock.json'
+          cache-dependency-path: './packages/${{ matrix.package }}/package-lock.json'
 
       - name: Install dependencies
         run: npm ci

.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: Deploy Documentation
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.vitepress/**'
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch: # Allow manual triggering
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: './package-lock.json'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build VitePress site
+        run: npm run docs:build
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/.vitepress/dist'
+
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

.gitignore

@@ -27,4 +27,6 @@ lerna-debug.log*
 # misc
 .DS_Store
 *.ignored.*
-coverage/
+coverage/
+docs/.vitepress/
+

README.md

@@ -0,0 +1,41 @@
+# @wataruoguchi/emmett-libs
+
+Event sourcing libraries built on [Emmett](https://github.com/event-driven-io/emmett).
+
+## 📚 Documentation
+
+**👉 [View Full Documentation →](https://wataruoguchi.github.io/emmett-libs/)**
+
+## 📦 Packages
+
+- **[@wataruoguchi/emmett-event-store-kysely](./packages/emmett-event-store-kysely)** - Kysely-based event store with PostgreSQL
+- **[@wataruoguchi/emmett-crypto-shredding](./packages/emmett-crypto-shredding)** - Crypto shredding for event streams
+- **[@wataruoguchi/emmett-crypto-shredding-kysely](./packages/emmett-crypto-shredding-kysely)** - Kysely adapters for crypto shredding
+
+## 📖 Example Project
+
+The [`example`](./example) directory contains a working SaaS application demonstrating how to use these packages together:
+
+- **Event Store Integration** - See how `@wataruoguchi/emmett-event-store-kysely` is used for event sourcing with PostgreSQL
+  - Located in `example/src/modules/*/application/event-sourcing/`
+  - Example modules: `cart`, `generator`, `tenant`
+
+- **Crypto Shredding Implementation** - Complete example of `@wataruoguchi/emmett-crypto-shredding` with Kysely adapters
+  - See `example/src/modules/generator/application/event-sourcing/crypto/` for crypto adapters usage
+  - Check `example/src/modules/generator/tests/generator.crypto.e2e.spec.ts` for comprehensive test coverage including:
+    - Key scopes (stream, type, tenant)
+    - Multi-tenant isolation
+    - Key rotation and crypto shredding
+    - Graceful error handling
+
+- **Database Migrations** - Example migrations for both event store and crypto shredding tables
+  - Event store tables in `example/database/migrations/`
+  - Crypto shredding tables in `packages/emmett-crypto-shredding-kysely/database/migrations/`
+
+- **Projections** - Examples of building read models with snapshot projections
+  - See `example/src/modules/generator/application/event-sourcing/generator.event-handler.ts`
+  - Example read model migrations in `example/database/migrations/`
+
+## 📄 License
+
+MIT

docs/emmett-crypto-shredding-kysely.md

@@ -0,0 +1,125 @@
+---
+outline: deep
+---
+
+# @wataruoguchi/emmett-crypto-shredding-kysely
+
+Kysely adapters for [Emmett Crypto Shredding](./emmett-crypto-shredding), providing PostgreSQL-backed implementations for key storage and policy resolution.
+
+## Installation
+
+```bash
+npm install @wataruoguchi/emmett-crypto-shredding-kysely @wataruoguchi/emmett-crypto-shredding kysely pg
+```
+
+## Quick Start
+
+### 1. Run Database Migration
+
+Copy the migration file from `database/migrations/` to your migrations directory.
+
+### 2. Create Key Management and Policy Resolver
+
+```typescript
+import { 
+  createKeyManagement, 
+  createPolicyResolver 
+} from '@wataruoguchi/emmett-crypto-shredding-kysely';
+
+const keyManagement = createKeyManagement(db);
+const policyResolver = createPolicyResolver(db, logger);
+```
+
+### 3. Set Up Encryption Policies
+
+```typescript
+import { createDefaultPolicies, createPolicies } from '@wataruoguchi/emmett-crypto-shredding-kysely';
+
+// Option 1: Use default policies
+// Creates policies for common stream types:
+// - user-data: AES-GCM, 180 day rotation, stream scope
+// - audit-log: AES-GCM, 365 day rotation, stream scope
+await createDefaultPolicies(db, 'tenant-123');
+
+// Option 2: Create custom policies
+await createPolicies(db, [
+  {
+    policyId: 'tenant-123-user-data',
+    partition: 'tenant-123',
+    streamTypeClass: 'user-data',
+    encryptionAlgorithm: 'AES-GCM',
+    keyRotationIntervalDays: 180,
+    keyScope: 'stream',
+  },
+]);
+```
+
+### 4. Create Encrypted Event Store
+
+```typescript
+import { createCryptoEventStore } from '@wataruoguchi/emmett-crypto-shredding';
+import { getKyselyEventStore } from '@wataruoguchi/emmett-event-store-kysely';
+
+const baseEventStore = getKyselyEventStore({ db, logger });
+
+const cryptoEventStore = createCryptoEventStore({
+  baseEventStore,
+  keyManagement,
+  policyResolver,
+  buildAAD: (ctx) => JSON.stringify({
+    partition: ctx.partition,
+    streamId: ctx.streamId,
+    streamType: ctx.streamType,
+    eventType: ctx.eventType,
+  }),
+  logger,
+});
+```
+
+## API Reference
+
+### Key Management
+
+```typescript
+// Get or create active key
+const key = await keyManagement.getActiveKey({
+  partition: 'tenant-123',
+  keyRef: 'user-data',
+});
+
+// Rotate key
+await keyManagement.rotateKey({
+  partition: 'tenant-123',
+  keyRef: 'user-data',
+});
+
+// Destroy all keys for a partition (crypto shredding)
+await keyManagement.destroyPartitionKeys({
+  partition: 'tenant-123',
+});
+```
+
+### Policy Management
+
+```typescript
+// Create policies
+await createPolicies(db, policies);
+
+// Update policy
+await updatePolicy(db, policyId, partition, {
+  encryptionAlgorithm: 'AES-GCM',
+  keyRotationIntervalDays: 365,
+});
+
+// List policies
+const policies = await listPolicies(db, partition);
+
+// Delete policy
+await deletePolicy(db, policyId, partition);
+```
+
+## See Also
+
+- [Crypto Shredding Core](./emmett-crypto-shredding) - Core encryption functionality
+- [Event Store Kysely](./emmett-event-store-kysely) - Base event store implementation
+- [Example Application](https://github.com/wataruoguchi/emmett-libs/tree/main/example) - Complete working example