noesis-auth

library0.1.3jsnpmunverified

TypeScript Auth SDK for AI tool integration with the Noesis AIToolCenter platform. Current stable version is 0.1.3, released on npm. The SDK provides JWT validation with RS256 (JWKS) and HS256, OAuth2 PKCE flows, token introspection, refresh, and activation code redemption. Key differentiators: zero runtime dependencies beyond jose, Express middleware for drop-in auth, configurable timeouts, and automatic JWKS retry. Designed specifically for AI tool ecosystems where token payloads include entitlements and tool access.

security

npm install noesis-auth

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NOESIS-AUTH

noesis-auth

securityjavascriptv0.1.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

JWTValidator

✓ import { JWTValidator } from 'noesis-auth'

✗ const JWTValidator = require('noesis-auth').JWTValidator

ESM-only package; CommonJS require works with destructuring but named export is preferred.

createAuthMiddleware

✓ import { createAuthMiddleware } from 'noesis-auth'

Factory function returning middleware object with requireAuth() and requireToolAccess() methods.

AuthClient

✓ import { AuthClient } from 'noesis-auth'

✗ const AuthClient = require('noesis-auth').AuthClient

Constructor takes base URL and optional timeout (ms).

AuthError

✓ import { AuthError } from 'noesis-auth'

Error class with code property. All HTTP errors throw this.

type TokenPayload

✓ import type { TokenPayload } from 'noesis-auth'

TypeScript type for decoded JWT payload (sub, entitlements, etc.). Import only when using TypeScript.

Validates a JWT and sets up Express middleware for tool access authorization.

import { JWTValidator } from 'noesis-auth'; import { createAuthMiddleware } from 'noesis-auth'; // Validate a JWT token const validator = new JWTValidator('https://your-platform.com/.well-known/jwks.json'); const payload = await validator.validate(token); console.log(payload.sub, payload.entitlements); // Express middleware setup const auth = createAuthMiddleware({ jwksUrl: 'https://your-platform.com/.well-known/jwks.json' }); app.get('/api/generate', auth.requireToolAccess('your-tool-id'), (req, res) => { const payload = req.auth; res.json({ user: payload.sub }); });

Debug

Known issues

gotchaHS256 is only used when the token's JWT header explicitly declares alg: HS256. The SDK will NOT silently fall back to HS256 if JWKS is unavailable. If you want to support both, you must provide hs256Secret and ensure tokens are properly configured.

fix

Always check token header for alg. Provide hs256Secret only if you intend to support symmetric JWT validation.

affects: >=0.0.0

gotchaThe AuthClient constructor timeout parameter defaults to 10000ms (10 seconds). If your platform's endpoints are slow, you may encounter premature timeouts. The timeout is enforced via AbortController.

fix

Pass a higher timeout value (e.g., 30000) to the AuthClient constructor: new AuthClient(url, 30000).

affects: >=0.0.0

gotchaThe requireToolAccess middleware expects the toolId parameter as a string or number. If you pass undefined or null, it may throw or behave unexpectedly.

fix

Always provide a valid toolId: app.get(..., auth.requireToolAccess('tool-123'), ...)

affects: >=0.0.0

gotchaThe token payload is attached as req.auth (typed as TokenPayload). TypeScript users must cast (req as any).auth or augment the Express Request type.

fix

Declare module augmentation: declare module 'express-serve-static-core' { interface Request { auth: TokenPayload } }

affects: >=0.0.0

gotchaActivation code redemption may return a new JWT (new_access_token) if token_refresh_required is true. You must store and use this new token for subsequent requests.

fix

Check result.token_refresh_required and update your stored access token with result.new_access_token.

affects: >=0.0.0

Errors

Common errors & fixes

Error: Cannot find module 'jose'

jose is a peer dependency but was not installed.

fix

Run `npm install jose` or ensure your package manager installs peer deps.

TypeError: validator.validate is not a function

Importing JWTValidator incorrectly (e.g., default import instead of named).

fix

Import as named: `import { JWTValidator } from 'noesis-auth'`

AuthError: Token is expired

JWT token has expired and cannot be used.

fix

Refresh the token using the refreshToken method on AuthClient.

AuthError: JWKS fetch failed after 3 retries

The JWKS endpoint is unreachable or returning invalid data.

fix

Check the JWKS URL is correct and accessible. Ensure the server is online.

Upgrade

Version history

0.1.3latest on npm

Audit

Dependencies

joserequiredJWT validation and JWKS fetching

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Noesis-AI-Technologies/AIToolCenter ↗

packagenoesis-auth ↗

homepagehttps://github.com/Noesis-AI-Technologies/AIToolCenter/blob/main/docs/auth-sdk-guide.md ↗