nuxt-bearer-auth 0.1.6 → 0.1.8

package/README.md

@@ -21,6 +21,10 @@ Reusable Nuxt authentication for APIs that issue bearer tokens. It is designed f
 - Session revocation
 - SSR auth hydration
 - Global route middleware
+- Optional authorization with abilities normalization (disabled by default)
+- Route/page authorization via `definePageMeta` metadata (`all` / `any` modes)
+- Declarative `<Can>` / `<Cannot>` UI authorization components (advisory rendering only)
+- Server-side `requireAbility()` guard via the `nuxt-bearer-auth/server` export
 - `useBearerAuth()` composable
 - `useAuth()` alias for convenience
 
@@ -180,8 +184,145 @@ Available composable state and methods:
 - `forgotPassword`
 - `resetPassword`
 - `resendOtp`
+- `abilities`
+- `can(ability)`
+- `cannot(ability)`
 - `clearAuthState`
 
+## Authorization
+
+Authorization is opt-in and disabled by default. Backend roles, permissions, and direct abilities are normalized into a sorted `string[]`. Roles use the `role:` prefix by default.
+
+```ts
+export default defineNuxtConfig({
+  bearerAuth: {
+    authorization: {
+      enabled: true,
+      source: "session",
+      responsePaths: {
+        abilities: ["abilities", "data.abilities"],
+        roles: ["roles", "data.roles"],
+        permissions: ["permissions", "data.permissions"],
+      },
+      rolePrefix: "role:",
+    },
+    redirects: {
+      unauthorized: "/auth/not-allowed",
+    },
+  },
+});
+```
+
+```ts
+const auth = useBearerAuth();
+
+await auth.login(credentials);
+auth.can("campaign.create");
+auth.cannot("campaign.delete");
+auth.abilities.value;
+```
+
+Abilities are persisted with the server session and hydrated during SSR. Login, social login, registration, OTP verification, refresh, and `me` responses can update them. An omitted authorization field preserves the current list; logout and failed authentication clear it. Tokens, passwords, OTPs, and raw backend responses are never authorization state.
+
+### Client Checks Are Not Security
+
+`auth.can()` and `auth.cannot()` are advisory UI helpers for showing or hiding controls. They do not secure APIs. A user who bypasses your UI can still call any endpoint directly, so your backend must authorize every request it receives.
+
+### UI Authorization Components
+
+`<Can>` and `<Cannot>` provide the same advisory checks declaratively. Both are auto-imported, evaluate the existing `auth.abilities` state reactively through one shared evaluator, and match route/server semantics exactly (exact strings, `mode` defaults to `"all"`, empty `abilities` means unrestricted, malformed props or state fail closed):
+
+```vue
+<template>
+  <!-- single ability -->
+  <Can ability="users.delete">
+    Delete
+  </Can>
+
+  <!-- every listed ability (default) / at least one -->
+  <Can :abilities="['users.view', 'users.edit']">Edit</Can>
+  <Can :abilities="['reports.view', 'reports.export']" mode="any">
+    Export
+  </Can>
+
+  <!-- inverse rendering -->
+  <Cannot ability="users.delete">
+    <template #fallback>Request access</template>
+  </Cannot>
+</template>
+```
+
+Unauthorized content is removed from the DOM; an optional `#fallback` slot renders instead. Disabled authorization behaves like `auth.can()` — ability state stays `null`, so `<Can>` renders fallback/nothing. SSR output matches hydration because evaluation is synchronous over the transferred state.
+
+As with all client checks: **UI authorization controls rendering only. It never secures API requests. Your backend must authorize every request it receives.**
+
+### Route Authorization
+
+Pages opt in by declaring required abilities in `definePageMeta`. The global `bearer-auth` middleware enforces them when authorization is enabled:
+
+```vue
+<script setup lang="ts">
+definePageMeta({
+  authorization: {
+    abilities: ["users.view"],
+    // optional — defaults to "all"
+    mode: "all",
+  },
+});
+</script>
+```
+
+Semantics:
+
+- `mode` defaults to `"all"`: every listed ability must exist on the session.
+- `mode: "any"`: at least one listed ability must exist.
+- Matching is exact string equality. `users.*`, prefixes, and hierarchy are not supported.
+- Routes without metadata behave exactly as before. When `authorization.enabled` is `false`, metadata is ignored.
+- Unauthenticated visitors follow the normal login flow (`?redirect=` preserved). Authenticated users without the required abilities are redirected to `redirects.unauthorized` — not to login.
+
+Route authorization protects navigation inside your Nuxt app only. It never authorizes external API requests.
+
+### Server Enforcement with requireAbility()
+
+Nitro server routes use the dedicated server-only export:
+
+```ts
+import { requireAbility } from "nuxt-bearer-auth/server";
+
+export default defineEventHandler((event) => {
+  const session = requireAbility(event, "users.delete");
+
+  // every ability required (default):
+  requireAbility(event, ["users.view", "users.export"]);
+  // at least one required:
+  requireAbility(event, ["reports.view", "reports.export"], "any");
+
+  return { ok: true };
+});
+```
+
+Behavior:
+
+- Throws `401 Unauthenticated` when there is no authenticated session and `403 Authorization required` when the session lacks the ability.
+- Reads abilities only from `event.context.auth` — the Redis-backed server session. It never reads client state (`useState("bearer-auth-abilities")`), headers, query parameters, or request bodies.
+- On success it sets `event.context.authorization = { abilities, source: "session" }` (normalized strings only, no tokens) and returns the session.
+- Fails closed: if the session has no abilities, every requirement is rejected.
+- The helper lives behind the `nuxt-bearer-auth/server` subpath so it is never bundled into client code.
+
+### Security Boundary
+
+Authorization is layered, and the lower layer is always authoritative:
+
+```text
+UI checks (auth.can)          → convenience only
+Nuxt enforcement (meta/403)   → protects pages and Nuxt routes
+Laravel backend               → authoritative for its own endpoints
+```
+
+`requireAbility(event, "campaign.delete")` stops your Nuxt route from running, but if that route calls `DELETE /campaigns/123`, Laravel must still authorize `campaign.delete`. This package never claims to replace backend authorization.
+
+Declarative `<Can>` / `<Cannot>` components ship with the package — see [UI Authorization Components](#ui-authorization-components). Directives such as `v-can` are intentionally not provided.
+
 ## Redis Sessions
 
 The backend token is stored server-side in Redis. The browser only receives a secure HTTP-only session id cookie. Nuxt server routes can read the hydrated session from:

package/dist/module.d.mts

@@ -1,146 +1,130 @@
-declare const module = defineNuxtModule({
-  meta: {
-    name: "nuxt-bearer-auth",
-    configKey: "bearerAuth",
-    compatibility: {
-      nuxt: "^3.12.0 || ^4.0.0"
-    }
-  },
-  defaults: defaultOptions,
-  async setup(moduleOptions, nuxt) {
-    const resolver = createResolver(import.meta.url);
-    const options = defu(moduleOptions, defaultOptions);
-    nuxt.options.runtimeConfig.bearerAuth = defu(
-      nuxt.options.runtimeConfig.bearerAuth,
-      {
-        apiBaseUrl: options.apiBaseUrl,
-        redisUrl: options.redisUrl,
-        sessionSecret: options.sessionSecret,
-        appEnv: options.appEnv,
-        endpoints: options.endpoints,
-        responsePaths: options.responsePaths,
-        sessionCookie: options.sessionCookie,
-        verificationRequiredActions: options.verificationRequiredActions,
-        twoFactorRequiredActions: options.twoFactorRequiredActions
-      }
-    );
-    nuxt.options.runtimeConfig.public.bearerAuth = defu(
-      nuxt.options.runtimeConfig.public.bearerAuth,
-      {
-        redirects: options.redirects,
-        routes: options.routes
-      }
-    );
-    if (options.installCsurf && options.csrf?.enabled) {
-      await installModule("nuxt-csurf", {
-        https: options.csrf.https,
-        cookieKey: options.appEnv === "local" || options.appEnv === "development" ? options.csrf.devCookieKey : options.csrf.cookieKey,
-        cookie: options.csrf.cookie,
-        methods: options.csrf.methods,
-        methodsToProtect: options.csrf.methodsToProtect,
-        encryptAlgorithm: "aes-256-cbc",
-        addCsrfTokenToEventCtx: true,
-        headerName: options.csrf.headerName
-      });
-      const prefix2 = options.routes?.localApiPrefix || "/api/auth";
-      nuxt.options.routeRules = {
-        ...nuxt.options.routeRules,
-        [`${prefix2}/login`]: { csurf: false, ...nuxt.options.routeRules?.[`${prefix2}/login`] },
-        [`${prefix2}/register`]: { csurf: false, ...nuxt.options.routeRules?.[`${prefix2}/register`] },
-        [`${prefix2}/social-login`]: { csurf: false, ...nuxt.options.routeRules?.[`${prefix2}/social-login`] },
-        [`${prefix2}/forgot-password`]: { csurf: false, ...nuxt.options.routeRules?.[`${prefix2}/forgot-password`] },
-        [`${prefix2}/reset-password`]: { csurf: false, ...nuxt.options.routeRules?.[`${prefix2}/reset-password`] },
-        [`${prefix2}/otp-verification`]: { csurf: false, ...nuxt.options.routeRules?.[`${prefix2}/otp-verification`] },
-        [`${prefix2}/resend-otp/**`]: { csurf: false, ...nuxt.options.routeRules?.[`${prefix2}/resend-otp/**`] },
-        "/api/_csrf": { csurf: false, ...nuxt.options.routeRules?.["/api/_csrf"] }
-      };
-    }
-    addImports([
-      {
-        name: "useBearerAuth",
-        from: resolver.resolve("runtime/composables/useBearerAuth")
-      },
-      {
-        name: "useBearerAuth",
-        as: "useAuth",
-        from: resolver.resolve("runtime/composables/useBearerAuth")
-      }
-    ]);
-    addPlugin(resolver.resolve("runtime/plugins/bearer-auth.server"));
-    if (options.routes?.middleware !== false) {
-      addRouteMiddleware({
-        name: "bearer-auth",
-        path: resolver.resolve("runtime/middleware/bearer-auth.global"),
-        global: true
-      });
-    }
-    addServerPlugin(resolver.resolve("runtime/server/plugins/redis"));
-    addServerHandler({
-      middleware: true,
-      handler: resolver.resolve("runtime/server/middleware/auth")
-    });
-    const prefix = options.routes?.localApiPrefix || "/api/auth";
-    addServerHandler({
-      route: `${prefix}/login`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/login.post")
-    });
-    addServerHandler({
-      route: `${prefix}/social-login`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/social-login.post")
-    });
-    addServerHandler({
-      route: `${prefix}/logout`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/logout.post")
-    });
-    addServerHandler({
-      route: `${prefix}/me`,
-      method: "get",
-      handler: resolver.resolve("runtime/server/api/auth/me.get")
-    });
-    addServerHandler({
-      route: `${prefix}/refresh`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/refresh.post")
-    });
-    addServerHandler({
-      route: `${prefix}/forgot-password`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/forgot-password.post")
-    });
-    addServerHandler({
-      route: `${prefix}/reset-password`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/reset-password.post")
-    });
-    addServerHandler({
-      route: `${prefix}/otp-verification`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/otp-verification.post")
-    });
-    addServerHandler({
-      route: `${prefix}/resend-otp/:identifier`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/resend-otp/[identifier].post")
-    });
-    addServerHandler({
-      route: `${prefix}/register`,
-      method: "post",
-      handler: resolver.resolve("runtime/server/api/auth/register.post")
-    });
-    addServerHandler({
-      route: `${prefix}/sessions`,
-      method: "get",
-      handler: resolver.resolve("runtime/server/api/auth/sessions.get")
-    });
-    addServerHandler({
-      route: `${prefix}/sessions/:id`,
-      method: "delete",
-      handler: resolver.resolve("runtime/server/api/auth/sessions/[id].delete")
-    });
-  }
-});
+import * as _nuxt_schema from '@nuxt/schema';
+export * from '../dist/runtime/types/auth.js';
+
+type SameSite = true | false | "lax" | "strict" | "none";
+interface BearerAuthEndpointOptions {
+    login: string;
+    socialLogin: string;
+    logout: string;
+    me: string;
+    refresh: string;
+    forgotPassword: string;
+    resetPassword: string;
+    verifyOtp: string;
+    resendOtp: string;
+    register: string;
+}
+interface BearerAuthResponsePaths {
+    token: string[];
+    refreshToken: string[];
+    user: string[];
+    userId: string[];
+    message: string[];
+    success: string[];
+    code: string[];
+    nextAction: string[];
+}
+interface BearerAuthRedirectOptions {
+    login: string;
+    authenticated: string;
+    logout: string;
+    unauthorized: string;
+}
+interface BearerAuthRouteOptions {
+    localApiPrefix: string;
+    public: string[];
+    authPages: string[];
+    protectedApiPrefixes: string[];
+    publicApiPrefixes: string[];
+    middleware: boolean;
+}
+interface BearerAuthCookieOptions {
+    name: string;
+    devName: string;
+    maxAge: number;
+    sameSite: SameSite;
+    secure?: boolean;
+    domain?: string;
+    path: string;
+}
+interface BearerAuthCsrfOptions {
+    enabled: boolean;
+    https: boolean;
+    cookieKey: string;
+    devCookieKey: string;
+    headerName: string;
+    methods: string[];
+    methodsToProtect: string[];
+    cookie: {
+        path: string;
+        httpOnly: boolean;
+        sameSite: SameSite;
+        secure?: boolean;
+    };
+}
+type Ability = string;
+type AuthorizationSource = "session" | "endpoint";
+type AuthorizationMatchMode = "all" | "any";
+interface AuthorizationRouteRequirement {
+    abilities: string[];
+    mode?: AuthorizationMatchMode;
+}
+interface AuthorizationResponsePaths {
+    roles?: string[];
+    permissions?: string[];
+    abilities?: string[];
+}
+interface BearerAuthAuthorizationConfig {
+    enabled: boolean;
+    source: AuthorizationSource;
+    endpoint?: string;
+    responsePaths: AuthorizationResponsePaths;
+    rolePrefix: string;
+}
+/**
+ * Shape of the private (server-side) `runtimeConfig.bearerAuth` namespace
+ * populated by the module. Never place functions or secrets beyond what the
+ * server requires here; runtime configuration must stay serializable.
+ */
+interface BearerAuthPrivateRuntimeConfig {
+    apiBaseUrl: string;
+    redisUrl: string;
+    sessionSecret: string;
+    appEnv: string;
+    endpoints: BearerAuthEndpointOptions;
+    responsePaths: BearerAuthResponsePaths;
+    sessionCookie: BearerAuthCookieOptions;
+    authorization: BearerAuthAuthorizationConfig;
+    verificationRequiredActions: string[];
+    twoFactorRequiredActions: string[];
+}
+/**
+ * Shape of the public `runtimeConfig.public.bearerAuth` namespace.
+ * Only serializable, browser-safe values are allowed here.
+ */
+interface BearerAuthPublicRuntimeConfig {
+    redirects: Required<BearerAuthRedirectOptions>;
+    routes: Required<BearerAuthRouteOptions>;
+    authorizationEnabled: boolean;
+}
+interface BearerAuthModuleOptions {
+    apiBaseUrl?: string;
+    redisUrl?: string;
+    sessionSecret?: string;
+    appEnv?: string;
+    installCsurf?: boolean;
+    endpoints?: Partial<BearerAuthEndpointOptions>;
+    responsePaths?: Partial<BearerAuthResponsePaths>;
+    redirects?: Partial<BearerAuthRedirectOptions>;
+    routes?: Partial<BearerAuthRouteOptions>;
+    sessionCookie?: Partial<BearerAuthCookieOptions>;
+    csrf?: Partial<BearerAuthCsrfOptions>;
+    authorization?: Partial<BearerAuthAuthorizationConfig>;
+    verificationRequiredActions?: string[];
+    twoFactorRequiredActions?: string[];
+}
+
+declare const module: _nuxt_schema.NuxtModule<BearerAuthModuleOptions, BearerAuthModuleOptions, false>;
 
 export { module as default };
+export type { Ability, AuthorizationMatchMode, AuthorizationResponsePaths, AuthorizationRouteRequirement, AuthorizationSource, BearerAuthAuthorizationConfig, BearerAuthCookieOptions, BearerAuthCsrfOptions, BearerAuthEndpointOptions, BearerAuthModuleOptions, BearerAuthPrivateRuntimeConfig, BearerAuthPublicRuntimeConfig, BearerAuthRedirectOptions, BearerAuthResponsePaths, BearerAuthRouteOptions, SameSite };