@frigear-nu/oauth-server 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,50 @@
-# Temporary Holding Version
+# @frigear-nu/oauth-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An OAuth 2.0 / OpenID Connect server for the frigear ecosystem. Register **applications**, restrict them to users
+with certain roles, and let those users sign in to them through your app (authorization code flow with PKCE, rotating
+refresh tokens, RS256 ID tokens). The module stays bare-bone: roles, the admin gate and extra claims are supplied by the
+consuming app through Nitro hooks.
+
+## Quick Setup
+
+Requires `@nuxthub/core` and `@frigear-nu/users` (server mode). `@frigear-nu/menu` (account tiles) and `@nuxt/ui`
+(the shipped pages) are optional.
+
+```ts
+export default defineNuxtConfig({
+  modules: ['@frigear-nu/menu', '@frigear-nu/users', '@frigear-nu/oauth-server'],
+  oauthServer: {
+    issuer: 'https://id.example.com',
+    settings: { pages: { admin: true, applications: true } },
+  },
+})
+```
+
+Create a signing key and expose it through the environment (the public key is derived from it):
+
+```bash
+openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 | awk 'NF {printf "%s\\n", $0}'
+# NUXT_OAUTH_SERVER_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
+```
+
+Generate and commit a migration for the three `oauth_*` tables in your app (see the repository `AGENTS.md`).
+
+Nobody can manage applications or hold a role until the host says so:
+
+```ts
+// server/plugins/oauth.ts
+export default defineNitroPlugin((nitro) => {
+  nitro.hooks.hook('oauth:authorize', async (ctx) => { ctx.allowed = await isStaff(ctx.userId) })
+  nitro.hooks.hook('oauth:user:roles', async (ctx) => { ctx.roles.push(...await rolesFor(ctx.userId)) })
+})
+```
+
+Full documentation with examples: `apps/docs/content/4.modules/500.oauth-server.md`.
+
+## Development
+
+```bash
+pnpm --filter @frigear-nu/oauth-server test
+pnpm --filter @frigear-nu/oauth-server lint
+pnpm --filter @frigear-nu/oauth-server dev
+```

package/dist/module.d.mts

@@ -0,0 +1,206 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { H3Event } from 'h3';
+
+type ModuleOptions = {
+    /**
+     * The `iss` claim and the discovery issuer, e.g. `https://id.example.com`. Defaults to the origin of the
+     * incoming request, which is fine in development but should be set explicitly behind proxies.
+     */
+    issuer?: string;
+    /** `kid` of the signing key (published in the JWKS). Defaults to `key-1`; change it when rotating keys. */
+    keyId?: string;
+    /** Access and ID token lifetime in seconds. Defaults to `3600`. */
+    accessTokenTtl?: number;
+    /** Refresh token lifetime in seconds. Defaults to 30 days. */
+    refreshTokenTtl?: number;
+    /** Authorization code lifetime in seconds. Defaults to `600`. */
+    codeTtl?: number;
+    /** Path appended to an application's `websiteUrl` to form its redirect URI. Defaults to `/auth/frigear`. */
+    callbackPath?: string;
+    /** Extra scopes advertised and accepted next to `openid profile email`. Enrich their claims with `oauth:claims`. */
+    scopes?: string[];
+    settings?: {
+        pages?: {
+            /** Consent screen. On by default (`/authorize`); pass `false` to provide your own page at that path. */
+            authorize?: string | boolean;
+            /** Admin UI for applications. `true` = `/admin/oauth`. Needs `@nuxt/ui`. */
+            admin?: string | boolean;
+            /** The signed-in user's applications. `true` = `/account/applications`. Needs `@nuxt/ui`. */
+            applications?: string | boolean;
+        };
+        /** Where unauthenticated users are sent to sign in. Defaults to the `@frigear-nu/users` login page. */
+        signInPath?: string;
+    };
+};
+/** Private runtime config (`runtimeConfig.oauthServer`). Keys are PEM strings, set them through env. */
+type OAuthServerRuntimeConfig = {
+    /** PKCS8 RSA private key (`NUXT_OAUTH_SERVER_PRIVATE_KEY`). Single-line PEM with literal `\n` works. */
+    privateKey: string;
+    /** SPKI RSA public key (`NUXT_OAUTH_SERVER_PUBLIC_KEY`). Derived from the private key when empty. */
+    publicKey: string;
+    /**
+     * Public keys of earlier signing keys, kept during a rotation: `{ "<kid>": "<SPKI PEM>" }` (an object, or
+     * the same as a JSON string for `NUXT_OAUTH_SERVER_PREVIOUS_PUBLIC_KEYS`). They are published in the JWKS and
+     * still verify tokens, but nothing is signed with them.
+     */
+    previousPublicKeys: string | Record<string, string>;
+    issuer?: string;
+    keyId: string;
+    accessTokenTtl: number;
+    refreshTokenTtl: number;
+    codeTtl: number;
+    callbackPath: string;
+    scopes: string[];
+    authorizePath: string;
+    signInPath?: string;
+};
+type PublicModuleOptions = {
+    pages: {
+        authorize?: string;
+        admin?: string;
+        applications?: string;
+    };
+};
+/** The user as read from the `users` table (including columns the host added through `extend.sqlite.ts`). */
+type OAuthUser = {
+    id: number;
+    name: string;
+    email: string;
+    avatar: string | null;
+} & Record<string, unknown>;
+/** An application without its secret hash. */
+type OAuthApplication = {
+    /** `app_` + random id; it is the OAuth `client_id`. */
+    id: string;
+    name: string;
+    description: string | null;
+    icon: string | null;
+    priority: number;
+    websiteUrl: string;
+    loginUrl: string | null;
+    previewUrlPattern: string | null;
+    /** Extra exact redirect URIs next to the derived `websiteUrl + callbackPath`. */
+    redirectUris: string[];
+    /** Roles allowed to sign in. Empty = every signed-in user. */
+    allowedRoles: string[];
+    tags: string[];
+    ownerId: number | null;
+    isActive: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+};
+/** What the signed-in user needs to see to launch an application. */
+type UserApplicationDto = Pick<OAuthApplication, 'id' | 'name' | 'description' | 'icon' | 'priority' | 'websiteUrl' | 'tags'> & {
+    loginUrl: string;
+};
+type ApplicationInput = {
+    name: string;
+    websiteUrl: string;
+    description?: string | null;
+    icon?: string | null;
+    priority?: number;
+    loginUrl?: string | null;
+    previewUrlPattern?: string | null;
+    redirectUris?: string[];
+    allowedRoles?: string[];
+    tags?: string[];
+    isActive?: boolean;
+};
+type TokenType = 'id_token' | 'access_token' | 'userinfo';
+type AuthorizeContext = {
+    event: H3Event;
+    userId: number;
+    allowed: boolean;
+};
+type UserRolesContext = {
+    event?: H3Event;
+    userId: number;
+    /** Push the user's roles here. Several listeners add up. */
+    roles: string[];
+};
+type ApplicationAccessContext = {
+    event?: H3Event;
+    user: OAuthUser;
+    application: OAuthApplication;
+    /** The roles resolved through `oauth:user:roles`. */
+    roles: string[];
+    /** `true` when the role check passed; set `false` (and optionally `reason`) to veto. */
+    allowed: boolean;
+    reason?: string;
+};
+type ClaimsContext = {
+    user: OAuthUser;
+    application: OAuthApplication;
+    /** The granted scopes. */
+    scope: string[];
+    roles: string[];
+    tokenType: TokenType;
+    /** Mutate this to add, change or remove claims. Standard claims (`sub`, `iss`, `aud`, `exp`, `iat`) are set afterwards. */
+    claims: Record<string, unknown>;
+};
+type TokenIssuedContext = {
+    userId: number;
+    applicationId: string;
+    scope: string[];
+    grant: 'authorization_code' | 'refresh_token';
+};
+type TokenRevokedContext = {
+    applicationId: string;
+    userId: number | null;
+    reason: 'revoked' | 'reuse_detected' | 'user_grants_revoked';
+};
+/** What the admin API returns (dates are ISO strings over the wire). */
+type AdminApplicationDto = Omit<OAuthApplication, 'createdAt' | 'updatedAt'> & {
+    createdAt: string;
+    updatedAt: string;
+    /** Refresh tokens that are still valid, i.e. users currently signed in. */
+    activeGrants?: number;
+    /** The redirect URI the application has to accept. */
+    callbackUrl: string;
+};
+/** Returned once when an application is created. */
+type CreatedApplicationDto = AdminApplicationDto & {
+    clientId: string;
+    clientSecret: string;
+};
+type ConsentDto = {
+    application: Pick<OAuthApplication, 'id' | 'name' | 'description' | 'icon' | 'websiteUrl'>;
+    scope: string[];
+    user: {
+        name: string;
+        email: string;
+        avatar: string | null;
+    };
+};
+
+declare module '@nuxt/schema' {
+    interface NuxtConfig {
+        oauthServer?: ModuleOptions;
+    }
+    interface RuntimeConfig {
+        oauthServer: OAuthServerRuntimeConfig;
+    }
+    interface PublicRuntimeConfig {
+        oauthServer: PublicModuleOptions;
+    }
+}
+declare module 'nitropack' {
+    interface NitroRuntimeHooks {
+        /** Admin gate (manage applications): set `ctx.allowed = true` to let the user in. Denied by default. */
+        'oauth:authorize': (ctx: AuthorizeContext) => void | Promise<void>;
+        /** Push the user's roles onto `ctx.roles`. Without a listener nobody has a role. */
+        'oauth:user:roles': (ctx: UserRolesContext) => void | Promise<void>;
+        /** Extra veto after the role check: set `ctx.allowed = false` (and `ctx.reason`) to deny. */
+        'oauth:application:access': (ctx: ApplicationAccessContext) => void | Promise<void>;
+        /** Enrich ID tokens, access tokens and userinfo: mutate `ctx.claims`. */
+        'oauth:claims': (ctx: ClaimsContext) => void | Promise<void>;
+        /** Tokens were issued (code exchange or refresh). Audit logging etc. */
+        'oauth:token:issued': (ctx: TokenIssuedContext) => void | Promise<void>;
+        /** A refresh token (family) was revoked. */
+        'oauth:token:revoked': (ctx: TokenRevokedContext) => void | Promise<void>;
+    }
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { AdminApplicationDto, ApplicationAccessContext, ApplicationInput, AuthorizeContext, ClaimsContext, ConsentDto, CreatedApplicationDto, ModuleOptions, OAuthApplication, OAuthServerRuntimeConfig, OAuthUser, PublicModuleOptions, TokenIssuedContext, TokenRevokedContext, TokenType, UserApplicationDto, UserRolesContext };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@frigear-nu/oauth-server",
+  "configKey": "oauthServer",
+  "version": "0.0.2",
+  "builder": {
+    "@nuxt/module-builder": "1.0.3",
+    "unbuild": "unknown"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,107 @@
+import { defineNuxtModule, createResolver, hasNuxtModule, addServerHandler, addServerImportsDir, addImports, extendPages } from '@nuxt/kit';
+import { registerModule, registerDatabaseTable, defineModulePage, moduleApiUrl } from '@frigear-nu/module-kit/utils';
+
+const MODULE_NAME = "@frigear-nu/oauth-server";
+const API_NAME = "oauthServer";
+function resolvePagePath(setting, defaultPath) {
+  if (typeof setting === "string") return setting;
+  if (setting === true) return defaultPath;
+  return void 0;
+}
+const module$1 = defineNuxtModule({
+  meta: { name: MODULE_NAME, configKey: "oauthServer" },
+  defaults: {
+    keyId: "key-1",
+    accessTokenTtl: 3600,
+    refreshTokenTtl: 60 * 60 * 24 * 30,
+    codeTtl: 600,
+    callbackPath: "/auth/frigear",
+    scopes: [],
+    settings: { pages: {} }
+  },
+  moduleDependencies: {
+    "@nuxthub/core": { version: ">=0.10" },
+    "@frigear-nu/module-kit": { version: ">=0.0.1" },
+    "@frigear-nu/users": { version: ">=0.0.1" },
+    "@frigear-nu/menu": { version: ">=0.0.1", optional: true }
+  },
+  async setup(options, nuxt) {
+    registerModule(MODULE_NAME, nuxt);
+    const resolver = createResolver(import.meta.url);
+    const settings = options.settings ?? {};
+    const withMenus = hasNuxtModule("@frigear-nu/menu");
+    const authorizePath = settings.pages?.authorize === false ? "/authorize" : resolvePagePath(settings.pages?.authorize ?? true, "/authorize");
+    const adminPath = resolvePagePath(settings.pages?.admin, "/admin/oauth");
+    const applicationsPath = resolvePagePath(settings.pages?.applications, "/account/applications");
+    const existing = nuxt.options.runtimeConfig.oauthServer;
+    nuxt.options.runtimeConfig.oauthServer = {
+      privateKey: "",
+      publicKey: "",
+      previousPublicKeys: "",
+      ...existing,
+      issuer: options.issuer,
+      keyId: options.keyId ?? "key-1",
+      accessTokenTtl: options.accessTokenTtl ?? 3600,
+      refreshTokenTtl: options.refreshTokenTtl ?? 60 * 60 * 24 * 30,
+      codeTtl: options.codeTtl ?? 600,
+      callbackPath: options.callbackPath ?? "/auth/frigear",
+      scopes: options.scopes ?? [],
+      authorizePath,
+      signInPath: settings.signInPath
+    };
+    nuxt.options.runtimeConfig.public.oauthServer = {
+      pages: {
+        authorize: settings.pages?.authorize === false ? void 0 : authorizePath,
+        admin: adminPath,
+        applications: applicationsPath
+      }
+    };
+    await registerDatabaseTable(nuxt, {
+      resolver,
+      schema: (dialect) => `./runtime/server/db/schema.${dialect}`
+    });
+    const handler = (file) => resolver.resolve(`./runtime/server/routes/${file}`);
+    addServerHandler({ route: "/.well-known/openid-configuration", method: "get", handler: handler("oidc/openid-configuration.get") });
+    addServerHandler({ route: "/.well-known/jwks.json", method: "get", handler: handler("oidc/jwks.get") });
+    addServerHandler({ route: "/oauth/authorize", method: "get", handler: handler("oidc/authorize.get") });
+    addServerHandler({ route: "/oauth/authorize", method: "post", handler: handler("oidc/authorize.post") });
+    addServerHandler({ route: "/oauth/token", method: "post", handler: handler("oidc/token.post") });
+    addServerHandler({ route: "/oauth/revoke", method: "post", handler: handler("oidc/revoke.post") });
+    addServerHandler({ route: "/oauth/userinfo", method: "get", handler: handler("oidc/userinfo.get") });
+    const api = (method, path, file) => addServerHandler({ route: moduleApiUrl(API_NAME, path), method, handler: handler(file) });
+    api("get", "consent", "api/consent.get");
+    api("get", "me/applications", "api/me-applications.get");
+    api("get", "admin/applications", "api/admin/applications.get");
+    api("post", "admin/applications", "api/admin/applications.post");
+    api("get", "admin/applications/:id", "api/admin/application.get");
+    api("patch", "admin/applications/:id", "api/admin/application.patch");
+    api("delete", "admin/applications/:id", "api/admin/application.delete");
+    api("post", "admin/applications/:id/secret", "api/admin/application-secret.post");
+    api("post", "admin/applications/:id/revoke", "api/admin/application-revoke.post");
+    addServerImportsDir(resolver.resolve("./runtime/server/utils"));
+    addImports([
+      { name: "useOAuthApplications", from: resolver.resolve("./runtime/app/composables/useOAuthApplications") },
+      { name: "useMyApplications", from: resolver.resolve("./runtime/app/composables/useOAuthApplications") }
+    ]);
+    if (settings.pages?.authorize !== false || adminPath || applicationsPath) {
+      extendPages((pages) => {
+        const existingPaths = new Set(pages.map((page) => page.path));
+        if (settings.pages?.authorize !== false && !existingPaths.has(authorizePath)) {
+          pages.push(defineModulePage(MODULE_NAME, { name: "oauth-authorize", path: authorizePath, file: resolver.resolve("./runtime/app/pages/authorize.vue") }));
+        }
+        if (adminPath && !existingPaths.has(adminPath)) {
+          pages.push(defineModulePage(MODULE_NAME, { name: "oauth-admin", path: adminPath, file: resolver.resolve("./runtime/app/pages/admin.vue") }));
+        }
+        if (applicationsPath && !existingPaths.has(applicationsPath)) {
+          pages.push(defineModulePage(MODULE_NAME, { name: "oauth-applications", path: applicationsPath, file: resolver.resolve("./runtime/app/pages/applications.vue") }));
+        }
+      });
+    }
+    if (withMenus) {
+      const { registerMenuSource } = await import('@frigear-nu/menu/utils');
+      registerMenuSource(nuxt, { file: resolver.resolve("./runtime/menus"), menu: "dashboard.account" });
+    }
+  }
+});
+
+export { module$1 as default };

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

@@ -0,0 +1 @@
+export { useOAuthApplications, useMyApplications } from './useOAuthApplications.js';

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

@@ -0,0 +1 @@
+export { useOAuthApplications, useMyApplications } from "./useOAuthApplications.js";

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

@@ -0,0 +1,19 @@
+import type { ApplicationInput } from '../../../types.js';
+/** Admin CRUD for applications. Every call needs the host's `oauth:authorize` hook to allow the user. */
+export declare function useOAuthApplications(): {
+    applications: any;
+    status: any;
+    error: any;
+    refresh: any;
+    create: (input: ApplicationInput) => Promise<any>;
+    update: (id: string, patch: Partial<ApplicationInput>) => Promise<any>;
+    remove: (id: string) => Promise<void>;
+    rotateSecret: (id: string) => Promise<any>;
+    revokeGrants: (id: string) => Promise<void>;
+};
+/** The applications the signed-in user may sign in to. */
+export declare function useMyApplications(): {
+    applications: any;
+    status: any;
+    refresh: any;
+};

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

@@ -0,0 +1,41 @@
+const BASE = "/api/oauth-server";
+export function useOAuthApplications() {
+  const { data, status, error, refresh } = useFetch(`${BASE}/admin/applications`, {
+    key: "oauth-server:applications",
+    default: () => []
+  });
+  async function create(input) {
+    const created = await $fetch(`${BASE}/admin/applications`, { method: "POST", body: input });
+    await refresh();
+    return created;
+  }
+  async function update(id, patch) {
+    const updated = await $fetch(`${BASE}/admin/applications/${id}`, { method: "PATCH", body: patch });
+    await refresh();
+    return updated;
+  }
+  async function remove(id) {
+    await $fetch(`${BASE}/admin/applications/${id}`, { method: "DELETE" });
+    await refresh();
+  }
+  async function rotateSecret(id) {
+    const { clientSecret } = await $fetch(`${BASE}/admin/applications/${id}/secret`, { method: "POST" });
+    await refresh();
+    return clientSecret;
+  }
+  async function revokeGrants(id) {
+    await $fetch(`${BASE}/admin/applications/${id}/revoke`, { method: "POST" });
+    await refresh();
+  }
+  return { applications: data, status, error, refresh, create, update, remove, rotateSecret, revokeGrants };
+}
+export function useMyApplications() {
+  const { loggedIn } = useUserSession();
+  const { data, status, refresh } = useFetch(`${BASE}/me/applications`, {
+    key: "oauth-server:mine",
+    immediate: loggedIn.value,
+    watch: false,
+    default: () => []
+  });
+  return { applications: data, status, refresh };
+}

package/dist/runtime/app/pages/admin.d.vue.ts

@@ -0,0 +1,3 @@
+declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+declare const _default: typeof __VLS_export;
+export default _default;