@jengolabs/auth-server-sdk 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,134 @@
+# @jengolabs/auth-server-sdk
+
+Server-side SDK for [Jengo Auth](https://github.com/jengolabs/jen-auth) — session verification, middleware for Hono and NestJS, and typed session data.
+
+## Installation
+
+```bash
+npm install @jengolabs/auth-server-sdk
+```
+
+## Quick start
+
+```typescript
+import { AuthClient } from '@jengolabs/auth-server-sdk';
+
+const authClient = new AuthClient({
+  authServerUrl: 'https://auth.yourdomain.com',
+  tenantApiKey: process.env.TENANT_API_KEY,
+  appSlug: 'your-app',
+  cacheTtlMs: 30_000, // optional — cache verified sessions for 30s
+});
+```
+
+## Hono middleware
+
+```typescript
+import { Hono } from 'hono';
+import { createHonoAuthMiddleware, requireAppRole } from '@jengolabs/auth-server-sdk';
+
+const app = new Hono();
+
+app.use('*', createHonoAuthMiddleware({
+  authClient,
+  publicPaths: ['/health', '/public'],
+}));
+
+// Role-based access
+app.get('/admin', requireAppRole('admin', 'owner'), (c) => {
+  const user = c.get('user');
+  return c.json({ user });
+});
+```
+
+The middleware attaches the following to the Hono context after successful auth:
+
+| Key | Type | Description |
+|---|---|---|
+| `user` | `AuthUser` | Authenticated user |
+| `session` | `AuthSessionData` | Session metadata |
+| `appGrant` | `AuthAppGrant` | App-level role grant |
+| `organization` | `object \| undefined` | Organization membership |
+
+## NestJS guard
+
+```bash
+npm install @jengolabs/auth-server-sdk @nestjs/common
+```
+
+```typescript
+import { Module, APP_GUARD } from '@nestjs/common';
+import { AuthClient } from '@jengolabs/auth-server-sdk';
+import { JengoAuthGuard } from '@jengolabs/auth-server-sdk/nestjs';
+
+const authClient = new AuthClient({ ... });
+
+@Module({
+  providers: [
+    { provide: APP_GUARD, useValue: new JengoAuthGuard(authClient) },
+  ],
+})
+export class AppModule {}
+```
+
+Access session data in controllers:
+
+```typescript
+import { Controller, Get, Req } from '@nestjs/common';
+import { getUser, getSession, getAppGrant } from '@jengolabs/auth-server-sdk/nestjs';
+import type { Request } from 'express';
+
+@Controller('profile')
+export class ProfileController {
+  @Get()
+  profile(@Req() req: Request) {
+    const user = getUser(req);       // AuthUser
+    const grant = getAppGrant(req);  // AuthAppGrant | null
+    return { user, grant };
+  }
+}
+```
+
+## Generic / Express / other frameworks
+
+```typescript
+import { verifyRequest } from '@jengolabs/auth-server-sdk';
+
+// Works with any framework — pass headers directly
+const session = await verifyRequest(authClient, {
+  authorization: req.headers.authorization,
+  cookie: req.headers.cookie,
+});
+```
+
+## AuthClient options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `authServerUrl` | `string` | ✓ | Base URL of your Jengo Auth server |
+| `tenantApiKey` | `string` | ✓ | Tenant API key from the admin dashboard |
+| `appSlug` | `string` | ✓ | Application slug to verify access grants |
+| `cacheTtlMs` | `number` | — | Cache verified sessions (ms). Omit to disable |
+| `timeoutMs` | `number` | — | Request timeout in ms (default: 5000) |
+| `onError` | `(err: Error) => void` | — | Error callback for monitoring |
+
+## Error types
+
+```typescript
+import { AuthenticationError, AuthorizationError } from '@jengolabs/auth-server-sdk';
+
+try {
+  await authClient.verifySession(token);
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    // 401 — invalid or expired session
+  }
+  if (err instanceof AuthorizationError) {
+    // 403 — valid session but insufficient access
+  }
+}
+```
+
+## License
+
+MIT

package/dist/middleware/nestjs.d.ts

@@ -0,0 +1,12 @@
+import type { CanActivate, ExecutionContext } from "@nestjs/common";
+import { AuthClient } from "../client";
+import type { AuthSessionWithGrant, AuthUser, AuthAppGrant } from "../types";
+export declare class JengoAuthGuard implements CanActivate {
+    private readonly authClient;
+    constructor(authClient: AuthClient);
+    canActivate(context: ExecutionContext): Promise<boolean>;
+}
+export declare function getSession(request: object): AuthSessionWithGrant;
+export declare function getUser(request: object): AuthUser;
+export declare function getAppGrant(request: object): AuthAppGrant | null;
+//# sourceMappingURL=nestjs.d.ts.map

package/dist/middleware/nestjs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestjs.d.ts","sourceRoot":"","sources":["../../src/middleware/nestjs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAyB7E,qBAAa,cAAe,YAAW,WAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,UAAU;IAE7C,WAAW,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;CAyB/D;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,oBAAoB,CAEhE;AAED,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAEjD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAEhE"}

package/dist/middleware/nestjs.js

@@ -0,0 +1,59 @@
+import { AuthenticationError, AuthorizationError } from "../errors";
+const SESSION_KEY = "jengoSession";
+function throwHttp(status, message) {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const nestjs = require("@nestjs/common");
+        if (status === 401)
+            throw new nestjs.UnauthorizedException(message);
+        throw new nestjs.ForbiddenException(message);
+    }
+    catch (err) {
+        if (err.code === "MODULE_NOT_FOUND") {
+            const fallback = new Error(message);
+            Object.assign(fallback, { statusCode: status });
+            throw fallback;
+        }
+        throw err;
+    }
+}
+export class JengoAuthGuard {
+    authClient;
+    constructor(authClient) {
+        this.authClient = authClient;
+    }
+    async canActivate(context) {
+        const request = context.switchToHttp().getRequest();
+        const authHeader = request.headers["authorization"];
+        const cookieHeader = request.headers["cookie"];
+        const credential = authHeader ?? cookieHeader ?? null;
+        if (!credential) {
+            throwHttp(401, "Authentication required");
+        }
+        try {
+            const session = await this.authClient.verifySession(credential);
+            if (!session.appGrant) {
+                throwHttp(403, "Access denied for this application");
+            }
+            request[SESSION_KEY] = session;
+            return true;
+        }
+        catch (error) {
+            if (error instanceof AuthorizationError)
+                throwHttp(403, error.message);
+            if (error instanceof AuthenticationError)
+                throwHttp(401, error.message);
+            throw error;
+        }
+    }
+}
+export function getSession(request) {
+    return request[SESSION_KEY];
+}
+export function getUser(request) {
+    return getSession(request).user;
+}
+export function getAppGrant(request) {
+    return getSession(request).appGrant;
+}
+//# sourceMappingURL=nestjs.js.map

package/dist/middleware/nestjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nestjs.js","sourceRoot":"","sources":["../../src/middleware/nestjs.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAGpE,MAAM,WAAW,GAAG,cAAc,CAAC;AAOnC,SAAS,SAAS,CAAC,MAAiB,EAAE,OAAe;IACnD,IAAI,CAAC;QACH,iEAAiE;QACjE,MAAM,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;QACzC,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM,IAAI,MAAM,CAAC,qBAAqB,CAAC,OAAO,CAAC,CAAC;QACpE,MAAM,IAAI,MAAM,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAK,GAA6B,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAC/D,MAAM,QAAQ,GAAG,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;YACpC,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;YAChD,MAAM,QAAQ,CAAC;QACjB,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,MAAM,OAAO,cAAc;IACI;IAA7B,YAA6B,UAAsB;QAAtB,eAAU,GAAV,UAAU,CAAY;IAAG,CAAC;IAEvD,KAAK,CAAC,WAAW,CAAC,OAAyB;QACzC,MAAM,OAAO,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,UAAU,EAAe,CAAC;QACjE,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC;QACpD,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/C,MAAM,UAAU,GAAG,UAAU,IAAI,YAAY,IAAI,IAAI,CAAC;QAEtD,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,SAAS,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;YAEhE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;gBACtB,SAAS,CAAC,GAAG,EAAE,oCAAoC,CAAC,CAAC;YACvD,CAAC;YAED,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC;YAC/B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,kBAAkB;gBAAE,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACvE,IAAI,KAAK,YAAY,mBAAmB;gBAAE,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YACxE,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,OAAQ,OAAmC,CAAC,WAAW,CAAyB,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,UAAU,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC;AACtC,CAAC"}

package/package.json

@@ -1,25 +1,43 @@
 {
   "name": "@jengolabs/auth-server-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Server-side SDK for Jengo Auth — AuthClient, Hono/Express middleware, typed session verification",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./nestjs": {
+      "types": "./dist/middleware/nestjs.d.ts",
+      "default": "./dist/middleware/nestjs.js"
+    }
+  },
   "files": [
-    "dist/**/*"
+    "dist/**/*",
+    "README.md"
   ],
   "dependencies": {
     "hono": "^4.7.8"
   },
   "devDependencies": {
     "typescript": "^5.8.3",
-    "@types/node": "^22.15.21"
+    "@types/node": "^22.15.21",
+    "@nestjs/common": "^10.0.0",
+    "reflect-metadata": "^0.1.13",
+    "vitest": "^3.1.1"
   },
   "peerDependencies": {
-    "hono": ">=4.0.0"
+    "hono": ">=4.0.0",
+    "@nestjs/common": ">=9.0.0"
   },
   "peerDependenciesMeta": {
     "hono": {
       "optional": true
+    },
+    "@nestjs/common": {
+      "optional": true
     }
   },
   "license": "MIT",
@@ -31,6 +49,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "clean": "rm -rf dist"
   }
 }