Advanced
API Reference
Complete reference of classes, functions, types, and exports provided by @eienjs/adonisjs-simple-auth.
This page documents all public exports, classes, methods, and TypeScript interfaces exposed by @eienjs/adonisjs-simple-auth.
Package Entrypoints
| Import Path | Exports |
|---|---|
@eienjs/adonisjs-simple-auth | defineConfig, SimpleAuth, SimpleAuthException, configure, stubsRoot |
@eienjs/adonisjs-simple-auth/types | SimpleAuthConfig, ResolvedSimpleAuthConfig |
@eienjs/adonisjs-simple-auth/middleware/simple_auth_middleware | default (SimpleAuthMiddleware) |
@eienjs/adonisjs-simple-auth/providers/simple_auth_provider | default (SimpleAuthProvider) |
@eienjs/adonisjs-simple-auth/plugins/api_client | simpleAuthApiClient |
@eienjs/adonisjs-simple-auth/commands | Ace commands index |
@eienjs/adonisjs-simple-auth/commands/generate_api_key | default (GenerateApiKey) |
defineConfig
Creates a ConfigProvider that resolves SimpleAuthConfig into ResolvedSimpleAuthConfig.
import { defineConfig } from '@eienjs/adonisjs-simple-auth';
function defineConfig(
config: SimpleAuthConfig
): ConfigProvider<ResolvedSimpleAuthConfig>;
Types (@eienjs/adonisjs-simple-auth/types)
import type { Secret } from '@adonisjs/core/helpers';
export interface SimpleAuthConfig {
/**
* HTTP header name to read the API key from.
* @default 'x-api-key'
*/
apiKeyHeader?: string;
/**
* Expected API key value. Strings are automatically wrapped in `Secret`.
*/
apiKeyValue: string | Secret<string>;
}
export interface ResolvedSimpleAuthConfig {
apiKeyHeader: string;
apiKeyValue: Secret<string>;
}
SimpleAuth
Main authentication class attached to HttpContext as ctx.simpleAuth by SimpleAuthMiddleware.
import { SimpleAuth } from '@eienjs/adonisjs-simple-auth';
class SimpleAuth {
constructor(ctx: HttpContext, config: ResolvedSimpleAuthConfig);
/**
* Verifies that the request contains a non-empty API key header
* matching the configured `apiKeyValue` using timing-safe comparison.
* Throws `SimpleAuthException` on failure.
*/
authenticate(): void;
/**
* Creates the `SimpleAuthException` instance thrown on failure.
*/
protected authenticationFailed(): SimpleAuthException;
/**
* Reads and validates the presence of the API key header from `ctx.request`.
*/
protected getApiKeyRequest(): string;
}
HttpContext Augmentation
Importing @eienjs/adonisjs-simple-auth/providers/simple_auth_provider augments @adonisjs/core/http:
declare module '@adonisjs/core/http' {
export interface HttpContext {
simpleAuth: SimpleAuth;
}
}
SimpleAuthException
Exception thrown when authentication fails. Extends Exception from @adonisjs/core/exceptions.
import { SimpleAuthException } from '@eienjs/adonisjs-simple-auth';
class SimpleAuthException extends Exception {
static readonly code = 'E_SIMPLE_UNAUTHORIZED_ACCESS';
static readonly status = 401;
/**
* Translation identifier used with `@adonisjs/i18n`.
* Defaults to `'errors.E_SIMPLE_UNAUTHORIZED_ACCESS'`.
*/
identifier: string;
/**
* Resolves the error message using `ctx.i18n` when available,
* falling back to `error.message`.
*/
getResponseMessage(error: this, ctx: HttpContext): string;
/**
* Sends a 401 response formatted for JSON, HTML, or JSON:API.
*/
handle(error: this, ctx: HttpContext): Promise<void>;
}
SimpleAuthMiddleware
Router middleware that initializes ctx.simpleAuth on incoming HTTP requests.
import SimpleAuthMiddleware from '@eienjs/adonisjs-simple-auth/middleware/simple_auth_middleware';
class SimpleAuthMiddleware {
constructor(config: ResolvedSimpleAuthConfig);
handle(ctx: HttpContext, next: NextFn): Promise<unknown>;
}
SimpleAuthProvider
AdonisJS service provider that registers SimpleAuthMiddleware as a singleton in the IoC container using the resolved config/simpleauth.ts configuration.
import SimpleAuthProvider from '@eienjs/adonisjs-simple-auth/providers/simple_auth_provider';
class SimpleAuthProvider {
constructor(app: ApplicationService);
register(): void;
}
If
config/simpleauth.ts is missing or does not use defineConfig, resolving SimpleAuthMiddleware or running simpleAuthApiClient throws a RuntimeException:
Invalid "config/simpleauth.ts" file. Make sure you are using the "defineConfig" method.simpleAuthApiClient
Japa plugin that adds the .withApiKey() macro to @japa/api-client's ApiRequest.
import { simpleAuthApiClient } from '@eienjs/adonisjs-simple-auth/plugins/api_client';
function simpleAuthApiClient(app: ApplicationService): PluginFn;
Augments @japa/api-client:
declare module '@japa/api-client' {
export interface ApiRequest {
withApiKey: () => this;
}
}