@meistrari/auth-nuxt 3.10.0 → 3.11.0

package/README.md

@@ -32,9 +32,9 @@ export default defineNuxtConfig({
 })
 ```
 
-Application auth auto-imports `useTelaApplicationAuth()`, registers `<TelaRole>`, installs role directives, and adds SDK routes under `/auth/*` plus `/api/auth/api-key/**`. `useTelaApiKey()` is also available; in application mode it targets the local API key proxy for app-scoped user API keys.
+Application auth auto-imports `useTelaApplicationAuth()` and the application-mode `useTelaOrganization()`, registers `<TelaRole>`, installs role directives, and adds SDK routes under `/auth/*` plus `/api/auth/api-key/**` and `/api/auth/organization/**`. `useTelaApiKey()` is also available; in application mode it targets the local API key proxy for app-scoped user API keys.
 
-First-party auth auto-imports `useTelaSession()`, `useTelaOrganization()`, and `useTelaApiKey()`.
+First-party auth auto-imports `useTelaSession()`, `useTelaSessionAssurance()`, `useTelaOrganization()`, and `useTelaApiKey()`.
 
 ## API Reference
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@meistrari/auth-nuxt",
   "configKey": "telaAuth",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/module.mjs

@@ -28,6 +28,11 @@ const module$1 = defineNuxtModule({
         as: "useTelaOrganization",
         from: resolver.resolve("runtime/composables/application/organization")
       });
+      addImports({
+        name: "useTelaSessionAssurance",
+        as: "useTelaSessionAssurance",
+        from: resolver.resolve("runtime/composables/application/session-assurance")
+      });
       addComponent({
         name: "TelaRole",
         filePath: resolver.resolve("./runtime/components/tela-role.vue"),
@@ -110,6 +115,11 @@ const module$1 = defineNuxtModule({
       as: "useTelaOrganization",
       from: resolver.resolve("runtime/composables/organization")
     });
+    addImports({
+      name: "useTelaAdmin",
+      as: "useTelaAdmin",
+      from: resolver.resolve("runtime/composables/admin")
+    });
     addPlugin(resolver.resolve("./runtime/plugins/handshake"));
   }
 });

package/dist/runtime/composables/admin.d.ts

@@ -0,0 +1,49 @@
+import type { AdminOrganization, CreateAdminOrganizationOptions, GetAdminOrganizationOptions, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminUsersOptions, ListAdminUsersResult, UpdateAdminOrganizationOptions } from '@meistrari/auth-core';
+export interface UseTelaAdminReturn {
+    /**
+     * Lists users from the Better Auth `user` table as a global admin.
+     * @param options - Pagination, search, filter, and ordering options
+     * @returns The paginated user listing
+     */
+    listUsers: (options?: ListAdminUsersOptions) => Promise<ListAdminUsersResult>;
+    /**
+     * Lists all organizations as a global admin, optionally with member and
+     * application previews and totals when a preview size is requested.
+     * @param options - Pagination, ordering, search, and preview options
+     * @returns The paginated organization listing
+     */
+    listOrganizations: (options?: ListAdminOrganizationsOptions) => Promise<ListAdminOrganizationsResult>;
+    /**
+     * Fetches a single organization as a global admin, optionally with adjacent
+     * IDs in the listing defined by the ordering options.
+     * @param options - Organization ID and listing adjacency options
+     * @returns The organization
+     */
+    getOrganization: (options: GetAdminOrganizationOptions) => Promise<AdminOrganization>;
+    /**
+     * Lists active members for a single organization as a global admin.
+     * @param options - Organization ID and pagination options
+     * @returns The paginated organization member listing
+     */
+    listOrganizationMembers: (options: ListAdminOrganizationMembersOptions) => Promise<ListAdminOrganizationMembersResult>;
+    /**
+     * Creates an organization as a global admin without joining it.
+     * @param options - Organization name and optional slug, logo, metadata, and settings
+     * @returns The created organization
+     */
+    createOrganization: (options: CreateAdminOrganizationOptions) => Promise<AdminOrganization>;
+    /**
+     * Updates an organization's profile and settings as a global admin.
+     * @param options - Organization ID and the fields to update
+     * @returns The updated organization
+     */
+    updateOrganization: (options: UpdateAdminOrganizationOptions) => Promise<AdminOrganization>;
+}
+/**
+ * Composable for global admin operations.
+ *
+ * All operations require the authenticated user to hold the global admin role.
+ *
+ * @returns An object containing admin management functions.
+ */
+export declare function useTelaAdmin(): UseTelaAdminReturn;

package/dist/runtime/composables/admin.js

@@ -0,0 +1,32 @@
+import { useCookie, useRuntimeConfig } from "#app";
+import { createNuxtAuthClient } from "../shared.js";
+export function useTelaAdmin() {
+  const { jwtCookieName, apiUrl } = useRuntimeConfig().public.telaAuth;
+  const authClient = createNuxtAuthClient(apiUrl, () => useCookie(jwtCookieName).value ?? null);
+  async function listUsers(options) {
+    return await authClient.admin.listUsers(options);
+  }
+  async function listOrganizations(options) {
+    return await authClient.admin.listOrganizations(options);
+  }
+  async function getOrganization(options) {
+    return await authClient.admin.getOrganization(options);
+  }
+  async function listOrganizationMembers(options) {
+    return await authClient.admin.listOrganizationMembers(options);
+  }
+  async function createOrganization(options) {
+    return await authClient.admin.createOrganization(options);
+  }
+  async function updateOrganization(options) {
+    return await authClient.admin.updateOrganization(options);
+  }
+  return {
+    listUsers,
+    listOrganizations,
+    getOrganization,
+    listOrganizationMembers,
+    createOrganization,
+    updateOrganization
+  };
+}

package/dist/runtime/composables/application/auth.d.ts

@@ -1,5 +1,77 @@
 import type { Ref } from 'vue';
 import type { FullOrganization, User } from '@meistrari/auth-core';
+export interface UseTelaApplicationAuthReturn {
+    /** Reactive reference to the current user. Null if not authenticated. */
+    user: Ref<User | null>;
+    /** Reactive reference to the active organization. Null if not authenticated. */
+    activeOrganization: Ref<FullOrganization | null>;
+    /**
+     * Initiates the OAuth 2.0 authorization flow with PKCE.
+     *
+     * Calls the server route to generate state and challenge. The server stores the
+     * verifier securely and returns only the challenge and state to the client.
+     * Then redirects to the auth dashboard login page.
+     *
+     * @throws {AuthorizationFlowError} If called on the server
+     */
+    login: () => Promise<void>;
+    /**
+     * Logs out the current user.
+     *
+     * Clears all authentication cookies and session state.
+     * After logout, the user will need to login again to access protected resources.
+     * Note: Code verifier cookies expire automatically after 10 minutes.
+     */
+    logout: () => Promise<void>;
+    /**
+     * Initializes or restores the user session.
+     *
+     * @deprecated The SDK's Nuxt plugin handles session restoration and background
+     * token refresh automatically. On app startup it hydrates `user` and
+     * `activeOrganization` via `/auth/whoami` (client) or `whoAmI` (server) and
+     * schedules refreshes ahead of access-token expiry. Calling this function
+     * is redundant in normal usage and will be removed in a future release.
+     *
+     * Validates the existing access token and triggers a refresh only if it is
+     * expired or within 1 minute of expiry.
+     *
+     * @throws {UserNotLoggedInError} If no access token is found in cookies
+     * @throws {RefreshTokenExpiredError} If tokens are missing, expired, or cannot be refreshed
+     */
+    initSession: () => Promise<void>;
+    /**
+     * Lists the organizations the user can access through this application.
+     *
+     * @deprecated Use `useTelaOrganization().listOrganizations()` instead.
+     * @returns The accessible organizations.
+     */
+    getAvailableOrganizations: () => Promise<FullOrganization[]>;
+    /**
+     * Switches the active organization.
+     *
+     * @deprecated Use `useTelaOrganization().setActiveOrganization(organizationId)` instead.
+     * @param organizationId - The id of the organization to make active.
+     */
+    switchOrganization: (organizationId: string) => Promise<void>;
+    /**
+     * Refreshes the access token using the refresh token.
+     *
+     * Calls the server route which exchanges the refresh token (stored in httponly cookie)
+     * for new access and refresh tokens. The server updates the cookies and returns
+     * the user and organization data.
+     *
+     * @throws {RefreshTokenExpiredError} If no refresh token is available or refresh fails
+     */
+    refreshToken: () => Promise<void>;
+    /**
+     * Retrieves the current access token.
+     * If the token is expired, or close to expiry, it will be refreshed automatically.
+     *
+     * @returns The current access token
+     * @throws {RefreshTokenExpiredError} If the token is expired and cannot be refreshed
+     */
+    getToken: () => Promise<string | null | undefined>;
+}
 /**
  * Composable for managing Tela application authentication with OAuth 2.0 PKCE flow
  *
@@ -32,20 +104,4 @@ import type { FullOrganization, User } from '@meistrari/auth-core';
  * await auth.logout()
  * ```
  */
-export declare function useTelaApplicationAuth(): {
-    user: Ref<User | null>;
-    activeOrganization: Ref<FullOrganization | null>;
-    login: () => Promise<void>;
-    logout: () => Promise<void>;
-    initSession: () => Promise<void>;
-    /**
-     * @deprecated Use `useTelaOrganization().listOrganizations()` instead.
-     */
-    getAvailableOrganizations: () => Promise<FullOrganization[]>;
-    /**
-     * @deprecated Use `useTelaOrganization().setActiveOrganization(organizationId)` instead.
-     */
-    switchOrganization: (organizationId: string) => Promise<void>;
-    refreshToken: () => Promise<void>;
-    getToken: () => Promise<string | null | undefined>;
-};
+export declare function useTelaApplicationAuth(): UseTelaApplicationAuthReturn;

package/dist/runtime/composables/application/auth.js

@@ -92,13 +92,6 @@ export function useTelaApplicationAuth() {
     activeOrganization: state.activeOrganization,
     login,
     logout,
-    /**
-     * @deprecated The SDK's Nuxt plugin handles session restoration and background
-     * token refresh automatically. On app startup it hydrates `user` and
-     * `activeOrganization` via `/auth/whoami` (client) or `whoAmI` (server) and
-     * schedules refreshes ahead of access-token expiry. Calling this function
-     * is redundant in normal usage and will be removed in a future release.
-     */
     initSession,
     getAvailableOrganizations,
     switchOrganization,

package/dist/runtime/composables/application/organization.d.ts

@@ -1,27 +1,205 @@
 import type { CreateTeamPayload, FullOrganization, Invitation, InviteUserToOrganizationOptions, ListMembersOptions, Member, RemoveUserFromOrganizationOptions, Team, TeamMember, UpdateMemberRoleOptions, UpdateTeamPayload } from '@meistrari/auth-core';
 import type { Ref } from 'vue';
 export interface UseTelaApplicationOrganizationReturn {
+    /** Reactive reference to the active organization with members, invitations, and teams. */
     activeOrganization: Ref<FullOrganization | null>;
+    /** Reactive reference to the current user's membership in the active organization. */
     activeMember: Ref<Member | null>;
+    /**
+     * Re-fetches the full active organization (members, invitations, teams) from
+     * the Auth API and writes it back into `activeOrganization` state.
+     *
+     * Use this to reload the active organization on demand — for instance after
+     * mutations performed outside this composable. It is a no-op that returns
+     * `undefined` when there is no active organization id in state yet.
+     *
+     * @returns The refreshed active organization, or `undefined` when none is active.
+     */
     getActiveOrganization: () => Promise<FullOrganization | undefined>;
+    /**
+     * Alias for {@link listOrganizations}.
+     *
+     * @returns The organizations the user can access through this application.
+     */
     getAvailableOrganizations: () => Promise<FullOrganization[]>;
+    /**
+     * Lists the organizations the user can access through this application.
+     *
+     * This is not every organization the user belongs to: the Auth API only
+     * returns organizations the user is entitled to within the current
+     * application, so it doubles as the set of valid targets for
+     * {@link setActiveOrganization}.
+     *
+     * @returns The organizations accessible through this application.
+     */
     listOrganizations: () => Promise<FullOrganization[]>;
+    /**
+     * Switches the active organization via the `/auth/switch-organization` server
+     * route, then updates `user`, `activeOrganization`, and session assurance from
+     * the response.
+     *
+     * @param id - The id of the organization to make active.
+     */
     setActiveOrganization: (id: string) => Promise<void>;
+    /**
+     * Lists members of the active organization.
+     *
+     * Returns members on demand without touching `activeOrganization` state — the
+     * mutating methods here (invite/accept/remove/update-role) are what keep the
+     * cached `activeOrganization.members` in sync.
+     *
+     * @param options - Optional filtering/pagination options.
+     * @returns The active organization's members.
+     */
     listMembers: (options?: ListMembersOptions) => Promise<Member[]>;
+    /**
+     * Fetches the current user's own member record in the active organization
+     * (their role and membership metadata) and caches it in `activeMember` state.
+     *
+     * Useful for role-gating UI, since it reflects the caller's role in the
+     * organization currently active for this application.
+     *
+     * @returns The caller's member record in the active organization.
+     */
     getActiveMember: () => Promise<Member>;
+    /**
+     * Invites a user to the active organization.
+     *
+     * The invitation is created **application-scoped**: the Auth API tags it with
+     * the application derived from the access token, so accepting it later grants
+     * the invitee access to this application. The new invitation is appended to
+     * `activeOrganization.invitations` in local state.
+     *
+     * @param options - Invitee email, role, and optional team/resend settings.
+     * @returns The created invitation.
+     */
     inviteUserToOrganization: (options: InviteUserToOrganizationOptions) => Promise<Invitation>;
+    /**
+     * Accepts an invitation by id.
+     *
+     * For an application-scoped invitation, accepting **grants the user access to
+     * the associated application** (the Auth API writes an entitlement rule) and
+     * returns that application's `homeUrl`. For an invitation with no application,
+     * `homeUrl` is `null`. The active organization's member list is refreshed
+     * afterwards.
+     *
+     * @param id - The invitation id to accept.
+     * @returns An object with `homeUrl`: the application's home URL, or `null`.
+     */
     acceptInvitation: (id: string) => Promise<{
         homeUrl: string | null;
     }>;
+    /**
+     * Cancels a pending invitation before it is accepted, revoking it so the link
+     * can no longer be used, and removes it from `activeOrganization.invitations`
+     * in local state.
+     *
+     * @param id - The invitation id to cancel.
+     */
     cancelInvitation: (id: string) => Promise<void>;
+    /**
+     * Removes a member from the active organization, revoking their access, and
+     * prunes them from `activeOrganization.members` in local state.
+     *
+     * Since access to this application is granted through organization membership,
+     * removing the member also revokes their access to the application through
+     * this organization.
+     *
+     * @param options - Identifies the member to remove (by `memberId`).
+     */
     removeUserFromOrganization: (options: RemoveUserFromOrganizationOptions) => Promise<void>;
+    /**
+     * Changes a member's role in the active organization, then re-fetches the full
+     * member list and writes it back into `activeOrganization.members`.
+     *
+     * The role drives that member's permissions for organization operations, and
+     * the role-aware UI helpers (`<TelaRole>`, `v-if-role`, `v-show-role`) read
+     * from it.
+     *
+     * @param options - Identifies the member and the new role to assign.
+     */
     updateMemberRole: (options: UpdateMemberRoleOptions) => Promise<void>;
+    /**
+     * Creates a team in the active organization and appends it to
+     * `activeOrganization.teams` in local state.
+     *
+     * @param payload - The team creation payload.
+     * @returns The created team.
+     */
     createTeam: (payload: CreateTeamPayload) => Promise<Team>;
+    /**
+     * Updates a team and replaces it in `activeOrganization.teams` in local state.
+     *
+     * @param id - The team id to update.
+     * @param payload - The team update payload.
+     * @returns The updated team.
+     */
     updateTeam: (id: string, payload: UpdateTeamPayload) => Promise<Team>;
+    /**
+     * Deletes a team and removes it from `activeOrganization.teams` in local state.
+     *
+     * @param id - The team id to delete.
+     */
     deleteTeam: (id: string) => Promise<void>;
+    /**
+     * Fetches teams of the active organization on demand.
+     *
+     * Unlike {@link createTeam}/{@link updateTeam}/{@link deleteTeam}, this does
+     * not read from or write to the cached `activeOrganization.teams`; it always
+     * hits the Auth API.
+     *
+     * @returns The active organization's teams.
+     */
     listTeams: () => Promise<Team[]>;
+    /**
+     * Lists the users belonging to a team within the active organization.
+     *
+     * Team members are a subset of organization members; the team must belong to
+     * the active organization.
+     *
+     * @param id - The team id to list members for.
+     * @returns The team's members.
+     */
     listTeamMembers: (id: string) => Promise<TeamMember[]>;
+    /**
+     * Adds an existing organization member to a team.
+     *
+     * The user must already be a member of the active organization — this assigns
+     * them to a team within it, it does not invite them to the organization. The
+     * cached `activeOrganization.teams` is left untouched.
+     *
+     * @param teamId - The team to add the user to.
+     * @param userId - The id of the organization member to add.
+     * @returns The created team membership.
+     */
     addTeamMember: (teamId: string, userId: string) => Promise<TeamMember>;
+    /**
+     * Removes a user from a team without removing them from the organization.
+     *
+     * The user keeps their organization membership (and application access); only
+     * their team assignment is dropped.
+     *
+     * @param teamId - The team to remove the user from.
+     * @param userId - The id of the user to remove from the team.
+     */
     removeTeamMember: (teamId: string, userId: string) => Promise<void>;
 }
+/**
+ * Composable for managing organizations in application authentication mode.
+ *
+ * Most methods call the Auth API through an application-scoped client built from
+ * the current application access token (`tela-access-token`). `setActiveOrganization`
+ * is the exception: it goes through the Nuxt server route `/auth/switch-organization`
+ * rather than that client, but the token is still forwarded via the
+ * `tela-access-token` cookie, so every method stays application-scoped. Scoping to
+ * the configured application is automatic: the Auth API derives the application
+ * from the token's audience (`aud`) claim, so callers never pass an `applicationId`.
+ * Invitations created here are tagged with the application, and accepting an
+ * application-scoped invitation grants the user access to that application.
+ *
+ * Methods that mutate organization data also keep the local `activeOrganization`
+ * state in sync (members, invitations, teams) so the UI updates without a refetch.
+ *
+ * @returns Organization state refs and management methods.
+ */
 export declare function useTelaOrganization(): UseTelaApplicationOrganizationReturn;

package/dist/runtime/composables/application/session-assurance.d.ts

@@ -0,0 +1,27 @@
+import type { Ref } from 'vue';
+import type { JWTPayload } from '@meistrari/auth-core';
+export type ApplicationSessionAssuranceValue = JWTPayload['assurance'] | null;
+export interface UseTelaApplicationSessionAssuranceReturn {
+    /** Read-only reactive reference to the current application session assurance. */
+    assurance: Readonly<Ref<ApplicationSessionAssuranceValue>>;
+    /**
+     * Refreshes the application auth tokens through the `/auth/refresh` server
+     * route and updates `user`, `activeOrganization`, and the session assurance
+     * from the response.
+     *
+     * @returns The current session assurance after refreshing.
+     */
+    refreshSessionAssurance: () => Promise<ApplicationSessionAssuranceValue>;
+}
+/**
+ * Read-only composable for inspecting the application session assurance.
+ *
+ * In application authentication mode this composable only reads the current
+ * assurance and can refresh the application auth tokens to pick up a newly
+ * stepped-up assurance value. First-party step-up/write actions
+ * (`stepUpWithPassword`, `sendOtp`, `verifyOtp`, OAuth step-up) are not available
+ * in application mode.
+ *
+ * @returns The read-only `assurance` ref and `refreshSessionAssurance()`.
+ */
+export declare function useTelaSessionAssurance(): UseTelaApplicationSessionAssuranceReturn;

package/dist/runtime/composables/application/session-assurance.js

@@ -0,0 +1,21 @@
+import { useRequestFetch } from "#app";
+import { readonly } from "vue";
+import { useApplicationSessionState } from "../state.js";
+export function useTelaSessionAssurance() {
+  const { activeOrganization, sessionAssurance, user } = useApplicationSessionState();
+  const assurance = readonly(sessionAssurance);
+  const requestFetch = useRequestFetch();
+  async function refreshSessionAssurance() {
+    const result = await requestFetch("/auth/refresh", {
+      method: "POST"
+    });
+    user.value = result.user;
+    activeOrganization.value = result.organization;
+    sessionAssurance.value = result.assurance;
+    return result.assurance;
+  }
+  return {
+    assurance,
+    refreshSessionAssurance
+  };
+}

package/dist/runtime/server/tsconfig.json

@@ -1,6 +1,6 @@
 {
     "extends": [
-        "../../../../../../node_modules/@meistrari/mise-en-place/tsconfig.base.json",
+        "../../../../../node_modules/@meistrari/mise-en-place/tsconfig.base.json",
         "../../../.nuxt/tsconfig.server.json"
     ],
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/auth-nuxt",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "type": "module",
   "exports": {
     ".": {
@@ -36,7 +36,7 @@
     "docs": "nuxt-module-build prepare && typedoc"
   },
   "dependencies": {
-    "@meistrari/auth-core": "1.21.0",
+    "@meistrari/auth-core": "1.22.0",
     "jose": "6.1.3"
   },
   "peerDependencies": {