Skip to content

@venturekit/auth

Installation

npm install @venturekit/auth@dev

What It Provides

Cognito Configuration

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

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

Role-Based Access Control

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

getScopesForRoles(['member'], rolesConfig);  // → ['users.read', 'users.write']
hasScope(['admin'], 'admin.users', config);  // → true

JWT / Session Utilities

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

// Unsafe decoder — use only when the token has already been verified
// upstream (e.g. API Gateway Cognito Authorizer). The `Unsafe` suffix is
// deliberate so reviewers can spot authentication bypasses.
const claims  = decodeTokenUnsafe(jwt);
const user    = extractUserFromToken(jwt);
const expired = isTokenExpired(jwt);

// Signature-verifying decoder for paths that haven't been gated upstream
// (cookie-based sessions, background jobs, internal HTTP callers, etc.).
const verified = await verifyAndDecode(jwt, {
  userPoolId: 'eu-west-1_xxxxx',
  clientId: process.env.COGNITO_APP_CLIENT_ID,
  tokenUse: 'access',
});

decodeToken is exported as a deprecated alias of decodeTokenUnsafe for backward compatibility — prefer the explicit name in new code.

Types

User, Session, Role, Permission — auth domain types
RolesConfig — role definitions
UserPoolOutputs, UserPoolInfraConfig — Cognito infrastructure types

Dependencies

@venturekit/core — required

Authentication Guide — setup walkthrough
Handlers — scope-based auth in handlers
API Reference — full type documentation