@classytic/arc 2.3.0 → 2.4.2

package/skills/arc/references/auth.md

@@ -0,0 +1,250 @@
+# Arc Authentication & Authorization
+
+## Auth Strategies (Discriminated Union)
+
+Auth config uses `type` field to select strategy:
+
+### JWT (`type: 'jwt'`)
+
+```typescript
+const app = await createApp({
+  auth: {
+    type: 'jwt',
+    jwt: {
+      secret: process.env.JWT_SECRET,      // Required, 32+ chars
+      expiresIn: '15m',                    // Access token TTL
+      refreshSecret: process.env.JWT_REFRESH_SECRET,
+      refreshExpiresIn: '7d',
+    },
+    // Optional: custom authenticator with JWT helpers
+    authenticate: async (request, { jwt }) => {
+      const token = request.headers.authorization?.split(' ')[1];
+      if (!token) return null;
+      const decoded = jwt.verify(token);
+      return await User.findById(decoded._id);
+    },
+  },
+});
+// Decorates: app.authenticate, app.optionalAuthenticate, app.authorize, app.auth
+```
+
+**Token lifecycle:**
+
+```typescript
+// Issue tokens
+const tokens = app.auth.issueTokens({ _id: user._id, email, role });
+// Returns: { accessToken, refreshToken?, expiresIn, tokenType: 'Bearer' }
+
+// Verify refresh token (rejects access tokens)
+const decoded = app.auth.verifyRefreshToken(refreshToken);
+```
+
+### Better Auth (`type: 'betterAuth'`)
+
+```typescript
+import { createBetterAuthAdapter } from '@classytic/arc/auth';
+
+const adapter = createBetterAuthAdapter({
+  auth,                    // Your betterAuth() instance
+  basePath: '/api/auth',
+  orgContext: true,        // Extract org membership into request.scope
+});
+
+const app = await createApp({
+  auth: { type: 'betterAuth', betterAuth: adapter },
+});
+```
+
+**Org context flow** (when `orgContext: true`):
+1. Gets session via Better Auth
+2. Reads `session.activeOrganizationId`, or falls back to `x-organization-id` header (needed for API key auth where synthetic sessions have no org context)
+3. Looks up org membership via `getActiveMemberRole` (with explicit `organizationId` param for header-based resolution)
+4. Splits roles: `"admin,recruiter"` → `['admin', 'recruiter']`
+5. Sets `request.scope`: `{ kind: 'member', organizationId, orgRoles: string[], teamId? }`
+
+### API Key Auth (Better Auth `apiKey()` plugin)
+
+When the `apiKey()` plugin is enabled in Better Auth, Arc's adapter automatically:
+- Resolves API key sessions via `enableSessionForAPIKeys: true`
+- Falls back to `x-organization-id` header for org context (API key sessions have no `activeOrganizationId`)
+- Generates OpenAPI security schemes dynamically — `apiKeyAuth` only appears in the spec when the plugin is active
+
+```
+x-api-key: ak_live_...           # Authentication
+x-organization-id: org_abc123    # Org context (required for org-scoped resources)
+```
+
+**OpenAPI security semantics:**
+- Resource paths: `security: [{ bearerAuth: [] }, { apiKeyAuth: [], orgHeader: [] }]`
+  - Meaning: bearer token alone **OR** (API key **AND** org header together)
+- Auth endpoints: `security: [{ cookieAuth: [] }, { bearerAuth: [] }, { apiKeyAuth: [] }]`
+  - No org header required for auth management endpoints
+
+### Custom Plugin (`type: 'custom'`)
+
+```typescript
+auth: { type: 'custom', plugin: myAuthPlugin }
+// Plugin must decorate fastify.authenticate
+```
+
+### Custom Function (`type: 'authenticator'`)
+
+```typescript
+auth: {
+  type: 'authenticator',
+  authenticate: async (req, reply) => {
+    const session = await validateSession(req);
+    if (!session) reply.code(401).send({ error: 'Unauthorized' });
+    req.user = session.user;
+  },
+}
+```
+
+### Disabled
+
+```typescript
+auth: false
+```
+
+## Fastify Decorators
+
+| Decorator | Description | JWT | Better Auth |
+|-----------|-------------|-----|-------------|
+| `fastify.authenticate` | Verify JWT/session, set `request.user` | Yes | Yes |
+| `fastify.optionalAuthenticate` | Parse token if present, skip if absent | Yes | Yes |
+| `fastify.authorize(...roles)` | Check `user.role`. `authorize('*')` = any auth user | Yes | No |
+
+## Permission Functions
+
+```typescript
+import {
+  allowPublic, requireAuth, requireRoles, requireOwnership,
+  requireOrgMembership, requireOrgRole, requireTeamMembership,
+  allOf, anyOf, when, denyAll,
+} from '@classytic/arc';
+```
+
+| Function | Description |
+|----------|-------------|
+| `allowPublic()` | No authentication |
+| `requireAuth()` | Any authenticated user |
+| `requireRoles(['admin'])` | At least one role matches |
+| `requireOwnership('userId')` | Resource owner only (elevated bypasses) |
+| `requireOrgMembership()` | Must be org member |
+| `requireOrgRole('admin', 'owner')` | Must have org-level role |
+| `requireTeamMembership()` | Must have active team |
+| `allOf(p1, p2)` | AND — all must pass |
+| `anyOf(p1, p2)` | OR — any can pass |
+| `denyAll(reason?)` | Always deny |
+
+**Custom permission:**
+
+```typescript
+const requirePro = (): PermissionCheck => async (ctx) => {
+  if (!ctx.user) return { granted: false, reason: 'Auth required' };
+  return { granted: ctx.user.plan === 'pro' };
+};
+```
+
+## Dynamic ACL (DB-managed)
+
+```typescript
+import { createDynamicPermissionMatrix } from '@classytic/arc/permissions';
+
+const acl = createDynamicPermissionMatrix({
+  resolveRolePermissions: async ({ request }) => aclService.getRoleMatrix(orgId),
+  cacheStore: new RedisCacheStore({ client: redis, prefix: 'acl:' }),
+});
+
+permissions: { list: acl.canAction('product', 'read') }
+```
+
+- Reads org roles from `request.scope.orgRoles`
+- Elevated scope bypasses all checks
+- Supports `*` wildcard for resource/action
+- Cache failures fail open to resolver
+
+## Org Guards
+
+```typescript
+import { orgGuard, requireOrg, requireOrgRole } from '@classytic/arc/org';
+
+// Require org context
+fastify.get('/invoices', { preHandler: [fastify.authenticate, requireOrg()] }, handler);
+
+// Require specific org role
+fastify.post('/invoices', { preHandler: [fastify.authenticate, requireOrgRole('admin')] }, handler);
+```
+
+## Request Scope
+
+```typescript
+import type { RequestScope } from '@classytic/arc/scope';
+import { getUserId, getUserRoles, getOrgId, getOrgRoles, getTeamId } from '@classytic/arc/scope';
+
+// Variants (userId/userRoles on all authenticated variants):
+// { kind: 'public' }
+// { kind: 'authenticated', userId?, userRoles? }
+// { kind: 'member', userId?, userRoles, organizationId, orgRoles: string[], teamId? }
+// { kind: 'elevated', userId?, organizationId?, elevatedBy }
+
+const userId = getUserId(request.scope);         // string | undefined
+const globalRoles = getUserRoles(request.scope); // string[]
+const orgId = getOrgId(request.scope);           // string | undefined
+const orgRoles = getOrgRoles(request.scope);     // string[]
+```
+
+## Two Role Layers
+
+| Layer | Source | Scope Field | Checked By |
+|-------|--------|-------------|------------|
+| Global roles | `user.role` | `scope.userRoles` | `requireRoles()`, `authorize()` |
+| Org roles | Org membership | `scope.orgRoles` | `requireOrgRole()`, `requireOrgMembership()` |
+
+## Role Hierarchy
+
+```typescript
+import { createRoleHierarchy } from '@classytic/arc/permissions';
+
+const hierarchy = createRoleHierarchy({
+  superadmin: ['admin'],
+  admin: ['branch_manager'],
+});
+
+hierarchy.expand(['superadmin']); // → ['superadmin', 'admin', 'branch_manager']
+hierarchy.includes(['admin'], 'branch_manager'); // → true
+```
+
+## Token Extraction & Revocation
+
+```typescript
+auth: {
+  type: 'jwt', jwt: { secret },
+  tokenExtractor: (req) => req.cookies?.['auth-token'] ?? null,
+  isRevoked: async (decoded) => redis.sismember('revoked', decoded.jti),
+}
+```
+
+## Microservice Gateway Pattern
+
+```
+Frontend → API Gateway (Arc + Better Auth) → Downstream Services
+                                  ↓
+                    Forwards: X-User-Id, X-Org-Id, X-User-Roles
+```
+
+Gateway verifies session, downstream services trust headers:
+
+```typescript
+// Downstream — no Better Auth needed
+const app = await createApp({
+  auth: {
+    type: 'authenticator',
+    authenticate: async (req, reply) => {
+      const userId = req.headers['x-user-id'];
+      if (!userId) return reply.code(401).send({ error: 'Unauthorized' });
+      req.user = { id: userId, role: JSON.parse(req.headers['x-user-roles'] || '[]') };
+    },
+  },
+});
+```

package/skills/arc/references/events.md

@@ -0,0 +1,272 @@
+# Arc Events System
+
+Domain event pub/sub with pluggable transports. Auto-emits events on CRUD operations.
+
+## Hooks vs Events
+
+| Aspect | Hooks | Events |
+|--------|-------|--------|
+| Purpose | Internal lifecycle callbacks | External integration |
+| Scope | Same process, synchronous flow | Cross-service, async |
+| Use when | Validating, transforming, auditing | Notifying services, event-driven systems |
+| Transport | In-process only | Pluggable (Memory → Redis → Kafka) |
+| Pattern | `beforeCreate`, `afterUpdate` | `product.created`, `order.updated` |
+
+## Setup
+
+The `createApp()` factory auto-registers `eventPlugin` — no manual registration needed:
+
+```typescript
+import { createApp } from '@classytic/arc/factory';
+
+// Development (in-memory, default — zero config)
+const app = await createApp({ preset: 'development' });
+// app.events is ready to use
+
+// Production (Redis transport, with retry)
+import { RedisEventTransport } from '@classytic/arc/events/redis';
+
+const app = await createApp({
+  stores: { events: new RedisEventTransport(redis) },
+  arcPlugins: {
+    events: {
+      logEvents: true,
+      failOpen: true,            // default: suppress transport failures
+      retry: { maxRetries: 3, backoffMs: 1000 },
+    },
+  },
+});
+
+// Disable event plugin entirely
+const app = await createApp({ arcPlugins: { events: false } });
+```
+
+**Manual registration** (for apps not using `createApp`):
+
+```typescript
+import { eventPlugin } from '@classytic/arc/events';
+
+await fastify.register(eventPlugin);  // Memory transport
+
+// Redis Pub/Sub
+import { RedisEventTransport } from '@classytic/arc/events/redis';
+await fastify.register(eventPlugin, {
+  transport: new RedisEventTransport(redisClient, { channel: 'arc-events' }),
+  logEvents: true,
+});
+
+// Redis Streams (ordered, persistent, consumer groups)
+import { RedisStreamTransport } from '@classytic/arc/events/redis-stream';
+await fastify.register(eventPlugin, {
+  transport: new RedisStreamTransport(redisClient, {
+    stream: 'arc:events',
+    group: 'api-service',
+    consumer: 'worker-1',
+  }),
+});
+```
+
+`failOpen` behavior:
+- `true` (default): publish/subscribe/close transport errors are logged and suppressed.
+- `false`: transport errors are thrown to caller.
+
+## Auto-Emitted Events
+
+BaseController automatically emits events when eventPlugin is registered:
+
+| Operation | Event Type | Payload |
+|-----------|------------|---------|
+| `create()` | `{resource}.created` | Created document |
+| `update()` | `{resource}.updated` | Updated document |
+| `delete()` | `{resource}.deleted` | Deleted document |
+| `restore()` | `{resource}.restored` | Restored document |
+
+Disable per-controller: `super({ disableEvents: true })`
+
+## Publishing & Subscribing
+
+```typescript
+// Publish
+await fastify.events.publish('order.created', {
+  orderId: 'order-123',
+  total: 99.99,
+}, {
+  userId: request.user._id,
+  organizationId: getOrgId(request.scope),
+  correlationId: request.id,
+});
+
+// Subscribe to specific event
+await fastify.events.subscribe('order.created', async (event) => {
+  await sendConfirmation(event.payload);
+});
+
+// Subscribe to pattern (wildcard)
+await fastify.events.subscribe('order.*', async (event) => {
+  await updateAnalytics(event.type, event.payload);
+});
+
+// Subscribe to all
+await fastify.events.subscribe('*', async (event) => {
+  await auditLog.create(event);
+});
+
+// Unsubscribe
+const unsub = await fastify.events.subscribe('order.created', handler);
+unsub();
+```
+
+## Event Structure
+
+```typescript
+interface DomainEvent<T> {
+  type: string;          // e.g., 'order.created'
+  payload: T;
+  meta: {
+    id: string;          // Unique event ID
+    timestamp: Date;
+    source?: string;
+    resource?: string;
+    resourceId?: string;
+    userId?: string;
+    organizationId?: string;
+    correlationId?: string;
+  };
+}
+```
+
+## Custom Transport
+
+Implement `EventTransport` for RabbitMQ, Kafka, etc.:
+
+```typescript
+import type { EventTransport, DomainEvent } from '@classytic/arc/events';
+
+class KafkaTransport implements EventTransport {
+  readonly name = 'kafka';
+
+  async publish(event: DomainEvent): Promise<void> {
+    await this.producer.send({ topic: event.type, messages: [{ value: JSON.stringify(event) }] });
+  }
+
+  async subscribe(pattern: string, handler: EventHandler): Promise<() => void> {
+    // Subscribe to Kafka topic matching pattern
+    return () => { /* unsubscribe */ };
+  }
+
+  async close(): Promise<void> {
+    await this.producer.disconnect();
+  }
+}
+```
+
+## Built-in Transports
+
+| Transport | Import | Use Case |
+|-----------|--------|----------|
+| Memory | `@classytic/arc/events` (default) | Development, testing, single-instance |
+| Redis Pub/Sub | `@classytic/arc/events/redis` | Multi-instance, real-time |
+| Redis Streams | `@classytic/arc/events/redis-stream` | Ordered, persistent, consumer groups |
+
+## Injectable Logger
+
+All transports and retry accept a `logger` option — defaults to `console`, compatible with pino/fastify.log:
+
+```typescript
+import type { EventLogger } from '@classytic/arc/events';
+
+// Interface: { warn(msg, ...args): void; error(msg, ...args): void }
+
+// Use Fastify's logger
+await fastify.register(eventPlugin, {
+  transport: new RedisEventTransport(redisClient, {
+    logger: fastify.log,    // pino logger
+  }),
+});
+
+// Use with Memory transport
+new MemoryEventTransport({ logger: fastify.log });
+
+// Use with Redis Streams
+new RedisStreamTransport(redisClient, { logger: fastify.log });
+
+// Use with retry wrapper
+import { withRetry } from '@classytic/arc/events';
+const retried = withRetry(handler, { maxRetries: 3, logger: fastify.log });
+```
+
+| Component | File | `logger` option |
+|-----------|------|-----------------|
+| `MemoryEventTransport` | `EventTransport.ts` | `MemoryEventTransportOptions.logger` |
+| `withRetry()` | `retry.ts` | `RetryOptions.logger` |
+| `RedisEventTransport` | `transports/redis.ts` | `RedisEventTransportOptions.logger` |
+| `RedisStreamTransport` | `transports/redis-stream.ts` | `RedisStreamTransportOptions.logger` |
+
+## Typed Events — defineEvent & Event Registry
+
+Declare events with schemas for runtime validation and introspection:
+
+```typescript
+import { defineEvent, createEventRegistry } from '@classytic/arc/events';
+
+const OrderCreated = defineEvent({
+  name: 'order.created',
+  version: 1,
+  description: 'Emitted when an order is placed',
+  schema: {
+    type: 'object',
+    properties: {
+      orderId: { type: 'string' },
+      total: { type: 'number' },
+    },
+    required: ['orderId', 'total'],
+  },
+});
+
+// Type-safe event creation
+const event = OrderCreated.create({ orderId: 'o-1', total: 100 }, { userId: 'user-1' });
+await app.events.publish(event.type, event.payload, event.meta);
+```
+
+**Event Registry** — catalog + auto-validation on publish:
+
+```typescript
+const registry = createEventRegistry();
+registry.register(OrderCreated);
+
+const app = await createApp({
+  arcPlugins: {
+    events: { registry, validateMode: 'warn' },
+    // 'warn' (default): log warning, still publish
+    // 'reject': throw error, do NOT publish
+    // 'off': registry is introspection-only
+  },
+});
+
+// Introspect at runtime
+app.events.registry?.catalog();
+// → [{ name: 'order.created', version: 1, schema: {...} }, ...]
+```
+
+## QueryCache Integration
+
+QueryCache uses events for auto-invalidation. When `arcPlugins.queryCache` is enabled, all CRUD events automatically bump resource versions, invalidating cached queries — zero config required.
+
+## Retry Logic
+
+Events module includes retry with exponential backoff for failed handlers:
+
+```typescript
+import { withRetry } from '@classytic/arc/events';
+
+const retriedHandler = withRetry(async (event) => {
+  await processEvent(event);
+}, {
+  maxRetries: 3,           // default: 3
+  backoffMs: 1000,         // initial delay, doubles each retry (default: 1000)
+  maxBackoffMs: 30000,     // cap (default: 30000)
+  logger: fastify.log,     // default: console
+});
+
+await fastify.events.subscribe('order.created', retriedHandler);
+```