@agnostic-cloud/identity

Unified Cloud Identity, JWT & OIDC Token Verification (Data Plane), and User Management & Administration (Control Plane) across AWS Cognito, Google Cloud / Firebase Auth, Microsoft Entra ID (Azure AD), Okta, and Generic OIDC providers.

Features

• 🚀 Sub-Millisecond Token Verification: Zero cloud SDK dependencies for runtime token verification, powered by the lightweight jose standard library and WebCrypto.
• ⚡ In-Memory JWKS Key Caching: Automatic key rotation, single-flight request coalescing, and 5-second cooldown throttling to protect against cache thrashing/DoS.
• 👥 Full User Management (identity.admin): Agnostic user creation, profile updates, password resets, suspension, activation, and directory listing across AWS, GCP, Azure, and Okta.
• 🛡️ Hardened Security (RFC 8725): Immune to alg: none, Asymmetric-to-Symmetric Key Confusion, jku/x5u injection, multi-tenant issuer spoofing, and claim prototype pollution.
• 🌐 Universal HTTP Middleware: First-class support for Node.js HTTP (IncomingMessage), Web API (Request), Express, Next.js, and Cloudflare Workers.
• 🔄 Zero-Code-Change Cloud Migration: Switch identity providers seamlessly by simply modifying the configuration.

Installation

npm install @agnostic-cloud/identity

Quick Start

1. Data Plane: Token Verification & HTTP Authentication

import { createIdentity } from '@agnostic-cloud/identity'

// Initialize identity strategy (AWS Cognito example)
const identity = createIdentity({
  cloud: 'aws',
  userPoolId: 'us-east-1_example123',
  region: 'us-east-1',
  clientId: 'my-app-client-id',
})

// Verify raw JWT string
const user = await identity.verifyToken(token)
console.log('User:', user.id, user.email, user.roles)

// Authenticate incoming HTTP request
export async function GET(request: Request) {
  const user = await identity.authenticateRequest(request, {
    requiredRoles: ['admin'],
  })
  return Response.json({ message: `Hello ${user.displayName || user.email}` })
}

2. Control Plane: User Administration (identity.admin)

// Create a new user
const newUser = await identity.admin.createUser({
  email: '[email protected]',
  password: 'StrongPassword123!',
  displayName: 'Dev User',
  roles: ['engineer', 'operator'],
})

// Look up user
const user = await identity.admin.getUserByEmail('[email protected]')

// Update password
await identity.admin.updateUserPassword(user.id, 'NewStrongPassword456!')

// Suspend / Disable account
await identity.admin.disableUser(user.id)

// Delete account
await identity.admin.deleteUser(user.id)

Providers Configuration

AWS Cognito

const identity = createIdentity({
  cloud: 'aws',
  userPoolId: 'us-east-1_xyz123',
  region: 'us-east-1',
  clientId: 'app-client-id',
  adminConfig: {
    credentials: { accessKeyId: '...', secretAccessKey: '...' },
  },
})

Google Cloud / Firebase Auth

const identity = createIdentity({
  cloud: 'gcp',
  projectId: 'my-firebase-project',
  flavor: 'firebase', // or 'google-oidc'
  adminConfig: {
    apiKey: '...', // or bearerToken
  },
})

Microsoft Entra ID (Azure AD)

const identity = createIdentity({
  cloud: 'azure',
  tenantId: '00000000-0000-0000-0000-000000000000', // or 'common' for multi-tenant
  clientId: 'api://my-api-audience',
  adminConfig: {
    bearerToken: '...',
  },
})

Okta

const identity = createIdentity({
  cloud: 'okta',
  domain: 'dev-12345.okta.com',
  audience: 'api://default',
  adminConfig: {
    apiToken: '...',
  },
})

Error Handling

All errors extend CloudError:

import {
  TokenExpiredError,
  UnauthorizedError,
  UserAlreadyExistsError,
  UserNotFoundError,
} from '@agnostic-cloud/identity'

try {
  await identity.admin.createUser({ email: '[email protected]', password: '...' })
} catch (err) {
  if (err instanceof UserAlreadyExistsError) {
    console.error('Email already registered')
  }
}

License

MIT