@auditauth/node 0.2.0-beta.1

package/README.md

@@ -0,0 +1,135 @@
+# @auditauth/node
+
+`@auditauth/node` is the AuditAuth SDK for Node.js backends. It verifies
+AuditAuth access tokens with the AuditAuth public key and validates issuer and
+audience claims for your application.
+
+## Install
+
+Install the package in your Node.js service.
+
+```bash
+npm install @auditauth/node
+```
+
+## Verify a bearer token
+
+Use `verifyAccessToken()` when you already have a raw JWT string.
+
+```ts
+import { verifyAccessToken } from '@auditauth/node'
+
+const payload = await verifyAccessToken({
+  token: accessToken,
+  appId: process.env.AUDITAUTH_APP_ID!,
+})
+
+console.log(payload.sub)
+console.log(payload.email)
+```
+
+The SDK validates:
+
+- Signature (`RS256`)
+- Issuer (`iss`) against AuditAuth settings
+- Audience (`aud`) against the `appId` you pass
+
+## Verify an incoming HTTP request
+
+Use `verifyRequest()` to extract and validate the `Authorization` header in one
+step.
+
+```ts
+import { verifyRequest } from '@auditauth/node'
+
+export async function handler(request: Request) {
+  const session = await verifyRequest({
+    request,
+    appId: process.env.AUDITAUTH_APP_ID!,
+  })
+
+  return Response.json({
+    userId: session.sub,
+    email: session.email,
+  })
+}
+```
+
+`verifyRequest()` accepts these request shapes:
+
+- `Request`
+- `{ headers: Headers }`
+- `{ headers: Record<string, string> }`
+
+This makes it compatible with native Fetch handlers and common Node.js server
+adapters.
+
+## Express middleware example
+
+Use `verifyRequest()` in middleware to protect private routes.
+
+```ts
+import express from 'express'
+import { verifyRequest } from '@auditauth/node'
+
+const app = express()
+
+app.get('/private', async (req, res) => {
+  try {
+    const session = await verifyRequest({
+      request: { headers: req.headers as Record<string, string> },
+      appId: process.env.AUDITAUTH_APP_ID!,
+    })
+
+    res.json({ accountId: session.account_id, email: session.email })
+  } catch {
+    res.status(401).json({ error: 'Unauthorized' })
+  }
+})
+```
+
+## Token payload type
+
+The SDK returns `AuditAuthTokenPayload`, which extends `JWTPayload` and
+includes these AuditAuth claims:
+
+- `sub: string`
+- `email: string`
+- `aud: string`
+- `account_id: string`
+- `app_id: string`
+
+## API reference
+
+Exports from `@auditauth/node`:
+
+- `verifyAccessToken(input): Promise<AuditAuthTokenPayload>`
+- `verifyRequest(input): Promise<AuditAuthTokenPayload>`
+- `AuditAuthTokenPayload` (type)
+- `VerifyAccessTokenPayload` (type)
+- `VerifyRequestParams` (type)
+
+## Errors
+
+Verification throws an error when:
+
+- The token is missing.
+- The `Authorization` header is missing or not `Bearer <token>`.
+- The JWT signature is invalid.
+- `iss` or `aud` claims do not match expected values.
+
+Handle these errors in your framework and return `401 Unauthorized` for failed
+authentication.
+
+## Compatibility
+
+This package requires Node.js `>=18.18.0`.
+
+## Resources
+
+- Repository: https://github.com/nimibyte/auditauth-sdk
+- Documentation: https://docs.auditauth.com
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { AuditAuthTokenPayload } from './types';
+type VerifyAccessTokenPayload = {
+    token: string;
+    appId: string;
+};
+declare const verifyAccessToken: ({ token, appId }: VerifyAccessTokenPayload) => Promise<AuditAuthTokenPayload>;
+type VerifyRequestParams = {
+    request: Request | {
+        headers: Headers;
+    } | {
+        headers: Record<string, string>;
+    };
+    appId: string;
+};
+declare const verifyRequest: ({ request, appId }: VerifyRequestParams) => Promise<AuditAuthTokenPayload>;
+export { verifyAccessToken, verifyRequest };
+export type { VerifyRequestParams, VerifyAccessTokenPayload, AuditAuthTokenPayload };

package/dist/index.js

@@ -0,0 +1,27 @@
+import { importSPKI, jwtVerify } from 'jose';
+import { CORE_SETTINGS } from '@auditauth/core';
+let cachedKey = null;
+const verifyAccessToken = async ({ token, appId }) => {
+    if (!token) {
+        throw new Error('Missing token');
+    }
+    if (!cachedKey) {
+        cachedKey = await importSPKI(CORE_SETTINGS.jwt_public_key, 'RS256');
+    }
+    const { payload } = await jwtVerify(token, cachedKey, {
+        issuer: CORE_SETTINGS.jwt_issuer,
+        audience: appId,
+    });
+    return payload;
+};
+const verifyRequest = async ({ request, appId }) => {
+    const authHeader = request.headers instanceof Headers
+        ? request.headers.get('authorization')
+        : request.headers['authorization'] || request.headers['Authorization'];
+    if (!authHeader || !authHeader?.startsWith('Bearer ')) {
+        throw new Error('Missing or invalid Authorization header');
+    }
+    const token = authHeader.replace('Bearer ', '').trim();
+    return verifyAccessToken({ token, appId });
+};
+export { verifyAccessToken, verifyRequest };

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+import { JWTPayload } from "jose";
+type AuditAuthTokenPayload = JWTPayload & {
+    sub: string;
+    email: string;
+    aud: string;
+    account_id: string;
+    app_id: string;
+};
+export type { AuditAuthTokenPayload };

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@auditauth/node",
+  "version": "0.2.0-beta.1",
+  "description": "AuditAuth Node SDK - JWT verification",
+  "license": "MIT",
+  "author": "Nimibyte",
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nimibyte/auditauth-sdk.git"
+  },
+  "homepage": "https://docs.auditauth.com",
+  "bugs": {
+    "url": "https://github.com/nimibyte/auditauth-sdk/issues"
+  },
+  "keywords": [
+    "authentication",
+    "auth",
+    "oauth",
+    "identity",
+    "jwt",
+    "security",
+    "auditauth"
+  ],
+  "module": "dist/index.js",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "jose": "^5.2.0",
+    "@auditauth/core": "^0.2.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "typescript": "^5.4.0"
+  }
+}