Errors and transport mapping

The security guards report failures using framework-neutral errors. This package does not convert them into HTTP responses or message acknowledgements, because the correct representation depends on the transport and application.

Error types

Error	When it is thrown	Useful fields
AuthenticationError	A secured target has no successful authentication result.	response, options.cause, options.description
AuthorizationError	One or more policies denied a secured target.	response, causes, options.cause, options.description
SecurityError	Base class for security errors; useful for catching both categories.	response, status, options

AuthorizationError.causes contains each policy's decision. Denials include their reason, which can help create audit logs or diagnostics. Decide carefully whether internal reasons should be returned to external callers; applications can log the detailed cause while returning a generic response.

SecurityError.status is a package category value (1 for authentication and 2 for authorization). It is not an HTTP status code. Use the concrete error type or its name to map errors to transport semantics.

HTTP error filter example

import { Catch, ExecutionTransport, Filter, FilteredError, StepPriority } from '@axisparkjs/engine';
import { HttpResults } from '@axisparkjs/http';
import { AuthenticationError, SecurityError } from '@axisparkjs/security';

@Filter({ global: true, transport: ExecutionTransport.Http, priority: StepPriority.Critical })
export class SecurityErrorHttpFilter {
    @Catch(SecurityError)
    map(@FilteredError() error: SecurityError) {
        return error instanceof AuthenticationError
            ? HttpResults.Unauthorized(error.response, error.options)
            : HttpResults.Forbidden(error.response, error.options);
    }
}

This example maps unauthenticated calls to 401 and policy denials to 403. Register an equivalent error handler for each transport the application uses. The complete implementation is in the feel-secured sample.