nuxt-authorization

管理应用程序和服务器内部的权限。
10.8K 下载330 星v0.3.5
barbapapazesbarbapapazes

Nuxt 授权

npm versionnpm downloadsLicenseNuxtpkg.pr.new

在 Nuxt 和 Nitro 中轻松处理授权。

此模块不实现 ACL 或 RBAC。它提供低级原语，您可以利用它们来实现自己的授权逻辑。

!注意 将来，此模块可能会作为 Nitro 模块和 Nuxt 模块提供，但 Nitro 模块尚未准备就绪。

要了解有关此模块及其解决的问题的更多信息，请查看我的关于 Nuxt 中的授权 的博客文章。

功能

  • ⛰  在客户端 (Nuxt) 和服务器 (Nitro) 上均可使用
  • 🌟  一次编写能力，随处使用
  • 👨‍👩‍👧‍👦  与身份验证层无关
  • 🫸  使用组件有条件地显示 UI 的一部分
  • 💧  可以访问原语以进行完全自定义

快速设置

通过一个命令将模块安装到您的 Nuxt 应用中

npx nuxi module add nuxt-authorization

就这样！您现在可以在 Nuxt 应用程序中使用该模块了 ✨

文档

!注意 您可以查看 playground 以查看模块的实际运行情况。

设置

在使用模块和定义您的第一个能力之前，您需要提供 2 个解析器。这些函数在内部用于检索用户，但您必须实现它们。这使得模块与身份验证层无关。

对于 Nuxt 应用程序，在 plugins/authorization-resolver.ts 中创建一个新插件

export default defineNuxtPlugin({
  name: 'authorization-resolver',
  parallel: true,
  setup() {
    return {
      provide: {
        authorization: {
          resolveClientUser: () => {
            // Your logic to retrieve the user from the client
          },
        },
      },
    }
  },
})

当您在客户端检查授权时，会调用此函数。它应该返回用户对象，如果用户未通过身份验证，则返回 null。它可以是异步的。

对于 Nitro 服务器，在 server/plugins/authorization-resolver.ts 中创建一个新插件

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', async (event) => {
    event.context.$authorization = {
      resolveServerUser: () => {
        // Your logic to retrieve the user from the server
      },
    }
  })
})

!注意 阅读有关 event.context 的更多信息

此解析器在 request 钩子中设置并接收事件。您可以使用它从会话或请求中检索用户。它应该返回用户对象，如果用户未通过身份验证，则返回 null。它可以是异步的。

通常，您会使用插件在应用程序启动时获取用户，然后存储它。解析器函数应该只返回存储的用户，而不是再次获取（否则，您可能会遇到严重的性能问题）。

使用 nuxt-auth-utils 的示例

模块 nuxt-auth-utils 为 Nuxt 提供了一个身份验证层。如果您使用此模块，您可以使用以下解析器

Nuxt 插件

export default defineNuxtPlugin({
  name: 'authorization-resolver',
  parallel: true,
  setup() {
    return {
      provide: {
        authorization: {
          resolveClientUser: () => useUserSession().user.value,
        },
      },
    }
  },
})

Nitro 插件

export default defineNitroPlugin((nitroApp) => {
  nitroApp.hooks.hook('request', async (event) => {
    event.context.$authorization = {
      resolveServerUser: async () => {
        const session = await getUserSession(event)
        return session.user ?? null
      },
    }
  })
})

简单！

定义能力

!注意 随着 Nuxt 4 的发布，将引入一个新的 shared 目录，以便在客户端和服务器之间轻松共享代码。请参阅 Alexander Lichter 的视频。

现在解析器已设置好，您可以定义您的第一个能力。能力是一个函数，它至少接受用户，并返回一个布尔值以指示用户是否可以执行该操作。它还可以接受额外的参数。

我建议创建一个新文件 shared/utils/abilities.ts 来创建您的能力

export const listPosts = defineAbility(() => true) // Only authenticated users can list posts

export const editPost = defineAbility((user: User, post: Post) => {
  return user.id === post.authorId
})

如果您有很多能力，您可能更喜欢创建一个目录 shared/utils/abilities/ 并为每个能力创建一个文件。将能力放在 shared/utils 目录中允许自动导入在客户端工作，同时在服务器 ~~/shared/utils/abilities 中进行简单的导入。请记住，共享文件夹只导出目录的第一级。因此，您必须在 shared/utils/abilities/index.ts 文件中导出能力。

默认情况下，访客不允许执行任何操作，并且不调用能力。此行为可以按能力更改

export const listPosts = defineAbility({ allowGuest: true }, (user: User | null) => true)

现在，未经验证的用户可以列出帖子。

使用能力

要使用能力，您可以使用 3 个 bouncer 函数：allows、denies 和 authorize。它们在客户端和服务器中都可用。实现不同，但 API（几乎）相同，并且对开发人员完全透明。在服务器上，第一个参数是处理程序中的 event。

如果用户可以执行该操作，则 allows 函数返回一个布尔值

if (await allows(listPosts)) {
  // User can list posts
}

对于服务器

if (await allows(event, listPosts)) {
  // User can list posts
}

如果用户无法执行该操作，则 denies 函数返回一个布尔值

if (await denies(editPost, post)) {
  // User cannot edit the post
}

对于服务器

if (await denies(event, editPost, post)) {
  // User cannot edit the post
}

如果用户无法执行该操作，则 authorize 函数会抛出错误

await authorize(editPost, post)

// User can edit the post

对于服务器

await authorize(event, editPost, post)

您可以根据能力的返回值自定义错误消息和状态码。这对于返回 404 而不是 403 以使用户不知道资源的存在很有用。

export const editPost = defineAbility((user: User, post: Post) => {
  if(user.id === post.authorId) {
    return true // or allow()
  }

  return deny('This post does not exist', 404)
})

allow 和 deny 类似于返回 true 和 false，但 deny 允许为错误返回自定义消息和状态码。

大多数情况下，您的 API 端点将使用 authorize。如果不需要参数，这可以是端点的第一行，或者在数据库查询之后检查用户是否可以访问资源。您无需捕获错误，因为它是 H3Error，并且将被 Nitro 服务器捕获。

allows 和 denies 函数在客户端用于执行条件渲染或逻辑。您还可以使用它们来对授权逻辑进行精细控制。

使用组件

该模块提供了 2 个组件，可帮助您有条件地显示 UI 的一部分。假设您有一个编辑帖子的按钮，未经授权的用户不应该看到该按钮。

<template>
  <Can
    :ability="editPost"
    :args="[post]" // Optional if the ability does not take any arguments
  >
    <button>Edit</button>
  </Can>
</template>

Can 组件只会在用户可以编辑帖子时渲染按钮。如果用户无法编辑帖子，则不会渲染按钮。

作为对应，您可以使用 Cannot 组件只在用户无法编辑帖子时渲染按钮。

<template>
  <Cannot
    :ability="editPost"
    :args="[post]" // Optional if the ability does not take any arguments
  >
    <p>You're not allowed to edit the post.</p>
  </Cannot>
</template>

Bouncer 组件提供了一种更灵活、更集中的方式，可以在单个组件中处理“可以”和“不可以”的场景。您无需使用单独的 Can 和 Cannot 组件，而是可以利用 Bouncer 组件及其 命名插槽 在统一块中处理这两种状态。

<Bouncer
  :ability="editPost"
  :args="[post]" // Optional if the ability does not take any arguments
>
  <template #can>
    <button>Edit</button>
  </template>

  <template #cannot>
    <p>You're not allowed to edit the post.</p>
  </template>
</Bouncer>

所有这些组件都接受一个名为 as 的 prop，用于定义要渲染的 HTML 标签。默认情况下，它是一个无渲染组件。

<Can
  :ability="editPost"
  :args="[post]"
  as="div"
>
  <button>Edit</button>
</Can>

这将渲染

<div>
  <button>Edit</button>
</div>

而不是

<button>Edit</button>

多项能力

如果您拥有多项能力，您可以向组件提供一个能力数组。组件只会在所有能力都符合组件的指定要求时才渲染。

<Can :ability="[editPost, deletePost]" :args="[[post], [post]]" />

<Cannot :ability="[editPost, deletePost]" :args="[[post], [post]]" />

<Bouncer :ability="[editPost, deletePost]" :args="[[post], [post]]">
  <template #can>
    <button>Edit</button>
    <button>Delete</button>
  </template>

  <template #cannot>
    <p>You're not allowed to edit or delete the post.</p>
  </template>
</Bouncer>

贡献

本地开发
# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release

鸣谢

此模块，包括代码和设计，都深受 Adonis Bouncer 的启发。它是一个编写精良的软件包，我认为每次都重新发明轮子是没有必要的。

许可证

麻省理工学院许可证