@jengolabs/auth-server-sdk

Server-side SDK for Jengo Auth — session verification, middleware for Hono and NestJS, and typed session data.

Installation

npm install @jengolabs/auth-server-sdk

Quick start

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

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

npm install @jengolabs/auth-server-sdk @nestjs/common

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:

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

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

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