@cboxdk/id-nuxt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Cbox
+
+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,95 @@
+# @cboxdk/id-nuxt
+
+Nuxt module for [Cbox ID](https://github.com/cboxdk/laravel-id). It wires the
+[`@cboxdk/id-js`](https://github.com/cboxdk/id-js) OIDC client to your Nuxt app:
+drop-in **sign-in / callback / sign-out** routes, a sealed session, and a
+`useCboxUser()` composable — add authentication with one module entry.
+
+Pair it with [`@cboxdk/id-vue`](https://github.com/cboxdk/id-vue) for the
+`<CboxUserButton>` and other widgets.
+
+## Install
+
+```bash
+npm install @cboxdk/id-nuxt
+```
+
+## Configure
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ['@cboxdk/id-nuxt'],
+  cboxId: {
+    // or set CBOX_ID_ISSUER / CBOX_ID_CLIENT_ID / CBOX_ID_CLIENT_SECRET / CBOX_ID_REDIRECT_URI
+    issuer: 'https://id.acme.com',
+    clientId: process.env.CBOX_ID_CLIENT_ID,
+    clientSecret: process.env.CBOX_ID_CLIENT_SECRET,
+    redirectUri: 'https://app.acme.com/auth/callback',
+  },
+});
+```
+
+Set a session secret so the session cookie is sealed:
+
+```dotenv
+CBOX_ID_SESSION_PASSWORD=at-least-32-characters-of-random
+```
+
+## Use
+
+The module registers these routes for you:
+
+| Route | Does |
+|---|---|
+| `GET /auth/sign-in` | starts login (accepts `?redirect=/where/next`) |
+| `GET /auth/callback` | verifies the login and stores the session |
+| `GET /auth/sign-out` | clears the session and logs out |
+| `GET /api/_cbox/user` | the current user as JSON (used internally) |
+
+Link to them and read the user reactively anywhere:
+
+```vue
+<script setup lang="ts">
+const user = useCboxUser();
+</script>
+
+<template>
+  <div v-if="user">
+    Hi {{ user.name }} — <a href="/auth/sign-out">Sign out</a>
+  </div>
+  <a v-else href="/auth/sign-in">Sign in</a>
+</template>
+```
+
+Protect a route with middleware:
+
+```ts
+// middleware/auth.ts
+export default defineNuxtRouteMiddleware(() => {
+  const user = useCboxUser();
+  if (!user.value) {
+    return navigateTo('/auth/sign-in?redirect=' + encodeURIComponent(useRoute().fullPath));
+  }
+});
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `issuer` / `clientId` / `clientSecret` / `redirectUri` | from env | the Cbox ID connection |
+| `scopes` | `openid profile email` | requested at login |
+| `accountPath` | `/settings` | hosted profile page path |
+| `loginPath` / `callbackPath` / `logoutPath` | `/auth/*` | override the route paths |
+
+## Scope
+
+This module handles login, session and sign-out against a Cbox ID instance. Profile
+management (password, MFA, passkeys) is hosted by the instance — link users to
+`accountPath` there. SSO/SCIM/org administration are platform capabilities of
+[`cboxdk/laravel-id`](https://github.com/cboxdk/laravel-id), not this module.
+
+## License
+
+MIT © Cbox.

package/dist/module.d.mts

@@ -0,0 +1,31 @@
+import * as _nuxt_schema from '@nuxt/schema';
+
+interface ModuleOptions {
+    /** Base URL of the Cbox ID instance (or set CBOX_ID_ISSUER). */
+    issuer?: string;
+    /** Your OAuth client id (or set CBOX_ID_CLIENT_ID). */
+    clientId?: string;
+    /** Your client secret (or set CBOX_ID_CLIENT_SECRET). */
+    clientSecret?: string;
+    /** Your callback URL, registered on the client (or set CBOX_ID_REDIRECT_URI). */
+    redirectUri?: string;
+    /** The instance's hosted account path. Defaults to /settings. */
+    accountPath?: string;
+    /** Scopes requested at login. */
+    scopes?: string[];
+    /** Route that starts login. Defaults to /auth/sign-in. */
+    loginPath?: string;
+    /** Route that handles the callback. Defaults to /auth/callback. */
+    callbackPath?: string;
+    /** Route that signs out. Defaults to /auth/sign-out. */
+    logoutPath?: string;
+}
+/**
+ * Nuxt module for Cbox ID. Registers the sign-in / callback / sign-out routes and a
+ * `useCboxUser()` composable, all backed by @cboxdk/id-js. Configure it under the
+ * `cboxId` key or via environment variables.
+ */
+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": "@cboxdk/id-nuxt",
+  "configKey": "cboxId",
+  "compatibility": {
+    "nuxt": ">=3.0.0"
+  },
+  "version": "0.1.0",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,64 @@
+import { defineNuxtModule, createResolver, addServerHandler, addImportsDir, addPlugin } from '@nuxt/kit';
+import { defu } from 'defu';
+
+const module$1 = defineNuxtModule({
+  meta: {
+    name: "@cboxdk/id-nuxt",
+    configKey: "cboxId",
+    compatibility: { nuxt: ">=3.0.0" }
+  },
+  defaults: {
+    accountPath: "/settings",
+    loginPath: "/auth/sign-in",
+    callbackPath: "/auth/callback",
+    logoutPath: "/auth/sign-out"
+  },
+  setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.cboxId = defu(
+      nuxt.options.runtimeConfig.cboxId,
+      {
+        issuer: options.issuer ?? process.env.CBOX_ID_ISSUER ?? "",
+        clientId: options.clientId ?? process.env.CBOX_ID_CLIENT_ID ?? "",
+        clientSecret: options.clientSecret ?? process.env.CBOX_ID_CLIENT_SECRET ?? "",
+        redirectUri: options.redirectUri ?? process.env.CBOX_ID_REDIRECT_URI ?? "",
+        accountPath: options.accountPath,
+        scopes: options.scopes,
+        sessionPassword: process.env.CBOX_ID_SESSION_PASSWORD ?? ""
+      }
+    );
+    nuxt.options.runtimeConfig.public.cboxId = defu(
+      nuxt.options.runtimeConfig.public.cboxId,
+      {
+        loginPath: options.loginPath,
+        logoutPath: options.logoutPath,
+        accountPath: options.accountPath
+      }
+    );
+    nuxt.options.build.transpile.push(resolver.resolve("./runtime"));
+    addServerHandler({
+      route: options.loginPath,
+      method: "get",
+      handler: resolver.resolve("./runtime/server/routes/sign-in.get")
+    });
+    addServerHandler({
+      route: options.callbackPath,
+      method: "get",
+      handler: resolver.resolve("./runtime/server/routes/callback.get")
+    });
+    addServerHandler({
+      route: options.logoutPath,
+      method: "get",
+      handler: resolver.resolve("./runtime/server/routes/sign-out.get")
+    });
+    addServerHandler({
+      route: "/api/_cbox/user",
+      method: "get",
+      handler: resolver.resolve("./runtime/server/routes/user.get")
+    });
+    addImportsDir(resolver.resolve("./runtime/composables"));
+    addPlugin(resolver.resolve("./runtime/plugin"));
+  }
+});
+
+export { module$1 as default };

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

@@ -0,0 +1,5 @@
+/**
+ * The signed-in Cbox ID user (reactive), or null when signed out. Hydrated by the
+ * module's plugin from the server session.
+ */
+export declare function useCboxUser(): any;

package/dist/runtime/composables/useCboxUser.js

@@ -0,0 +1,4 @@
+import { useState } from "#imports";
+export function useCboxUser() {
+  return useState("cbox-id-user", () => null);
+}

package/dist/runtime/plugin.d.ts

@@ -0,0 +1,3 @@
+/** Hydrate the current user from the server session once, on app start. */
+declare const _default: any;
+export default _default;

package/dist/runtime/plugin.js

@@ -0,0 +1,13 @@
+import { defineNuxtPlugin, useRequestFetch } from "#imports";
+import { useCboxUser } from "./composables/useCboxUser.js";
+export default defineNuxtPlugin(async () => {
+  const user = useCboxUser();
+  if (user.value !== null) {
+    return;
+  }
+  try {
+    user.value = await useRequestFetch()("/api/_cbox/user");
+  } catch {
+    user.value = null;
+  }
+});

package/dist/runtime/server/routes/callback.get.d.ts

@@ -0,0 +1,3 @@
+/** Complete login: verify state, exchange the code, verify the id_token, store user. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/routes/callback.get.js

@@ -0,0 +1,37 @@
+import { defineEventHandler, getQuery, sendRedirect, useSession } from "h3";
+import { cboxSessionConfig, getCboxClient } from "../utils/client.js";
+function asString(value) {
+  return typeof value === "string" ? value : void 0;
+}
+export default defineEventHandler(async (event) => {
+  const client = getCboxClient(event);
+  const session = await useSession(event, cboxSessionConfig(event));
+  const query = getQuery(event);
+  const user = await client.authenticate({
+    params: {
+      code: asString(query.code),
+      state: asString(query.state),
+      error: asString(query.error),
+      error_description: asString(query.error_description)
+    },
+    stored: {
+      state: session.data.state ?? "",
+      codeVerifier: session.data.codeVerifier ?? "",
+      nonce: session.data.nonce ?? ""
+    }
+  });
+  const redirectTo = session.data.redirectTo ?? "/";
+  await session.update({
+    user: {
+      id: user.id,
+      email: user.email,
+      name: user.name,
+      organizationId: user.organizationId
+    },
+    state: void 0,
+    codeVerifier: void 0,
+    nonce: void 0,
+    redirectTo: void 0
+  });
+  return sendRedirect(event, redirectTo);
+});

package/dist/runtime/server/routes/sign-in.get.d.ts

@@ -0,0 +1,3 @@
+/** Start login: create the authorization request, stash PKCE/state/nonce, redirect. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/routes/sign-in.get.js

@@ -0,0 +1,15 @@
+import { defineEventHandler, getQuery, sendRedirect, useSession } from "h3";
+import { cboxSessionConfig, getCboxClient } from "../utils/client.js";
+export default defineEventHandler(async (event) => {
+  const client = getCboxClient(event);
+  const request = await client.createAuthorizationRequest();
+  const session = await useSession(event, cboxSessionConfig(event));
+  const redirect = getQuery(event).redirect;
+  await session.update({
+    state: request.state,
+    codeVerifier: request.codeVerifier,
+    nonce: request.nonce,
+    redirectTo: typeof redirect === "string" ? redirect : "/"
+  });
+  return sendRedirect(event, request.url);
+});

package/dist/runtime/server/routes/sign-out.get.d.ts

@@ -0,0 +1,3 @@
+/** Clear the session and redirect to RP-initiated logout (or home). */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/routes/sign-out.get.js

@@ -0,0 +1,10 @@
+import { defineEventHandler, getRequestURL, sendRedirect, useSession } from "h3";
+import { cboxSessionConfig, getCboxClient } from "../utils/client.js";
+export default defineEventHandler(async (event) => {
+  const client = getCboxClient(event);
+  const session = await useSession(event, cboxSessionConfig(event));
+  await session.clear();
+  const origin = getRequestURL(event).origin;
+  const logoutUrl = await client.logoutUrl(origin);
+  return sendRedirect(event, logoutUrl ?? "/");
+});

package/dist/runtime/server/routes/user.get.d.ts

@@ -0,0 +1,4 @@
+import type { CboxSessionUser } from '../../types.js';
+/** Return the signed-in user from the session, or null. */
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<CboxSessionUser | null>>;
+export default _default;

package/dist/runtime/server/routes/user.get.js

@@ -0,0 +1,6 @@
+import { defineEventHandler, useSession } from "h3";
+import { cboxSessionConfig } from "../utils/client.js";
+export default defineEventHandler(async (event) => {
+  const session = await useSession(event, cboxSessionConfig(event));
+  return session.data.user ?? null;
+});

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

@@ -0,0 +1,6 @@
+import { CboxIdClient } from '@cboxdk/id-js';
+import type { H3Event, SessionConfig } from 'h3';
+/** Build a CboxIdClient from the module's server runtime config. */
+export declare function getCboxClient(event: H3Event): CboxIdClient;
+/** The sealed-cookie session config (h3 useSession). */
+export declare function cboxSessionConfig(event: H3Event): SessionConfig;

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

@@ -0,0 +1,24 @@
+import { CboxIdClient } from "@cboxdk/id-js";
+import { useRuntimeConfig } from "#imports";
+export function getCboxClient(event) {
+  const cfg = useRuntimeConfig(event).cboxId;
+  const config = {
+    issuer: cfg.issuer,
+    clientId: cfg.clientId,
+    redirectUri: cfg.redirectUri
+  };
+  if (cfg.clientSecret) {
+    config.clientSecret = cfg.clientSecret;
+  }
+  if (cfg.accountPath) {
+    config.accountPath = cfg.accountPath;
+  }
+  if (cfg.scopes && cfg.scopes.length > 0) {
+    config.scopes = cfg.scopes;
+  }
+  return new CboxIdClient(config);
+}
+export function cboxSessionConfig(event) {
+  const cfg = useRuntimeConfig(event).cboxId;
+  return { password: cfg.sessionPassword, name: "cbox_id" };
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,25 @@
+/** The signed-in user we keep in the session and expose via useCboxUser(). */
+export interface CboxSessionUser {
+    id: string;
+    email: string | null;
+    name: string | null;
+    organizationId: string | null;
+}
+/** The shape of our sealed session. */
+export interface CboxSessionData {
+    state?: string;
+    codeVerifier?: string;
+    nonce?: string;
+    redirectTo?: string;
+    user?: CboxSessionUser;
+}
+/** The private runtime config this module reads server-side. */
+export interface CboxRuntimeConfig {
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    accountPath?: string;
+    scopes?: string[];
+    sessionPassword: string;
+}

package/dist/types.d.mts

@@ -0,0 +1,3 @@
+export { default } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@cboxdk/id-nuxt",
+  "version": "0.1.0",
+  "description": "Nuxt module for Cbox ID — drop-in sign-in / callback / sign-out routes and session handling built on @cboxdk/id-js. Add authentication to a Nuxt app with one module entry.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Sylvester Damgaard <sn@cbox.dk>",
+  "homepage": "https://github.com/cboxdk/id-nuxt",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cboxdk/id-nuxt.git"
+  },
+  "bugs": {
+    "url": "https://github.com/cboxdk/id-nuxt/issues"
+  },
+  "keywords": [
+    "cbox-id",
+    "nuxt",
+    "nuxt-module",
+    "authentication",
+    "oidc",
+    "sso"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
+  "types": "./dist/types.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "prepare-types": "nuxt-module-build prepare",
+    "build": "nuxt-module-build build",
+    "check": "npm run prepare-types && npm run build"
+  },
+  "dependencies": {
+    "@cboxdk/id-js": "^0.1.0",
+    "@nuxt/kit": "^3.0.0 || ^4.0.0",
+    "defu": "^6.1.0",
+    "h3": "^1.13.0"
+  },
+  "devDependencies": {
+    "@nuxt/module-builder": "^1.0.0",
+    "@nuxt/schema": "^3.0.0 || ^4.0.0",
+    "typescript": "^5.9.2"
+  }
+}