@jskit-ai/auth-web 0.1.245 → 0.1.246

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/auth-web",
-  "version": "0.1.245",
+  "version": "0.1.246",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
@@ -25,10 +25,10 @@
     "@mdi/js": "^7.4.47"
   },
   "peerDependencies": {
-    "@jskit-ai/auth-core": "0.1.242",
-    "@jskit-ai/http-runtime": "0.1.242",
-    "@jskit-ai/kernel": "0.1.244",
-    "@jskit-ai/shell-web": "0.1.249",
+    "@jskit-ai/auth-core": "0.1.243",
+    "@jskit-ai/http-runtime": "0.1.243",
+    "@jskit-ai/kernel": "0.1.245",
+    "@jskit-ai/shell-web": "0.1.250",
     "@tanstack/vue-query": "^5.90.5",
     "pinia": "^4.0.3",
     "vue": "^3.5.44",

package/patterns/auth-surface/PATTERN.md

@@ -30,16 +30,33 @@ Use the views, auth guard, HTTP client integration, sign-out runtime, providers,
 and Playwright auth helper exported by `@jskit-ai/auth-web`. Use auth policies
 from `@jskit-ai/auth-core` for server authorization.
 
-For a managed preview, copy the app-owned `tools/preview-identity` executable
-and declare it under `#### Preview identity` in the project's web-presented
-Vibe64 `Outputs` target with protocol `vibe64.preview-identity.command.v1`.
-Declare `AUTH_DEV_BYPASS_ENABLED` as its Enabled environment and
-`AUTH_DEV_BYPASS_SECRET` as its Secret environment so the preview host supplies
-fresh output-run-scoped values; users do not set those values by hand. JSKIT
-owns this executable/library pattern, Vibe64 owns the `Outputs` grammar and
-runtime behavior, and Genesis only composes that consumer-owned section as
-opaque text. The executable calls the exported managed-preview identity library
-directly; it does not require a JSKIT CLI.
+Every application with accounts includes the managed-preview login. It is
+standard, not optional: adding this pattern adds it, so a managed host's
+preview can sign its browser in as an existing account without anyone asking
+for it. Copy the app-owned `tools/preview-identity` executable (keep it
+executable) and declare it under `#### Preview identity` in the project's
+web-presented Vibe64 `Outputs` target, exactly:
+
+```markdown
+#### Preview identity
+
+- Command: `tools/preview-identity`
+- Protocol: `vibe64.preview-identity.command.v1`
+- Identity types: `email` `user-id`
+- Enabled environment: `AUTH_DEV_BYPASS_ENABLED`
+- Secret environment: `AUTH_DEV_BYPASS_SECRET`
+- Runtimes: `nodejs`
+```
+
+The preview host supplies fresh output-run-scoped values for both environment
+names; users do not set them by hand, and the exchange stays disabled without
+them. The person using the host chooses which existing accounts the preview may
+sign in as; the application never creates users for it. JSKIT owns this
+executable/library pattern, Vibe64 owns the `Outputs` grammar and runtime
+behavior, and Genesis only composes that consumer-owned section as opaque text.
+The executable calls the exported managed-preview identity library directly; it
+does not require a JSKIT CLI. A project without Genesis or a managed host keeps
+the executable; it is inert unless both environment values are present.
 
 Choose local-auth storage through the installed capability provider. A
 database-backed application installs `@jskit-ai/auth-provider-local-db-core`,
@@ -52,6 +69,8 @@ a user as a side effect.
 ## Invariants
 
 - Credentials and provider secrets come from environment values.
+- An application with accounts ships the executable `tools/preview-identity`
+  and declares it under `#### Preview identity` in its web `Outputs` target.
 - Auth backend selection comes from the installed provider graph, not an
   `AUTH_LOCAL_BACKEND` environment value.
 - The selected auth backend and the storage containing the application's users
@@ -72,7 +91,8 @@ a user as a side effect.
 
 `example/` contains concrete route wrappers, editable view wrappers, and the
 client runtime helpers needed by an authentication surface. It also contains
-the optional app-owned managed-preview identity executable. Compose their
+the standard app-owned managed-preview identity executable,
+`tools/preview-identity`. Compose their
 surface and placement declarations into the application's ordinary config and
 placement files.
 
@@ -87,6 +107,8 @@ Exercise failed and successful login, sign-out, reset, protected navigation,
 keyboard interaction, warm-cache return navigation, and browser refresh.
 Open the login route with an existing authenticated session and confirm it
 returns to the requested screen; repeat signed out and confirm the form remains.
+Confirm `tools/preview-identity` is committed as executable and the web
+`Outputs` target declares the `#### Preview identity` block above.
 
 ## Avoid
 

package/src/client/composables/loginView/oauthCallbackUrl.js

@@ -19,6 +19,7 @@ function stripOAuthParamsFromLocation() {
     "expires_at",
     "token_type",
     "state",
+    "iss",
     "sb",
     "type",
     "error",

package/src/client/composables/loginView/useLoginViewActions.js

@@ -14,6 +14,7 @@ import { normalizeAuthReturnToPath } from "../../lib/returnToPath.js";
 import { normalizeEmailAddress } from "./identityHelpers.js";
 import { readRememberedAccountHint } from "./rememberedAccountStorage.js";
 import { stripOAuthParamsFromLocation } from "./oauthCallbackUrl.js";
+import { completeOAuthPopupSignIn } from "../../runtime/popupOAuthLaunchClient.js";
 import { ensureCommandSectionValid } from "./validationHelpers.js";
 import { resolveRegisterCompletionState } from "./registerCompletion.js";
 
@@ -282,6 +283,9 @@ export function useLoginViewActions({
         shouldRemember: state.rememberAccountOnDevice.value !== false
       });
 
+      // A sign-in window opened by a framed app hands back and closes; if the
+      // browser keeps it open, it continues like an ordinary sign-in.
+      completeOAuthPopupSignIn();
       stripOAuthParamsFromLocation();
       if (typeof window === "object" && window.location) {
         window.location.replace(state.requestedReturnTo.value);

package/src/client/index.js

@@ -10,6 +10,10 @@ export { default as AuthProfileWidget } from "./views/AuthProfileWidget.vue";
 export { default as AuthProfileMenuLinkItem } from "./views/AuthProfileMenuLinkItem.vue";
 export { useAuthStore } from "./stores/useAuthStore.js";
 export { useAuthGuardRuntime } from "./runtime/inject.js";
+export {
+  completeOAuthPopupSignIn,
+  createPopupOAuthLaunchClient
+} from "./runtime/popupOAuthLaunchClient.js";
 export {
   completeOAuthCallbackFromCurrentLocation,
   completeOAuthCallbackFromUrl,

package/src/client/runtime/authClient.js

@@ -3,7 +3,7 @@ import { resolveSurfaceNavigationTargetFromPlacementContext } from "@jskit-ai/sh
 import { resolveAllowedReturnToOriginsFromPlacementContext } from "../lib/returnToPath.js";
 import { createAuthGuardRuntime } from "./authGuardRuntime.js";
 import { completeOAuthCallbackFromUrl } from "./oauthCallbackRuntime.js";
-import { createBrowserOAuthLaunchClient } from "./oauthLaunchClient.js";
+import { createPopupOAuthLaunchClient } from "./popupOAuthLaunchClient.js";
 import {
   AUTH_GUARD_RUNTIME_INJECTION_KEY,
   AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY
@@ -44,7 +44,7 @@ function createAuthClient({ mobile = null, pinia, realtime = null, shell, vueApp
     realtimeSocket: realtime?.socket || null
   });
   const mobileCallback = createMobileCallbackCompleter();
-  const oauthLaunch = mobile?.oauthLaunch || createBrowserOAuthLaunchClient();
+  const oauthLaunch = mobile?.oauthLaunch || createPopupOAuthLaunchClient();
   let stopAuthRefresh = null;
 
   async function initialize() {

package/src/client/runtime/inject.js

@@ -1,7 +1,8 @@
 import { inject } from "vue";
 import { normalizeAuthCapabilities } from "@jskit-ai/auth-core/shared/authCapabilities";
 import { isAuthGuardRuntime } from "./authGuardRuntime.js";
-import { createBrowserOAuthLaunchClient, isAuthOAuthLaunchClient } from "./oauthLaunchClient.js";
+import { isAuthOAuthLaunchClient } from "./oauthLaunchClient.js";
+import { createPopupOAuthLaunchClient } from "./popupOAuthLaunchClient.js";
 
 const AUTH_GUARD_RUNTIME_INJECTION_KEY = "jskit.auth-web.runtime.auth-guard.client";
 const AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY = "jskit.auth-web.runtime.oauth-launch.client";
@@ -52,7 +53,7 @@ function useAuthOAuthLaunchClient({ required = false } = {}) {
     throw new Error("OAuth launch client is not available in Vue injection context.");
   }
 
-  return createBrowserOAuthLaunchClient();
+  return createPopupOAuthLaunchClient();
 }
 
 export {

package/src/client/runtime/oauthCallbackRuntime.js

@@ -21,6 +21,8 @@ function readOAuthCallbackParamsFromUrl(url = "") {
 
   const { searchParams } = callbackUrlParams;
   const code = readAuthCallbackParam(callbackUrlParams, "code");
+  const state = readAuthCallbackParam(callbackUrlParams, "state");
+  const iss = readAuthCallbackParam(callbackUrlParams, "iss");
   const accessToken = readAuthCallbackParam(callbackUrlParams, "access_token");
   const refreshToken = readAuthCallbackParam(callbackUrlParams, "refresh_token");
   const errorCode = String(
@@ -39,6 +41,8 @@ function readOAuthCallbackParamsFromUrl(url = "") {
 
   return Object.freeze({
     code,
+    state,
+    iss,
     accessToken,
     refreshToken,
     hasSessionPair,
@@ -57,6 +61,12 @@ function buildOAuthCompletePayload({ callbackParams = null, provider = "", hasSe
   if (callbackParams?.code) {
     payload.code = callbackParams.code;
   }
+  if (callbackParams?.state) {
+    payload.state = callbackParams.state;
+  }
+  if (callbackParams?.iss) {
+    payload.iss = callbackParams.iss;
+  }
   if (hasSessionPair) {
     payload.accessToken = callbackParams?.accessToken;
     payload.refreshToken = callbackParams?.refreshToken;
@@ -142,7 +152,10 @@ async function completeOAuthCallbackFromUrl({
     return Object.freeze({
       handled: true,
       completed: true,
-      returnTo,
+      // A provider with one fixed redirect address returns the requested page itself.
+      returnTo: oauthResult?.returnTo && !callbackParams.returnTo
+        ? normalizeAuthReturnToPath(oauthResult.returnTo, fallbackReturnTo, { allowedOrigins: allowedReturnToOrigins })
+        : returnTo,
       callbackParams,
       oauthResult,
       session

package/src/client/runtime/popupOAuthLaunchClient.js

@@ -0,0 +1,144 @@
+import { createBrowserOAuthLaunchClient } from "./oauthLaunchClient.js";
+
+// A sign-in page refuses to be framed, so a framed app (an editor Preview, an
+// embedded dashboard) signs in through a window of its own. The window
+// completes the callback on the app's origin, tells the framed page, and closes.
+const OAUTH_POPUP_WINDOW_NAME = "jskit-oauth-sign-in";
+const OAUTH_POPUP_MESSAGE_TYPE = "jskit.auth-web.oauth-popup.complete";
+const OAUTH_POPUP_MARKER_KEY = "jskit.auth-web.oauth-popup.started-at";
+const OAUTH_POPUP_LIFETIME_MS = 10 * 60 * 1000;
+const OAUTH_POPUP_BLOCKED_MESSAGE =
+  "Your browser blocked the sign-in window. Allow pop-ups for this page, then try again.";
+
+function browserWindow() {
+  return typeof window === "object" && window ? window : null;
+}
+
+function isFramedWindow(win) {
+  try {
+    return win.self !== win.top;
+  } catch {
+    // A cross-origin parent hides window.top: that is a frame too.
+    return true;
+  }
+}
+
+function storageOf(win) {
+  try {
+    return win.localStorage || null;
+  } catch {
+    return null;
+  }
+}
+
+function popupFeatures(win, width = 520, height = 680) {
+  const left = Math.max(0, Math.round((win.screenX || 0) + ((win.outerWidth || width) - width) / 2));
+  const top = Math.max(0, Math.round((win.screenY || 0) + ((win.outerHeight || height) - height) / 2));
+  return `popup=yes,width=${width},height=${height},left=${left},top=${top}`;
+}
+
+function openChannel(win) {
+  return typeof win.BroadcastChannel === "function" ? new win.BroadcastChannel(OAUTH_POPUP_MESSAGE_TYPE) : null;
+}
+
+function createPopupOAuthLaunchClient({
+  window: win = browserWindow(),
+  fallback = createBrowserOAuthLaunchClient(),
+  onComplete = null
+} = {}) {
+  return Object.freeze({
+    async open({ url = "" } = {}) {
+      if (!win || !isFramedWindow(win)) {
+        return fallback.open({ url });
+      }
+      const normalizedUrl = String(url || "").trim();
+      if (!normalizedUrl) {
+        throw new Error("OAuth launch URL is required.");
+      }
+      const popup = win.open(normalizedUrl, OAUTH_POPUP_WINDOW_NAME, popupFeatures(win));
+      if (!popup) {
+        throw new Error(OAUTH_POPUP_BLOCKED_MESSAGE);
+      }
+      storageOf(win)?.setItem(OAUTH_POPUP_MARKER_KEY, String(Date.now()));
+      popup.focus?.();
+
+      // Some sign-in pages cut the opener link, so the window also answers on
+      // a same-origin channel. Closing it without finishing leaves this page as it was.
+      return new Promise((resolve) => {
+        const channel = openChannel(win);
+        let timer = null;
+        const finish = (completed) => {
+          win.removeEventListener("message", onMessage);
+          channel?.close();
+          win.clearTimeout(timer);
+          resolve(completed);
+          if (!completed) {
+            return;
+          }
+          if (typeof onComplete === "function") {
+            onComplete();
+          } else {
+            win.location.reload();
+          }
+        };
+        const onMessage = (event) => {
+          if (event?.origin === win.location.origin && event?.data?.type === OAUTH_POPUP_MESSAGE_TYPE) {
+            finish(true);
+          }
+        };
+        win.addEventListener("message", onMessage);
+        if (channel) {
+          channel.onmessage = (event) => {
+            if (event?.data?.type === OAUTH_POPUP_MESSAGE_TYPE) {
+              finish(true);
+            }
+          };
+        }
+        timer = win.setTimeout(() => finish(false), OAUTH_POPUP_LIFETIME_MS);
+      });
+    }
+  });
+}
+
+function sameOriginOpener(win) {
+  try {
+    const opener = win.opener;
+    return opener && opener !== win && !opener.closed && opener.location.origin === win.location.origin ? opener : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Called by the callback page after a completed sign-in. When this page is the
+ * sign-in window opened by a framed app, it tells that app and closes, and the
+ * function returns true. Otherwise it does nothing and returns false.
+ */
+function completeOAuthPopupSignIn(win = browserWindow()) {
+  if (!win) {
+    return false;
+  }
+  const storage = storageOf(win);
+  const startedAt = Number(storage?.getItem(OAUTH_POPUP_MARKER_KEY) || 0);
+  const opener = sameOriginOpener(win);
+  const recentlyStarted = startedAt > 0 && Date.now() - startedAt < OAUTH_POPUP_LIFETIME_MS;
+  if (!opener && !recentlyStarted) {
+    return false;
+  }
+  storage?.removeItem(OAUTH_POPUP_MARKER_KEY);
+  const message = { type: OAUTH_POPUP_MESSAGE_TYPE };
+  opener?.postMessage(message, win.location.origin);
+  const channel = openChannel(win);
+  channel?.postMessage(message);
+  channel?.close();
+  win.close();
+  return true;
+}
+
+export {
+  OAUTH_POPUP_BLOCKED_MESSAGE,
+  OAUTH_POPUP_MESSAGE_TYPE,
+  completeOAuthPopupSignIn,
+  createPopupOAuthLaunchClient,
+  isFramedWindow
+};

package/src/client/views/DefaultLoginView.vue

@@ -233,6 +233,7 @@ import { mdiEye, mdiEyeOff } from "@mdi/js";
 import { useDisplay } from "vuetify";
 import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
 import { useWebPlacementContext } from "@jskit-ai/shell-web/client/placement";
+import { useAuthOAuthLaunchClient } from "../runtime/inject.js";
 import { useLoginViewState } from "../composables/loginView/useLoginViewState.js";
 import { useLoginViewValidation } from "../composables/loginView/useLoginViewValidation.js";
 import { useLoginViewActions } from "../composables/loginView/useLoginViewActions.js";
@@ -250,7 +251,8 @@ const actions = useLoginViewActions({
   state,
   validation,
   queryClient,
-  errorRuntime
+  errorRuntime,
+  oauthLaunchClient: useAuthOAuthLaunchClient()
 });
 
 onMounted(actions.initializeOnMounted);
@@ -323,11 +325,13 @@ function toggleConfirmPasswordVisibility() {
 
 <style scoped>
 .login-screen {
+  /* Start below shell banners shown on a surface without an app bar. */
+  --auth-screen-height: calc(100dvh - var(--shell-error-banners-inline-height, 0px));
   position: fixed;
-  inset: 0;
+  inset: var(--shell-error-banners-inline-height, 0px) 0 0;
   z-index: 1;
   overflow-y: auto;
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
   background-color: rgb(var(--v-theme-background));
   background-image: radial-gradient(circle at 15% 12%, rgba(var(--v-theme-primary), 0.14), transparent 32%);
 }
@@ -337,7 +341,7 @@ function toggleConfirmPasswordVisibility() {
 }
 
 .login-shell {
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
 }
 
 .login-shell--mobile {
@@ -350,7 +354,7 @@ function toggleConfirmPasswordVisibility() {
 
 .auth-card--mobile {
   width: 100%;
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
 }
 
 .auth-content {
@@ -358,7 +362,7 @@ function toggleConfirmPasswordVisibility() {
 }
 
 .auth-content--mobile {
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
   padding: calc(24px + env(safe-area-inset-top, 0px)) 20px calc(32px + env(safe-area-inset-bottom, 0px));
 }
 

package/src/client/views/DefaultResetPasswordView.vue

@@ -175,16 +175,18 @@ onMounted(exchangeRecoveryToken);
 
 <style scoped>
 .reset-screen {
+  /* Start below shell banners shown on a surface without an app bar. */
+  --auth-screen-height: calc(100dvh - var(--shell-error-banners-inline-height, 0px));
   position: fixed;
-  inset: 0;
+  inset: var(--shell-error-banners-inline-height, 0px) 0 0;
   z-index: 1;
   overflow-y: auto;
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
   background-color: rgb(var(--v-theme-background));
 }
 
 .reset-shell {
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
 }
 
 .reset-card {
@@ -193,7 +195,7 @@ onMounted(exchangeRecoveryToken);
 
 .reset-card--mobile {
   width: 100%;
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
 }
 
 .reset-content {
@@ -201,7 +203,7 @@ onMounted(exchangeRecoveryToken);
 }
 
 .reset-content--mobile {
-  min-height: 100dvh;
+  min-height: var(--auth-screen-height);
   padding: calc(24px + env(safe-area-inset-top, 0px)) 20px calc(32px + env(safe-area-inset-bottom, 0px));
 }
 

package/src/server/controllers/AuthController.js

@@ -1,3 +1,4 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { normalizeAuthDenied } from "@jskit-ai/auth-core/shared/authDenied";
 import { AUTH_ACTION_IDS } from "../constants/authActionIds.js";
 import { AuthWebService } from "../services/AuthWebService.js";
@@ -75,20 +76,34 @@ class AuthController {
   async oauthStart(request, reply) {
     const provider = request.params?.provider;
     const returnTo = request.query?.returnTo;
-    const result = await this.service.oauthStart(request, { provider, returnTo });
+    let result;
+    try {
+      result = await this.service.oauthStart(request, { provider, returnTo });
+    } catch (error) {
+      if (!(error instanceof AppError) || error.statusCode === 500) {
+        throw error;
+      }
+      // The browser navigated here, so the login page explains instead of a JSON body.
+      const explained = new URLSearchParams({ error: "sign_in_unavailable", error_description: error.message });
+      reply.redirect(`/auth/login?${explained}`);
+      return;
+    }
+    this.service.writeOAuthStartCookies(reply, result);
     reply.redirect(result.url);
   }
 
   async oauthComplete(request, reply) {
     const payload = request.body || {};
     const result = await this.service.oauthComplete(request, payload);
+    this.service.clearOAuthStartCookies(reply);
     this.service.writeSessionCookies(reply, result.session);
 
     reply.code(200).send({
       ok: true,
       provider: result.provider,
       username: result.actor.displayName,
-      email: result.actor.email
+      email: result.actor.email,
+      ...(result.returnTo ? { returnTo: result.returnTo } : {})
     });
   }
 

package/src/server/services/AuthWebService.js

@@ -124,6 +124,22 @@ class AuthWebService {
     }
   }
 
+  // Providers that bind an OAuth attempt to the browser (state, nonce, PKCE)
+  // keep it in their own short-lived cookie; others need no hook.
+  writeOAuthStartCookies(reply, result) {
+    const authService = this.resolveAuthService();
+    if (reply && typeof authService.writeOAuthStartCookies === "function") {
+      authService.writeOAuthStartCookies(reply, result);
+    }
+  }
+
+  clearOAuthStartCookies(reply) {
+    const authService = this.resolveAuthService();
+    if (reply && typeof authService.clearOAuthStartCookies === "function") {
+      authService.clearOAuthStartCookies(reply);
+    }
+  }
+
   clearSessionCookies(reply) {
     if (reply) {
       this.resolveAuthService().clearSessionCookies(reply);

package/test/clientSurface.test.js

@@ -92,7 +92,17 @@ test("default login view owns the viewport and becomes a full-screen mobile scre
   assert.match(viewSource, /:elevation="isMobileViewport \? 0 : 1"/);
   assert.match(viewSource, /:border="!isMobileViewport"/);
   assert.match(viewSource, /\.login-screen\s*\{[\s\S]*position:\s*fixed;/);
-  assert.match(viewSource, /\.login-screen\s*\{[\s\S]*inset:\s*0;/);
+  // The full-viewport screen starts below shell banners shown on this bar-less surface.
+  assert.match(viewSource, /\.login-screen\s*\{[\s\S]*inset:\s*var\(--shell-error-banners-inline-height, 0px\) 0 0;/);
+});
+
+test("default reset view starts below shell banners on its bar-less surface", () => {
+  const viewPath = fileURLToPath(new URL("../src/client/views/DefaultResetPasswordView.vue", import.meta.url));
+  const viewSource = readFileSync(viewPath, "utf8");
+
+  assert.match(viewSource, /\.reset-screen\s*\{[\s\S]*position:\s*fixed;/);
+  assert.match(viewSource, /\.reset-screen\s*\{[\s\S]*inset:\s*var\(--shell-error-banners-inline-height, 0px\) 0 0;/);
+  assert.doesNotMatch(viewSource, /min-height:\s*100dvh/);
 });
 
 test("default login view avoids decorative login chrome", () => {
@@ -167,3 +177,10 @@ test("default reset password view preserves recovery session-pair callback token
   assert.doesNotMatch(viewSource, /if \(!recoveryPayload\)\s*\{\s*status\.value = "error";/);
   assert.doesNotMatch(viewSource, /hash\.get\("access_token"\)[\s\S]*code:/);
 });
+
+test("default login view hands its OAuth buttons the launch client", () => {
+  const viewPath = fileURLToPath(new URL("../src/client/views/DefaultLoginView.vue", import.meta.url));
+  const viewSource = readFileSync(viewPath, "utf8");
+
+  assert.match(viewSource, /oauthLaunchClient: useAuthOAuthLaunchClient\(\)/);
+});

package/test/managedPreviewIdentity.test.js

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import { readFileSync, statSync } from "node:fs";
 import test from "node:test";
 
 import {
@@ -105,3 +106,22 @@ test("managed preview identity rejects a disabled or non-local exchange", async
   assert.equal(remote.ok, false);
   assert.equal(remote.code, "jskit_managed_preview_identity_target_invalid");
 });
+
+test("the auth surface pattern ships the managed-preview login as standard", () => {
+  const pattern = readFileSync(new URL("../patterns/auth-surface/PATTERN.md", import.meta.url), "utf8");
+  const executable = new URL("../patterns/auth-surface/example/tools/preview-identity", import.meta.url);
+
+  assert.equal(statSync(executable).mode & 0o111, 0o111);
+  assert.match(readFileSync(executable, "utf8"), /runManagedPreviewIdentityCommand/u);
+  assert.match(pattern, /standard, not optional/u);
+  assert.ok(pattern.includes([
+    "#### Preview identity",
+    "",
+    "- Command: `tools/preview-identity`",
+    `- Protocol: \`${MANAGED_PREVIEW_IDENTITY_PROTOCOL}\``,
+    "- Identity types: `email` `user-id`",
+    "- Enabled environment: `AUTH_DEV_BYPASS_ENABLED`",
+    "- Secret environment: `AUTH_DEV_BYPASS_SECRET`",
+    "- Runtimes: `nodejs`"
+  ].join("\n")));
+});

package/test/oauthCallbackRuntime.test.js

@@ -15,6 +15,8 @@ test("readOAuthCallbackParamsFromUrl reads query and hash callback params", () =
     readOAuthCallbackParamsFromUrl("/auth/login?oauthProvider=google&oauthReturnTo=%2Fw%2Facme&code=abc"),
     {
       code: "abc",
+      state: "",
+      iss: "",
       accessToken: "",
       refreshToken: "",
       hasSessionPair: false,
@@ -29,6 +31,8 @@ test("readOAuthCallbackParamsFromUrl reads query and hash callback params", () =
     readOAuthCallbackParamsFromUrl("/auth/login?oauthReturnTo=%2Fhome#access_token=access&refresh_token=refresh"),
     {
       code: "",
+      state: "",
+      iss: "",
       accessToken: "access",
       refreshToken: "refresh",
       hasSessionPair: true,
@@ -208,3 +212,19 @@ test("completeOAuthCallbackFromCurrentLocation reads from window.location.href",
     globalThis.window = originalWindow;
   }
 });
+
+test("completeOAuthCallbackFromUrl forwards state and iss, and takes the page from a fixed-address provider", async () => {
+  const calls = [];
+  const result = await completeOAuthCallbackFromUrl({
+    url: "/auth/login?code=abc&state=st-1&iss=https%3A%2F%2Faccounts.example.test",
+    defaultProvider: "oidc",
+    request: async (path, options) => {
+      calls.push(options.body);
+      return { username: "Ada", email: "ada@example.com", returnTo: "/reports" };
+    },
+    refreshSession: async () => ({ authenticated: true })
+  });
+  assert.deepEqual(calls, [{ provider: "oidc", code: "abc", state: "st-1", iss: "https://accounts.example.test" }]);
+  assert.equal(result.completed, true);
+  assert.equal(result.returnTo, "/reports");
+});

package/test/popupOAuthLaunchClient.test.js

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  OAUTH_POPUP_BLOCKED_MESSAGE,
+  OAUTH_POPUP_MESSAGE_TYPE,
+  completeOAuthPopupSignIn,
+  createPopupOAuthLaunchClient
+} from "../src/client/runtime/popupOAuthLaunchClient.js";
+
+function memoryStorage() {
+  const values = new Map();
+  return {
+    getItem: (key) => (values.has(key) ? values.get(key) : null),
+    setItem: (key, value) => values.set(key, String(value)),
+    removeItem: (key) => values.delete(key)
+  };
+}
+
+function fakeWindow({ framed = false, popup = {}, storage = memoryStorage() } = {}) {
+  const listeners = new Set();
+  const win = {
+    location: { origin: "https://app.example.test", reloaded: 0, reload() { this.reloaded += 1; } },
+    localStorage: storage,
+    opened: [],
+    closed: false,
+    open(url, name, features) {
+      this.opened.push({ url, name, features });
+      return popup;
+    },
+    close() {
+      this.closed = true;
+    },
+    addEventListener: (_type, listener) => listeners.add(listener),
+    removeEventListener: (_type, listener) => listeners.delete(listener),
+    dispatch: (event) => [...listeners].forEach((listener) => listener(event)),
+    setTimeout: () => 1,
+    clearTimeout() {},
+    listenerCount: () => listeners.size
+  };
+  win.self = win;
+  win.top = framed ? {} : win;
+  return win;
+}
+
+test("an unframed page signs in by navigating, as before", async () => {
+  const navigations = [];
+  const win = fakeWindow();
+  const client = createPopupOAuthLaunchClient({ window: win, fallback: { open: async ({ url }) => navigations.push(url) } });
+  await client.open({ url: "/api/oauth/oidc/start" });
+  assert.deepEqual(navigations, ["/api/oauth/oidc/start"]);
+  assert.equal(win.opened.length, 0);
+});
+
+test("a framed page opens a sign-in window and reloads when it reports success", async () => {
+  const win = fakeWindow({ framed: true });
+  const client = createPopupOAuthLaunchClient({ window: win });
+  const opening = client.open({ url: "/api/oauth/oidc/start?returnTo=%2F" });
+  assert.equal(win.opened[0].url, "/api/oauth/oidc/start?returnTo=%2F");
+  assert.equal(win.opened[0].name, "jskit-oauth-sign-in");
+  assert.match(win.opened[0].features, /^popup=yes,width=520,height=680/u);
+
+  win.dispatch({ origin: "https://attacker.example", data: { type: OAUTH_POPUP_MESSAGE_TYPE } });
+  win.dispatch({ origin: "https://app.example.test", data: { type: "something-else" } });
+  assert.equal(win.location.reloaded, 0, "only this origin's completion message counts");
+
+  win.dispatch({ origin: "https://app.example.test", data: { type: OAUTH_POPUP_MESSAGE_TYPE } });
+  assert.equal(await opening, true);
+  assert.equal(win.location.reloaded, 1);
+  assert.equal(win.listenerCount(), 0);
+});
+
+test("a blocked window says how to allow it", async () => {
+  const win = fakeWindow({ framed: true, popup: null });
+  await assert.rejects(createPopupOAuthLaunchClient({ window: win }).open({ url: "/start" }), { message: OAUTH_POPUP_BLOCKED_MESSAGE });
+});
+
+test("the callback window tells its opener and closes", () => {
+  const messages = [];
+  const opener = { closed: false, location: { origin: "https://app.example.test" }, postMessage: (message, origin) => messages.push({ message, origin }) };
+  const popupWindow = { ...fakeWindow(), opener };
+  assert.equal(completeOAuthPopupSignIn(popupWindow), true);
+  assert.deepEqual(messages, [{ message: { type: OAUTH_POPUP_MESSAGE_TYPE }, origin: "https://app.example.test" }]);
+  assert.equal(popupWindow.closed, true);
+});
+
+test("a callback in an ordinary tab is left alone", () => {
+  const tab = fakeWindow();
+  assert.equal(completeOAuthPopupSignIn(tab), false);
+  assert.equal(tab.closed, false);
+  const foreignOpener = { ...fakeWindow(), opener: { closed: false, location: { get origin() { throw new Error("cross-origin"); } } } };
+  assert.equal(completeOAuthPopupSignIn(foreignOpener), false);
+});
+
+test("a window whose opener link was cut still finishes through the shared channel", () => {
+  const storage = memoryStorage();
+  const framed = fakeWindow({ framed: true, storage, popup: {} });
+  createPopupOAuthLaunchClient({ window: framed }).open({ url: "/start" });
+  const callback = fakeWindow({ storage });
+  callback.opener = null;
+  assert.equal(completeOAuthPopupSignIn(callback), true);
+  assert.equal(callback.closed, true);
+  assert.equal(storage.getItem("jskit.auth-web.oauth-popup.started-at"), null);
+});