@drmhse/authos-node 0.1.3 → 0.1.4

package/README.md

@@ -192,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.3",
+  "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.8"
+    "@drmhse/sso-sdk": "^0.3.10"
   },
   "devDependencies": {
     "@types/express": "^5.0.0",