@i-dot-ai-npm/utilities-auth

Auth utilities for i-dot-ai applications. Provides a thin client for the I.AI Auth API plus a small set of helpers for authenticating users and translating Auth API errors.

Installation

npm install @i-dot-ai-npm/utilities-auth

Usage

AuthApiClient

A typed wrapper around the I.AI Auth API. Construct it with your application name and the Auth API base URL; a logger and request timeout (ms) are optional.

import { AuthApiClient } from '@i-dot-ai-npm/utilities-auth';

const client = new AuthApiClient({
  appName: 'my-app',
  authApiUrl: 'https://auth.example.gov.uk',
  // logger,        // optional; defaults to `console`
  // timeout: 5000, // optional; defaults to 5000ms
});

// Exchanges a user's auth token for their authorisation result.
const result = await client.getUserAuthorisationInfo(userAuthToken);
// result: { email: string; isAuthorised: boolean; authReason: AuthReason }

createAuthUtils

Higher-level helpers that bundle common auth flows. Pass an AuthApiClient instance and, optionally, a logger.

import { createAuthUtils, AuthApiRequestError } from '@i-dot-ai-npm/utilities-auth';

const auth = createAuthUtils(client /*, logger */);

try {
  // Returns true/false based on the Auth API decision.
  const allowed = await auth.isAuthorisedUser(userAuthToken);

  // Or retrieve the full result (email, isAuthorised, authReason).
  const info = await auth.getUserInfo(userAuthToken);

  // On a framework response object (e.g. Express), send a standard 401.
  if (!info.isAuthorised) {
    auth.handleUnauthorisedResponse(res, info);
  }
} catch (err) {
  if (err instanceof AuthApiRequestError) {
    // surface a typed error to the caller
  }
}

See src/types.ts and src/authReason.ts for the full type surface.

Version Bumping

This package is released independently via the reusable modular-release.yml workflow in i-dot-ai-core-github-actions (invoked from this repo's .github/workflows/release.yml). Releases use semantic-release with conventional commits scoped to auth:

• feat(auth): ... → Minor version bump
• fix(auth): ..., perf(auth): ..., refactor(auth): ... → Patch version bump
• feat(auth)!: ... (or BREAKING CHANGE: in body) → Major version bump
• Commits scoped to other modules produce no release for @i-dot-ai-npm/utilities-auth.

Tags are formatted v<semver>-auth.

Development

# From the repo root
pnpm install
pnpm --filter @i-dot-ai-npm/utilities-auth build
pnpm --filter @i-dot-ai-npm/utilities-auth test

License

MIT