@axowl/sdk-backend

Axowl SDK for Node.js backends — JWT verification, Express middleware, and Next.js helpers.

Install

npm install @axowl/sdk-backend

Express

Setup middleware

import express from 'express';
import { axowlMiddleware, requirePermission } from '@axowl/sdk-backend';

const app = express();

// Verify JWT on all routes
app.use(axowlMiddleware({
  orgSlug: 'my-org',
  apiKey: 'ah_live_xxxxx',
}));

// Access user info in routes
app.get('/api/me', (req, res) => {
  const { userId, email, permissions, orgSlug } = req.axowl;
  res.json({ userId, email, orgSlug });
});

// Require specific permissions
app.get('/api/reports', requirePermission('report.view'), (req, res) => {
  res.json({ reports: [] });
});

// Require multiple permissions
app.post('/api/reports/export', requirePermission('report.view', 'report.export'), (req, res) => {
  res.json({ download: '...' });
});

req.axowl object

interface AxowlRequestContext {
  token: DecodedToken;    // Full decoded JWT payload
  userId: string;         // User ID (sub claim)
  email?: string;         // User email
  orgSlug?: string;       // Organization slug
  connectedId?: string;   // Organization membership ID
  permissions: string[];  // Permission scopes
  raw: string;            // Raw JWT string
}

Next.js

App Router (Route Handlers)

import { NextRequest, NextResponse } from 'next/server';
import { getAuth, canAccess } from '@axowl/sdk-backend/next';

export async function GET(request: NextRequest) {
  const auth = getAuth(request);

  if (!auth) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  if (!canAccess(auth, 'dashboard.view')) {
    return NextResponse.json({ error: 'Forbidden' }, { status: 403 });
  }

  return NextResponse.json({
    userId: auth.userId,
    email: auth.email,
  });
}

Middleware (Edge)

// middleware.ts
import { NextRequest, NextResponse } from 'next/server';
import { getAuth } from '@axowl/sdk-backend/next';

export function middleware(request: NextRequest) {
  const auth = getAuth(request);

  if (!auth && request.nextUrl.pathname.startsWith('/api/')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next();
}

export const config = {
  matcher: '/api/:path*',
};

Standalone Token Verification

import { verifyToken, extractBearerToken } from '@axowl/sdk-backend';

// From Authorization header
const token = extractBearerToken('Bearer eyJhbGci...');

if (token) {
  const context = verifyToken(token);
  console.log(context.userId);
  console.log(context.permissions);
}

Permission Utilities

import { hasPermission, hasAllPermissions, hasAnyPermission } from '@axowl/sdk-backend';

const permissions = ['dashboard.*', 'report.view'];

hasPermission(permissions, 'dashboard.edit');       // true (wildcard match)
hasAllPermissions(permissions, ['dashboard.view', 'report.view']); // true
hasAnyPermission(permissions, ['billing.view', 'report.view']);    // true

TypeScript

Add type support for req.axowl:

import type { AxowlRequest } from '@axowl/sdk-backend';

app.get('/api/me', (req, res) => {
  const { userId, email } = (req as AxowlRequest).axowl;
  res.json({ userId, email });
});

API Reference

| Export | Type | Description | |---|---|---| | axowlMiddleware(config) | Express middleware | Validates JWT, attaches req.axowl | | requirePermission(...scopes) | Express middleware | Checks permissions (403 if denied) | | getAuth(request) | Function | Extract auth from Next.js request | | canAccess(auth, scope) | Function | Check permission on auth context | | verifyToken(token) | Function | Decode and validate JWT | | extractBearerToken(header) | Function | Extract token from Bearer ... header |

License

MIT