@spfn/core 0.2.0-beta.12 → 0.2.0-beta.13

package/dist/types-B-lVqv6b.d.ts

@@ -0,0 +1,298 @@
+import { Context } from 'hono';
+import { E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './router-Di7ENoah.js';
+
+/**
+ * SSE Token Manager
+ *
+ * Auth-agnostic token issuance and verification for SSE connections.
+ * Issues one-time-use tokens with TTL for Token Exchange pattern.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SSETokenManager({ ttl: 30000 });
+ *
+ * // Issue token for authenticated user
+ * const token = await manager.issue('user-123');
+ *
+ * // Verify and consume token (one-time use)
+ * const subject = await manager.verify(token); // 'user-123'
+ * const again = await manager.verify(token);   // null (already consumed)
+ *
+ * // Cleanup on shutdown
+ * manager.destroy();
+ * ```
+ */
+/**
+ * Stored SSE token data
+ */
+interface SSEToken {
+    token: string;
+    subject: string;
+    expiresAt: number;
+}
+/**
+ * Token storage interface
+ *
+ * Implement this for custom storage backends (e.g., Redis for multi-instance).
+ */
+interface SSETokenStore {
+    /** Store a token */
+    set(token: string, data: SSEToken): Promise<void>;
+    /** Get and delete a token (one-time use) */
+    consume(token: string): Promise<SSEToken | null>;
+    /** Remove expired tokens */
+    cleanup(): Promise<void>;
+}
+/**
+ * SSETokenManager configuration
+ */
+interface SSETokenManagerConfig {
+    /**
+     * Token time-to-live in milliseconds
+     * @default 30000
+     */
+    ttl?: number;
+    /**
+     * Custom token store (default: in-memory Map)
+     */
+    store?: SSETokenStore;
+    /**
+     * Cleanup interval in milliseconds
+     * @default 60000
+     */
+    cleanupInterval?: number;
+}
+declare class SSETokenManager {
+    private store;
+    private ttl;
+    private cleanupTimer;
+    constructor(config?: SSETokenManagerConfig);
+    /**
+     * Issue a new one-time-use token for the given subject
+     */
+    issue(subject: string): Promise<string>;
+    /**
+     * Verify and consume a token
+     * @returns subject string if valid, null if invalid/expired/already consumed
+     */
+    verify(token: string): Promise<string | null>;
+    /**
+     * Cleanup timer and resources
+     */
+    destroy(): void;
+}
+
+/**
+ * SSE Types
+ *
+ * Type definitions for Server-Sent Events
+ */
+
+/**
+ * SSE message sent from server
+ */
+interface SSEMessage<TEvent extends string = string, TPayload = unknown> {
+    /** Event name */
+    event: TEvent;
+    /** Event payload */
+    data: TPayload;
+    /** Optional message ID for reconnection */
+    id?: string;
+}
+/**
+ * SSE auth configuration (internal, non-generic)
+ *
+ * Stored in SSEHandlerConfig. Generic user-facing version is SSEAuthConfig.
+ */
+interface SSEHandlerAuthConfig {
+    /**
+     * Enable SSE token authentication
+     * @default false
+     */
+    enabled?: boolean;
+    /**
+     * Token TTL in milliseconds
+     * @default 30000
+     */
+    tokenTtl?: number;
+    /**
+     * Custom token store (e.g., Redis for multi-instance)
+     */
+    store?: SSETokenStore;
+    /**
+     * Extract subject (user ID) from Hono context
+     * @default (c) => c.get('auth')?.userId ?? null
+     */
+    getSubject?: (c: Context) => string | null;
+    /**
+     * Subscription authorization hook (called once on connect)
+     *
+     * Return allowed events subset. Empty array = 403 rejection.
+     */
+    authorize?: (subject: string, events: string[]) => Promise<string[]> | string[];
+    /**
+     * Per-event payload filter map (called on every event emission)
+     *
+     * Return false to skip sending the event to this user.
+     */
+    filter?: Record<string, (subject: string, payload: unknown) => boolean>;
+}
+/**
+ * SSE auth configuration (user-facing, generic)
+ *
+ * Provides type-safe event names and payload inference from EventRouter.
+ *
+ * @example
+ * ```typescript
+ * .events(eventRouter, {
+ *     auth: {
+ *         enabled: true,
+ *         authorize: async (subject, events) => {
+ *             // events: ('userCreated' | 'orderUpdated')[]
+ *             return events.filter(e => hasPermission(subject, e));
+ *         },
+ *         filter: {
+ *             orderUpdated: (subject, payload) => {
+ *                 // payload: { orderId: string; userId: string }
+ *                 return payload.userId === subject;
+ *             },
+ *         },
+ *     },
+ * })
+ * ```
+ */
+interface SSEAuthConfig<TRouter extends EventRouterDef<any>> {
+    enabled?: boolean;
+    tokenTtl?: number;
+    store?: SSETokenStore;
+    getSubject?: (c: Context) => string | null;
+    authorize?: (subject: string, events: InferEventNames<TRouter>[]) => Promise<InferEventNames<TRouter>[]> | InferEventNames<TRouter>[];
+    filter?: {
+        [K in InferEventNames<TRouter>]?: (subject: string, payload: InferEventPayload<TRouter, K>) => boolean;
+    };
+}
+/**
+ * SSE Handler configuration
+ */
+interface SSEHandlerConfig {
+    /**
+     * Keep-alive ping interval in milliseconds
+     * @default 30000
+     */
+    pingInterval?: number;
+    /**
+     * Custom headers for SSE response
+     */
+    headers?: Record<string, string>;
+    /**
+     * Authentication and authorization configuration
+     */
+    auth?: SSEHandlerAuthConfig;
+}
+/**
+ * SSE Client configuration
+ */
+interface SSEClientConfig {
+    /**
+     * Backend API host URL
+     * @default NEXT_PUBLIC_SPFN_API_URL || 'http://localhost:8790'
+     * @example 'http://localhost:8790'
+     * @example 'https://api.example.com'
+     */
+    host?: string;
+    /**
+     * SSE endpoint pathname
+     * @default '/events/stream'
+     */
+    pathname?: string;
+    /**
+     * Full URL (overrides host + pathname)
+     * @deprecated Use host and pathname instead
+     * @example 'http://localhost:8790/events/stream'
+     */
+    url?: string;
+    /**
+     * Auto reconnect on disconnect
+     * @default true
+     */
+    reconnect?: boolean;
+    /**
+     * Reconnect delay in milliseconds
+     * @default 3000
+     */
+    reconnectDelay?: number;
+    /**
+     * Maximum reconnect attempts (0 = infinite)
+     * @default 0
+     */
+    maxReconnectAttempts?: number;
+    /**
+     * Include credentials (cookies) in request
+     * @default false
+     */
+    withCredentials?: boolean;
+    /**
+     * Acquire a one-time SSE token before connecting.
+     *
+     * Called on every (re)connect. The returned token is appended
+     * to the SSE URL as `?token=...`.
+     *
+     * @example
+     * ```typescript
+     * acquireToken: async () => {
+     *     const res = await fetch('/api/events/token', {
+     *         method: 'POST',
+     *         credentials: 'include',
+     *     });
+     *     const data = await res.json();
+     *     return data.token;
+     * }
+     * ```
+     */
+    acquireToken?: () => Promise<string>;
+}
+/**
+ * Event handler function
+ */
+type SSEEventHandler<TPayload> = (payload: TPayload) => void;
+/**
+ * Event handlers map for EventRouter
+ */
+type SSEEventHandlers<TRouter extends EventRouterDef<any>> = {
+    [K in InferEventNames<TRouter>]?: SSEEventHandler<InferEventPayload<TRouter, K>>;
+};
+/**
+ * Subscription options
+ */
+interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
+    /**
+     * Events to subscribe
+     */
+    events: InferEventNames<TRouter>[];
+    /**
+     * Event handlers
+     */
+    handlers: SSEEventHandlers<TRouter>;
+    /**
+     * Called when connection opens
+     */
+    onOpen?: () => void;
+    /**
+     * Called on connection error
+     */
+    onError?: (error: Event) => void;
+    /**
+     * Called when reconnecting
+     */
+    onReconnect?: (attempt: number) => void;
+}
+/**
+ * SSE connection state
+ */
+type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
+/**
+ * Unsubscribe function
+ */
+type SSEUnsubscribe = () => void;
+
+export { type SSEHandlerConfig as S, type SSEAuthConfig as a, SSETokenManager as b, type SSEToken as c, type SSETokenStore as d, type SSETokenManagerConfig as e, type SSEMessage as f, type SSEHandlerAuthConfig as g, type SSEClientConfig as h, type SSEEventHandler as i, type SSEEventHandlers as j, type SSESubscribeOptions as k, type SSEConnectionState as l, type SSEUnsubscribe as m };

package/docs/event.md

@@ -99,6 +99,64 @@ export default defineServerConfig()
 })
 ```
 
+## SSE Authentication
+
+Browser `EventSource` API does not support custom headers. SPFN uses a **Token Exchange** pattern:
+
+1. Client sends `POST /events/token` with Bearer JWT
+2. Server returns a one-time token (30s TTL)
+3. Client connects to `GET /events/stream?token=...&events=...`
+
+```typescript
+// server.config.ts
+import { defineServerConfig } from '@spfn/core/server';
+import { authenticate } from '@spfn/auth/server';
+
+export default defineServerConfig()
+    .middlewares([authenticate])
+    .routes(appRouter)
+    .events(eventRouter, {
+        auth: { enabled: true },  // This is all you need
+    })
+    .build();
+// → POST /events/token (protected by authenticate middleware)
+// → GET /events/stream?token=...&events=... (token verified)
+```
+
+### Authorization Hooks
+
+#### `authorize` — Subscription Authorization (once on connect)
+
+```typescript
+.events(eventRouter, {
+    auth: {
+        enabled: true,
+        authorize: async (subject, events) =>
+        {
+            // events: ('userCreated' | 'orderPlaced')[] — type inferred
+            const user = await usersRepository.findById(subject);
+            if (user.role === 'admin') return events;
+            return events.filter(e => !e.startsWith('admin.'));
+        },
+    },
+})
+```
+
+#### `filter` — Payload Filtering (on every event emission)
+
+```typescript
+.events(eventRouter, {
+    auth: {
+        enabled: true,
+        filter: {
+            // payload type inferred per-event — no casting needed
+            orderPlaced: (subject, payload) => payload.userId === subject,
+            // userCreated: no filter → sent to all authenticated users
+        },
+    },
+})
+```
+
 ## Browser Client
 
 ```typescript
@@ -135,6 +193,24 @@ const unsubscribe = client.subscribe({
 unsubscribe();
 ```
 
+### With Authentication
+
+```typescript
+const client = createSSEClient<EventRouter>({
+    acquireToken: async () =>
+    {
+        const res = await fetch('/api/events/token', {
+            method: 'POST',
+            credentials: 'include',
+        });
+        const data = await res.json();
+        return data.token;
+    },
+});
+```
+
+`acquireToken` is called on every (re)connect — one-time tokens are handled automatically.
+
 ## Simple Subscribe Helper
 
 ```typescript
@@ -267,6 +343,18 @@ await userCreated.emit({ userId: '123' });
 | `reconnectDelay` | number | `3000` | Reconnect delay (ms) |
 | `maxReconnectAttempts` | number | `0` | Max attempts (0 = infinite) |
 | `withCredentials` | boolean | `false` | Include cookies |
+| `acquireToken` | () => Promise\<string\> | - | Acquire one-time SSE token before connecting |
+
+### SSE Auth Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `false` | Enable token authentication |
+| `tokenTtl` | number | `30000` | Token TTL in milliseconds |
+| `store` | SSETokenStore | InMemory | Custom token store (e.g., Redis) |
+| `getSubject` | (c) => string \| null | `c.get('auth')?.userId` | Extract subject from context |
+| `authorize` | (subject, events) => events[] | - | Subscription authorization hook |
+| `filter` | { [event]: (subject, payload) => boolean } | - | Per-event payload filter |
 
 ## Event Flow Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spfn/core",
-  "version": "0.2.0-beta.12",
+  "version": "0.2.0-beta.13",
   "description": "SPFN Framework Core - File-based routing, transactions, repository pattern",
   "type": "module",
   "exports": {

package/dist/types-B-e_f2dQ.d.ts

@@ -1,121 +0,0 @@
-import { E as EventRouterDef, I as InferEventNames, b as InferEventPayload } from './router-Di7ENoah.js';
-
-/**
- * SSE Types
- *
- * Type definitions for Server-Sent Events
- */
-
-/**
- * SSE message sent from server
- */
-interface SSEMessage<TEvent extends string = string, TPayload = unknown> {
-    /** Event name */
-    event: TEvent;
-    /** Event payload */
-    data: TPayload;
-    /** Optional message ID for reconnection */
-    id?: string;
-}
-/**
- * SSE Handler configuration
- */
-interface SSEHandlerConfig {
-    /**
-     * Keep-alive ping interval in milliseconds
-     * @default 30000
-     */
-    pingInterval?: number;
-    /**
-     * Custom headers for SSE response
-     */
-    headers?: Record<string, string>;
-}
-/**
- * SSE Client configuration
- */
-interface SSEClientConfig {
-    /**
-     * Backend API host URL
-     * @default NEXT_PUBLIC_SPFN_API_URL || 'http://localhost:8790'
-     * @example 'http://localhost:8790'
-     * @example 'https://api.example.com'
-     */
-    host?: string;
-    /**
-     * SSE endpoint pathname
-     * @default '/events/stream'
-     */
-    pathname?: string;
-    /**
-     * Full URL (overrides host + pathname)
-     * @deprecated Use host and pathname instead
-     * @example 'http://localhost:8790/events/stream'
-     */
-    url?: string;
-    /**
-     * Auto reconnect on disconnect
-     * @default true
-     */
-    reconnect?: boolean;
-    /**
-     * Reconnect delay in milliseconds
-     * @default 3000
-     */
-    reconnectDelay?: number;
-    /**
-     * Maximum reconnect attempts (0 = infinite)
-     * @default 0
-     */
-    maxReconnectAttempts?: number;
-    /**
-     * Include credentials (cookies) in request
-     * @default false
-     */
-    withCredentials?: boolean;
-}
-/**
- * Event handler function
- */
-type SSEEventHandler<TPayload> = (payload: TPayload) => void;
-/**
- * Event handlers map for EventRouter
- */
-type SSEEventHandlers<TRouter extends EventRouterDef<any>> = {
-    [K in InferEventNames<TRouter>]?: SSEEventHandler<InferEventPayload<TRouter, K>>;
-};
-/**
- * Subscription options
- */
-interface SSESubscribeOptions<TRouter extends EventRouterDef<any>> {
-    /**
-     * Events to subscribe
-     */
-    events: InferEventNames<TRouter>[];
-    /**
-     * Event handlers
-     */
-    handlers: SSEEventHandlers<TRouter>;
-    /**
-     * Called when connection opens
-     */
-    onOpen?: () => void;
-    /**
-     * Called on connection error
-     */
-    onError?: (error: Event) => void;
-    /**
-     * Called when reconnecting
-     */
-    onReconnect?: (attempt: number) => void;
-}
-/**
- * SSE connection state
- */
-type SSEConnectionState = 'connecting' | 'open' | 'closed' | 'error';
-/**
- * Unsubscribe function
- */
-type SSEUnsubscribe = () => void;
-
-export type { SSEHandlerConfig as S, SSEMessage as a, SSEClientConfig as b, SSEEventHandler as c, SSEEventHandlers as d, SSESubscribeOptions as e, SSEConnectionState as f, SSEUnsubscribe as g };