Merge pull request #23 from wataruoguchi/support_requiring_policy

test(emmett-crypto-shredding-kysely): make policies required

Author: wataruoguchi

docs/emmett-crypto-shredding-kysely.md

@@ -16,110 +16,249 @@ npm install @wataruoguchi/emmett-crypto-shredding-kysely @wataruoguchi/emmett-cr
 
 ### 1. Run Database Migration
 
-Copy the migration file from [`database/migrations/`](https://github.com/wataruoguchi/emmett-libs/blob/main/packages/emmett-crypto-shredding-kysely/database/migrations/1761627233034_crypto_shredding.ts) to your migrations directory.
+Copy the migration file from [`database/migrations/`](https://github.com/wataruoguchi/emmett-libs/blob/main/packages/emmett-crypto-shredding-kysely/database/migrations/1761627233034_crypto_shredding.ts) to your migrations directory and run it.
 
-### 2. Create Key Management and Policy Resolver
+### 2. Create Encryption Policies
+
+**⚠️ Important:** Policies must be created **before** events can be encrypted. Create them during:
+
+- **Tenant onboarding** - When a new tenant/partition is created
+- **Application setup** - As a one-time bootstrap step
+- **Feature enablement** - When enabling crypto shredding for existing streams
 
 ```typescript
-import { 
-  createKeyManagement, 
-  createPolicyResolver 
-} from '@wataruoguchi/emmett-crypto-shredding-kysely';
+import { createPolicies } from '@wataruoguchi/emmett-crypto-shredding-kysely';
 
-const keyManagement = createKeyManagement(db);
-const policyResolver = createPolicyResolver(db, logger);
+// Example: During tenant onboarding
+async function onboardTenant(tenantId: string) {
+  // Create tenant...
+  
+  // Set up encryption policies for sensitive streams
+  await createPolicies(db, [
+    {
+      policyId: `${tenantId}-generator`,
+      partition: tenantId,
+      streamTypeClass: 'generator', // Stream type to encrypt
+      encryptionAlgorithm: 'AES-GCM',
+      keyRotationIntervalDays: 180,
+      keyScope: 'stream', // 'stream' or 'type'
+    },
+  ]);
+}
 ```
 
-### 3. Set Up Encryption Policies
+**Alternative:** Use default policies for common use cases:
 
 ```typescript
-import { createDefaultPolicies, createPolicies } from '@wataruoguchi/emmett-crypto-shredding-kysely';
+import { createDefaultPolicies } 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
+// Creates policies for 'user-data' and 'audit-log' stream types
 await createDefaultPolicies(db, 'tenant-123');
+```
+
+### 3. Create Encrypted Event Store in Your Module
+
+Wire up the crypto event store in your module factory:
+
+```typescript
+import { 
+  createCryptoEventStore,
+  createWebCryptoProvider,
+  type CryptoContext,
+} from '@wataruoguchi/emmett-crypto-shredding';
+import {
+  createKeyManagement,
+  createPolicyResolver,
+} from '@wataruoguchi/emmett-crypto-shredding-kysely';
+import { getKyselyEventStore } from '@wataruoguchi/emmett-event-store-kysely';
+
+export function createGeneratorModule({ db, logger }) {
+  const eventStore = createCryptoEventStore(
+    getKyselyEventStore({ db, logger }),
+    {
+      policy: createPolicyResolver(db, logger),
+      keys: createKeyManagement(db),
+      crypto: createWebCryptoProvider(),
+      buildAAD: ({ partition, streamId }: CryptoContext) =>
+        new TextEncoder().encode(`${partition}:${streamId}`),
+      logger,
+    },
+  );
+  
+  // Use eventStore in your event handler...
+  return createService({ eventStore });
+}
+```
+
+**How it works:**
+
+1. When events are appended, the policy resolver checks if the stream type has a policy
+2. If a policy exists, events are encrypted using the specified algorithm
+3. Keys are automatically generated and managed per the policy's `keyScope`
+4. If no policy exists for a stream type, events are stored unencrypted
+
+## API Reference
+
+### Policy Management
 
-// Option 2: Create custom policies
+#### Creating Policies
+
+```typescript
+import { 
+  createPolicies, 
+  createDefaultPolicies,
+  type DatabasePolicyConfig 
+} from '@wataruoguchi/emmett-crypto-shredding-kysely';
+
+// Create custom policies
 await createPolicies(db, [
   {
-    policyId: 'tenant-123-user-data',
+    policyId: 'tenant-123-generator',
     partition: 'tenant-123',
-    streamTypeClass: 'user-data',
+    streamTypeClass: 'generator',
     encryptionAlgorithm: 'AES-GCM',
     keyRotationIntervalDays: 180,
-    keyScope: 'stream',
+    keyScope: 'stream', // 'stream' = one key per stream, 'type' = one key per stream type
   },
 ]);
+
+// Or use defaults (creates 'user-data' and 'audit-log' policies)
+await createDefaultPolicies(db, 'tenant-123');
 ```
 
-### 4. Create Encrypted Event Store
+#### Managing Policies
 
 ```typescript
-import { createCryptoEventStore } from '@wataruoguchi/emmett-crypto-shredding';
-import { getKyselyEventStore } from '@wataruoguchi/emmett-event-store-kysely';
+import { 
+  updatePolicy, 
+  listPolicies, 
+  deletePolicy 
+} from '@wataruoguchi/emmett-crypto-shredding-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,
+// Update policy
+await updatePolicy(db, 'tenant-123-generator', 'tenant-123', {
+  encryptionAlgorithm: 'AES-GCM',
+  keyRotationIntervalDays: 365,
 });
-```
 
-## API Reference
+// List all policies for a partition
+const policies = await listPolicies(db, 'tenant-123');
+
+// Delete policy (stops encrypting new events for this stream type)
+await deletePolicy(db, 'tenant-123-generator', 'tenant-123');
+```
 
 ### Key Management
 
+The `createKeyManagement` function returns a service that automatically manages encryption keys based on your policies:
+
 ```typescript
-// Get or create active key
+import { createKeyManagement } from '@wataruoguchi/emmett-crypto-shredding-kysely';
+
+const keyManagement = createKeyManagement(db);
+
+// Get or create active key (usually done automatically by crypto event store)
 const key = await keyManagement.getActiveKey({
   partition: 'tenant-123',
-  keyRef: 'user-data',
+  keyRef: 'generator-stream-123', // Varies based on keyScope
 });
 
-// Rotate key
+// Manually rotate key for a specific reference
 await keyManagement.rotateKey({
   partition: 'tenant-123',
-  keyRef: 'user-data',
+  keyRef: 'generator-stream-123',
 });
 
-// Destroy all keys for a partition (crypto shredding)
+// Crypto shredding: Destroy all keys for a partition
+// This makes all encrypted events for this partition unrecoverable
 await keyManagement.destroyPartitionKeys({
   partition: 'tenant-123',
 });
 ```
 
-### Policy Management
+## Common Patterns
+
+### Tenant Onboarding with Encryption
 
 ```typescript
-// Create policies
-await createPolicies(db, policies);
+async function createTenantWithEncryption(tenantData: { name: string }) {
+  // 1. Create tenant
+  const tenant = await tenantRepository.create(tenantData);
+  
+  // 2. Set up encryption policies for sensitive streams
+  await createPolicies(db, [
+    {
+      policyId: `${tenant.id}-user-data`,
+      partition: tenant.id,
+      streamTypeClass: 'user-data',
+      encryptionAlgorithm: 'AES-GCM',
+      keyRotationIntervalDays: 180,
+      keyScope: 'stream',
+    },
+  ]);
+  
+  return tenant;
+}
+```
 
-// Update policy
-await updatePolicy(db, policyId, partition, {
-  encryptionAlgorithm: 'AES-GCM',
-  keyRotationIntervalDays: 365,
-});
+### Selective Encryption by Stream Type
+
+Only encrypt sensitive stream types. Other streams remain unencrypted for performance:
+
+```typescript
+// Encrypt sensitive streams
+await createPolicies(db, [
+  {
+    policyId: `${tenantId}-user-data`,
+    partition: tenantId,
+    streamTypeClass: 'user-data', // ✅ Encrypted
+    encryptionAlgorithm: 'AES-GCM',
+    keyRotationIntervalDays: 180,
+    keyScope: 'stream',
+  },
+]);
+
+// No policy for 'cart' stream type → stored unencrypted ✓
+```
 
-// List policies
-const policies = await listPolicies(db, partition);
+### Crypto Shredding (Right to be Forgotten)
 
-// Delete policy
-await deletePolicy(db, policyId, partition);
+```typescript
+async function forgetTenant(tenantId: string) {
+  // Destroy all encryption keys for the tenant
+  // This makes all encrypted events permanently unrecoverable
+  await keyManagement.destroyPartitionKeys({ partition: tenantId });
+  
+  // Optionally: Delete unencrypted data or anonymize tenant records
+  // ...
+}
 ```
 
+## Troubleshooting
+
+### Events Not Being Encrypted
+
+**Problem:** Events are stored in plaintext even though policies exist.
+
+**Checklist:**
+
+1. ✅ Verify policy exists: `await listPolicies(db, tenantId)`
+2. ✅ Check `streamTypeClass` matches your stream type exactly
+3. ✅ Ensure policy was created before appending events
+4. ✅ Verify `createCryptoEventStore` is being used (not just base event store)
+
+### Cannot Read Encrypted Events
+
+**Problem:** Events cannot be decrypted or appear as `[encrypted]`.
+
+**Possible causes:**
+
+- Keys have been destroyed (crypto shredding)
+- Wrong partition/tenant context
+- Database connectivity issues with `encryption_keys` table
+
 ## 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
+- [Example Application](https://github.com/wataruoguchi/emmett-libs/tree/main/example) - Complete working example with crypto shredding