nuxt-authorization

To add the module to your Nuxt application, use the following command:

npx nuxi module add nuxt-authorization

An authorizer function can return several types of responses to indicate authorization status:

1. boolean: A simple true (authorized) or false (unauthorized).
2. AuthorizationResponse: An object providing more context, such as a custom statusCode and message to be returned when authorization fails.
3. Promise<boolean | AuthorizationResponse>: An asynchronous version of the above, allowing for database lookups or external API calls during authorization checks.

export type AuthorizationResponse = {
  statusCode?: number
  message?: string
  authorized: boolean
}

export type AuthorizerResponse
  = | boolean
    | AuthorizationResponse
    | Promise<boolean | AuthorizationResponse>

The module provides three primary functions to check permissions. On the server, you must pass the event as the first argument.

// --- Client Side ---

// Check if user can perform action (returns boolean)
if (await allows(listPosts)) { /* ... */ }

// Check if user cannot perform action (returns boolean)
if (await denies(editPost, post)) { /* ... */ }

// Throw error if user cannot perform action
await authorize(editPost, post)


// --- Server Side ---

// Check if user can perform action (requires event)
if (await allows(event, listPosts)) { /* ... */ }

// Check if user cannot perform action (requires event)
if (await denies(event, editPost, post)) { /* ... */ }

// Throw error if user cannot perform action (requires event)
await authorize(event, editPost, post)

Use authorize to enforce permissions. If the user does not have the required ability, this function will throw a Nuxt error. This is useful for protecting client-side logic or component lifecycle hooks where an unauthorized state should halt execution.

If the underlying authorization check fails with an AuthorizationError, authorize catches it and re-throws it using Nuxt's createError utility, preserving the original statusCode and message.

// Example: Enforcing permission before executing a sensitive action
try {
  await authorize('user:delete', userId);
  // If we reach here, the user is authorized
  await performDelete(userId);
} catch (err) {
  // err will be a Nuxt error with the appropriate statusCode
  console.error('Unauthorized:', err.message);
}

Use allows and denies within Nuxt server routes (H3 events) to perform non-blocking permission checks. These functions resolve the current server user from event.context.$authorization and return a boolean based on the provided ability and arguments.

• allows(event, ability, ...args): Returns true if the user is permitted, false otherwise.
• denies(event, ability, ...args): Returns true if the user is forbidden, false otherwise.

// Example usage in a server route
export default defineEventHandler(async (event) => {
  const canEdit = await allows(event, 'edit_post', postId);
  
  if (!canEdit) {
    throw createError({ statusCode: 403, statusMessage: 'Forbidden' });
  }
  
  // Proceed with logic...
});

Use authorize to enforce a permission check. If the user does not have the required ability, this function will throw a Nuxt-compatible error using createError.

If the underlying authorization logic fails with an AuthorizationError, authorize catches it and re-throws it as a standard Nuxt error, preserving the original statusCode and message. This is the preferred method for protecting server routes where unauthorized access should immediately halt execution.

// Example usage in a server route
export default defineEventHandler(async (event) => {
  // This will throw a 403 (or appropriate status) if the user is not authorized
  await authorize(event, 'delete_user', userId);

  // If we reach here, the user is authorized
  await performDelete(userId);
});

The normalizeAuthorizationResponse utility converts different result types into a consistent AuthorizationResponse object. It accepts either a simple boolean or a full AuthorizationResponse object, ensuring the output always follows the { authorized: boolean, message?: string, statusCode?: number } shape.

// If input is boolean:
// normalizeAuthorizationResponse(true) -> { authorized: true }

// If input is object:
// normalizeAuthorizationResponse({ authorized: false, message: 'No access' }) -> { authorized: false, message: 'No access' }

Use allows and denies to perform non-blocking permission checks in your client-side Nuxt application. These functions resolve the current client user automatically and return a boolean indicating whether the user has the specified ability with the provided arguments.

• allows(ability, ...args): Returns true if the user is permitted to perform the action.
• denies(ability, ...args): Returns true if the user is explicitly forbidden from performing the action.

// Example: Checking if a user can edit a specific post
const canEdit = await allows('post:edit', postId);
if (canEdit) {
  // Proceed with logic
}

// Example: Checking if a user is denied access
const isDenied = await denies('admin:access');

Use allows to verify if a user has permission to perform an action, returning a boolean. Use denies to verify the inverse (returning true if the user is unauthorized). Both functions execute the provided ability and normalize the response.

• allows(ability, user, ...args): Returns true if authorized, false otherwise.
• denies(ability, user, ...args): Returns true if unauthorized, false otherwise.

// Example usage of allows and denies
const canEdit = await allows(editPostAbility, currentUser, postId);
const isForbidden = await denies(adminOnlyAbility, currentUser);