@drmhse/authos-node 0.1.2 → 0.1.4

package/README.md

@@ -44,22 +44,25 @@ console.log(verified.claims);
 
 ### TypeScript Integration
 
-To get type support for `req.auth` in Express, you can extend the Request interface or use our utility type:
+The `req.auth` type is automatically augmented when you import from `@drmhse/authos-node/express`. No manual setup required!
 
 ```ts
-import { Request } from 'express';
-import { TokenClaims } from '@drmhse/authos-node';
-
-// Extend Express Request
-declare global {
-  namespace Express {
-    interface Request {
-      auth?: {
-        claims: TokenClaims;
-        token: string;
-      };
-    }
-  }
+import { createAuthMiddleware } from '@drmhse/authos-node/express';
+
+// TypeScript knows about req.auth automatically
+app.get('/profile', requireAuth(), (req, res) => {
+  const userId = req.auth?.claims.sub;  // ✓ Typed correctly
+  res.json({ userId });
+});
+```
+
+If you need access to the token claims type directly:
+
+```ts
+import { TokenClaims, VerifiedToken } from '@drmhse/authos-node';
+
+function processUser(auth: VerifiedToken) {
+  console.log(auth.claims.email);
 }
 ```
 
@@ -189,6 +192,44 @@ app.get('/org/:slug/data',
 );
 ```
 
+## Understanding JWT Context
+
+The middleware functions check claims embedded in the JWT by the client SDK during login:
+
+| SDK Initialization | JWT Claims | Middleware to Use |
+|-------------------|-----------|------------------|
+| Platform-level (`baseURL` only) | `is_platform_owner: true` | `requirePlatformOwner()` |
+| Multi-tenant (`baseURL` + `org` + `service`) | `org: 'slug'` | `requireOrganization()` |
+| With permissions | `permissions: ['users:write', ...]` | `requirePermission()` |
+
+### How It Works
+
+1. **Client-side**: User logs in via `@drmhse/sso-sdk` or `@drmhse/authos-react`
+2. **JWT issued**: AuthOS embeds context (`org`, `service`, `is_platform_owner`) in claims
+3. **Server-side**: This package verifies the JWT and middleware checks the claims
+
+```ts
+// Example: Route for organization admins only
+app.get('/org/:slug/settings',
+  requireAuth(),                                    // 1. Verify JWT signature
+  requireOrganization((req) => req.params.slug),   // 2. Check org claim matches URL
+  (req, res) => {
+    // User is authenticated AND belongs to this org
+    res.json({ org: req.auth?.claims.org });
+  }
+);
+
+// Example: Route for platform owners only
+app.get('/platform/analytics',
+  requireAuth(),           // 1. Verify JWT signature
+  requirePlatformOwner(),  // 2. Check is_platform_owner: true
+  (req, res) => {
+    // User is a platform owner
+    res.json({ data: '...' });
+  }
+);
+```
+
 ## Webhook Verification
 
 Verify webhooks from AuthOS:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drmhse/authos-node",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Node.js server adapter for AuthOS authentication - Express middleware and token verification",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -58,7 +58,7 @@
     }
   },
   "dependencies": {
-    "@drmhse/sso-sdk": "^0.3.3"
+    "@drmhse/sso-sdk": "^0.3.10"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",