@olane/o-server 0.8.3 → 0.8.5

package/README.md

@@ -7,7 +7,7 @@ HTTP server entrypoint for Olane OS nodes. Exposes a node's `use` functionality
 ## Installation
 
 ```bash
-npm install @olane/o-server
+pnpm install @olane/o-server
 ```
 
 ## Quick Start
@@ -219,11 +219,19 @@ const server = oServer({
     credentials: true
   },
   
-  // Optional: Authentication middleware
-  authenticate: async (req) => {
-    const token = req.headers.authorization;
-    return validateToken(token);
+  // Optional: JWT authentication (recommended)
+  jwtAuth: {
+    method: 'secret',
+    secret: 'your-jwt-secret',
+    issuer: 'https://auth.example.com',
+    audience: 'https://api.example.com'
   },
+
+  // DEPRECATED: Use jwtAuth instead. Will be removed in a future version.
+  // authenticate: async (req) => {
+  //   const token = req.headers.authorization;
+  //   return validateToken(token);
+  // },
   
   // Optional: Enable debug logging (default: false)
   debug: true
@@ -232,28 +240,71 @@ const server = oServer({
 await server.start();
 ```
 
-### Authentication
+### JWT Authentication (Recommended)
+
+Protect your endpoints with built-in JWT verification. All routes except `/health` require a valid token when `jwtAuth` is configured.
+
+**RS256 with public key:**
+```typescript
+const server = oServer({
+  node: myNode,
+  port: 3000,
+  jwtAuth: {
+    method: 'publicKey',
+    publicKeyPath: '/path/to/public-key.pem',
+    issuer: 'https://auth.example.com',
+    audience: 'https://api.example.com',
+    algorithms: ['RS256']
+  }
+});
+```
+
+**HS256 with shared secret:**
+```typescript
+const server = oServer({
+  node: myNode,
+  port: 3000,
+  jwtAuth: {
+    method: 'secret',
+    secret: process.env.JWT_SECRET!,
+    clockTolerance: 5  // seconds of tolerance for exp/nbf
+  }
+});
+```
+
+**`jwtAuth` configuration options:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `method` | `'publicKey' \| 'secret'` | Yes | Verification method |
+| `publicKeyPath` | `string` | If `method='publicKey'` | Path to PEM public key file |
+| `secret` | `string` | If `method='secret'` | Shared secret for HS256 |
+| `issuer` | `string` | No | Expected `iss` claim |
+| `audience` | `string` | No | Expected `aud` claim |
+| `algorithms` | `Algorithm[]` | No | Allowed algorithms (defaults based on method) |
+| `clockTolerance` | `number` | No | Seconds of clock tolerance (default: 0) |
 
-Protect your endpoints with authentication:
+### Legacy Authentication (Deprecated)
+
+> **Deprecated**: The `authenticate` option is deprecated and will be removed in a future version. Migrate to `jwtAuth` instead.
 
 ```typescript
+// @deprecated - use jwtAuth instead
 const server = oServer({
   node: myNode,
   port: 3000,
+  // @deprecated - use jwtAuth instead
   authenticate: async (req) => {
-    // Validate JWT token
     const token = req.headers.authorization?.split(' ')[1];
-    
+
     if (!token) {
       throw new Error('No token provided');
     }
-    
+
     const user = await verifyJWT(token);
     return { userId: user.id, roles: user.roles };
   }
 });
-
-// Now all requests require valid authentication
 ```
 
 ### CORS Configuration
@@ -323,6 +374,8 @@ await server.start();
 
 ```typescript
 // frontend/src/api.ts
+// Note: HTTP responses from o-server use the flat { success, data, error } format.
+// This is different from internal node.use() calls which return response.result.success.
 export async function analyzeRevenue(startDate: string, endDate: string) {
   const response = await fetch('http://localhost:3000/api/v1/use', {
     method: 'POST',
@@ -333,8 +386,13 @@ export async function analyzeRevenue(startDate: string, endDate: string) {
       params: { startDate, endDate }
     })
   });
-  
+
   const result = await response.json();
+
+  if (!result.success) {
+    throw new Error(result.error?.message || 'Request failed');
+  }
+
   return result.data;
 }
 ```
@@ -349,11 +407,10 @@ import { oServer } from '@olane/o-server';
 const server = oServer({
   node: myNode,
   port: 8080,
-  authenticate: async (req) => {
-    // Validate Firebase auth token
-    const token = req.headers.authorization?.split(' ')[1];
-    const decodedToken = await admin.auth().verifyIdToken(token);
-    return { userId: decodedToken.uid };
+  jwtAuth: {
+    method: 'secret',
+    secret: process.env.JWT_SECRET!,
+    issuer: 'https://your-firebase-project.firebaseapp.com'
   }
 });
 
@@ -373,17 +430,22 @@ const server = oServer({ node: myNode, port: 3000 });
 // Stripe webhook
 server.app.post('/webhooks/stripe', async (req, res) => {
   const event = req.body;
-  
-  // Process via your node
-  await myNode.use(
+
+  // Process via your node (internal call uses response.result pattern)
+  const response = await myNode.use(
     new oAddress('o://payments/processor'),
     {
       method: 'handle_payment',
       params: { event }
     }
   );
-  
-  res.json({ received: true });
+
+  if (!response.result.success) {
+    res.status(500).json({ error: response.result.error });
+    return;
+  }
+
+  res.json({ received: true, data: response.result.data });
 });
 
 await server.start();
@@ -420,18 +482,20 @@ await server.start();
 //   -d '{"address": "o://any/node/in/network", "method": "...", "params": {...}}'
 ```
 
-## Error Handling
+## Response Structure
 
-`o-server` provides consistent error responses:
+### HTTP Response (from o-server)
 
-```typescript
-// Success response
+`o-server` flattens the internal node response into a simple HTTP-friendly format:
+
+```json
+// Success response (HTTP)
 {
   "success": true,
   "data": { ... }
 }
 
-// Error response
+// Error response (HTTP)
 {
   "success": false,
   "error": {
@@ -442,6 +506,38 @@ await server.start();
 }
 ```
 
+### Internal Node Response (from node.use())
+
+Within the Olane node ecosystem, `node.use()` returns a JSON-RPC wrapped response. When calling nodes programmatically (not via HTTP), always access data through the `result` property:
+
+```typescript
+const response = await node.use(address, { method: 'my_method', params: {} });
+
+// Access the response correctly:
+if (response.result.success) {
+  const data = response.result.data;    // Your method's return value
+} else {
+  const error = response.result.error;  // Error message string
+}
+
+// Full internal response shape:
+// {
+//   jsonrpc: "2.0",
+//   id: "request-id",
+//   result: {
+//     success: boolean,
+//     data: any,          // Present on success
+//     error?: string      // Present on failure
+//   }
+// }
+```
+
+> **Important**: The `o-server` translates the internal `response.result.success` / `response.result.data` / `response.result.error` structure into the flat HTTP `{ success, data }` / `{ success, error }` format. When writing code that runs inside the node ecosystem (not behind o-server), always use `response.result.success`, `response.result.data`, and `response.result.error`.
+
+## Error Handling
+
+`o-server` provides consistent error responses:
+
 **Common error codes:**
 - `INVALID_PARAMS` - Missing or invalid request parameters
 - `NODE_NOT_FOUND` - Target node address not found
@@ -540,8 +636,9 @@ const config: ServerConfig = {
   cors: {
     origin: 'https://example.com'
   },
-  authenticate: async (req) => {
-    return { userId: '123' };
+  jwtAuth: {
+    method: 'secret',
+    secret: process.env.JWT_SECRET!,
   },
   debug: true
 };
@@ -568,13 +665,15 @@ LOG_LEVEL=info
 # Dockerfile
 FROM node:20-alpine
 
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
 WORKDIR /app
 
-COPY package*.json ./
-RUN npm ci --only=production
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --prod
 
 COPY . .
-RUN npm run build
+RUN pnpm run build
 
 EXPOSE 8080
 
@@ -686,13 +785,13 @@ Complete examples:
 const server = oServer({ node: myNode, port: 3000 });
 await server.start();
 
-// With authentication
+// With JWT authentication
 const server = oServer({
   node: myNode,
   port: 3000,
-  authenticate: async (req) => {
-    const token = req.headers.authorization;
-    return await validateJWT(token);
+  jwtAuth: {
+    method: 'secret',
+    secret: process.env.JWT_SECRET!,
   }
 });
 

package/dist/src/o-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"o-server.d.ts","sourceRoot":"","sources":["../../src/o-server.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,cAAc,EACf,MAAM,yCAAyC,CAAC;AAiBjD,wBAAgB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAgR5D"}
+{"version":3,"file":"o-server.d.ts","sourceRoot":"","sources":["../../src/o-server.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,YAAY,EACZ,cAAc,EACf,MAAM,yCAAyC,CAAC;AAiBjD,wBAAgB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc,CAoW5D"}

package/dist/src/o-server.js

@@ -4,13 +4,57 @@ import { errorHandler } from './middleware/error-handler.js';
 import { authMiddleware } from './middleware/auth.js';
 import { createJwtMiddleware } from './middleware/jwt-auth.js';
 import { ServerLogger } from './utils/logger.js';
-import { oAddress } from '@olane/o-core';
+import { oAddress, oRequestContext } from '@olane/o-core';
 import { validateAddress, validateMethod, sanitizeParams, validateRequest, useRequestSchema, streamRequestSchema, } from './validation/index.js';
 export function oServer(config) {
     const { node, port = 3000, basePath = '/api/v1', cors: corsConfig, authenticate, jwtAuth, debug = false, } = config;
     const app = express();
     const logger = new ServerLogger(debug);
     let server = null;
+    /**
+     * Build auth context from a JWT-verified Express request.
+     * Returns undefined if no JWT is present (e.g. JWT auth is disabled).
+     */
+    function buildAuthFromRequest(req) {
+        if (!req.jwt)
+            return undefined;
+        // Extract raw token from Authorization header
+        const authHeader = req.headers.authorization;
+        const token = authHeader?.startsWith('Bearer ')
+            ? authHeader.slice(7)
+            : '';
+        return {
+            token,
+            claims: req.jwt,
+        };
+    }
+    /**
+     * Remove any client-injected _auth from params (anti-spoofing).
+     * Server-verified auth is injected separately.
+     */
+    function stripClientAuth(params) {
+        if (!params || typeof params !== 'object')
+            return params;
+        const { _auth, ...rest } = params;
+        return rest;
+    }
+    /**
+     * Deep-strip _auth from response data before sending to HTTP client.
+     * Prevents leaking tokens in response payloads.
+     */
+    function stripAuthFromResponse(obj) {
+        if (obj === null || obj === undefined || typeof obj !== 'object')
+            return obj;
+        if (Array.isArray(obj))
+            return obj.map(stripAuthFromResponse);
+        const result = {};
+        for (const key of Object.keys(obj)) {
+            if (key === '_auth')
+                continue;
+            result[key] = stripAuthFromResponse(obj[key]);
+        }
+        return result;
+    }
     // Middleware
     app.use(express.json());
     if (corsConfig) {
@@ -53,18 +97,25 @@ export function oServer(config) {
             validateAddress(addressStr);
             // Validate method
             validateMethod(method);
+            // Strip client-injected _auth before sanitization (anti-spoofing)
+            const strippedParams = stripClientAuth(params);
             // Sanitize params
-            const sanitizedParams = sanitizeParams(params);
+            const sanitizedParams = sanitizeParams(strippedParams);
+            // Build server-verified auth from JWT
+            const auth = buildAuthFromRequest(req);
+            // Inject _auth into params if JWT is present
+            const finalParams = auth
+                ? { ...sanitizedParams, _auth: auth }
+                : sanitizedParams;
             logger.debugLog(`Calling use with address ${addressStr}, method: ${method}`);
             const address = new oAddress(addressStr);
-            const result = await node.use(address, {
-                method,
-                params: sanitizedParams,
-                id,
-            });
+            // Wrap in request context for AsyncLocalStorage propagation
+            const result = await (auth
+                ? oRequestContext.run({ auth }, () => node.use(address, { method, params: finalParams, id }))
+                : node.use(address, { method, params: finalParams, id }));
             const response = {
                 success: true,
-                data: result.result,
+                data: stripAuthFromResponse(result.result),
             };
             res.json(response);
         }
@@ -84,17 +135,25 @@ export function oServer(config) {
             validateAddress(addressStr);
             // Validate method
             validateMethod(method);
+            // Strip client-injected _auth before sanitization (anti-spoofing)
+            const strippedParams = stripClientAuth(params);
             // Sanitize params
-            const sanitizedParams = sanitizeParams(params);
+            const sanitizedParams = sanitizeParams(strippedParams);
+            // Build server-verified auth from JWT
+            const auth = buildAuthFromRequest(req);
+            // Inject _auth into params if JWT is present
+            const finalParams = auth
+                ? { ...sanitizedParams, _auth: auth }
+                : sanitizedParams;
             logger.debugLog(`Calling method ${method} on ${addressParam} with params:`, sanitizedParams);
             const address = new oAddress(addressStr);
-            const result = await node.use(address, {
-                method,
-                params: sanitizedParams,
-            });
+            // Wrap in request context for AsyncLocalStorage propagation
+            const result = await (auth
+                ? oRequestContext.run({ auth }, () => node.use(address, { method, params: finalParams }))
+                : node.use(address, { method, params: finalParams }));
             const response = {
                 success: true,
-                data: result.result,
+                data: stripAuthFromResponse(result.result),
             };
             res.json(response);
         }
@@ -112,8 +171,16 @@ export function oServer(config) {
             validateAddress(addressStr);
             // Validate method
             validateMethod(method);
+            // Strip client-injected _auth before sanitization (anti-spoofing)
+            const strippedParams = stripClientAuth(params);
             // Sanitize params
-            const sanitizedParams = sanitizeParams(params);
+            const sanitizedParams = sanitizeParams(strippedParams);
+            // Build server-verified auth from JWT
+            const auth = buildAuthFromRequest(req);
+            // Inject _auth into params if JWT is present
+            const finalParams = auth
+                ? { ...sanitizedParams, _auth: auth }
+                : sanitizedParams;
             logger.debugLog(`Streaming use call to ${addressStr}, method: ${method}`);
             // Set headers for Server-Sent Events
             res.setHeader('Content-Type', 'text/event-stream');
@@ -123,13 +190,12 @@ export function oServer(config) {
             try {
                 // TODO: Implement actual streaming support when available
                 // For now, execute and return result
-                const result = await node.use(address, {
-                    method,
-                    params: sanitizedParams,
-                });
+                const result = await (auth
+                    ? oRequestContext.run({ auth }, () => node.use(address, { method, params: finalParams }))
+                    : node.use(address, { method, params: finalParams }));
                 res.write(`data: ${JSON.stringify({
                     type: 'complete',
-                    result: result.result,
+                    result: stripAuthFromResponse(result.result),
                 })}\n\n`);
                 res.end();
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olane/o-server",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -61,7 +61,7 @@
     "typescript": "5.4.5"
   },
   "dependencies": {
-    "@olane/o-core": "0.8.3",
+    "@olane/o-core": "0.8.5",
     "cors": "^2.8.5",
     "debug": "^4.4.1",
     "dotenv": "^16.5.0",
@@ -69,5 +69,5 @@
     "jsonwebtoken": "^9.0.3",
     "zod": "^3.25.76"
   },
-  "gitHead": "189c0cf7b6dd9d5d961f5424af21d37978092d9e"
+  "gitHead": "e88f1e55dcc92d9a410d28200e4220697116f82f"
 }