@atlasauth/nuxt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atlas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# @atlas/nuxt
+
+The official **Nuxt 3** module for [Atlas](https://atlasauth.net). A thin Nuxt
+binding: the client half is [`@atlas/vue`](../vue) (the `createAtlas()` plugin,
+its composables and components), the server half mirrors
+[`@atlas/nextjs`](../nextjs) — it verifies the `__session` JWT **locally** with
+`@atlas/backend` inside a Nitro middleware and exposes a `getAtlasAuth(event)`
+helper to your server routes.
+
+- **No secrets in the browser.** The client holds only the short-lived session
+  JWT in memory. `jwksUrl` / `issuer` live in the **server-only**
+  `runtimeConfig` and never reach the client bundle.
+- **No round trip on the hot path.** Server verification is local against cached
+  JWKS (§7.3) — the same engine every other Atlas SDK uses.
+
+## Install
+
+```bash
+pnpm add @atlas/nuxt
+```
+
+## Configure
+
+Add the module and set your instance config. Public values (`publishableKey`,
+`frontendApi`) are safe in the client; the verification values go under the
+server-only `runtimeConfig.atlas`.
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@atlas/nuxt'],
+
+  atlas: {
+    // Public — sent to the browser.
+    publishableKey: 'pk_test_...',
+    frontendApi: 'https://your-instance.fapi.atlasauth.net',
+  },
+
+  runtimeConfig: {
+    // Server-only — used by the Nitro side to verify session JWTs.
+    atlas: {
+      jwksUrl: '',   // NUXT_ATLAS_JWKS_URL
+      issuer: '',    // NUXT_ATLAS_ISSUER
+      // authorizedParties: ['https://app.example.com'], // optional azp allowlist
+    },
+    public: {
+      atlas: {
+        publishableKey: '', // NUXT_PUBLIC_ATLAS_PUBLISHABLE_KEY
+        frontendApi: '',    // NUXT_PUBLIC_ATLAS_FRONTEND_API
+      },
+    },
+  },
+})
+```
+
+In production, prefer environment variables (they override the config above):
+
+```bash
+NUXT_PUBLIC_ATLAS_PUBLISHABLE_KEY=pk_live_...
+NUXT_PUBLIC_ATLAS_FRONTEND_API=https://your-instance.fapi.atlasauth.net
+NUXT_ATLAS_JWKS_URL=https://your-instance.fapi.atlasauth.net/.well-known/jwks.json
+NUXT_ATLAS_ISSUER=https://your-instance.fapi.atlasauth.net
+```
+
+## Use in pages and components
+
+Every `@atlas/vue` composable and component is **auto-imported** — no `import`
+line needed.
+
+**Components** (`SignedIn`, `SignedOut`, `Protect`, `SignIn`, `SignUp`,
+`UserButton`, `OrganizationSwitcher`, `UserProfile`, `OrganizationProfile`,
+`AtlasLoading`, `AtlasLoaded`):
+
+```vue
+<template>
+  <AtlasLoading><p>Loading…</p></AtlasLoading>
+
+  <SignedIn>
+    <UserButton />
+    <Protect permission="org:billing:manage">
+      <button>Manage billing</button>
+      <template #fallback><p>Ask an admin.</p></template>
+    </Protect>
+  </SignedIn>
+
+  <SignedOut>
+    <SignIn />
+  </SignedOut>
+</template>
+```
+
+**Composables** (`useUser`, `useSession`, `useAuth`, `useOrganization`,
+`useSignIn`, `useSignUp`, `useFlow`, `useAtlas`):
+
+```vue
+<script setup lang="ts">
+const { isLoaded, isSignedIn, user } = useUser()
+const { userId, getToken, has, signOut } = useAuth()
+
+async function callApi() {
+  const token = await getToken() // always fresh; refreshes if near expiry
+  await $fetch('/api/me', { headers: { Authorization: `Bearer ${token}` } })
+}
+</script>
+```
+
+> `<Protect>` and `has()` decide what a user **sees**, never what they may
+> **do** — seeing is not doing. The server checking the same condition is what
+> actually stops them. See the next section.
+
+## Read auth in a server route
+
+`getAtlasAuth(event)` is auto-imported into every Nitro handler. It returns the
+verified state for the request (memoized — the global middleware already ran the
+verify once).
+
+```ts
+// server/api/me.get.ts
+export default defineEventHandler(async (event) => {
+  const auth = await getAtlasAuth(event)
+
+  if (!auth.isSignedIn) {
+    return { signedIn: false }
+  }
+
+  return {
+    signedIn: true,
+    userId: auth.userId,
+    orgId: auth.orgId,
+    canManageBilling: auth.has({ permission: 'org:billing:manage' }),
+  }
+})
+```
+
+Use `protect()` to hard-stop a route. It throws an HTTP error Nitro maps to a
+status: **401** for an anonymous caller, **403** when signed in but missing the
+role/permission.
+
+```ts
+// server/api/billing.post.ts
+export default defineEventHandler(async (event) => {
+  const auth = await getAtlasAuth(event)
+  auth.protect({ permission: 'org:billing:manage' }) // 401 / 403 as appropriate
+
+  // ...only reached by an authorized caller
+  return { ok: true }
+})
+```
+
+The resolved state is also on `event.context.auth` for any handler or util that
+prefers reading it directly.
+
+### The `AtlasAuth` surface
+
+| field / method                     | description                                                        |
+| ---------------------------------- | ------------------------------------------------------------------ |
+| `userId` / `sessionId`             | the `sub` / `sid` claims, or `null` when signed out                |
+| `orgId` / `orgRole`                | the active organization and role, or `null`                        |
+| `isSignedIn`                       | `true` once a valid token verified                                 |
+| `claims`                           | the raw verified `SessionClaims`, or `null`                        |
+| `has(condition?)`                  | boolean check — `permission` / `role` / `anyPermission` / `allPermissions` |
+| `protect(condition?)`              | assert; throws 401 (signed out) / 403 (insufficient)               |
+
+You can also `import { getAtlasAuth, verifyCarriers, atlasBackend } from '@atlas/nuxt/server'`
+if you prefer explicit imports.
+
+## How it fits together
+
+| layer                | package        | what it does                                                             |
+| -------------------- | -------------- | ----------------------------------------------------------------------- |
+| client plugin        | `@atlas/vue`   | `createAtlas()` installed on the Nuxt Vue app (per request during SSR)   |
+| composables / comps  | `@atlas/vue`   | auto-imported into pages/components                                      |
+| Nitro middleware     | `@atlas/backend` | verifies `__session` once per request → `event.context.auth`          |
+| `getAtlasAuth`       | `@atlas/backend` | the server-route auth helper (local verify, cached JWKS)              |
+
+## Build & test
+
+- **Build:** `pnpm build` (via `@nuxt/module-builder` — emits `dist/module.mjs`
+  and the runtime under `dist/runtime`).
+- **Typecheck:** `pnpm typecheck`.
+- **Test:** `pnpm test` — a vitest suite (`src/runtime/server/auth.test.ts`)
+  covering the Nitro verify helper end-to-end with a real RS256 keypair.
+
+## License
+
+MIT

package/dist/module.cjs

@@ -0,0 +1,5 @@
+module.exports = function(...args) {
+  return import('./module.mjs').then(m => m.default.call(this, ...args))
+}
+const _meta = module.exports.meta = require('./module.json')
+module.exports.getMeta = () => Promise.resolve(_meta)

package/dist/module.d.mts

@@ -0,0 +1,47 @@
+import * as nuxt_schema from 'nuxt/schema';
+
+/**
+ * `@atlasauth/nuxt` — the official Nuxt 3 module for Atlas.
+ *
+ * A thin Nuxt binding: the client half is `@atlasauth/vue` (the `createAtlas()`
+ * plugin, its composables and components), installed app-wide through a Nuxt
+ * plugin and surfaced via auto-imports; the server half mirrors `@atlasauth/nextjs`,
+ * verifying the `__session` JWT locally with `@atlasauth/backend` inside a Nitro
+ * middleware and exposing a `getAtlasAuth(event)` helper to server routes.
+ *
+ * The design mirrors the other framework bindings exactly:
+ *   - the browser holds only the short-lived JWT, never a secret;
+ *   - the server verifies against cached JWKS with no call back to Atlas on the
+ *     hot path (§7.3);
+ *   - `jwksUrl` / `issuer` live in the SERVER-only `runtimeConfig`, never in the
+ *     public config a client bundle can read.
+ */
+interface ModuleOptions {
+    /**
+     * The instance publishable key (`pk_...`). Safe to expose to the browser; it
+     * ends up in `runtimeConfig.public.atlas`. Prefer the
+     * `NUXT_PUBLIC_ATLAS_PUBLISHABLE_KEY` env var in production.
+     */
+    publishableKey?: string;
+    /** The instance's FAPI origin (e.g. `https://fox.fapi.atlas.dev`). Public. */
+    frontendApi?: string;
+    /**
+     * The instance's JWKS URL, used by the Nitro side to verify session JWTs.
+     * SERVER-ONLY — kept in `runtimeConfig.atlas`, never sent to the client.
+     */
+    jwksUrl?: string;
+    /**
+     * Expected token `iss`. SERVER-ONLY. Required for server-side verification —
+     * an unchecked issuer would accept a token from any Atlas instance.
+     */
+    issuer?: string;
+    /**
+     * Optional `azp` allowlist. When set, a token minted for another origin is
+     * refused server-side (§7.3). SERVER-ONLY.
+     */
+    authorizedParties?: string[];
+}
+declare const _default: nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.d.ts

@@ -0,0 +1,47 @@
+import * as nuxt_schema from 'nuxt/schema';
+
+/**
+ * `@atlasauth/nuxt` — the official Nuxt 3 module for Atlas.
+ *
+ * A thin Nuxt binding: the client half is `@atlasauth/vue` (the `createAtlas()`
+ * plugin, its composables and components), installed app-wide through a Nuxt
+ * plugin and surfaced via auto-imports; the server half mirrors `@atlasauth/nextjs`,
+ * verifying the `__session` JWT locally with `@atlasauth/backend` inside a Nitro
+ * middleware and exposing a `getAtlasAuth(event)` helper to server routes.
+ *
+ * The design mirrors the other framework bindings exactly:
+ *   - the browser holds only the short-lived JWT, never a secret;
+ *   - the server verifies against cached JWKS with no call back to Atlas on the
+ *     hot path (§7.3);
+ *   - `jwksUrl` / `issuer` live in the SERVER-only `runtimeConfig`, never in the
+ *     public config a client bundle can read.
+ */
+interface ModuleOptions {
+    /**
+     * The instance publishable key (`pk_...`). Safe to expose to the browser; it
+     * ends up in `runtimeConfig.public.atlas`. Prefer the
+     * `NUXT_PUBLIC_ATLAS_PUBLISHABLE_KEY` env var in production.
+     */
+    publishableKey?: string;
+    /** The instance's FAPI origin (e.g. `https://fox.fapi.atlas.dev`). Public. */
+    frontendApi?: string;
+    /**
+     * The instance's JWKS URL, used by the Nitro side to verify session JWTs.
+     * SERVER-ONLY — kept in `runtimeConfig.atlas`, never sent to the client.
+     */
+    jwksUrl?: string;
+    /**
+     * Expected token `iss`. SERVER-ONLY. Required for server-side verification —
+     * an unchecked issuer would accept a token from any Atlas instance.
+     */
+    issuer?: string;
+    /**
+     * Optional `azp` allowlist. When set, a token minted for another origin is
+     * refused server-side (§7.3). SERVER-ONLY.
+     */
+    authorizedParties?: string[];
+}
+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": "@atlasauth/nuxt",
+  "configKey": "atlas",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "0.8.4",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,72 @@
+import { defineNuxtModule, createResolver, addPlugin, addImports, addComponent, addServerHandler, addServerImports } from '@nuxt/kit';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "@atlasauth/nuxt",
+    configKey: "atlas",
+    compatibility: {
+      nuxt: ">=3.0.0"
+    }
+  },
+  defaults: {
+    publishableKey: "",
+    frontendApi: "",
+    jwksUrl: "",
+    issuer: "",
+    authorizedParties: []
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const publicConfig = nuxt.options.runtimeConfig.public.atlas ?? {};
+    nuxt.options.runtimeConfig.public.atlas = {
+      publishableKey: options.publishableKey || publicConfig.publishableKey || "",
+      frontendApi: options.frontendApi || publicConfig.frontendApi || ""
+    };
+    const privateConfig = nuxt.options.runtimeConfig.atlas ?? {};
+    nuxt.options.runtimeConfig.atlas = {
+      jwksUrl: options.jwksUrl || privateConfig.jwksUrl || "",
+      issuer: options.issuer || privateConfig.issuer || "",
+      authorizedParties: options.authorizedParties?.length ? options.authorizedParties : privateConfig.authorizedParties || []
+    };
+    nuxt.options.build.transpile.push("@atlasauth/vue", "@atlasauth/js", "@atlasauth/authz", resolver.resolve("./runtime"));
+    addPlugin({ src: resolver.resolve("./runtime/plugin"), mode: "all" });
+    const composables = [
+      "useAtlas",
+      "useUser",
+      "useSession",
+      "useAuth",
+      "useOrganization",
+      "useSignIn",
+      "useSignUp",
+      "useFlow"
+    ];
+    for (const name of composables) {
+      addImports({ name, as: name, from: "@atlasauth/vue" });
+    }
+    const components = [
+      "SignedIn",
+      "SignedOut",
+      "AtlasLoading",
+      "AtlasLoaded",
+      "Protect",
+      "SignIn",
+      "SignUp",
+      "UserButton",
+      "OrganizationSwitcher",
+      "UserProfile",
+      "OrganizationProfile"
+    ];
+    for (const name of components) {
+      addComponent({ name, export: name, filePath: "@atlasauth/vue" });
+    }
+    addServerHandler({
+      handler: resolver.resolve("./runtime/server/middleware"),
+      middleware: true
+    });
+    addServerImports([
+      { name: "getAtlasAuth", as: "getAtlasAuth", from: resolver.resolve("./runtime/server/index") }
+    ]);
+  }
+});
+
+export { module as default };

package/dist/runtime/nuxt-shims.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Fallback type declarations for the Nuxt virtual modules this package's runtime
+ * imports from (`#imports`).
+ *
+ * When the module is built with `@nuxt/module-builder` (or consumed inside a
+ * Nuxt app), Nuxt generates the authoritative types for these virtual modules
+ * and they take precedence. This shim only exists so that a standalone
+ * `tsc --noEmit` typecheck of `packages/nuxt` — run outside a Nuxt project —
+ * still resolves the handful of runtime helpers we use, rather than erroring on
+ * an unresolvable `#imports`.
+ *
+ * The signatures are intentionally narrow: only what the runtime touches.
+ */
+declare module '#imports' {
+  /**
+   * The subset of Nuxt's runtime app object our plugin touches. Nuxt's own
+   * generated types supply the full `NuxtApp` when this package is built inside
+   * a Nuxt project; this narrow shape only needs to type the standalone
+   * `tsc --noEmit` so the plugin callback's parameter isn't an implicit `any`.
+   */
+  export interface NuxtApp {
+    vueApp: { use(plugin: unknown): unknown };
+  }
+  /** Register a Nuxt app plugin (function form — the callback receives the app). */
+  export function defineNuxtPlugin<T>(plugin: (nuxtApp: NuxtApp) => T): (nuxtApp: NuxtApp) => T;
+  /** Resolve the merged runtime config (public on the client, public + private on the server). */
+  export function useRuntimeConfig(): {
+    public: {
+      atlas: {
+        publishableKey: string;
+        frontendApi: string;
+      };
+    };
+    atlas: {
+      jwksUrl: string;
+      issuer: string;
+      authorizedParties: string[];
+    };
+  };
+}

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The client plugin: installs the `@atlasauth/vue` plugin on Nuxt's Vue app.
+ *
+ * This is the Nuxt peer of calling `app.use(createAtlas(...))` in a plain Vue
+ * app, and of wrapping the tree in `<AtlasProvider>` in React. It runs once per
+ * app instance — which on the server means once per request, so each SSR render
+ * gets its own reactive client and never shares auth state between two users
+ * sharing the process (the exact leak `@atlasauth/vue`'s per-app `inject` avoids).
+ *
+ * `createAtlas` reads only the PUBLIC config (publishable key + FAPI origin).
+ * The verification secrets stay server-side and are never referenced here, so
+ * nothing secret is bundled into the client.
+ */
+declare const _default: any;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,12 @@
+import { createAtlas } from "@atlasauth/vue";
+import { defineNuxtPlugin, useRuntimeConfig } from "#imports";
+export default defineNuxtPlugin((nuxtApp) => {
+  const { atlas } = useRuntimeConfig().public;
+  nuxtApp.vueApp.use(
+    createAtlas({
+      publishableKey: atlas.publishableKey,
+      // Empty string → let @atlasauth/vue fall back to its default (same-origin FAPI).
+      frontendApi: atlas.frontendApi || void 0
+    })
+  );
+});

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

@@ -0,0 +1,48 @@
+import { AtlasBackend, type ProtectCondition, type SessionClaims } from '@atlasauth/backend';
+/**
+ * The server-side auth surface exposed to Nitro routes — the Nuxt peer of the
+ * Next.js `auth()` helper (`@atlasauth/nextjs`'s `createAuthHelper`).
+ *
+ * A signed-out request is NOT an error: it produces a state with
+ * `isSignedIn: false` and every id null, because a route that renders
+ * differently for anonymous visitors is the normal case. `protect()` is the
+ * opt-in hard stop for routes that must refuse anonymous or under-privileged
+ * callers, and it throws a properly-typed HTTP error rather than a bare
+ * exception so Nitro maps it to 401/403.
+ */
+export interface AtlasAuth {
+    userId: string | null;
+    sessionId: string | null;
+    orgId: string | null;
+    orgRole: string | null;
+    isSignedIn: boolean;
+    claims: SessionClaims | null;
+    /**
+     * True when the claims satisfy the condition (an empty condition means
+     * "signed in"). Delegates to the shared `@atlasauth/authz` primitive — identical
+     * to the client `useAuth().has()` and the React/Next `<Protect>`.
+     */
+    has(condition?: ProtectCondition): boolean;
+    /**
+     * Assert access, throwing an HTTP error when unmet: 401 for a signed-out
+     * caller, 403 when signed in but missing the role/permission. With no argument
+     * it asserts merely "signed in".
+     */
+    protect(condition?: ProtectCondition): void;
+}
+/** Build the `AtlasAuth` view over a (possibly null) verified claims set. */
+export declare function build(claims: SessionClaims | null): AtlasAuth;
+/**
+ * Verify whatever token a request carries and produce the `AtlasAuth` state.
+ *
+ * Mirrors `@atlasauth/backend`'s carrier rules: an `Authorization: Bearer` header
+ * wins over the `__session` cookie, because a caller that set the header did so
+ * deliberately. A token that fails verification yields the signed-out state —
+ * never a throw — so a bad or expired token degrades to "not signed in" rather
+ * than taking the whole request down (the Nitro peer of `@atlasauth/nextjs`'s
+ * `resolveAuth`).
+ */
+export declare function verifyCarriers(backend: AtlasBackend, carriers: {
+    authorization?: string | null;
+    sessionCookie?: string | null;
+}): Promise<AtlasAuth>;

package/dist/runtime/server/auth.js

@@ -0,0 +1,39 @@
+import {
+  evaluate,
+  hasFromClaims
+} from "@atlasauth/backend";
+import { createError } from "h3";
+function signedOut() {
+  return build(null);
+}
+export function build(claims) {
+  return {
+    userId: claims?.sub ?? null,
+    sessionId: claims?.sid ?? null,
+    orgId: claims?.org_id ?? null,
+    orgRole: claims?.org_role ?? null,
+    isSignedIn: claims !== null,
+    claims,
+    has(condition = {}) {
+      return hasFromClaims(claims, condition);
+    },
+    protect(condition = {}) {
+      const outcome = evaluate(claims, condition);
+      if (outcome.allowed) return;
+      throw createError({
+        statusCode: outcome.reason === "signed_out" ? 401 : 403,
+        statusMessage: outcome.reason === "signed_out" ? "Unauthorized" : "Forbidden",
+        data: { reason: outcome.reason }
+      });
+    }
+  };
+}
+export async function verifyCarriers(backend, carriers) {
+  const header = carriers.authorization ?? void 0;
+  const bearer = header?.startsWith("Bearer ") ? header.slice(7) : void 0;
+  const token = bearer ?? carriers.sessionCookie ?? void 0;
+  if (!token) return signedOut();
+  const result = await backend.verify(token);
+  if (!result.ok) return signedOut();
+  return build(result.claims);
+}

package/dist/runtime/server/auth.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/runtime/server/auth.test.js

@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { SignJWT, exportJWK, generateKeyPair } from "jose";
+import { AtlasBackend } from "@atlasauth/backend";
+import { build, verifyCarriers } from "./auth.js";
+const ISSUER = "https://fox.fapi.atlas.test";
+const JWKS_URL = `${ISSUER}/.well-known/jwks.json`;
+async function keyring() {
+  const { privateKey, publicKey } = await generateKeyPair("RS256");
+  const jwk = { ...await exportJWK(publicKey), kid: "kid-1", alg: "RS256", use: "sig" };
+  return { privateKey, jwks: { keys: [jwk] } };
+}
+async function token(privateKey, claims = {}) {
+  return new SignJWT({ sid: "sess_1", ...claims }).setProtectedHeader({ alg: "RS256", kid: "kid-1" }).setSubject("user_1").setIssuer(ISSUER).setIssuedAt().setExpirationTime("60s").sign(privateKey);
+}
+const serving = (jwks) => async () => new Response(JSON.stringify(jwks), { status: 200 });
+async function backendFor(jwks) {
+  return new AtlasBackend({ jwksUrl: JWKS_URL, issuer: ISSUER, fetchImpl: serving(jwks) });
+}
+describe("verifyCarriers", () => {
+  it("resolves a signed-in state from the __session cookie", async () => {
+    const { privateKey, jwks } = await keyring();
+    const backend = await backendFor(jwks);
+    const jwt = await token(privateKey);
+    const auth = await verifyCarriers(backend, { sessionCookie: jwt });
+    expect(auth.isSignedIn).toBe(true);
+    expect(auth.userId).toBe("user_1");
+    expect(auth.sessionId).toBe("sess_1");
+    expect(auth.has()).toBe(true);
+  });
+  it("lets the Authorization header win over the cookie", async () => {
+    const { privateKey, jwks } = await keyring();
+    const backend = await backendFor(jwks);
+    const good = await token(privateKey, { sid: "from_header" });
+    const auth = await verifyCarriers(backend, {
+      authorization: `Bearer ${good}`,
+      sessionCookie: "garbage.cookie.token"
+    });
+    expect(auth.isSignedIn).toBe(true);
+    expect(auth.sessionId).toBe("from_header");
+  });
+  it("returns signed-out (never throws) for a missing token", async () => {
+    const { jwks } = await keyring();
+    const backend = await backendFor(jwks);
+    const auth = await verifyCarriers(backend, {});
+    expect(auth.isSignedIn).toBe(false);
+    expect(auth.userId).toBeNull();
+    expect(auth.has()).toBe(false);
+  });
+  it("returns signed-out (never throws) for an unverifiable token", async () => {
+    const { jwks } = await keyring();
+    const backend = await backendFor(jwks);
+    const auth = await verifyCarriers(backend, { sessionCookie: "not.a.jwt" });
+    expect(auth.isSignedIn).toBe(false);
+  });
+  it("surfaces the active org role and permissions", async () => {
+    const { privateKey, jwks } = await keyring();
+    const backend = await backendFor(jwks);
+    const jwt = await token(privateKey, {
+      org_id: "org_1",
+      org_role: "admin",
+      org_permissions: ["org:billing:manage"]
+    });
+    const auth = await verifyCarriers(backend, { sessionCookie: jwt });
+    expect(auth.orgId).toBe("org_1");
+    expect(auth.orgRole).toBe("admin");
+    expect(auth.has({ permission: "org:billing:manage" })).toBe(true);
+    expect(auth.has({ permission: "org:members:manage" })).toBe(false);
+  });
+});
+describe("build().protect", () => {
+  it("is a no-op for a signed-in caller", () => {
+    const auth = build({ iss: ISSUER, sub: "u", sid: "s", exp: 0 });
+    expect(() => auth.protect()).not.toThrow();
+  });
+  it("throws a 401 for an anonymous caller", () => {
+    const auth = build(null);
+    expect(() => auth.protect()).toThrowError(expect.objectContaining({ statusCode: 401 }));
+  });
+  it("throws a 403 when signed in but missing the permission", () => {
+    const auth = build({
+      iss: ISSUER,
+      sub: "u",
+      sid: "s",
+      exp: 0,
+      org_id: "org_1",
+      org_role: "member",
+      org_permissions: []
+    });
+    expect(() => auth.protect({ permission: "org:billing:manage" })).toThrowError(
+      expect.objectContaining({ statusCode: 403 })
+    );
+  });
+});

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

@@ -0,0 +1,2 @@
+import { AtlasBackend } from '@atlasauth/backend';
+export declare function atlasBackend(): AtlasBackend;

package/dist/runtime/server/backend.js

@@ -0,0 +1,18 @@
+import { AtlasBackend } from "@atlasauth/backend";
+import { useRuntimeConfig } from "#imports";
+let cached = null;
+export function atlasBackend() {
+  if (cached) return cached;
+  const { atlas } = useRuntimeConfig();
+  if (!atlas.jwksUrl || !atlas.issuer) {
+    throw new Error(
+      "@atlasauth/nuxt: server-side auth needs `runtimeConfig.atlas.jwksUrl` and `runtimeConfig.atlas.issuer` (set them via the module options or the NUXT_ATLAS_JWKS_URL / NUXT_ATLAS_ISSUER env vars)."
+    );
+  }
+  cached = new AtlasBackend({
+    jwksUrl: atlas.jwksUrl,
+    issuer: atlas.issuer,
+    authorizedParties: atlas.authorizedParties?.length ? atlas.authorizedParties : void 0
+  });
+  return cached;
+}

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

@@ -0,0 +1,24 @@
+import { type H3Event } from 'h3';
+/**
+ * Cross-property SSO handshake for a Nuxt/Nitro route — the peer of the Next.js
+ * `atlasMiddleware({ handshake: true })`. Call it at the top of a protected
+ * server route: if the visitor has no local session it bounces them once
+ * through the Atlas handshake, and on the way back it redeems the cross-domain
+ * nonce for a fresh FIRST-PARTY session on this property (setting `__session` +
+ * `__atlas_rt`). Returns `true` when it has issued a redirect (the caller should
+ * stop and return); `false` when the request may proceed (signed in, or the
+ * handshake reported signed-out — send them to your sign-in then).
+ *
+ * ```ts
+ * export default defineEventHandler(async (event) => {
+ *   if (await atlasHandshake(event)) return;   // redirected
+ *   const auth = await getAtlasAuth(event);
+ *   auth.protect();
+ *   return { userId: auth.userId };
+ * });
+ * ```
+ *
+ * Requires `runtimeConfig.atlas.publishableKey` (and `jwksUrl`, from which the
+ * FAPI origin is derived unless `atlas.fapiOrigin` is set).
+ */
+export declare function atlasHandshake(event: H3Event): Promise<boolean>;

package/dist/runtime/server/handshake.js

@@ -0,0 +1,60 @@
+import { getCookie, getQuery, getRequestURL, sendRedirect, setCookie } from "h3";
+import { useRuntimeConfig } from "#imports";
+import { createPkcePair, redeemHandshake } from "@atlasauth/backend";
+import { getAtlasAuth } from "./index.js";
+export async function atlasHandshake(event) {
+  const { atlas } = useRuntimeConfig();
+  const publishableKey = atlas.publishableKey;
+  const fapiOrigin = atlas.fapiOrigin ?? (atlas.jwksUrl ? new URL(atlas.jwksUrl).origin : void 0);
+  if (!publishableKey || !fapiOrigin) {
+    return false;
+  }
+  const q = getQuery(event);
+  const url = getRequestURL(event);
+  if (q.__atlas_hs === "ok" && q.__atlas_hu && q.__atlas_hn) {
+    const codeVerifier = getCookie(event, "__atlas_hv");
+    const session = codeVerifier ? await redeemHandshake({
+      fapiOrigin,
+      publishableKey,
+      userId: q.__atlas_hu,
+      nonce: q.__atlas_hn,
+      codeVerifier
+    }) : null;
+    const clean = new URL(url.toString());
+    for (const k of ["__atlas_hs", "__atlas_hu", "__atlas_hn"]) clean.searchParams.delete(k);
+    setCookie(event, "__atlas_hv", "", { path: "/", maxAge: 0 });
+    if (session) {
+      setCookie(event, "__session", session.jwt, { path: "/", sameSite: "lax", secure: true });
+      setCookie(event, "__atlas_rt", session.refreshToken, {
+        path: "/",
+        httpOnly: true,
+        sameSite: "lax",
+        secure: true
+      });
+      await sendRedirect(event, clean.pathname + clean.search, 303);
+      return true;
+    }
+    clean.searchParams.set("__atlas_hs", "failed");
+    await sendRedirect(event, clean.pathname + clean.search, 303);
+    return true;
+  }
+  const auth = await getAtlasAuth(event);
+  if (auth.userId) return false;
+  if (!q.__atlas_hs) {
+    const { verifier, challenge } = await createPkcePair();
+    setCookie(event, "__atlas_hv", verifier, {
+      path: "/",
+      httpOnly: true,
+      sameSite: "lax",
+      secure: true,
+      maxAge: 300
+    });
+    const hs = new URL("/v1/client/handshake", fapiOrigin);
+    hs.searchParams.set("publishable_key", publishableKey);
+    hs.searchParams.set("redirect_url", url.toString());
+    hs.searchParams.set("code_challenge", challenge);
+    await sendRedirect(event, hs.toString(), 303);
+    return true;
+  }
+  return false;
+}

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

@@ -0,0 +1,29 @@
+import { type H3Event } from 'h3';
+import { type AtlasAuth } from './auth.js';
+export type { AtlasAuth } from './auth.js';
+export { verifyCarriers, build } from './auth.js';
+export { atlasBackend } from './backend.js';
+export { atlasHandshake } from './handshake.js';
+/**
+ * Read the verified auth state for the current request — the server-route peer
+ * of the client `useAuth()`.
+ *
+ * ```ts
+ * export default defineEventHandler(async (event) => {
+ *   const auth = await getAtlasAuth(event)
+ *   auth.protect()                 // 401 if not signed in
+ *   return { userId: auth.userId }
+ * })
+ * ```
+ *
+ * The result is memoized on `event.context.auth`, so the global middleware and
+ * any number of handlers on the same request share ONE verification. The header
+ * takes precedence over the `__session` cookie, matching `@atlasauth/backend`.
+ */
+export declare function getAtlasAuth(event: H3Event): Promise<AtlasAuth>;
+declare module 'h3' {
+    interface H3EventContext {
+        /** The Atlas auth state resolved for this request by `@atlasauth/nuxt`. */
+        auth?: AtlasAuth;
+    }
+}

package/dist/runtime/server/index.js

@@ -0,0 +1,15 @@
+import { getRequestHeader, getCookie } from "h3";
+import { atlasBackend } from "./backend.js";
+import { verifyCarriers } from "./auth.js";
+export { verifyCarriers, build } from "./auth.js";
+export { atlasBackend } from "./backend.js";
+export { atlasHandshake } from "./handshake.js";
+export async function getAtlasAuth(event) {
+  if (event.context.auth) return event.context.auth;
+  const auth = await verifyCarriers(atlasBackend(), {
+    authorization: getRequestHeader(event, "authorization") ?? null,
+    sessionCookie: getCookie(event, "__session") ?? null
+  });
+  event.context.auth = auth;
+  return auth;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Global Nitro middleware — the Nuxt peer of the Next.js `atlasMiddleware`.
+ *
+ * It verifies the `__session` JWT once, up front, and stashes the result on
+ * `event.context.auth`, so every downstream `defineEventHandler` (and any server
+ * util) reads the same resolved auth without repeating the verify. It does NOT
+ * enforce a route policy here — verification is local and cheap, but redirect /
+ * 401 decisions belong to each route via `auth.protect(...)`, keeping the
+ * middleware a pure "who is this" step rather than a "may they" one.
+ */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/middleware.js

@@ -0,0 +1,5 @@
+import { defineEventHandler } from "h3";
+import { getAtlasAuth } from "./index.js";
+export default defineEventHandler(async (event) => {
+  await getAtlasAuth(event);
+});

package/dist/types.d.mts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module.js'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module.js'

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { NuxtModule } from '@nuxt/schema'
+
+import type { default as Module } from './module'
+
+export type ModuleOptions = typeof Module extends NuxtModule<infer O> ? Partial<O> : Record<string, any>
+
+export { default } from './module'

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@atlasauth/nuxt",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Official Nuxt 3 module for Atlas — SSR session verification (Nitro) built on the @atlasauth/vue client.",
+  "license": "MIT",
+  "main": "./dist/module.mjs",
+  "types": "./dist/types.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    },
+    "./server": {
+      "types": "./dist/runtime/server/index.d.ts",
+      "import": "./dist/runtime/server/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@nuxt/kit": "^3.13.0",
+    "@atlasauth/js": "0.1.0",
+    "@atlasauth/backend": "0.1.0",
+    "@atlasauth/authz": "0.1.0",
+    "@atlasauth/vue": "0.1.0"
+  },
+  "peerDependencies": {
+    "nuxt": "^3"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "^0.8.4",
+    "@nuxt/schema": "^3.13.0",
+    "h3": "^1.12.0",
+    "jose": "^5.9.6",
+    "nuxt": "^3.13.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4",
+    "vue": "^3.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}