@venturekit/auth

Warning: This package is in active development and not production-ready. APIs may change without notice.

Authentication and authorization for VentureKit — Cognito integration, RBAC, scope checking, and JWT utilities.

Installation

npm install @venturekit/auth@dev

Overview

@venturekit/auth provides:

• Cognito configuration — createCognitoConfig(), buildUserPoolConfig()
• Role-based access control — define roles, check scopes, validate permissions
• Scope utilities — hasScope(), hasAnyScope(), hasAllScopes(), getScopesForRoles()
• Session/JWT utilities — decodeToken(), extractUserFromToken(), isTokenExpired()

Roles

Define roles that map to OAuth scopes:

import type { RolesConfig } from '@venturekit/auth';

const roles: RolesConfig = {
  roles: [
    { name: 'viewer', description: 'Read only', scopes: ['users.read'] },
    { name: 'member', description: 'Standard user', scopes: ['users.read', 'users.write'] },
    { name: 'admin', description: 'Full access', scopes: ['users.read', 'users.write', 'admin.users'], isSystem: true },
  ],
  defaultRole: 'viewer',
  superAdminRole: 'admin',
};

Scope Checking

import { hasScope, hasAnyScope, hasAllScopes, getScopesForRoles } from '@venturekit/auth';

const allScopes = getScopesForRoles(['member'], rolesConfig);
// → ['users.read', 'users.write']

hasScope(['member'], 'users.write', rolesConfig);    // true
hasAnyScope(['viewer'], ['users.write'], rolesConfig); // false
hasAllScopes(['admin'], ['users.read', 'admin.users'], rolesConfig); // true

JWT Utilities

import { decodeToken, extractUserFromToken, isTokenExpired, getTokenExpiry } from '@venturekit/auth';

const claims = decodeToken(jwt);          // Decode WITHOUT verification
const user = extractUserFromToken(jwt);   // Extract user from ID token
const expired = isTokenExpired(jwt);      // Check exp claim
const expiry = getTokenExpiry(jwt);       // Get expiry as Date

Security: decodeToken does NOT verify the JWT signature. Signature verification should be handled by API Gateway's Cognito Authorizer.

Cognito Configuration

import { createCognitoConfig, buildUserPoolConfig } from '@venturekit/auth';

const cognitoConfig = createCognitoConfig(securityConfig);
const userPoolConfig = buildUserPoolConfig(cognitoConfig);

API Reference

See the API reference for full documentation.

License

Apache-2.0 — see LICENSE for details.