nuxt-huia-headless 1.0.0-alpha.5

package/README.md

@@ -0,0 +1,110 @@
+# nuxt-huia-headless
+
+**Nuxt 4** authentication module for [`Huia.Headless`](https://github.com/Ayman-Elfaki/Huia) — a
+bearer-token identity API (register, login, refresh, passkeys, passwordless SMS, external providers)
+with no OAuth redirect dance for password/phone sign-in. Same dual-layer session principle as
+[`nuxt-huia-oidc`](../nuxt-huia-oidc): the browser only ever holds a sealed, chunked session cookie;
+access/refresh tokens live server-side in Nitro Storage and are refreshed transparently.
+
+- Requires Nuxt `>=4`, Nitro `>=2.10`, Node `>=20.11`
+- No `openid-client` dependency — this talks to Huia.Headless with plain `fetch`, since there is no
+  authorization-code redirect or discovery document to negotiate.
+- Docs: <https://github.com/Ayman-Elfaki/Huia/tree/main/docs/nuxt-headless>
+
+## Install
+
+```bash
+npm install nuxt-huia-headless
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['nuxt-huia-headless'],
+  huiaHeadless: {
+    baseUrl: 'https://api.example.com',
+    // session.password via NUXT_HUIA_HEADLESS_SESSION_PASSWORD (>= 32 chars)
+  },
+})
+```
+
+## Usage
+
+```vue
+<!-- app/pages/login.vue — the app owns this page; Huia.Headless has no hosted login UI -->
+<script setup lang="ts">
+const { login } = useHuia()
+const result = await login({ email, password })
+</script>
+```
+
+```vue
+<script setup lang="ts">
+const { user, loggedIn, logout } = useHuia()
+</script>
+```
+
+Passwordless SMS is a two- or three-step flow — `verifyPhoneLogin` returns the bearer session
+directly for a returning, complete-profile account, or `{ requiresProfile: true, flowId }` for a
+first-time number that still needs a name:
+
+```vue
+<script setup lang="ts">
+const { startPhoneLogin, verifyPhoneLogin, completePhoneProfile } = useHuia()
+
+const { flowId } = await startPhoneLogin({ phoneNumber: '+12025550123' })
+const result = await verifyPhoneLogin({ flowId, code })
+if (result.requiresProfile) {
+  await completePhoneProfile({ flowId: result.flowId, firstName, lastName })
+}
+</script>
+```
+
+External login (Google/GitHub/Microsoft/generic OIDC) is a real browser redirect through the
+provider, so it starts as a plain link, not a `fetch` call — `externalLoginHref` builds it:
+
+```vue
+<!-- app/pages/login.vue -->
+<a :href="useHuia().externalLoginHref('google', '/dashboard')">Sign in with Google</a>
+```
+
+```vue
+<!-- app/pages/auth/callback.vue — the page huiaHeadless.externalCallbackPage points at (default /auth/callback) -->
+<script setup lang="ts">
+const { code, returnTo } = useRoute().query
+const { exchangeExternalCode, completeExternalProfile } = useHuia()
+
+const result = await exchangeExternalCode(code as string)
+if (!result.requiresProfile) await navigateTo((returnTo as string) ?? '/')
+// else render a small first/last name form, then call completeExternalProfile({ code: result.flowId, firstName, lastName })
+</script>
+```
+
+```ts
+// server/api/me.get.ts
+export default defineEventHandler(async (event) => {
+  const { user } = await requireUserSession(event)   // 401 if anonymous
+  return { id: user.sub, email: user.email, roles: user.roles }
+})
+```
+
+Protect a page with the built-in `auth` middleware (`definePageMeta({ middleware: 'auth' })`, or
+`huiaHeadless.middleware.global = true` for every page); an unauthenticated visit redirects to
+`huiaHeadless.loginPage` (default `/login`) rather than an external URL — there is nothing external
+to redirect to. `huiaHeadless.middleware.exclude` (glob patterns, `**`/`*` supported) opts specific
+pages out; the module's own auth routes and `loginPage` are always excluded regardless.
+
+`logout()` is purely local — it clears the session cookie and the stored token record. Huia.Headless's
+bearer tokens are the framework's stock (non-revocable) format, so unlike `nuxt-huia-oidc` there is no
+upstream session to end and no redirect.
+
+## Develop
+
+```bash
+npm install
+npm run dev:prepare
+npm test            # Vitest unit + integration (mocked Huia.Headless backend)
+npm run dev          # playground on http://localhost:3000
+```
+
+`.npmrc` pins `legacy-peer-deps=true` (an npm 10 arborist crash on the nuxt peer graph).

package/dist/module.d.mts

@@ -0,0 +1,67 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    baseUrl?: string;
+    session?: {
+        name?: string;
+        password?: string;
+        maxAge?: number;
+        cookie?: {
+            sameSite?: 'lax' | 'strict' | 'none';
+            secure?: boolean;
+        };
+        userClaims?: string[];
+    };
+    storage?: {
+        base?: string;
+    };
+    refresh?: {
+        enabled?: boolean;
+        earlyRefreshSeconds?: number;
+        lock?: {
+            ttlMs?: number;
+            waitMs?: number;
+            pollMs?: number;
+        };
+    };
+    cookie?: {
+        chunkSize?: number;
+        maxChunks?: number;
+    };
+    middleware?: {
+        global?: boolean;
+        exclude?: string[];
+    };
+    hydration?: 'useState' | 'asyncData';
+    routes?: {
+        register?: string;
+        login?: string;
+        logout?: string;
+        refresh?: string;
+        session?: string;
+        confirmEmail?: string;
+        resendConfirmation?: string;
+        forgotPassword?: string;
+        resetPassword?: string;
+        phoneStart?: string;
+        phoneVerify?: string;
+        phoneCompleteProfile?: string;
+        /** Prefix the external-login challenge redirects from; the provider name is appended (`{prefix}/{provider}`). */
+        externalLogin?: string;
+        externalExchange?: string;
+        externalCompleteProfile?: string;
+        admin?: string;
+    };
+    /** The app's own login page (Huia.Headless has no hosted login UI to redirect to). */
+    loginPage?: string;
+    /**
+     * The app's own page that reads `?code=` off the query string after an external-provider callback
+     * and calls `externalExchange` (Huia.Headless has no hosted "completing sign-in…" page either).
+     */
+    externalCallbackPage?: string;
+    allowInsecureTls?: boolean;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,12 @@
+{
+  "name": "nuxt-huia-headless",
+  "configKey": "huiaHeadless",
+  "compatibility": {
+    "nuxt": ">=4.0.0"
+  },
+  "version": "1.0.0-alpha.5",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,146 @@
+import { defineNuxtModule, createResolver, addServerImportsDir, addImportsDir, addPlugin, addRouteMiddleware, addServerHandler } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const defaults = {
+  baseUrl: "",
+  session: {
+    name: "__Host-huia_headless_sess",
+    password: "",
+    maxAge: 60 * 60 * 24 * 7,
+    cookie: { sameSite: "lax" },
+    userClaims: ["sub", "email", "firstName", "lastName", "roles"]
+  },
+  storage: { base: "huia-headless-auth" },
+  refresh: {
+    enabled: true,
+    earlyRefreshSeconds: 60,
+    lock: { ttlMs: 1e4, waitMs: 8e3, pollMs: 150 }
+  },
+  cookie: { chunkSize: 3800, maxChunks: 8 },
+  middleware: { global: false, exclude: [] },
+  hydration: "useState",
+  routes: {
+    register: "/auth/register",
+    login: "/auth/login",
+    logout: "/auth/logout",
+    refresh: "/auth/refresh",
+    session: "/auth/session",
+    confirmEmail: "/auth/confirm-email",
+    resendConfirmation: "/auth/resend-confirmation",
+    forgotPassword: "/auth/forgot-password",
+    resetPassword: "/auth/reset-password",
+    phoneStart: "/auth/phone/start",
+    phoneVerify: "/auth/phone/verify",
+    phoneCompleteProfile: "/auth/phone/complete-profile",
+    externalLogin: "/auth/external",
+    externalExchange: "/auth/external-exchange",
+    externalCompleteProfile: "/auth/external-complete-profile",
+    admin: "/auth/admin"
+  },
+  loginPage: "/login",
+  externalCallbackPage: "/auth/callback",
+  allowInsecureTls: false
+};
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "nuxt-huia-headless",
+    configKey: "huiaHeadless",
+    compatibility: { nuxt: ">=4.0.0" }
+  },
+  defaults,
+  setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+    const opts = defu(options, defaults);
+    if (!opts.session.password && !process.env.NUXT_HUIA_HEADLESS_SESSION_PASSWORD) {
+      console.warn("[huia-headless-auth] no session password set \u2014 set NUXT_HUIA_HEADLESS_SESSION_PASSWORD (>= 32 chars)");
+    }
+    nuxt.options.runtimeConfig.huiaHeadless = defu(
+      nuxt.options.runtimeConfig.huiaHeadless,
+      {
+        baseUrl: opts.baseUrl ?? "",
+        session: { ...opts.session, password: opts.session.password ?? "" },
+        storage: opts.storage,
+        refresh: opts.refresh,
+        cookie: opts.cookie,
+        allowInsecureTls: opts.allowInsecureTls,
+        externalCallbackPath: opts.externalCallbackPage
+      }
+    );
+    nuxt.options.runtimeConfig.public.huiaHeadless = defu(
+      nuxt.options.runtimeConfig.public.huiaHeadless,
+      {
+        registerPath: opts.routes.register,
+        loginPath: opts.routes.login,
+        logoutPath: opts.routes.logout,
+        sessionPath: opts.routes.session,
+        loginPage: opts.loginPage,
+        phoneStartPath: opts.routes.phoneStart,
+        phoneVerifyPath: opts.routes.phoneVerify,
+        phoneCompleteProfilePath: opts.routes.phoneCompleteProfile,
+        externalLoginPath: opts.routes.externalLogin,
+        externalExchangePath: opts.routes.externalExchange,
+        externalCompleteProfilePath: opts.routes.externalCompleteProfile,
+        externalCallbackPage: opts.externalCallbackPage,
+        adminPath: opts.routes.admin,
+        // The module's own auth routes are never protected by its own middleware, regardless of
+        // `middleware.exclude`, plus the app's own login/callback pages — same rationale as
+        // nuxt-huia-oidc: applying "must be logged in" to the routes/pages that exist for the
+        // logged-out flow is never correct.
+        middlewareExclude: [
+          ...opts.middleware.exclude,
+          opts.loginPage,
+          opts.externalCallbackPage,
+          opts.routes.register,
+          opts.routes.login,
+          opts.routes.logout,
+          opts.routes.refresh,
+          opts.routes.session,
+          opts.routes.confirmEmail,
+          opts.routes.resendConfirmation,
+          opts.routes.forgotPassword,
+          opts.routes.resetPassword,
+          opts.routes.phoneStart,
+          opts.routes.phoneVerify,
+          opts.routes.phoneCompleteProfile,
+          `${opts.routes.externalLogin}/**`,
+          opts.routes.externalExchange,
+          opts.routes.externalCompleteProfile,
+          `${opts.routes.admin}/**`
+        ]
+      }
+    );
+    nuxt.options.alias["#huia-headless-auth"] = resolve("runtime/types");
+    addServerImportsDir(resolve("runtime/server/utils"));
+    addImportsDir(resolve("runtime/app/composables"));
+    if (opts.hydration === "useState") {
+      addPlugin({ src: resolve("runtime/app/plugins/session.server"), mode: "server" });
+    }
+    addRouteMiddleware({
+      name: "auth",
+      path: resolve("runtime/app/middleware/auth"),
+      global: opts.middleware.global
+    });
+    addServerHandler({ route: opts.routes.register, method: "post", handler: resolve("runtime/server/routes/auth/register.post") });
+    addServerHandler({ route: opts.routes.login, method: "post", handler: resolve("runtime/server/routes/auth/login.post") });
+    addServerHandler({ route: opts.routes.logout, method: "post", handler: resolve("runtime/server/routes/auth/logout.post") });
+    addServerHandler({ route: opts.routes.refresh, method: "post", handler: resolve("runtime/server/routes/auth/refresh.post") });
+    addServerHandler({ route: opts.routes.session, method: "get", handler: resolve("runtime/server/routes/auth/session.get") });
+    addServerHandler({ route: opts.routes.confirmEmail, method: "get", handler: resolve("runtime/server/routes/auth/confirm-email.get") });
+    addServerHandler({ route: opts.routes.resendConfirmation, method: "post", handler: resolve("runtime/server/routes/auth/resend-confirmation.post") });
+    addServerHandler({ route: opts.routes.forgotPassword, method: "post", handler: resolve("runtime/server/routes/auth/forgot-password.post") });
+    addServerHandler({ route: opts.routes.resetPassword, method: "post", handler: resolve("runtime/server/routes/auth/reset-password.post") });
+    addServerHandler({ route: opts.routes.phoneStart, method: "post", handler: resolve("runtime/server/routes/auth/phone/start.post") });
+    addServerHandler({ route: opts.routes.phoneVerify, method: "post", handler: resolve("runtime/server/routes/auth/phone/verify.post") });
+    addServerHandler({ route: opts.routes.phoneCompleteProfile, method: "post", handler: resolve("runtime/server/routes/auth/phone/complete-profile.post") });
+    addServerHandler({ route: `${opts.routes.externalLogin}/:provider`, method: "get", handler: resolve("runtime/server/routes/auth/external/[provider].get") });
+    addServerHandler({ route: opts.routes.externalExchange, method: "post", handler: resolve("runtime/server/routes/auth/external/exchange.post") });
+    addServerHandler({ route: opts.routes.externalCompleteProfile, method: "post", handler: resolve("runtime/server/routes/auth/external/complete-profile.post") });
+    addServerHandler({ route: `${opts.routes.admin}/**`, handler: resolve("runtime/server/routes/auth/admin") });
+    addServerHandler({ middleware: true, handler: resolve("runtime/server/middleware/session.context") });
+    nuxt.hook("prepare:types", ({ references }) => {
+      references.push({ path: resolve("runtime/types.d.ts") });
+    });
+  }
+});
+
+export { module$1 as default };

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

@@ -0,0 +1,107 @@
+import type { UserClaims } from '../../types.js';
+export interface HuiaLoginResult {
+    ok: boolean;
+    user?: UserClaims;
+    /** The raw problem-details body from Huia.Headless when `ok` is false. */
+    error?: unknown;
+}
+/** Either a completed sign-in, or a first-time sign-up still needing a first/last name. */
+export type HuiaFlowResult = {
+    ok: true;
+    requiresProfile: false;
+    user: UserClaims;
+} | {
+    ok: true;
+    requiresProfile: true;
+    flowId: string;
+    email?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+} | {
+    ok: false;
+    requiresProfile: false;
+    error: unknown;
+};
+export declare function useHuia(): {
+    user: import("vue").ComputedRef<UserClaims | null>;
+    loggedIn: import("vue").ComputedRef<boolean>;
+    session: Readonly<import("vue").Ref<{
+        readonly user?: {
+            readonly [x: string]: Readonly<unknown>;
+            readonly sub: string;
+            readonly email?: string | undefined;
+            readonly firstName?: string | undefined;
+            readonly lastName?: string | undefined;
+            readonly roles?: readonly string[] | undefined;
+        } | undefined;
+        readonly loggedIn?: boolean | undefined;
+        readonly expiresAt?: number | undefined;
+    }, {
+        readonly user?: {
+            readonly [x: string]: Readonly<unknown>;
+            readonly sub: string;
+            readonly email?: string | undefined;
+            readonly firstName?: string | undefined;
+            readonly lastName?: string | undefined;
+            readonly roles?: readonly string[] | undefined;
+        } | undefined;
+        readonly loggedIn?: boolean | undefined;
+        readonly expiresAt?: number | undefined;
+    }>>;
+    hasRole: (role: string) => boolean;
+    hasAnyRole: (...roles: string[]) => boolean;
+    /** Creates an account. Does not sign in — call `login()` afterward (once any required email confirmation is done). */
+    register(opts: {
+        email: string;
+        password: string;
+        firstName: string;
+        lastName: string;
+    }): Promise<{
+        ok: boolean;
+        error?: unknown;
+    }>;
+    /** Signs in with email + password (and, when required, a `twoFactorCode`/`twoFactorRecoveryCode`). */
+    login(opts: {
+        email: string;
+        password: string;
+        twoFactorCode?: string;
+        twoFactorRecoveryCode?: string;
+    }): Promise<HuiaLoginResult>;
+    /** Local logout — clears the session cookie and the stored tokens. Never redirects. */
+    logout: () => Promise<void>;
+    /** Sends a one-time SMS code and returns an opaque `flowId` — pass it to `verifyPhoneLogin`. */
+    startPhoneLogin(opts: {
+        phoneNumber: string;
+        country?: string;
+        captchaResponse?: string;
+    }): Promise<{
+        ok: boolean;
+        flowId?: string;
+        error?: unknown;
+    }>;
+    /** Verifies a phone one-time code. Signs in directly, or reports a first-time sign-up needs a name. */
+    verifyPhoneLogin(opts: {
+        flowId: string;
+        code: string;
+    }): Promise<HuiaFlowResult>;
+    /** Completes a first-time phone sign-up with a name, then signs in. */
+    completePhoneProfile(opts: {
+        flowId: string;
+        firstName: string;
+        lastName: string;
+    }): Promise<HuiaLoginResult>;
+    /**
+     * The URL to navigate the browser to (a plain link, not a fetch call) to start signing in with
+     * `provider` (must match a name configured on the Huia.Headless tenant). `returnTo` is a
+     * same-origin path within this app, resolved once the provider round trip completes.
+     */
+    externalLoginHref(provider: string, returnTo?: string): string;
+    /** Exchanges the one-time `code` from the callback URL. Signs in directly, or needs a name for a new sign-up. */
+    exchangeExternalCode(code: string): Promise<HuiaFlowResult>;
+    /** Completes a first-time external sign-up with a name, then signs in. */
+    completeExternalProfile(opts: {
+        code: string;
+        firstName: string;
+        lastName: string;
+    }): Promise<HuiaLoginResult>;
+};

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

@@ -0,0 +1,100 @@
+import { useRequestFetch, useRuntimeConfig } from "#imports";
+import { useUserSession } from "./useUserSession.js";
+export function useHuia() {
+  const { user, loggedIn, session, hasRole, hasAnyRole, fetch: fetchSession, clear } = useUserSession();
+  const paths = useRuntimeConfig().public.huiaHeadless;
+  return {
+    user,
+    loggedIn,
+    session,
+    hasRole,
+    hasAnyRole,
+    /** Creates an account. Does not sign in — call `login()` afterward (once any required email confirmation is done). */
+    async register(opts) {
+      try {
+        await useRequestFetch()(paths.registerPath, { method: "POST", body: opts });
+        return { ok: true };
+      } catch (err) {
+        return { ok: false, error: errorData(err) };
+      }
+    },
+    /** Signs in with email + password (and, when required, a `twoFactorCode`/`twoFactorRecoveryCode`). */
+    async login(opts) {
+      try {
+        const result = await useRequestFetch()(paths.loginPath, { method: "POST", body: opts });
+        await fetchSession();
+        return { ok: true, user: result.user };
+      } catch (err) {
+        return { ok: false, error: errorData(err) };
+      }
+    },
+    /** Local logout — clears the session cookie and the stored tokens. Never redirects. */
+    logout: clear,
+    /** Sends a one-time SMS code and returns an opaque `flowId` — pass it to `verifyPhoneLogin`. */
+    async startPhoneLogin(opts) {
+      try {
+        const result = await useRequestFetch()(paths.phoneStartPath, { method: "POST", body: opts });
+        return { ok: true, flowId: result.flowId };
+      } catch (err) {
+        return { ok: false, error: errorData(err) };
+      }
+    },
+    /** Verifies a phone one-time code. Signs in directly, or reports a first-time sign-up needs a name. */
+    async verifyPhoneLogin(opts) {
+      try {
+        const result = await useRequestFetch()(paths.phoneVerifyPath, { method: "POST", body: opts });
+        if ("requiresProfile" in result) {
+          return { ok: true, requiresProfile: true, flowId: result.flowId };
+        }
+        await fetchSession();
+        return { ok: true, requiresProfile: false, user: result.user };
+      } catch (err) {
+        return { ok: false, requiresProfile: false, error: errorData(err) };
+      }
+    },
+    /** Completes a first-time phone sign-up with a name, then signs in. */
+    async completePhoneProfile(opts) {
+      try {
+        const result = await useRequestFetch()(paths.phoneCompleteProfilePath, { method: "POST", body: opts });
+        await fetchSession();
+        return { ok: true, user: result.user };
+      } catch (err) {
+        return { ok: false, error: errorData(err) };
+      }
+    },
+    /**
+     * The URL to navigate the browser to (a plain link, not a fetch call) to start signing in with
+     * `provider` (must match a name configured on the Huia.Headless tenant). `returnTo` is a
+     * same-origin path within this app, resolved once the provider round trip completes.
+     */
+    externalLoginHref(provider, returnTo = "/") {
+      return `${paths.externalLoginPath}/${encodeURIComponent(provider)}?returnUrl=${encodeURIComponent(returnTo)}`;
+    },
+    /** Exchanges the one-time `code` from the callback URL. Signs in directly, or needs a name for a new sign-up. */
+    async exchangeExternalCode(code) {
+      try {
+        const result = await useRequestFetch()(paths.externalExchangePath, { method: "POST", body: { code } });
+        if ("requiresProfile" in result) {
+          return { ok: true, requiresProfile: true, flowId: result.code, email: result.email, firstName: result.firstName, lastName: result.lastName };
+        }
+        await fetchSession();
+        return { ok: true, requiresProfile: false, user: result.user };
+      } catch (err) {
+        return { ok: false, requiresProfile: false, error: errorData(err) };
+      }
+    },
+    /** Completes a first-time external sign-up with a name, then signs in. */
+    async completeExternalProfile(opts) {
+      try {
+        const result = await useRequestFetch()(paths.externalCompleteProfilePath, { method: "POST", body: opts });
+        await fetchSession();
+        return { ok: true, user: result.user };
+      } catch (err) {
+        return { ok: false, error: errorData(err) };
+      }
+    }
+  };
+}
+function errorData(err) {
+  return err?.data ?? err;
+}

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

@@ -0,0 +1,24 @@
+import type { HeadlessAdminUser, HeadlessAdminRole, HeadlessAdminUsersPage, CreateHeadlessAdminUserRequest, UpdateHeadlessAdminUserRequest } from 'huia-auth-core';
+export declare function useHuiaAdmin(): {
+    listUsers(params?: {
+        page?: number;
+        pageSize?: number;
+        search?: string;
+    }): Promise<HeadlessAdminUsersPage>;
+    getUser(id: string): Promise<HeadlessAdminUser>;
+    createUser(body: CreateHeadlessAdminUserRequest): Promise<HeadlessAdminUser>;
+    updateUser(id: string, body: UpdateHeadlessAdminUserRequest): Promise<HeadlessAdminUser>;
+    deleteUser(id: string): Promise<void>;
+    getUserRoles(id: string): Promise<string[]>;
+    addUserRole(id: string, role: string): Promise<void>;
+    removeUserRole(id: string, role: string): Promise<void>;
+    lockUser(id: string): Promise<void>;
+    unlockUser(id: string): Promise<void>;
+    listRoles(): Promise<{
+        data: HeadlessAdminRole[];
+    }>;
+    getRole(id: string): Promise<HeadlessAdminRole>;
+    createRole(name: string): Promise<HeadlessAdminRole>;
+    updateRole(id: string, name: string): Promise<HeadlessAdminRole>;
+    deleteRole(id: string): Promise<void>;
+};

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

@@ -0,0 +1,58 @@
+import { useRequestFetch, useRuntimeConfig } from "#imports";
+export function useHuiaAdmin() {
+  const paths = useRuntimeConfig().public.huiaHeadless;
+  const adminPath = paths.adminPath ?? "/auth/admin";
+  const fetch = useRequestFetch();
+  return {
+    async listUsers(params) {
+      const q = new URLSearchParams();
+      if (params?.page) q.set("page", String(params.page));
+      if (params?.pageSize) q.set("pageSize", String(params.pageSize));
+      if (params?.search) q.set("search", params.search);
+      const qs = q.toString() ? `?${q}` : "";
+      return await fetch(`${adminPath}/users${qs}`, { method: "GET" });
+    },
+    async getUser(id) {
+      return await fetch(`${adminPath}/users/${encodeURIComponent(id)}`, { method: "GET" });
+    },
+    async createUser(body) {
+      return await fetch(`${adminPath}/users`, { method: "POST", body });
+    },
+    async updateUser(id, body) {
+      return await fetch(`${adminPath}/users/${encodeURIComponent(id)}`, { method: "PUT", body });
+    },
+    async deleteUser(id) {
+      await fetch(`${adminPath}/users/${encodeURIComponent(id)}`, { method: "DELETE" });
+    },
+    async getUserRoles(id) {
+      return await fetch(`${adminPath}/users/${encodeURIComponent(id)}/roles`, { method: "GET" });
+    },
+    async addUserRole(id, role) {
+      await fetch(`${adminPath}/users/${encodeURIComponent(id)}/roles`, { method: "POST", body: { role } });
+    },
+    async removeUserRole(id, role) {
+      await fetch(`${adminPath}/users/${encodeURIComponent(id)}/roles/${encodeURIComponent(role)}`, { method: "DELETE" });
+    },
+    async lockUser(id) {
+      await fetch(`${adminPath}/users/${encodeURIComponent(id)}/lock`, { method: "POST" });
+    },
+    async unlockUser(id) {
+      await fetch(`${adminPath}/users/${encodeURIComponent(id)}/unlock`, { method: "POST" });
+    },
+    async listRoles() {
+      return await fetch(`${adminPath}/roles`, { method: "GET" });
+    },
+    async getRole(id) {
+      return await fetch(`${adminPath}/roles/${encodeURIComponent(id)}`, { method: "GET" });
+    },
+    async createRole(name) {
+      return await fetch(`${adminPath}/roles`, { method: "POST", body: { name } });
+    },
+    async updateRole(id, name) {
+      return await fetch(`${adminPath}/roles/${encodeURIComponent(id)}`, { method: "PUT", body: { name } });
+    },
+    async deleteRole(id) {
+      await fetch(`${adminPath}/roles/${encodeURIComponent(id)}`, { method: "DELETE" });
+    }
+  };
+}

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

@@ -0,0 +1,48 @@
+import type { UserClaims } from '../../types.js';
+export declare function useUserSession(): {
+    session: Readonly<import("vue").Ref<{
+        readonly user?: {
+            readonly [x: string]: Readonly<unknown>;
+            readonly sub: string;
+            readonly email?: string | undefined;
+            readonly firstName?: string | undefined;
+            readonly lastName?: string | undefined;
+            readonly roles?: readonly string[] | undefined;
+        } | undefined;
+        readonly loggedIn?: boolean | undefined;
+        readonly expiresAt?: number | undefined;
+    }, {
+        readonly user?: {
+            readonly [x: string]: Readonly<unknown>;
+            readonly sub: string;
+            readonly email?: string | undefined;
+            readonly firstName?: string | undefined;
+            readonly lastName?: string | undefined;
+            readonly roles?: readonly string[] | undefined;
+        } | undefined;
+        readonly loggedIn?: boolean | undefined;
+        readonly expiresAt?: number | undefined;
+    }>>;
+    user: import("vue").ComputedRef<UserClaims | null>;
+    loggedIn: import("vue").ComputedRef<boolean>;
+    expiresAt: import("vue").ComputedRef<number | undefined>;
+    /**
+     * Re-read the server session (after login, on tab focus, …). Client-only: called as the second
+     * nested `await` inside a login/exchange flow (e.g. `useHuia().login()` → `fetch()` →
+     * `useRequestFetch()`), which during SSR is one level deeper than Vue's `withAsyncContext` — set up
+     * only for a page's own top-level `await` — keeps the Nuxt app context alive for; `useRequestFetch()`
+     * then throws `NUXT_E1001` instead of refreshing anything. Skipping server-side is safe: the session
+     * cookie a login/exchange call sets is already on the response by the time `fetch()` runs, so a
+     * follow-up navigation (the usual next step) picks up the fresh session on its own next request
+     * regardless of whether this reactive `session` ref got updated first.
+     */
+    fetch(): Promise<void>;
+    /** Full logout via the server route (clears storage + cookies). Never redirects. */
+    clear(): Promise<void>;
+    /** Optimistic local reset only (UI); does not touch the server. */
+    clearLocal(): void;
+    /** Whether the signed-in user has `role` (requires Huia.Headless's `identity/me` to report it). */
+    hasRole(role: string): boolean;
+    /** Whether the signed-in user has at least one of `roles`. */
+    hasAnyRole(...roles: string[]): boolean;
+};