@frigear-nu/authorization 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @frigear-nu/authorization
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Policy-based authorization for the frigear ecosystem, built on [`@frigear-nu/users`](../users). Modelled on
+[nuxt-authorization](https://github.com/barbapapazes/nuxt-authorization): define policies with `defineAbility`, the
+current user is injected by a client/server resolver, and check with `authorize`/`allows`/`denies` or `<Can>`.
+
+- Adds a `role` column (default `'user'`) to the `users` table - generate and commit a migration in your app.
+- Route rules as keys on Nuxt's native `routeRules` (`roles`, `ability`, `guest`, `authenticated`) and per page (`definePageMeta({ authorize })`).
+- Overridable user resolvers (`authorization.resolvers.server` / `.client`).
+
+See the [documentation](../../apps/docs/content/4.modules/11.authorization.md) for usage.

package/dist/module.d.mts

@@ -0,0 +1,58 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { RouteRule, AuthorizeMeta } from '../dist/runtime/utils/types.js';
+export { Ability, AbilityArgs, AuthorizationResponse, AuthorizeMeta, RouteRule } from '../dist/runtime/utils/types.js';
+
+interface ModuleOptions {
+    /**
+     * Path to the file whose exports are the app's abilities (`defineAbility(...)`). Required to refer to
+     * abilities by name in `routes`/`definePageMeta`. Defaults to `shared/utils/abilities.ts` (auto-imported in app and server) or `shared/abilities.ts`.
+     */
+    abilities?: string;
+    /** Override how the user is resolved (paths to default-export functions). Defaults to the session user. */
+    resolvers?: {
+        /** `(event: H3Event) => User | null | Promise<User | null>` */
+        server?: string;
+        /** `() => User | null | Promise<User | null>` - runs in the app (client and SSR). */
+        client?: string;
+    };
+    /** Where to send unauthenticated visitors on page navigation. Omit to show a 401 error instead. */
+    redirectTo?: string;
+}
+/**
+ * Authorization keys that go directly on a `routeRules` entry. Ability names refer to exports of the abilities
+ * file and take no arguments.
+ */
+type AuthorizationRouteRules = Omit<RouteRule, 'args' | 'ability'> & {
+    ability?: string;
+};
+interface PublicModuleOptions {
+    /** The authorization keys of `routeRules`, collected at build time. */
+    routes?: Record<string, AuthorizationRouteRules>;
+    redirectTo?: string;
+}
+declare module 'nitropack' {
+    interface NitroRouteConfig extends AuthorizationRouteRules {
+    }
+}
+declare module 'nitropack/types' {
+    interface NitroRouteConfig extends AuthorizationRouteRules {
+    }
+}
+declare module '#app' {
+    interface PageMeta {
+        authorize?: AuthorizeMeta;
+    }
+}
+
+declare module 'nuxt/schema' {
+    interface NuxtConfig {
+        authorization?: ModuleOptions;
+    }
+    interface PublicRuntimeConfig {
+        authorization?: PublicModuleOptions;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { AuthorizationRouteRules, ModuleOptions, PublicModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/authorization",
+  "configKey": "authorization",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,121 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { defineNuxtModule, createResolver, addServerTemplate, addTemplate, addTypeTemplate, addImports, addServerImports, addComponentsDir, addServerImportsDir, addRouteMiddleware, addServerHandler } from '@nuxt/kit';
+import { registerModule, extendDatabaseTable } from '@frigear-nu/module-kit/utils';
+import { ROUTE_RULE_KEYS } from '../dist/runtime/utils/types.js';
+
+const module$1 = defineNuxtModule({
+  meta: { name: "@frigear-nu/authorization", configKey: "authorization" },
+  defaults: {
+    resolvers: {}
+  },
+  moduleDependencies: {
+    "@nuxthub/core": {
+      version: ">=0.10"
+    },
+    "@frigear-nu/module-kit": {
+      version: ">=0.0.1"
+    },
+    "@frigear-nu/users": {
+      version: ">=0.0.1"
+    }
+  },
+  async setup(options, nuxt) {
+    registerModule("@frigear-nu/authorization", nuxt);
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.public.authorization = {
+      routes: {},
+      redirectTo: options.redirectTo
+    };
+    nuxt.hook("modules:done", () => {
+      const routes = {};
+      const sources = [nuxt.options.routeRules, nuxt.options.nitro?.routeRules];
+      for (const [pattern, rule] of sources.flatMap((source) => Object.entries(source ?? {}))) {
+        const picked = Object.fromEntries(ROUTE_RULE_KEYS.filter((key) => rule[key] !== void 0).map((key) => [key, rule[key]]));
+        if (Object.keys(picked).length) routes[pattern] = { ...routes[pattern], ...picked };
+      }
+      nuxt.options.runtimeConfig.public.authorization = { routes, redirectTo: options.redirectTo };
+    });
+    extendDatabaseTable(nuxt, {
+      name: "users",
+      resolver,
+      file: (dialect) => `./runtime/server/db/schema.${dialect}`
+    });
+    const resolverSource = async (configured, fallback) => {
+      const target = configured ? await resolver.resolvePath(configured, { cwd: nuxt.options.rootDir }) : resolver.resolve(fallback);
+      return `export { default } from ${JSON.stringify(target)}`;
+    };
+    const abilitiesFile = options.abilities ? await resolver.resolvePath(options.abilities, { cwd: nuxt.options.rootDir }) : ["shared/utils/abilities.ts", "shared/abilities.ts"].map((file) => join(nuxt.options.rootDir, file)).find(existsSync);
+    const abilitiesSource = abilitiesFile ? `import * as abilities from ${JSON.stringify(abilitiesFile)}
+export { abilities }` : "export const abilities = {}";
+    addServerTemplate({
+      filename: "#authorization/server-resolver",
+      getContents: () => resolverSource(options.resolvers?.server, "./runtime/server/resolver")
+    });
+    addServerTemplate({
+      filename: "#authorization/abilities",
+      getContents: () => abilitiesSource
+    });
+    addTemplate({
+      filename: "authorization/client-resolver.mjs",
+      write: true,
+      getContents: () => resolverSource(options.resolvers?.client, "./runtime/app/resolver")
+    });
+    addTemplate({
+      filename: "authorization/abilities.mjs",
+      write: true,
+      getContents: () => abilitiesSource
+    });
+    addTypeTemplate({
+      filename: "types/authorization-virtual.d.ts",
+      getContents: () => `declare module '#authorization/server-resolver' {
+  const resolveServerUser: (event: import('h3').H3Event) => unknown | Promise<unknown>
+  export default resolveServerUser
+}
+declare module '#authorization/abilities' {
+  export const abilities: Record<string, unknown>
+}
+declare module '#build/authorization/client-resolver.mjs' {
+  const resolveClientUser: () => unknown | Promise<unknown>
+  export default resolveClientUser
+}
+declare module '#build/authorization/abilities.mjs' {
+  export const abilities: Record<string, unknown>
+}
+`
+    }, { nitro: true, nuxt: true });
+    addTypeTemplate({
+      filename: "types/authorization-user.d.ts",
+      getContents: () => `declare module '#auth-utils' {
+  interface User {
+    role: string
+  }
+}
+export {}
+`
+    }, { nitro: true, nuxt: true });
+    const abilityImports = ["defineAbility", "allow", "deny"].map((name) => ({
+      name,
+      from: resolver.resolve("./runtime/utils/ability")
+    }));
+    addImports(abilityImports);
+    addServerImports(abilityImports);
+    addImports(["allows", "denies", "authorize", "useAuthorization"].map((name) => ({
+      name,
+      from: resolver.resolve("./runtime/app/composables/useAuthorization")
+    })));
+    addComponentsDir({ path: resolver.resolve("./runtime/app/components") });
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addRouteMiddleware({
+      name: "authorization",
+      path: resolver.resolve("./runtime/app/middleware/authorization.global"),
+      global: true
+    });
+    addServerHandler({
+      middleware: true,
+      handler: resolver.resolve("./runtime/server/middleware/authorization")
+    });
+  }
+});
+
+export { module$1 as default };

package/dist/runtime/app/components/Can.d.vue.ts

@@ -0,0 +1,28 @@
+import type { Ability, AbilityArgs } from '../../utils/index.js';
+declare const __VLS_export: <A extends Ability>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        /** One ability, or several that must all pass. */
+        ability: A | A[];
+        /** Arguments for the ability (an array of argument arrays when `ability` is an array). */
+        args?: AbilityArgs<A> | AbilityArgs<A>[];
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        default?: (props: {}) => any;
+    } & {
+        fallback?: (props: {}) => any;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/app/components/Can.vue

@@ -0,0 +1,27 @@
+<script setup>
+import { allows } from "../composables/useAuthorization";
+import { ref, watchEffect } from "#imports";
+const props = defineProps({
+  ability: { type: null, required: true },
+  args: { type: null, required: false }
+});
+async function resolve() {
+  if (Array.isArray(props.ability)) {
+    const results = await Promise.all(props.ability.map((ability, index) => allows(ability, ...props.args?.[index] ?? [])));
+    return results.every(Boolean);
+  }
+  return allows(props.ability, ...props.args ?? []);
+}
+const can = ref(await resolve());
+watchEffect(async () => {
+  can.value = await resolve();
+});
+</script>
+
+<template>
+  <slot v-if="can" />
+  <slot
+    v-else
+    name="fallback"
+  />
+</template>

package/dist/runtime/app/components/Can.vue.d.ts

@@ -0,0 +1,28 @@
+import type { Ability, AbilityArgs } from '../../utils/index.js';
+declare const __VLS_export: <A extends Ability>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        /** One ability, or several that must all pass. */
+        ability: A | A[];
+        /** Arguments for the ability (an array of argument arrays when `ability` is an array). */
+        args?: AbilityArgs<A> | AbilityArgs<A>[];
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        default?: (props: {}) => any;
+    } & {
+        fallback?: (props: {}) => any;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/app/components/Cannot.d.vue.ts

@@ -0,0 +1,24 @@
+import type { Ability, AbilityArgs } from '../../utils/index.js';
+declare const __VLS_export: <A extends Ability>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        ability: A;
+        args?: AbilityArgs<A>;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        default?: (props: {}) => any;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/app/components/Cannot.vue

@@ -0,0 +1,17 @@
+<script setup>
+import { allows } from "../composables/useAuthorization";
+import { ref, watchEffect } from "#imports";
+const props = defineProps({
+  ability: { type: null, required: true },
+  args: { type: null, required: false }
+});
+const resolve = async () => !await allows(props.ability, ...props.args ?? []);
+const cannot = ref(await resolve());
+watchEffect(async () => {
+  cannot.value = await resolve();
+});
+</script>
+
+<template>
+  <slot v-if="cannot" />
+</template>

package/dist/runtime/app/components/Cannot.vue.d.ts

@@ -0,0 +1,24 @@
+import type { Ability, AbilityArgs } from '../../utils/index.js';
+declare const __VLS_export: <A extends Ability>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+    props: import("vue").PublicProps & __VLS_PrettifyLocal<{
+        ability: A;
+        args?: AbilityArgs<A>;
+    }> & (typeof globalThis extends {
+        __VLS_PROPS_FALLBACK: infer P;
+    } ? P : {});
+    expose: (exposed: {}) => void;
+    attrs: any;
+    slots: {
+        default?: (props: {}) => any;
+    };
+    emit: {};
+}>) => import("vue").VNode & {
+    __ctx?: NonNullable<Awaited<typeof __VLS_setup>>;
+};
+declare const _default: typeof __VLS_export;
+export default _default;
+type __VLS_PrettifyLocal<T> = (T extends any ? {
+    [K in keyof T]: T[K];
+} : {
+    [K in keyof T as K]: T[K];
+}) & {};

package/dist/runtime/app/composables/useAuthorization.d.ts

@@ -0,0 +1,11 @@
+import type { Ability, AbilityArgs } from '../../utils/index.js';
+/** Check whether the current (client-resolved) user may perform an action. */
+export declare function allows<A extends Ability>(ability: A, ...args: AbilityArgs<A>): Promise<boolean>;
+export declare function denies<A extends Ability>(ability: A, ...args: AbilityArgs<A>): Promise<boolean>;
+/** Throws a Nuxt error (403 by default) when the current user may not perform the action. */
+export declare function authorize<A extends Ability>(ability: A, ...args: AbilityArgs<A>): Promise<void>;
+export declare function useAuthorization(): {
+    allows: typeof allows;
+    denies: typeof denies;
+    authorize: typeof authorize;
+};

package/dist/runtime/app/composables/useAuthorization.js

@@ -0,0 +1,22 @@
+import { allows as _allows, denies as _denies, authorize as _authorize, AuthorizationError } from "../../utils/index.js";
+import resolveClientUser from "#build/authorization/client-resolver.mjs";
+import { createError } from "#imports";
+export async function allows(ability, ...args) {
+  return _allows(ability, await resolveClientUser(), ...args);
+}
+export async function denies(ability, ...args) {
+  return _denies(ability, await resolveClientUser(), ...args);
+}
+export async function authorize(ability, ...args) {
+  try {
+    await _authorize(ability, await resolveClientUser(), ...args);
+  } catch (error) {
+    if (error instanceof AuthorizationError) {
+      throw createError({ statusCode: error.statusCode, message: error.message });
+    }
+    throw error;
+  }
+}
+export function useAuthorization() {
+  return { allows, denies, authorize };
+}

package/dist/runtime/app/middleware/authorization.global.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("nuxt/app").RouteMiddleware;
+export default _default;

package/dist/runtime/app/middleware/authorization.global.js

@@ -0,0 +1,17 @@
+import { evaluateRule, normalizeAuthorizeMeta, resolveRule } from "../../utils/index.js";
+import { abilities } from "#build/authorization/abilities.mjs";
+import resolveClientUser from "#build/authorization/client-resolver.mjs";
+import { abortNavigation, createError, defineNuxtRouteMiddleware, navigateTo, useRuntimeConfig } from "#imports";
+export default defineNuxtRouteMiddleware(async (to) => {
+  const config = useRuntimeConfig().public.authorization;
+  const meta = to.meta.authorize;
+  const rule = meta ? normalizeAuthorizeMeta(meta) : resolveRule(config?.routes, to.path);
+  if (!rule) return;
+  const user = await resolveClientUser();
+  const response = await evaluateRule(rule, user, abilities);
+  if (response.authorized) return;
+  if (response.statusCode === 401 && config?.redirectTo) {
+    return navigateTo(config.redirectTo);
+  }
+  return abortNavigation(createError({ statusCode: response.statusCode ?? 403, message: response.message }));
+});

package/dist/runtime/app/resolver.d.ts

@@ -0,0 +1 @@
+export default function resolveClientUser(): any;

package/dist/runtime/app/resolver.js

@@ -0,0 +1,3 @@
+export default function resolveClientUser() {
+  return useUserSession().user.value ?? null;
+}

package/dist/runtime/server/db/schema.sqlite.d.ts

@@ -0,0 +1,26 @@
+export declare const users: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "users";
+    schema: undefined;
+    columns: {
+        role: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "role";
+            tableName: "users";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;

package/dist/runtime/server/db/schema.sqlite.js

@@ -0,0 +1,4 @@
+import { sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const users = sqliteTable("users", {
+  role: text("role").notNull().default("user")
+});

package/dist/runtime/server/middleware/authorization.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/middleware/authorization.js

@@ -0,0 +1,15 @@
+import { defineEventHandler, createError, getRequestURL } from "h3";
+import { evaluateRule, resolveRule } from "../../utils/index.js";
+import { abilities } from "#authorization/abilities";
+import resolveServerUser from "#authorization/server-resolver";
+import { useRuntimeConfig } from "#imports";
+export default defineEventHandler(async (event) => {
+  const { pathname } = getRequestURL(event);
+  if (!pathname.startsWith("/api/")) return;
+  const rule = resolveRule(useRuntimeConfig(event).public.authorization?.routes, pathname);
+  if (!rule) return;
+  const response = await evaluateRule(rule, await resolveServerUser(event), abilities);
+  if (!response.authorized) {
+    throw createError({ statusCode: response.statusCode ?? 403, message: response.message });
+  }
+});

package/dist/runtime/server/resolver.d.ts

@@ -0,0 +1,2 @@
+import type { H3Event } from 'h3';
+export default function resolveServerUser(event: H3Event): Promise<any>;

package/dist/runtime/server/resolver.js

@@ -0,0 +1,4 @@
+export default async function resolveServerUser(event) {
+  const session = await getUserSession(event);
+  return session.user ?? null;
+}

package/dist/runtime/server/utils/authorization.d.ts

@@ -0,0 +1,8 @@
+import type { H3Event } from 'h3';
+import type { Ability, AbilityArgs } from '../../utils/index.js';
+/** Resolve the current user with the configured server resolver (session user by default). */
+export declare function resolveAuthorizationUser(event: H3Event): any;
+export declare function allows<A extends Ability>(event: H3Event, ability: A, ...args: AbilityArgs<A>): Promise<boolean>;
+export declare function denies<A extends Ability>(event: H3Event, ability: A, ...args: AbilityArgs<A>): Promise<boolean>;
+/** Throws an h3 error (401 for guests, 403 otherwise) when the user may not perform the action. */
+export declare function authorize<A extends Ability>(event: H3Event, ability: A, ...args: AbilityArgs<A>): Promise<void>;

package/dist/runtime/server/utils/authorization.js

@@ -0,0 +1,21 @@
+import { allows as _allows, denies as _denies, authorize as _authorize, AuthorizationError } from "../../utils/index.js";
+import resolveServerUser from "#authorization/server-resolver";
+export function resolveAuthorizationUser(event) {
+  return resolveServerUser(event);
+}
+export async function allows(event, ability, ...args) {
+  return _allows(ability, await resolveServerUser(event), ...args);
+}
+export async function denies(event, ability, ...args) {
+  return _denies(ability, await resolveServerUser(event), ...args);
+}
+export async function authorize(event, ability, ...args) {
+  try {
+    await _authorize(ability, await resolveServerUser(event), ...args);
+  } catch (error) {
+    if (error instanceof AuthorizationError) {
+      throw createError({ statusCode: error.statusCode, message: error.message });
+    }
+    throw error;
+  }
+}

package/dist/runtime/utils/ability.d.ts

@@ -0,0 +1,21 @@
+import type { Ability, AuthorizationResponse, Authorizer, AuthorizerResponse } from './types.js';
+type AbilityFromAuthorizer<A> = A extends (user: infer User, ...args: any[]) => AuthorizerResponse ? Ability<User> : never;
+/**
+ * Define a policy. The resolved user is injected as the first argument; guests (no user) are denied
+ * before the policy runs unless `allowGuest` is set, in which case the policy receives `null`.
+ *
+ * @example
+ * export const editPost = defineAbility((user: User, post: Post) => user.id === post.userId)
+ * export const viewFeed = defineAbility({ allowGuest: true }, (user: User | null) => true)
+ */
+export declare function defineAbility<A extends Authorizer>(authorizer: A): AbilityFromAuthorizer<A> & Ability;
+export declare function defineAbility<A extends Authorizer>(options: {
+    allowGuest: boolean;
+}, authorizer: A): AbilityFromAuthorizer<A> & Ability;
+export declare function allow(): AuthorizationResponse;
+export declare function deny(options?: {
+    statusCode?: number;
+    message?: string;
+}): AuthorizationResponse;
+export declare function isAbility(value: unknown): value is Ability;
+export {};

package/dist/runtime/utils/ability.js

@@ -0,0 +1,21 @@
+export function defineAbility(optionsOrAuthorizer, maybeAuthorizer) {
+  const allowGuest = typeof optionsOrAuthorizer === "function" ? false : optionsOrAuthorizer.allowGuest;
+  const original = typeof optionsOrAuthorizer === "function" ? optionsOrAuthorizer : maybeAuthorizer;
+  return {
+    allowGuest,
+    original,
+    execute(user, ...args) {
+      if (user === null && !allowGuest) return { authorized: false };
+      return original(user, ...args);
+    }
+  };
+}
+export function allow() {
+  return { authorized: true };
+}
+export function deny(options = {}) {
+  return { authorized: false, ...options };
+}
+export function isAbility(value) {
+  return typeof value === "object" && value !== null && typeof value.execute === "function";
+}

package/dist/runtime/utils/bouncer.d.ts

@@ -0,0 +1,7 @@
+import type { Ability, AbilityArgs, AuthorizationResponse } from './types.js';
+export declare function normalizeResponse(result: boolean | AuthorizationResponse): AuthorizationResponse;
+/** Run an ability for an already-resolved user. Used by the client and server helpers. */
+export declare function check<A extends Ability>(ability: A, user: unknown, ...args: AbilityArgs<A>): Promise<AuthorizationResponse>;
+export declare function allows<A extends Ability>(ability: A, user: unknown, ...args: AbilityArgs<A>): Promise<boolean>;
+export declare function denies<A extends Ability>(ability: A, user: unknown, ...args: AbilityArgs<A>): Promise<boolean>;
+export declare function authorize<A extends Ability>(ability: A, user: unknown, ...args: AbilityArgs<A>): Promise<void>;

package/dist/runtime/utils/bouncer.js

@@ -0,0 +1,17 @@
+import { createAuthorizationError } from "./error.js";
+export function normalizeResponse(result) {
+  return typeof result === "boolean" ? { authorized: result } : result;
+}
+export async function check(ability, user, ...args) {
+  return normalizeResponse(await ability.execute(user ?? null, ...args));
+}
+export async function allows(ability, user, ...args) {
+  return (await check(ability, user, ...args)).authorized;
+}
+export async function denies(ability, user, ...args) {
+  return !await allows(ability, user, ...args);
+}
+export async function authorize(ability, user, ...args) {
+  const response = await check(ability, user, ...args);
+  if (!response.authorized) throw createAuthorizationError(response.message, response.statusCode);
+}

package/dist/runtime/utils/error.d.ts

@@ -0,0 +1,5 @@
+export declare class AuthorizationError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+export declare function createAuthorizationError(message?: string, statusCode?: number): AuthorizationError;

package/dist/runtime/utils/error.js

@@ -0,0 +1,11 @@
+export class AuthorizationError extends Error {
+  statusCode;
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "AuthorizationError";
+    this.statusCode = statusCode;
+  }
+}
+export function createAuthorizationError(message = "Unauthorized", statusCode = 403) {
+  return new AuthorizationError(message, statusCode);
+}

package/dist/runtime/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './error.js';
+export * from './ability.js';
+export * from './bouncer.js';
+export * from './rules.js';

package/dist/runtime/utils/index.js

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./error.js";
+export * from "./ability.js";
+export * from "./bouncer.js";
+export * from "./rules.js";

package/dist/runtime/utils/rules.d.ts

@@ -0,0 +1,20 @@
+import type { AuthorizationResponse, AuthorizeMeta, RouteRule } from './types.js';
+export type AbilityRegistry = Record<string, unknown>;
+/**
+ * Match a route path against a pattern: `/admin/**` (prefix), `*` (single segment) or an exact path.
+ */
+export declare function matchRoute(pattern: string, path: string): boolean;
+/**
+ * Resolve the rule for a path from `routeRules`-style entries. Like Nitro's route rules, every matching pattern
+ * contributes and keys of more specific patterns override less specific ones. Returns `undefined` when nothing
+ * applies, including when the merged result says `authenticated: false`.
+ */
+export declare function resolveRule(routes: Record<string, RouteRule> | undefined, path: string): RouteRule | undefined;
+export declare function normalizeAuthorizeMeta(meta: AuthorizeMeta): RouteRule;
+/**
+ * Evaluate a declarative route rule for an already-resolved user.
+ * Unauthenticated visitors get 401 (unless `guest` is set), role/ability mismatches get 403.
+ */
+export declare function evaluateRule(rule: RouteRule, user: {
+    role?: string;
+} | null, abilities?: AbilityRegistry): Promise<AuthorizationResponse>;

package/dist/runtime/utils/rules.js

@@ -0,0 +1,48 @@
+import { isAbility } from "./ability.js";
+import { normalizeResponse } from "./bouncer.js";
+export function matchRoute(pattern, path) {
+  const normalize = (value) => value.replace(/\/+$/, "") || "/";
+  const p = normalize(pattern);
+  const s = normalize(path);
+  if (p.endsWith("/**")) {
+    const base = p.slice(0, -3);
+    return s === base || s.startsWith(`${base}/`);
+  }
+  const patternSegments = p.split("/");
+  const pathSegments = s.split("/");
+  return patternSegments.length === pathSegments.length && patternSegments.every((segment, index) => segment === "*" || segment === pathSegments[index]);
+}
+function specificity(pattern) {
+  const segments = pattern.split("/").filter(Boolean);
+  const literals = segments.filter((segment) => segment !== "*" && segment !== "**").length;
+  return literals * 10 + (pattern.endsWith("/**") ? 0 : 5);
+}
+export function resolveRule(routes, path) {
+  const matches = Object.entries(routes ?? {}).filter(([pattern]) => matchRoute(pattern, path)).sort(([a], [b]) => specificity(a) - specificity(b));
+  if (!matches.length) return void 0;
+  const rule = Object.assign({}, ...matches.map(([, entry]) => entry));
+  return rule.authenticated === false ? void 0 : rule;
+}
+export function normalizeAuthorizeMeta(meta) {
+  if (typeof meta === "string") return { ability: meta };
+  if (isAbility(meta)) return { ability: meta };
+  return meta;
+}
+export async function evaluateRule(rule, user, abilities = {}) {
+  if (rule.authenticated === false) return { authorized: true };
+  if (!user && !rule.guest) {
+    return { authorized: false, statusCode: 401, message: "Authentication required" };
+  }
+  if (rule.roles?.length && (!user?.role || !rule.roles.includes(user.role))) {
+    return { authorized: false, statusCode: 403, message: "Forbidden" };
+  }
+  if (rule.ability) {
+    const ability = typeof rule.ability === "string" ? abilities[rule.ability] : rule.ability;
+    if (!isAbility(ability)) {
+      throw new Error(`[@frigear-nu/authorization] Unknown ability "${String(rule.ability)}". Export it from your abilities file.`);
+    }
+    const response = normalizeResponse(await ability.execute(user, ...rule.args ?? []));
+    if (!response.authorized) return { statusCode: 403, message: "Forbidden", ...response };
+  }
+  return { authorized: true };
+}

package/dist/runtime/utils/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Detailed outcome of an ability check. Lets an ability customise the error that is thrown on denial.
+ */
+export interface AuthorizationResponse {
+    authorized: boolean;
+    statusCode?: number;
+    message?: string;
+}
+export type AuthorizerResponse = boolean | AuthorizationResponse | Promise<boolean | AuthorizationResponse>;
+/** A policy function: receives the resolved user first, then any call-site arguments. */
+export type Authorizer<User = any> = (user: User, ...args: any[]) => AuthorizerResponse;
+export interface Ability<User = any> {
+    allowGuest: boolean;
+    original: Authorizer<User>;
+    execute: (user: User | null, ...args: any[]) => AuthorizerResponse;
+}
+/** Call-site arguments of an ability, inferred from the policy signature. */
+export type AbilityArgs<A extends Ability> = A extends {
+    original: (user: any, ...args: infer Args) => AuthorizerResponse;
+} ? Args : never;
+/** Declarative rule: the keys of a `routeRules` entry, or the object form of `definePageMeta({ authorize })`. */
+export interface RouteRule {
+    /** Allowed roles (matched against `user.role`). */
+    roles?: string[];
+    /** Name of an exported ability from the abilities file, or (page meta only) an ability object. */
+    ability?: string | Ability;
+    /** Arguments passed to the ability (page meta only - config rules cannot carry arguments). */
+    args?: unknown[];
+    /** Let unauthenticated visitors through (the ability/roles checks still apply). */
+    guest?: boolean;
+    /** `true`: require a logged-in user. `false`: no authorization at all (opens a sub-route of a protected pattern). */
+    authenticated?: boolean;
+}
+/** The authorization keys that go directly on a `routeRules` entry. */
+export declare const ROUTE_RULE_KEYS: readonly ["roles", "ability", "guest", "authenticated"];
+/** What `definePageMeta({ authorize })` accepts. */
+export type AuthorizeMeta = string | Ability | RouteRule;

package/dist/runtime/utils/types.js

@@ -0,0 +1 @@
+export const ROUTE_RULE_KEYS = ["roles", "ability", "guest", "authenticated"];

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+export { type Ability, type AbilityArgs, type AuthorizationResponse, type AuthorizeMeta, type RouteRule } from '../dist/runtime/utils/types.js'
+
+export { default } from './module.mjs'
+
+export { type AuthorizationRouteRules, type ModuleOptions, type PublicModuleOptions } from './module.mjs'

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@frigear-nu/authorization",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.2",
+  "description": "Policy-based authorization (abilities, resolvers, route rules, <Can>) for the frigear ecosystem, built on @frigear-nu/users.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/frigear-nu/frigear-nu.git",
+    "directory": "packages/authorization"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/module.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs",
+      "default": "./dist/module.mjs"
+    },
+    "./utils": {
+      "types": "./dist/runtime/utils/index.d.ts",
+      "import": "./dist/runtime/utils/index.js",
+      "default": "./dist/runtime/utils/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "workspaces": [
+    "playground"
+  ],
+  "dependencies": {
+    "@frigear-nu/module-kit": "0.1.3",
+    "@frigear-nu/users": "1.0.5",
+    "@libsql/client": "^0.18.0",
+    "@nuxt/kit": "^4.6.0",
+    "drizzle-kit": "^0.31.11",
+    "drizzle-orm": "^0.45.3"
+  },
+  "peerDependencies": {
+    "@nuxthub/core": "^0.10.8"
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.4.2",
+    "@nuxt/eslint-config": "^1.17.0",
+    "@nuxt/module-builder": "^1.0.3",
+    "@nuxt/schema": "^4.6.0",
+    "@nuxt/test-utils": "^4.3.2",
+    "@nuxthub/core": "^0.10.8",
+    "@types/node": "latest",
+    "eslint": "^10.10.0",
+    "nuxt": "^4.6.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.1",
+    "vue-tsc": "^3.3.11"
+  },
+  "scripts": {
+    "postinstall": "nuxt-module-build build --stub && nuxt prepare",
+    "build": "nuxt-module-build build",
+    "dev": "npm run dev:prepare && nuxt dev playground",
+    "dev:build": "nuxt build playground",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxt prepare playground",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:types": "vue-tsc --noEmit && cd playground && vue-tsc --noEmit"
+  },
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  }
 }