@quazardous/qdadm 2.16.1 → 2.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quazardous/qdadm",
-  "version": "2.16.1",
+  "version": "2.17.1",
   "description": "Vue 3 framework for admin dashboards with PrimeVue",
   "author": "quazardous",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "format": "prettier --write src/",
     "build:types": "vue-tsc --declaration --emitDeclarationOnly --outDir dist/types",
     "build:node": "tsc -p tsconfig.node.json",
-    "prepack": "npm run build:node"
+    "prepare": "npm run build:node"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -54,7 +54,7 @@
     "dist/node"
   ],
   "dependencies": {
-    "@quazardous/qdcore": "^1.1.0",
+    "@quazardous/qdcore": "^1.1.1",
     "@quazardous/qddebug": "^1.1.0",
     "@quazardous/quarkernel": "^2.1.0",
     "yaml": "^2.8.4"

package/src/auth/index.ts

@@ -13,3 +13,12 @@ export {
   type ISessionAuthAdapter,
   type LocalStorageAuthConfig,
 } from './SessionAuthAdapter'
+
+export {
+  GoogleOAuthAdapter,
+  createGoogleOAuthAdapter,
+  createPkceChallenge,
+  type GoogleOAuthAdapterOptions,
+  type OAuthExchangePayload,
+  type PkceChallenge,
+} from './oauth/index'

package/src/auth/oauth/GoogleOAuthAdapter.ts

@@ -0,0 +1,235 @@
+/**
+ * Google sign-in for qdadm, authorization-code + PKCE (#1775).
+ *
+ * ## The one rule this class exists to enforce
+ *
+ * qdadm **never** validates a Google credential in the browser. Decoding a JWT
+ * client-side proves nothing: anyone can mint one. The authorization code is
+ * therefore useless to the front — it is posted to *your* backend, which
+ * exchanges it with Google using the client secret, verifies the identity, and
+ * issues **its own** session. That session token is the only thing this adapter
+ * ever stores.
+ *
+ * There is deliberately no code path that turns a Google response into a
+ * session without your backend. That is a structural constraint, not advice.
+ *
+ * ## The backend contract is open
+ *
+ * `exchangeUrl` receives a POST and returns `{ token, user }`. Nothing about it
+ * is JavaScript: implement it in Python, Go, PHP, anything. Because the
+ * contract is open, configuration is enough for the common case —
+ *
+ * ```ts
+ * new GoogleOAuthAdapter({
+ *   clientId: '…apps.googleusercontent.com',
+ *   exchangeUrl: '/auth/google/exchange',
+ * })
+ * ```
+ *
+ * — and an app with a Python backend writes no adapter code at all. Override
+ * `exchange()` only when your endpoint cannot match the documented shape.
+ *
+ * See docs/auth-google.md for the wire contract and a reference backend.
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+
+import { LocalStorageSessionAuthAdapter, type AuthUser, type SessionData } from '../SessionAuthAdapter'
+import { createPkceChallenge, storeAttempt, takeAttempt, type StoredAttempt } from './pkce'
+
+/** What the front sends your backend. */
+export interface OAuthExchangePayload {
+  /** The authorization code the provider handed back. */
+  code: string
+  /** The PKCE verifier that proves this code belongs to this browser. */
+  codeVerifier: string
+  /** Echoed so the backend can pin the exchange to the same redirect. */
+  redirectUri: string
+}
+
+export interface GoogleOAuthAdapterOptions {
+  /** OAuth client id. Not a secret — the client SECRET stays on your backend. */
+  clientId: string
+  /**
+   * Your endpoint that trades the code for a session. POSTed
+   * `OAuthExchangePayload`, expected to answer `{ token, user }`.
+   */
+  exchangeUrl?: string
+  /**
+   * Where the provider redirects back. Must match a URI registered in the
+   * provider console **exactly** — that is the single most common setup
+   * failure. Defaults to `/auth/google/callback` on the current origin.
+   */
+  redirectUri?: string
+  /** Scopes requested. Defaults to identity only. */
+  scopes?: string[]
+  /**
+   * Ask for a refresh token. Requires `prompt: 'consent'` on Google to be
+   * issued reliably, and the token stays with your backend — the front never
+   * sees it.
+   */
+  offlineAccess?: boolean
+  /** localStorage key for the session (see ADR 0008 on shared origins). */
+  storageKey?: string
+  /** Authorization endpoint. Overridable for tests and for other providers. */
+  authorizeEndpoint?: string
+}
+
+const GOOGLE_AUTHORIZE = 'https://accounts.google.com/o/oauth2/v2/auth'
+
+export class GoogleOAuthAdapter<TUser extends AuthUser = AuthUser>
+  extends LocalStorageSessionAuthAdapter<TUser> {
+  protected _clientId: string
+  protected _exchangeUrl: string | null
+  protected _redirectUri: string
+  protected _scopes: string[]
+  protected _offlineAccess: boolean
+  protected _authorizeEndpoint: string
+
+  constructor(options: GoogleOAuthAdapterOptions) {
+    super({ storageKey: options.storageKey ?? 'qdadm_auth' })
+
+    if (!options?.clientId) {
+      throw new Error('[GoogleOAuthAdapter] clientId is required')
+    }
+
+    this._clientId = options.clientId
+    this._exchangeUrl = options.exchangeUrl ?? null
+    this._redirectUri =
+      options.redirectUri ??
+      (typeof window !== 'undefined'
+        ? `${window.location.origin}/auth/google/callback`
+        : '/auth/google/callback')
+    this._scopes = options.scopes ?? ['openid', 'email', 'profile']
+    this._offlineAccess = options.offlineAccess ?? false
+    this._authorizeEndpoint = options.authorizeEndpoint ?? GOOGLE_AUTHORIZE
+  }
+
+  /** The redirect URI this adapter will use — handy for error messages. */
+  get redirectUri(): string {
+    return this._redirectUri
+  }
+
+  /**
+   * Build the authorization URL for a fresh attempt.
+   *
+   * Stashes the PKCE verifier, the CSRF state and where the user was heading,
+   * so the callback can finish what this started.
+   */
+  async buildAuthorizeUrl(redirectTo = '/'): Promise<string> {
+    const { verifier, challenge, state } = await createPkceChallenge()
+    storeAttempt({ verifier, state, redirectTo })
+
+    const url = new URL(this._authorizeEndpoint)
+    url.searchParams.set('client_id', this._clientId)
+    url.searchParams.set('redirect_uri', this._redirectUri)
+    url.searchParams.set('response_type', 'code')
+    url.searchParams.set('scope', this._scopes.join(' '))
+    url.searchParams.set('state', state)
+    url.searchParams.set('code_challenge', challenge)
+    url.searchParams.set('code_challenge_method', 'S256')
+    if (this._offlineAccess) {
+      url.searchParams.set('access_type', 'offline')
+      // Google only re-issues a refresh token when consent is asked again.
+      url.searchParams.set('prompt', 'consent')
+    }
+
+    return url.toString()
+  }
+
+  /** Send the browser to the provider. */
+  async beginLogin(redirectTo = '/'): Promise<void> {
+    window.location.assign(await this.buildAuthorizeUrl(redirectTo))
+  }
+
+  /**
+   * Trade the code for a session **on your backend**.
+   *
+   * Override this when your endpoint's shape differs. Whatever you do, the
+   * exchange must happen server-side: the browser has no client secret and
+   * cannot verify anything Google says.
+   */
+  async exchange(payload: OAuthExchangePayload): Promise<SessionData<TUser>> {
+    if (!this._exchangeUrl) {
+      throw new Error(
+        '[GoogleOAuthAdapter] no exchangeUrl configured, and exchange() was not overridden. ' +
+          'The authorization code must be redeemed by your backend — the browser cannot do it.'
+      )
+    }
+
+    const response = await fetch(this._exchangeUrl, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      credentials: 'same-origin',
+      body: JSON.stringify(payload),
+    })
+
+    if (!response.ok) {
+      const detail = await response.text().catch(() => '')
+      throw new Error(
+        `[GoogleOAuthAdapter] exchange failed (${response.status})${detail ? `: ${detail.slice(0, 200)}` : ''}`
+      )
+    }
+
+    const data = (await response.json()) as SessionData<TUser>
+    if (!data?.token || !data?.user) {
+      throw new Error(
+        '[GoogleOAuthAdapter] exchange endpoint must return { token, user } — see docs/auth-google.md'
+      )
+    }
+    return data
+  }
+
+  /**
+   * Finish the login from the callback route's query string.
+   *
+   * @returns the session plus where to send the user next.
+   * @throws when the provider reported an error, when no attempt is pending,
+   *   or when `state` does not match — each of which is a reason to refuse.
+   */
+  async completeLogin(
+    query: URLSearchParams | Record<string, string | undefined>
+  ): Promise<SessionData<TUser> & { redirectTo: string }> {
+    const read = (key: string): string | undefined =>
+      query instanceof URLSearchParams ? (query.get(key) ?? undefined) : query[key]
+
+    const providerError = read('error')
+    if (providerError) {
+      throw new Error(`[GoogleOAuthAdapter] provider refused the login: ${providerError}`)
+    }
+
+    const attempt: StoredAttempt | null = takeAttempt()
+    if (!attempt) {
+      // No pending attempt: a replayed or bookmarked callback URL. Refusing is
+      // the point — the attempt is consumed on read.
+      throw new Error('[GoogleOAuthAdapter] no login attempt pending for this callback')
+    }
+
+    const state = read('state')
+    if (!state || state !== attempt.state) {
+      throw new Error('[GoogleOAuthAdapter] state mismatch — refusing the callback')
+    }
+
+    const code = read('code')
+    if (!code) {
+      throw new Error('[GoogleOAuthAdapter] callback carried no authorization code')
+    }
+
+    const session = await this.exchange({
+      code,
+      codeVerifier: attempt.verifier,
+      redirectUri: this._redirectUri,
+    })
+
+    this.setSession(session.token, session.user)
+    this.persist()
+
+    return { ...session, redirectTo: attempt.redirectTo || '/' }
+  }
+}
+
+export function createGoogleOAuthAdapter<TUser extends AuthUser = AuthUser>(
+  options: GoogleOAuthAdapterOptions
+): GoogleOAuthAdapter<TUser> {
+  return new GoogleOAuthAdapter<TUser>(options)
+}

package/src/auth/oauth/index.ts

@@ -0,0 +1,23 @@
+/**
+ * OAuth sign-in helpers (#1775).
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ *
+ * @module auth/oauth
+ */
+
+export {
+  GoogleOAuthAdapter,
+  createGoogleOAuthAdapter,
+  type GoogleOAuthAdapterOptions,
+  type OAuthExchangePayload,
+} from './GoogleOAuthAdapter'
+
+export {
+  createPkceChallenge,
+  storeAttempt,
+  takeAttempt,
+  clearAttempt,
+  type PkceChallenge,
+  type StoredAttempt,
+} from './pkce'

package/src/auth/oauth/pkce.ts

@@ -0,0 +1,96 @@
+/**
+ * PKCE and CSRF state for the OAuth authorization-code flow (#1775).
+ *
+ * No dependency: `crypto.getRandomValues` and `crypto.subtle` exist in every
+ * secure context, and `localhost` counts as one.
+ *
+ * Why both matter, since they are often confused:
+ *
+ * - **PKCE** protects the authorization code while it travels through the
+ *   browser. The code lands on a front-end route and is then posted to your
+ *   backend; without the verifier, whoever intercepts it can redeem it.
+ * - **`state`** is CSRF protection for the redirect itself: it proves the
+ *   callback being handled belongs to a login *this tab* started.
+ *
+ * Both live in `sessionStorage`, never `localStorage`: they are single-use,
+ * they belong to one tab, and they must not outlive it.
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+
+/** What one login attempt must remember across the redirect. */
+export interface PkceChallenge {
+  /** Kept locally, sent to your backend at exchange time — never to Google. */
+  verifier: string
+  /** Sent to the provider in the authorize URL. */
+  challenge: string
+  /** CSRF nonce echoed back by the provider. */
+  state: string
+}
+
+/** The pending attempt, recovered when the provider redirects back. */
+export interface StoredAttempt {
+  verifier: string
+  state: string
+  /** Where the user was heading before being sent to the login page. */
+  redirectTo: string
+}
+
+const STORAGE_KEY = 'qdadm_oauth_attempt'
+
+/** URL-safe base64 without padding, as RFC 7636 requires. */
+function base64Url(bytes: ArrayBuffer | Uint8Array): string {
+  const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes)
+  let binary = ''
+  for (const byte of view) binary += String.fromCharCode(byte)
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function randomString(byteLength = 32): string {
+  const bytes = new Uint8Array(byteLength)
+  crypto.getRandomValues(bytes)
+  return base64Url(bytes)
+}
+
+/**
+ * Build a fresh verifier / challenge / state triple.
+ *
+ * S256 only. The spec still allows `plain`, but `plain` sends the verifier to
+ * the authorization server, which defeats the point of having one.
+ */
+export async function createPkceChallenge(): Promise<PkceChallenge> {
+  const verifier = randomString(32)
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(verifier))
+
+  return { verifier, challenge: base64Url(digest), state: randomString(16) }
+}
+
+/** Stash the pending attempt for the trip through the provider. */
+export function storeAttempt(attempt: StoredAttempt): void {
+  sessionStorage.setItem(STORAGE_KEY, JSON.stringify(attempt))
+}
+
+/**
+ * Recover the pending attempt AND clear it.
+ *
+ * A login attempt is single-use: a replayed callback URL finds nothing and is
+ * rejected, which is half of what `state` is for.
+ */
+export function takeAttempt(): StoredAttempt | null {
+  const raw = sessionStorage.getItem(STORAGE_KEY)
+  sessionStorage.removeItem(STORAGE_KEY)
+  if (!raw) return null
+
+  try {
+    const parsed = JSON.parse(raw) as StoredAttempt
+    if (!parsed?.verifier || !parsed?.state) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+/** Drop a pending attempt without consuming it (the user backed out). */
+export function clearAttempt(): void {
+  sessionStorage.removeItem(STORAGE_KEY)
+}

package/src/components/index.ts

@@ -77,6 +77,7 @@ export { default as BannerZone } from './display/BannerZone.vue'
 
 // Pages
 export { default as LoginPage } from './pages/LoginPage.vue'
+export { default as OAuthCallbackPage } from './pages/OAuthCallbackPage.vue'
 export { default as NotFoundPage } from './pages/NotFoundPage.vue'
 
 // Host integration helper — render in a host App.vue when using

package/src/components/pages/LoginPage.vue

@@ -252,6 +252,14 @@ async function handleLogin(): Promise<void> {
             class="w-full"
             :loading="loading"
           />
+          <!-- Alternative sign-ins (#1775): SSO buttons go between the form
+               and the footer, which is where users look for them. Rendered
+               only when filled, so the divider never shows on its own. -->
+          <div v-if="$slots.alternatives" class="qdadm-login-alternatives">
+            <div class="qdadm-login-divider"><span>or</span></div>
+            <slot name="alternatives"></slot>
+          </div>
+
           <slot name="footer"></slot>
         </form>
       </template>
@@ -260,6 +268,27 @@ async function handleLogin(): Promise<void> {
 </template>
 
 <style scoped>
+.qdadm-login-alternatives {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+}
+
+.qdadm-login-divider {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  color: var(--p-text-muted-color, #6b7280);
+  font-size: 0.875rem;
+}
+
+.qdadm-login-divider::before,
+.qdadm-login-divider::after {
+  content: '';
+  flex: 1;
+  border-top: 1px solid var(--p-content-border-color, #e5e7eb);
+}
+
 /*
  * Only keep styles here that REQUIRE scoping (:deep, dynamic binding, component-specific overrides).
  * Generic/reusable styles belong in src/styles/ partials (see _forms.scss, _cards.scss, etc.).

package/src/components/pages/OAuthCallbackPage.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+/**
+ * OAuth callback landing page (#1775).
+ *
+ * Register this on a **public** route. `Kernel.routing.ts:192` sends anyone
+ * unauthenticated back to the login page, and at this exact moment the user is
+ * *not yet* authenticated — a guarded callback route bounces the provider's
+ * redirect straight back to login, which is the classic way this flow fails
+ * and gives no clue why:
+ *
+ * ```js
+ * ctx.routes('/auth/google', [{
+ *   path: 'callback',
+ *   name: 'google-callback',
+ *   component: () => import('@quazardous/qdadm/components/OAuthCallbackPage.vue'),
+ *   meta: { public: true },   // ← without this, nothing works
+ * }])
+ * ```
+ *
+ * The page itself does almost nothing: it hands the query string to the
+ * adapter, which validates `state`, has your backend redeem the code, and
+ * stores the session your backend issued. Then it goes where the user was
+ * headed before login sent them away.
+ *
+ * @experimental Shape may change in a minor release — see docs/API_STABILITY.md.
+ */
+import { ref, inject, onMounted } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import QdButton from '../base/QdButton.vue'
+
+interface OAuthCapableAdapter {
+  completeLogin: (
+    query: Record<string, string | undefined>
+  ) => Promise<{ user?: unknown; redirectTo: string }>
+}
+
+interface SignalsLike {
+  emit?: (signal: string, payload?: unknown) => unknown
+}
+
+const props = defineProps({
+  /** Where to send the user when the callback carries no destination. */
+  fallbackRedirect: { type: String, default: '/' },
+  /** Route to offer on failure. */
+  loginRoute: { type: String, default: '/login' },
+  /** Shown while the exchange is in flight. */
+  pendingLabel: { type: String, default: 'Signing you in…' },
+})
+
+const emit = defineEmits<{
+  (e: 'success', payload: unknown): void
+  (e: 'error', error: unknown): void
+}>()
+
+const route = useRoute()
+const router = useRouter()
+const authAdapter = inject<OAuthCapableAdapter | null>('authAdapter', null)
+const signals = inject<SignalsLike | null>('qdadmSignals', null)
+
+const error = ref<string | null>(null)
+
+onMounted(async () => {
+  if (typeof authAdapter?.completeLogin !== 'function') {
+    error.value =
+      'No OAuth-capable auth adapter is configured. The kernel needs an adapter exposing completeLogin().'
+    emit('error', new Error(error.value))
+    return
+  }
+
+  try {
+    const query = Object.fromEntries(
+      Object.entries(route.query).map(([key, value]) => [
+        key,
+        Array.isArray(value) ? value[0] : value,
+      ])
+    ) as Record<string, string | undefined>
+
+    const result = await authAdapter.completeLogin(query)
+
+    // Same signal the password form emits, so debug bar, SSE bridge and any
+    // listener see one authentication event whichever door was used.
+    signals?.emit?.('auth:login', { user: result.user })
+    emit('success', result)
+
+    await router.replace(result.redirectTo || props.fallbackRedirect)
+  } catch (err) {
+    error.value = (err as Error)?.message ?? 'Sign-in failed'
+    signals?.emit?.('auth:login:error', { error: error.value })
+    emit('error', err)
+  }
+})
+</script>
+
+<template>
+  <div class="qdadm-oauth-callback">
+    <template v-if="error">
+      <i class="pi pi-times-circle qdadm-oauth-icon qdadm-oauth-icon-error" />
+      <p class="qdadm-oauth-message">{{ error }}</p>
+      <QdButton label="Back to sign in" icon="pi pi-arrow-left" @click="router.replace(loginRoute)" />
+    </template>
+    <template v-else>
+      <i class="pi pi-spin pi-spinner qdadm-oauth-icon" />
+      <p class="qdadm-oauth-message">{{ pendingLabel }}</p>
+    </template>
+  </div>
+</template>
+
+<style scoped>
+.qdadm-oauth-callback {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+  min-height: 60vh;
+  padding: 2rem;
+  text-align: center;
+}
+
+.qdadm-oauth-icon {
+  font-size: 2rem;
+  color: var(--p-primary-color, #10b981);
+}
+
+.qdadm-oauth-icon-error {
+  color: var(--p-red-500, #ef4444);
+}
+
+.qdadm-oauth-message {
+  margin: 0;
+  color: var(--p-text-muted-color, #6b7280);
+  max-width: 34rem;
+}
+</style>

package/src/index.ts

@@ -164,6 +164,12 @@ export * from './entity/auth'
 // SESSION AUTH (user authentication)
 // ════════════════════════════════════════════════════════════════════════════
 export { LocalStorageSessionAuthAdapter } from './auth'
+export { GoogleOAuthAdapter, createGoogleOAuthAdapter, createPkceChallenge } from './auth'
+export type {
+  GoogleOAuthAdapterOptions,
+  OAuthExchangePayload,
+  PkceChallenge,
+} from './auth'
 export type {
   LoginCredentials,
   SessionData,