@wocha/nuxt

Nuxt 3 module for Wocha authentication using the BFF (Backend-for-Frontend) pattern. OAuth token exchange and refresh happen on Nitro server routes; sessions are stored in encrypted httpOnly cookies.

Install

npm install @wocha/nuxt
# or: pnpm add / yarn add @wocha/nuxt

Peer dependency: Nuxt >=3.10.

Quick start

1. Register the module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ["@wocha/nuxt"],
  wochaAuth: {
    clientId: process.env.WOCHA_CLIENT_ID,
    clientSecret: process.env.WOCHA_CLIENT_SECRET,
    issuer: process.env.WOCHA_ISSUER,
    // Optional:
    apiUrl: process.env.WOCHA_API_URL,
    publicPaths: ["/", "/about"],
  },
});

Environment variables are also read from runtimeConfig when set in nuxt.config.ts or .env:

WOCHA_CLIENT_ID=your-client-id
WOCHA_CLIENT_SECRET=your-client-secret
WOCHA_ISSUER=https://my-tenant.auth.wocha.ai

2. Server routes (auto-registered)

The module registers these Nitro routes:

| Route | Method | Purpose | |-------|--------|---------| | /api/auth/login | GET | Start OAuth login | | /api/auth/callback | GET | OAuth callback | | /api/auth/logout | GET | End session | | /api/auth/session | GET | Public session JSON | | /api/auth/refresh | POST | Refresh tokens | | /api/auth/switch-org | POST | Switch organisation |

3. Protect pages

Add the auth route middleware to protected pages:

<script setup lang="ts">
definePageMeta({ middleware: "auth" });
</script>

Or configure a global middleware name via authMiddlewareName in module options.

4. Composables (auto-imported)

<script setup lang="ts">
const { session, status } = useSession();
const user = useUser();
const { orgId } = useOrg();
const { signIn, signOut, switchOrg, hasPermission } = useWochaAuth();

async function checkAccess() {
  const allowed = await hasPermission({
    resource: { type: "document", id: "doc_123" },
    permission: "read",
  });
}
</script>

<template>
  <div v-if="status === 'authenticated'">
    <p>{{ user?.email }} · {{ orgId }}</p>
    <button @click="signOut()">Sign out</button>
  </div>
  <button v-else @click="signIn()">Sign in</button>
</template>

5. Server routes and middleware

Use server utilities in API routes or server middleware:

// server/api/me.get.ts
export default defineEventHandler(async (event) => {
  const session = await requireSession(event);
  return { user: session.user };
});

Module options

| Option | Default | Description | |--------|---------|-------------| | clientId | — | OAuth client ID (required) | | clientSecret | — | OAuth client secret (required) | | issuer | — | Wocha issuer URL (required) | | authBasePath | /api/auth | Auth route prefix | | publicPaths | ["/"] | Paths skipped by route middleware | | refreshBufferSeconds | 300 | Proactive refresh window | | authMiddlewareName | auth | Registered route middleware name | | enableClientPlugin | true | Hydrate session on client startup | | dpop | false | Enable DPoP sender-constrained tokens |

License

Apache-2.0