@jskit-ai/auth-web 0.1.64 → 0.1.65

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   "packageVersion": 1,
   "packageId": "@jskit-ai/auth-web",
-  "version": "0.1.64",
+  "version": "0.1.65",
   "kind": "runtime",
   "description": "Auth web module: Fastify auth routes plus web login/sign-out scaffolds.",
   "dependsOn": [
@@ -219,10 +219,10 @@ export default Object.freeze({
       "runtime": {
         "@tanstack/vue-query": "5.92.12",
         "@mdi/js": "^7.4.47",
-        "@jskit-ai/auth-core": "0.1.62",
-        "@jskit-ai/http-runtime": "0.1.62",
-        "@jskit-ai/kernel": "0.1.63",
-        "@jskit-ai/shell-web": "0.1.62",
+        "@jskit-ai/auth-core": "0.1.63",
+        "@jskit-ai/http-runtime": "0.1.63",
+        "@jskit-ai/kernel": "0.1.64",
+        "@jskit-ai/shell-web": "0.1.63",
         "vuetify": "^4.0.0"
       },
       "dev": {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/auth-web",
-  "version": "0.1.64",
+  "version": "0.1.65",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -14,17 +14,18 @@
     "./client/views/DefaultSignOutView": "./src/client/views/DefaultSignOutView.vue",
     "./client/runtime/authGuardRuntime": "./src/client/runtime/authGuardRuntime.js",
     "./client/runtime/authHttpClient": "./src/client/runtime/authHttpClient.js",
+    "./client/runtime/oauthCallbackRuntime": "./src/client/runtime/oauthCallbackRuntime.js",
     "./client/runtime/useSignOut": "./src/client/runtime/useSignOut.js"
   },
   "dependencies": {
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/auth-core": "0.1.62",
+    "@jskit-ai/auth-core": "0.1.63",
     "@mdi/js": "^7.4.47",
-    "@jskit-ai/kernel": "0.1.63",
-    "@jskit-ai/shell-web": "0.1.62",
+    "@jskit-ai/kernel": "0.1.64",
+    "@jskit-ai/shell-web": "0.1.63",
     "pinia": "^3.0.4",
     "vuetify": "^4.0.0",
-    "@jskit-ai/http-runtime": "0.1.62"
+    "@jskit-ai/http-runtime": "0.1.63"
   },
   "peerDependencies": {
     "vue": "^3.5.13",

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

@@ -2,6 +2,7 @@ import {
   OAUTH_QUERY_PARAM_PROVIDER,
   OAUTH_QUERY_PARAM_RETURN_TO
 } from "@jskit-ai/auth-core/shared/oauthCallbackParams";
+import { readOAuthCallbackParamsFromUrl } from "../../runtime/oauthCallbackRuntime.js";
 
 function stripOAuthParamsFromLocation() {
   if (typeof window !== "object" || !window.location) {
@@ -46,42 +47,7 @@ function readOAuthCallbackParamsFromLocation() {
     return null;
   }
 
-  const searchParams = new URLSearchParams(window.location.search || "");
-  const hashParams = new URLSearchParams((window.location.hash || "").replace(/^#/, ""));
-
-  const code = String(searchParams.get("code") || hashParams.get("code") || "").trim();
-  const accessToken = String(searchParams.get("access_token") || hashParams.get("access_token") || "").trim();
-  const refreshToken = String(searchParams.get("refresh_token") || hashParams.get("refresh_token") || "").trim();
-  const errorCode = String(
-    searchParams.get("error") ||
-      hashParams.get("error") ||
-      searchParams.get("errorCode") ||
-      hashParams.get("errorCode") ||
-      ""
-  ).trim();
-  const errorDescription = String(
-    searchParams.get("error_description") ||
-      hashParams.get("error_description") ||
-      searchParams.get("errorDescription") ||
-      hashParams.get("errorDescription") ||
-      ""
-  ).trim();
-  const hasSessionPair = Boolean(accessToken && refreshToken);
-
-  if (!code && !hasSessionPair && !errorCode) {
-    return null;
-  }
-
-  return {
-    code,
-    accessToken,
-    refreshToken,
-    hasSessionPair,
-    errorCode,
-    errorDescription,
-    provider: String(searchParams.get(OAUTH_QUERY_PARAM_PROVIDER) || "").trim().toLowerCase(),
-    returnTo: String(searchParams.get(OAUTH_QUERY_PARAM_RETURN_TO) || "").trim()
-  };
+  return readOAuthCallbackParamsFromUrl(window.location.href);
 }
 
 export {

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

@@ -5,17 +5,14 @@ import { authLoginPasswordCommand } from "@jskit-ai/auth-core/shared/commands/au
 import { authLoginOtpRequestCommand } from "@jskit-ai/auth-core/shared/commands/authLoginOtpRequestCommand";
 import { authLoginOtpVerifyCommand } from "@jskit-ai/auth-core/shared/commands/authLoginOtpVerifyCommand";
 import { authLoginOAuthStartCommand } from "@jskit-ai/auth-core/shared/commands/authLoginOAuthStartCommand";
-import { authLoginOAuthCompleteCommand } from "@jskit-ai/auth-core/shared/commands/authLoginOAuthCompleteCommand";
 import { authPasswordResetRequestCommand } from "@jskit-ai/auth-core/shared/commands/authPasswordResetRequestCommand";
 import { AUTH_PATHS, buildAuthOauthStartPath } from "@jskit-ai/auth-core/shared/authPaths";
 import { authHttpRequest } from "../../runtime/authHttpClient.js";
+import { completeOAuthCallbackFromCurrentLocation } from "../../runtime/oauthCallbackRuntime.js";
 import { normalizeAuthReturnToPath } from "../../lib/returnToPath.js";
 import { normalizeEmailAddress } from "./identityHelpers.js";
 import { readRememberedAccountHint } from "./rememberedAccountStorage.js";
-import {
-  stripOAuthParamsFromLocation,
-  readOAuthCallbackParamsFromLocation
-} from "./oauthCallbackUrl.js";
+import { stripOAuthParamsFromLocation } from "./oauthCallbackUrl.js";
 import { ensureCommandSectionValid } from "./validationHelpers.js";
 import { resolveRegisterCompletionState } from "./registerCompletion.js";
 
@@ -25,7 +22,8 @@ export function useLoginViewActions({
   state,
   validation,
   queryClient,
-  errorRuntime
+  errorRuntime,
+  oauthLaunchClient = null
 } = {}) {
   function reportAuthFeedback({
     message,
@@ -229,78 +227,46 @@ export function useLoginViewActions({
     await completeLogin();
   }
 
-  function buildOAuthCompletePayload({ callbackParams, provider, hasSessionPair }) {
-    const payload = {};
-    if (provider) {
-      payload.provider = provider;
-    }
-    if (callbackParams.code) {
-      payload.code = callbackParams.code;
-    }
-    if (hasSessionPair) {
-      payload.accessToken = callbackParams.accessToken;
-      payload.refreshToken = callbackParams.refreshToken;
-    }
-    return payload;
-  }
-
   async function handleOAuthCallbackIfPresent() {
-    const callbackParams = readOAuthCallbackParamsFromLocation();
-    if (!callbackParams) {
-      return false;
-    }
-
-    state.requestedReturnTo.value = normalizeAuthReturnToPath(callbackParams.returnTo, state.requestedReturnTo.value, {
-      allowedOrigins: state.allowedReturnToOrigins.value
+    const callbackResult = await completeOAuthCallbackFromCurrentLocation({
+      fallbackReturnTo: state.requestedReturnTo.value,
+      allowedReturnToOrigins: state.allowedReturnToOrigins.value,
+      defaultProvider: resolveDefaultOAuthProvider(),
+      request,
+      refreshSession
     });
 
-    const provider = String(callbackParams.provider || resolveDefaultOAuthProvider() || "")
-      .trim()
-      .toLowerCase();
-    const oauthError = callbackParams.errorCode;
-    const oauthErrorDescription = callbackParams.errorDescription;
-    const hasSessionPair = callbackParams.hasSessionPair === true;
-
-    if (!provider && !hasSessionPair) {
-      setErrorMessage("OAuth provider is missing from callback.", "auth-web.default-login-view:oauth-missing-provider");
-      stripOAuthParamsFromLocation();
-      return true;
+    if (callbackResult.handled !== true) {
+      return false;
     }
 
-    if (oauthError) {
-      setErrorMessage(oauthErrorDescription || oauthError, "auth-web.default-login-view:oauth-callback-error");
-      stripOAuthParamsFromLocation();
-      return true;
-    }
+    state.requestedReturnTo.value = normalizeAuthReturnToPath(
+      callbackResult.returnTo,
+      state.requestedReturnTo.value,
+      {
+        allowedOrigins: state.allowedReturnToOrigins.value
+      }
+    );
 
     state.loading.value = true;
     clearTransientMessages();
 
     try {
-      const payload = buildOAuthCompletePayload({
-        callbackParams,
-        provider,
-        hasSessionPair
-      });
-      ensureCommandSectionValid(
-        authLoginOAuthCompleteCommand,
-        "body",
-        payload,
-        "Invalid OAuth callback payload."
-      );
+      if (callbackResult.completed !== true) {
+        throw new Error(callbackResult.errorMessage || "Unable to complete OAuth sign-in.");
+      }
 
-      const oauthResult = await request(AUTH_PATHS.OAUTH_COMPLETE, {
-        method: "POST",
-        body: payload
-      });
       state.applyRememberedAccountPreference({
-        email: oauthResult?.email || state.email.value,
-        displayName: oauthResult?.username || oauthResult?.email || state.email.value,
+        email: callbackResult.oauthResult?.email || state.email.value,
+        displayName:
+          callbackResult.oauthResult?.username || callbackResult.oauthResult?.email || state.email.value,
         shouldRemember: state.rememberAccountOnDevice.value !== false
       });
 
       stripOAuthParamsFromLocation();
-      await completeLogin();
+      if (typeof window === "object" && window.location) {
+        window.location.replace(state.requestedReturnTo.value);
+      }
     } catch (error) {
       setErrorMessage(String(error?.message || "Unable to complete OAuth sign-in."));
       stripOAuthParamsFromLocation();
@@ -426,9 +392,9 @@ export function useLoginViewActions({
     return undefined;
   }
 
-  function startOAuthSignIn(providerId) {
+  async function startOAuthSignIn(providerId) {
     const provider = String(providerId || "").trim().toLowerCase();
-    if (!provider || typeof window !== "object" || !window.location) {
+    if (!provider) {
       return;
     }
 
@@ -458,7 +424,16 @@ export function useLoginViewActions({
 
     const params = new URLSearchParams(queryPayload);
     const oauthStartPath = buildAuthOauthStartPath(provider);
-    window.location.assign(`${oauthStartPath}?${params.toString()}`);
+    try {
+      if (!oauthLaunchClient || typeof oauthLaunchClient.open !== "function") {
+        throw new Error("OAuth launch client is unavailable.");
+      }
+      await oauthLaunchClient.open({
+        url: `${oauthStartPath}?${params.toString()}`
+      });
+    } catch (error) {
+      setErrorMessage(String(error?.message || "Unable to start OAuth sign-in."));
+    }
   }
 
   async function initializeOnMounted() {

package/src/client/index.js

@@ -9,6 +9,11 @@ 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 {
+  completeOAuthCallbackFromCurrentLocation,
+  completeOAuthCallbackFromUrl,
+  readOAuthCallbackParamsFromUrl
+} from "./runtime/oauthCallbackRuntime.js";
 
 const routeComponents = Object.freeze({
   "auth-login": DefaultLoginView,

package/src/client/providers/AuthWebClientProvider.js

@@ -2,9 +2,11 @@ import DefaultLoginView from "../views/DefaultLoginView.vue";
 import AuthProfileWidget from "../views/AuthProfileWidget.vue";
 import AuthProfileMenuLinkItem from "../views/AuthProfileMenuLinkItem.vue";
 import { createAuthGuardRuntime } from "../runtime/authGuardRuntime.js";
+import { completeOAuthCallbackFromUrl } from "../runtime/oauthCallbackRuntime.js";
 import { useLoginView } from "../runtime/useLoginView.js";
 import { bootAuthClientProvider } from "./bootAuthClientProvider.js";
 import { resolveSurfaceNavigationTargetFromPlacementContext } from "@jskit-ai/shell-web/client/placement";
+import { resolveAllowedReturnToOriginsFromPlacementContext } from "../lib/returnToPath.js";
 
 class AuthWebClientProvider {
   static id = "auth.web.client";
@@ -18,6 +20,27 @@ class AuthWebClientProvider {
     app.singleton("auth.login.useLoginView", () => useLoginView);
     app.singleton("auth.web.profile.widget", () => AuthProfileWidget);
     app.singleton("auth.web.profile.menu.link-item", () => AuthProfileMenuLinkItem);
+    app.singleton("auth.mobile-callback.client", () =>
+      Object.freeze({
+        async completeFromUrl({
+          url = "",
+          fallbackReturnTo = "/",
+          placementContext = null,
+          defaultProvider = "",
+          request = undefined,
+          refreshSession = async () => null
+        } = {}) {
+          return completeOAuthCallbackFromUrl({
+            url,
+            fallbackReturnTo,
+            allowedReturnToOrigins: resolveAllowedReturnToOriginsFromPlacementContext(placementContext),
+            defaultProvider,
+            ...(typeof request === "function" ? { request } : {}),
+            refreshSession
+          });
+        }
+      })
+    );
     app.singleton("runtime.auth-guard.client", () => {
       if (!app.has("runtime.web-placement.client")) {
         throw new Error("AuthWebClientProvider requires shell-web placement runtime.");

package/src/client/providers/bootAuthClientProvider.js

@@ -1,6 +1,12 @@
-import { AUTH_GUARD_RUNTIME_INJECTION_KEY } from "../runtime/inject.js";
+import {
+  AUTH_GUARD_RUNTIME_INJECTION_KEY,
+  AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY
+} from "../runtime/inject.js";
+import { createBrowserOAuthLaunchClient } from "../runtime/oauthLaunchClient.js";
 import { useAuthStore } from "../stores/useAuthStore.js";
 
+const AUTH_OAUTH_LAUNCH_CLIENT_TOKEN = "auth.oauth-launch.client";
+
 async function bootAuthClientProvider(app) {
   if (!app || typeof app.make !== "function" || typeof app.has !== "function") {
     throw new Error("AuthWebClientProvider requires application make()/has().");
@@ -33,7 +39,11 @@ async function bootAuthClientProvider(app) {
     return;
   }
 
+  const oauthLaunchClient = app.has(AUTH_OAUTH_LAUNCH_CLIENT_TOKEN)
+    ? app.make(AUTH_OAUTH_LAUNCH_CLIENT_TOKEN)
+    : createBrowserOAuthLaunchClient();
   vueApp.provide(AUTH_GUARD_RUNTIME_INJECTION_KEY, authGuardRuntime);
+  vueApp.provide(AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY, oauthLaunchClient);
 }
 
 export { bootAuthClientProvider };

package/src/client/runtime/inject.js

@@ -1,7 +1,9 @@
 import { inject } from "vue";
 import { isAuthGuardRuntime } from "./authGuardRuntime.js";
+import { createBrowserOAuthLaunchClient, isAuthOAuthLaunchClient } from "./oauthLaunchClient.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";
 
 const EMPTY_AUTH_GUARD_STATE = Object.freeze({
   authenticated: false,
@@ -38,9 +40,24 @@ function useAuthGuardRuntime({ required = false } = {}) {
   return EMPTY_AUTH_GUARD_RUNTIME;
 }
 
+function useAuthOAuthLaunchClient({ required = false } = {}) {
+  const client = inject(AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY, null);
+  if (isAuthOAuthLaunchClient(client)) {
+    return client;
+  }
+
+  if (required) {
+    throw new Error("OAuth launch client is not available in Vue injection context.");
+  }
+
+  return createBrowserOAuthLaunchClient();
+}
+
 export {
   AUTH_GUARD_RUNTIME_INJECTION_KEY,
+  AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY,
   EMPTY_AUTH_GUARD_STATE,
   EMPTY_AUTH_GUARD_RUNTIME,
-  useAuthGuardRuntime
+  useAuthGuardRuntime,
+  useAuthOAuthLaunchClient
 };

package/src/client/runtime/oauthCallbackRuntime.js

@@ -0,0 +1,194 @@
+import { authLoginOAuthCompleteCommand } from "@jskit-ai/auth-core/shared/commands/authLoginOAuthCompleteCommand";
+import {
+  OAUTH_QUERY_PARAM_PROVIDER,
+  OAUTH_QUERY_PARAM_RETURN_TO
+} from "@jskit-ai/auth-core/shared/oauthCallbackParams";
+import { AUTH_PATHS } from "@jskit-ai/auth-core/shared/authPaths";
+import { normalizeAuthReturnToPath } from "../lib/returnToPath.js";
+import { authHttpRequest } from "./authHttpClient.js";
+import { ensureCommandSectionValid } from "../composables/loginView/validationHelpers.js";
+
+function parseCallbackUrl(url = "") {
+  const normalizedUrl = String(url || "").trim();
+  if (!normalizedUrl) {
+    return null;
+  }
+
+  try {
+    return new URL(normalizedUrl, "https://jskit.invalid");
+  } catch {
+    return null;
+  }
+}
+
+function readOAuthCallbackParamsFromUrl(url = "") {
+  const parsedUrl = parseCallbackUrl(url);
+  if (!parsedUrl) {
+    return null;
+  }
+
+  const searchParams = new URLSearchParams(parsedUrl.search || "");
+  const hashParams = new URLSearchParams(String(parsedUrl.hash || "").replace(/^#/, ""));
+
+  const code = String(searchParams.get("code") || hashParams.get("code") || "").trim();
+  const accessToken = String(searchParams.get("access_token") || hashParams.get("access_token") || "").trim();
+  const refreshToken = String(searchParams.get("refresh_token") || hashParams.get("refresh_token") || "").trim();
+  const errorCode = String(
+    searchParams.get("error") ||
+      hashParams.get("error") ||
+      searchParams.get("errorCode") ||
+      hashParams.get("errorCode") ||
+      ""
+  ).trim();
+  const errorDescription = String(
+    searchParams.get("error_description") ||
+      hashParams.get("error_description") ||
+      searchParams.get("errorDescription") ||
+      hashParams.get("errorDescription") ||
+      ""
+  ).trim();
+  const hasSessionPair = Boolean(accessToken && refreshToken);
+
+  if (!code && !hasSessionPair && !errorCode) {
+    return null;
+  }
+
+  return Object.freeze({
+    code,
+    accessToken,
+    refreshToken,
+    hasSessionPair,
+    errorCode,
+    errorDescription,
+    provider: String(searchParams.get(OAUTH_QUERY_PARAM_PROVIDER) || "").trim().toLowerCase(),
+    returnTo: String(searchParams.get(OAUTH_QUERY_PARAM_RETURN_TO) || "").trim()
+  });
+}
+
+function buildOAuthCompletePayload({ callbackParams = null, provider = "", hasSessionPair = false } = {}) {
+  const payload = {};
+  if (provider) {
+    payload.provider = provider;
+  }
+  if (callbackParams?.code) {
+    payload.code = callbackParams.code;
+  }
+  if (hasSessionPair) {
+    payload.accessToken = callbackParams?.accessToken;
+    payload.refreshToken = callbackParams?.refreshToken;
+  }
+  return payload;
+}
+
+async function completeOAuthCallbackFromUrl({
+  url = "",
+  fallbackReturnTo = "/",
+  allowedReturnToOrigins = [],
+  defaultProvider = "",
+  request = authHttpRequest,
+  refreshSession = async () => null
+} = {}) {
+  const callbackParams = readOAuthCallbackParamsFromUrl(url);
+  if (!callbackParams) {
+    return Object.freeze({
+      handled: false,
+      completed: false,
+      returnTo: normalizeAuthReturnToPath("", fallbackReturnTo, {
+        allowedOrigins: allowedReturnToOrigins
+      })
+    });
+  }
+
+  const returnTo = normalizeAuthReturnToPath(callbackParams.returnTo, fallbackReturnTo, {
+    allowedOrigins: allowedReturnToOrigins
+  });
+  const provider = String(callbackParams.provider || defaultProvider || "")
+    .trim()
+    .toLowerCase();
+  const oauthError = callbackParams.errorCode;
+  const oauthErrorDescription = callbackParams.errorDescription;
+  const hasSessionPair = callbackParams.hasSessionPair === true;
+
+  if (oauthError) {
+    return Object.freeze({
+      handled: true,
+      completed: false,
+      returnTo,
+      errorMessage: oauthErrorDescription || oauthError,
+      callbackParams
+    });
+  }
+
+  if (!provider && !hasSessionPair) {
+    return Object.freeze({
+      handled: true,
+      completed: false,
+      returnTo,
+      errorMessage: "OAuth provider is missing from callback.",
+      callbackParams
+    });
+  }
+
+  try {
+    const payload = buildOAuthCompletePayload({
+      callbackParams,
+      provider,
+      hasSessionPair
+    });
+    ensureCommandSectionValid(
+      authLoginOAuthCompleteCommand,
+      "body",
+      payload,
+      "Invalid OAuth callback payload."
+    );
+
+    const oauthResult = await request(AUTH_PATHS.OAUTH_COMPLETE, {
+      method: "POST",
+      body: payload
+    });
+    const session = await refreshSession();
+    if (!session?.authenticated) {
+      throw new Error("Login succeeded but the session is not active yet. Please retry.");
+    }
+
+    return Object.freeze({
+      handled: true,
+      completed: true,
+      returnTo,
+      callbackParams,
+      oauthResult,
+      session
+    });
+  } catch (error) {
+    return Object.freeze({
+      handled: true,
+      completed: false,
+      returnTo,
+      callbackParams,
+      errorMessage: String(error?.message || "Unable to complete OAuth sign-in.")
+    });
+  }
+}
+
+async function completeOAuthCallbackFromCurrentLocation(options = {}) {
+  if (typeof window !== "object" || !window?.location) {
+    return Object.freeze({
+      handled: false,
+      completed: false,
+      returnTo: normalizeAuthReturnToPath("", options.fallbackReturnTo || "/", {
+        allowedOrigins: options.allowedReturnToOrigins
+      })
+    });
+  }
+
+  return completeOAuthCallbackFromUrl({
+    ...options,
+    url: window.location.href
+  });
+}
+
+export {
+  completeOAuthCallbackFromCurrentLocation,
+  completeOAuthCallbackFromUrl,
+  readOAuthCallbackParamsFromUrl
+};

package/src/client/runtime/oauthLaunchClient.js

@@ -0,0 +1,28 @@
+function createBrowserOAuthLaunchClient({ location = null } = {}) {
+  const resolvedLocation =
+    location || (typeof window === "object" && window?.location ? window.location : null);
+
+  return Object.freeze({
+    async open({ url = "" } = {}) {
+      const normalizedUrl = String(url || "").trim();
+      if (!normalizedUrl) {
+        throw new Error("OAuth launch URL is required.");
+      }
+      if (!resolvedLocation || typeof resolvedLocation.assign !== "function") {
+        throw new Error("Browser location.assign() is unavailable for OAuth launch.");
+      }
+
+      resolvedLocation.assign(normalizedUrl);
+      return true;
+    }
+  });
+}
+
+function isAuthOAuthLaunchClient(value = null) {
+  return Boolean(value && typeof value === "object" && typeof value.open === "function");
+}
+
+export {
+  createBrowserOAuthLaunchClient,
+  isAuthOAuthLaunchClient
+};

package/src/client/runtime/useLoginView.js

@@ -2,6 +2,7 @@ import { onMounted } from "vue";
 import { useQueryClient } from "@tanstack/vue-query";
 import { useShellWebErrorRuntime } from "@jskit-ai/shell-web/client/error";
 import { useWebPlacementContext } from "@jskit-ai/shell-web/client/placement";
+import { useAuthOAuthLaunchClient } from "./inject.js";
 import { useLoginViewState } from "../composables/loginView/useLoginViewState.js";
 import { useLoginViewValidation } from "../composables/loginView/useLoginViewValidation.js";
 import { useLoginViewActions } from "../composables/loginView/useLoginViewActions.js";
@@ -10,6 +11,9 @@ function useLoginView() {
   const { context: placementContext } = useWebPlacementContext();
   const queryClient = useQueryClient();
   const errorRuntime = useShellWebErrorRuntime();
+  const oauthLaunchClient = useAuthOAuthLaunchClient({
+    required: true
+  });
 
   const state = useLoginViewState({ placementContext });
   const validation = useLoginViewValidation({ state });
@@ -17,7 +21,8 @@ function useLoginView() {
     state,
     validation,
     queryClient,
-    errorRuntime
+    errorRuntime,
+    oauthLaunchClient
   });
 
   onMounted(actions.initializeOnMounted);

package/src/client/views/DefaultLoginView.vue

@@ -1,8 +1,22 @@
 <template>
-  <v-main class="login-main">
-    <v-container class="fill-height d-flex align-center justify-center py-8">
-      <v-card class="auth-card" rounded="lg" elevation="1" border>
-        <v-card-text class="pa-7">
+  <div class="login-screen" :class="{ 'login-screen--mobile': isMobileViewport }">
+    <v-container
+      fluid
+      class="login-shell fill-height d-flex"
+      :class="[
+        isMobileViewport
+          ? 'login-shell--mobile align-stretch justify-stretch pa-0'
+          : 'align-center justify-center py-8'
+      ]"
+    >
+      <v-card
+        class="auth-card"
+        :class="{ 'auth-card--mobile': isMobileViewport }"
+        :rounded="isMobileViewport ? false : 'lg'"
+        :elevation="isMobileViewport ? 0 : 1"
+        :border="!isMobileViewport"
+      >
+        <v-card-text class="auth-content" :class="{ 'auth-content--mobile': isMobileViewport }">
           <div class="auth-header d-flex align-start justify-space-between ga-3 mb-5">
             <div>
               <p class="auth-kicker">Jskit Workspace</p>
@@ -199,13 +213,14 @@
         </v-card-text>
       </v-card>
     </v-container>
-  </v-main>
+  </div>
 </template>
 
 <script setup>
 import { onMounted } from "vue";
 import { useQueryClient } from "@tanstack/vue-query";
 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 { useLoginViewState } from "../composables/loginView/useLoginViewState.js";
@@ -217,6 +232,7 @@ const {
 } = useWebPlacementContext();
 const queryClient = useQueryClient();
 const errorRuntime = useShellWebErrorRuntime();
+const { mobile: isMobileViewport } = useDisplay({ mobileBreakpoint: 960 });
 
 const state = useLoginViewState({ placementContext });
 const validation = useLoginViewValidation({ state });
@@ -290,15 +306,46 @@ function toggleConfirmPasswordVisibility() {
 </script>
 
 <style scoped>
-.login-main {
+.login-screen {
+  position: fixed;
+  inset: 0;
+  z-index: 1;
+  overflow-y: auto;
+  min-height: 100dvh;
   background-color: rgb(var(--v-theme-background));
   background-image: radial-gradient(circle at 15% 12%, rgba(var(--v-theme-primary), 0.14), transparent 32%);
 }
 
+.login-screen--mobile {
+  background-image: none;
+}
+
+.login-shell {
+  min-height: 100dvh;
+}
+
+.login-shell--mobile {
+  width: 100%;
+}
+
 .auth-card {
   width: min(520px, 100%);
 }
 
+.auth-card--mobile {
+  width: 100%;
+  min-height: 100dvh;
+}
+
+.auth-content {
+  padding: 28px;
+}
+
+.auth-content--mobile {
+  min-height: 100dvh;
+  padding: calc(24px + env(safe-area-inset-top, 0px)) 20px calc(32px + env(safe-area-inset-bottom, 0px));
+}
+
 .auth-kicker {
   margin: 0 0 8px;
   font-size: 12px;
@@ -361,10 +408,6 @@ function toggleConfirmPasswordVisibility() {
 }
 
 @media (max-width: 959px) {
-  .auth-content {
-    padding: 24px 20px;
-  }
-
   .auth-title {
     font-size: 26px;
   }

package/test/clientBoot.test.js

@@ -8,6 +8,7 @@ test("auth-web client index defines provider-based client routes surface", () =>
 
   assert.equal(source.includes('export { useAuthStore } from "./stores/useAuthStore.js";'), true);
   assert.equal(source.includes('export { useAuthGuardRuntime } from "./runtime/inject.js";'), true);
+  assert.equal(source.includes('export {\n  completeOAuthCallbackFromCurrentLocation,\n  completeOAuthCallbackFromUrl,\n  readOAuthCallbackParamsFromUrl\n} from "./runtime/oauthCallbackRuntime.js";'), true);
   assert.equal(source.includes('export { useAuth } from "./composables/useAuth.js";'), false);
   assert.equal(source.includes("const routeComponents = Object.freeze({"), true);
   assert.equal(source.includes('"auth-login": DefaultLoginView'), true);

package/test/clientSurface.test.js

@@ -65,6 +65,31 @@ test("auth-web runtime/useLoginView composes login view state, validation, and a
   assert.match(runtimeUseLoginViewSource, /export\s+\{\s*useLoginView\s*\};/);
 });
 
+test("auth-web client provider registers a mobile auth callback completion token", () => {
+  const providerPath = fileURLToPath(new URL("../src/client/providers/AuthWebClientProvider.js", import.meta.url));
+  const providerSource = readFileSync(providerPath, "utf8");
+
+  assert.match(providerSource, /auth\.mobile-callback\.client/);
+  assert.match(providerSource, /completeOAuthCallbackFromUrl/);
+});
+
+test("default login view owns the viewport and becomes a full-screen mobile screen", () => {
+  const viewPath = fileURLToPath(new URL("../src/client/views/DefaultLoginView.vue", import.meta.url));
+  const viewSource = readFileSync(viewPath, "utf8");
+
+  assert.match(viewSource, /import\s+\{\s*useDisplay\s*\}\s+from\s+"vuetify";/);
+  assert.match(viewSource, /useDisplay\(\{\s*mobileBreakpoint:\s*960\s*\}\)/);
+  assert.doesNotMatch(viewSource, /<v-main\b/);
+  assert.match(viewSource, /login-screen--mobile/);
+  assert.match(viewSource, /login-shell--mobile/);
+  assert.match(viewSource, /auth-card--mobile/);
+  assert.match(viewSource, /auth-content--mobile/);
+  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;/);
+});
+
 test("auth-web package exports only minimal client runtime/view subpaths", () => {
   const packageJson = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
   const exportsMap = packageJson && typeof packageJson === "object" ? packageJson.exports : {};
@@ -85,6 +110,10 @@ test("auth-web package exports only minimal client runtime/view subpaths", () =>
     exportsMap["./client/runtime/authHttpClient"],
     "./src/client/runtime/authHttpClient.js"
   );
+  assert.equal(
+    exportsMap["./client/runtime/oauthCallbackRuntime"],
+    "./src/client/runtime/oauthCallbackRuntime.js"
+  );
   assert.equal(exportsMap["./client/runtime/useSignOut"], "./src/client/runtime/useSignOut.js");
   assert.equal(exportsMap["./client/composables/useDefaultLoginView"], undefined);
   assert.equal(exportsMap["./client/composables/useDefaultSignOutView"], undefined);

package/test/loginViewActions.test.js

@@ -0,0 +1,59 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { buildAuthOauthStartPath } from "@jskit-ai/auth-core/shared/authPaths";
+import { useLoginViewActions } from "../src/client/composables/loginView/useLoginViewActions.js";
+
+function createMinimalLoginViewState(requestedReturnTo = "/") {
+  return {
+    requestedReturnTo: { value: requestedReturnTo },
+    allowedReturnToOrigins: { value: [] },
+    errorMessage: { value: "" },
+    infoMessage: { value: "" },
+    loading: { value: false },
+    email: { value: "" },
+    password: { value: "" },
+    otpCode: { value: "" },
+    otpRequestPending: { value: false },
+    registerConfirmationResendPending: { value: false },
+    pendingEmailConfirmationAddress: { value: "" },
+    oauthProviders: { value: [] },
+    oauthDefaultProvider: { value: "google" },
+    isRegister: { value: false },
+    isOtp: { value: false },
+    showRememberedAccount: { value: false },
+    rememberedAccountDisplayName: { value: "" },
+    clearTransientMessages() {},
+    applyRememberedAccountPreference() {},
+    applyRememberedAccountHint() {},
+    enterEmailConfirmationPendingState() {},
+    resolveNormalizedEmail() {
+      return "ada@example.com";
+    }
+  };
+}
+
+test("useLoginViewActions preserves the intended destination when starting OAuth sign-in", () => {
+  const state = createMinimalLoginViewState("/w/acme/workouts/2026-05-07?tab=chart");
+  const assignedTargets = [];
+  const actions = useLoginViewActions({
+    state,
+    validation: {},
+    queryClient: {},
+    errorRuntime: {
+      report() {}
+    },
+    oauthLaunchClient: {
+      async open({ url }) {
+        assignedTargets.push(url);
+      }
+    }
+  });
+
+  return actions.startOAuthSignIn("google").then(() => {
+    const expectedPath = buildAuthOauthStartPath("google");
+    assert.deepEqual(assignedTargets, [
+      `${expectedPath}?returnTo=%2Fw%2Facme%2Fworkouts%2F2026-05-07%3Ftab%3Dchart`
+    ]);
+    assert.equal(state.errorMessage.value, "");
+  });
+});

package/test/oauthCallbackRuntime.test.js

@@ -0,0 +1,164 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  completeOAuthCallbackFromCurrentLocation,
+  completeOAuthCallbackFromUrl,
+  readOAuthCallbackParamsFromUrl
+} from "../src/client/runtime/oauthCallbackRuntime.js";
+
+test("readOAuthCallbackParamsFromUrl returns null when the URL has no callback params", () => {
+  assert.equal(readOAuthCallbackParamsFromUrl("/auth/login"), null);
+});
+
+test("readOAuthCallbackParamsFromUrl reads query and hash callback params", () => {
+  assert.deepEqual(
+    readOAuthCallbackParamsFromUrl("/auth/login?oauthProvider=google&oauthReturnTo=%2Fw%2Facme&code=abc"),
+    {
+      code: "abc",
+      accessToken: "",
+      refreshToken: "",
+      hasSessionPair: false,
+      errorCode: "",
+      errorDescription: "",
+      provider: "google",
+      returnTo: "/w/acme"
+    }
+  );
+
+  assert.deepEqual(
+    readOAuthCallbackParamsFromUrl("/auth/login?oauthReturnTo=%2Fhome#access_token=access&refresh_token=refresh"),
+    {
+      code: "",
+      accessToken: "access",
+      refreshToken: "refresh",
+      hasSessionPair: true,
+      errorCode: "",
+      errorDescription: "",
+      provider: "",
+      returnTo: "/home"
+    }
+  );
+});
+
+test("completeOAuthCallbackFromUrl exchanges code callbacks and refreshes the session", async () => {
+  const calls = [];
+  const result = await completeOAuthCallbackFromUrl({
+    url: "/auth/login?oauthProvider=google&oauthReturnTo=%2Fw%2Facme&code=abc",
+    request: async (path, options) => {
+      calls.push({ path, options });
+      return {
+        username: "Ada",
+        email: "ada@example.com"
+      };
+    },
+    refreshSession: async () => ({
+      authenticated: true
+    })
+  });
+
+  assert.equal(result.handled, true);
+  assert.equal(result.completed, true);
+  assert.equal(result.returnTo, "/w/acme");
+  assert.deepEqual(calls, [
+    {
+      path: "/api/oauth/complete",
+      options: {
+        method: "POST",
+        body: {
+          provider: "google",
+          code: "abc"
+        }
+      }
+    }
+  ]);
+});
+
+test("completeOAuthCallbackFromUrl supports provider-less session-pair callbacks", async () => {
+  const result = await completeOAuthCallbackFromUrl({
+    url: "/auth/login?oauthReturnTo=%2Fhome#access_token=access&refresh_token=refresh",
+    request: async (path, options) => {
+      assert.equal(path, "/api/oauth/complete");
+      assert.deepEqual(options.body, {
+        accessToken: "access",
+        refreshToken: "refresh"
+      });
+      return {
+        username: "Ada"
+      };
+    },
+    refreshSession: async () => ({
+      authenticated: true
+    })
+  });
+
+  assert.equal(result.handled, true);
+  assert.equal(result.completed, true);
+  assert.equal(result.returnTo, "/home");
+});
+
+test("completeOAuthCallbackFromUrl reports callback errors without issuing a request", async () => {
+  const result = await completeOAuthCallbackFromUrl({
+    url: "/auth/login?error=access_denied&error_description=Provider%20denied%20access",
+    request: async () => {
+      throw new Error("request should not be called for callback errors");
+    }
+  });
+
+  assert.equal(result.handled, true);
+  assert.equal(result.completed, false);
+  assert.equal(result.errorMessage, "Provider denied access");
+});
+
+test("completeOAuthCallbackFromUrl reports missing providers for code callbacks", async () => {
+  const result = await completeOAuthCallbackFromUrl({
+    url: "/auth/login?code=abc",
+    request: async () => {
+      throw new Error("request should not be called when provider is missing");
+    }
+  });
+
+  assert.equal(result.handled, true);
+  assert.equal(result.completed, false);
+  assert.equal(result.errorMessage, "OAuth provider is missing from callback.");
+});
+
+test("completeOAuthCallbackFromUrl fails when the refreshed session is still unauthenticated", async () => {
+  const result = await completeOAuthCallbackFromUrl({
+    url: "/auth/login?oauthProvider=google&code=abc",
+    request: async () => ({
+      username: "Ada"
+    }),
+    refreshSession: async () => ({
+      authenticated: false
+    })
+  });
+
+  assert.equal(result.handled, true);
+  assert.equal(result.completed, false);
+  assert.equal(result.errorMessage, "Login succeeded but the session is not active yet. Please retry.");
+});
+
+test("completeOAuthCallbackFromCurrentLocation reads from window.location.href", async () => {
+  const originalWindow = globalThis.window;
+  globalThis.window = {
+    location: {
+      href: "https://app.example.com/auth/login?oauthProvider=google&code=abc"
+    }
+  };
+
+  try {
+    const result = await completeOAuthCallbackFromCurrentLocation({
+      request: async () => ({
+        username: "Ada"
+      }),
+      refreshSession: async () => ({
+        authenticated: true
+      })
+    });
+
+    assert.equal(result.handled, true);
+    assert.equal(result.completed, true);
+  } finally {
+    globalThis.window = originalWindow;
+  }
+});

package/test/provider.test.js

@@ -1,7 +1,10 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { createPinia } from "pinia";
-import { AUTH_GUARD_RUNTIME_INJECTION_KEY } from "../src/client/runtime/inject.js";
+import {
+  AUTH_GUARD_RUNTIME_INJECTION_KEY,
+  AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY
+} from "../src/client/runtime/inject.js";
 import { bootAuthClientProvider } from "../src/client/providers/bootAuthClientProvider.js";
 import { useAuthStore } from "../src/client/stores/useAuthStore.js";
 
@@ -56,7 +59,7 @@ function createAuthRuntimeStub(initialState = {}) {
   };
 }
 
-function createAppDouble({ authGuardRuntime, bootstrapRuntime = null } = {}) {
+function createAppDouble({ authGuardRuntime, bootstrapRuntime = null, oauthLaunchClient = null } = {}) {
   const singletons = new Map();
   const singletonInstances = new Map();
   const provided = [];
@@ -91,6 +94,9 @@ function createAppDouble({ authGuardRuntime, bootstrapRuntime = null } = {}) {
       if (token === "runtime.web-bootstrap.client") {
         return Boolean(bootstrapRuntime);
       }
+      if (token === "auth.oauth-launch.client") {
+        return Boolean(oauthLaunchClient);
+      }
       return singletons.has(token) || singletonInstances.has(token);
     },
     make(token) {
@@ -130,6 +136,9 @@ function createAppDouble({ authGuardRuntime, bootstrapRuntime = null } = {}) {
       if (token === "runtime.web-bootstrap.client") {
         return bootstrapRuntime;
       }
+      if (token === "auth.oauth-launch.client") {
+        return oauthLaunchClient;
+      }
       if (singletonInstances.has(token)) {
         return singletonInstances.get(token);
       }
@@ -168,6 +177,7 @@ test("auth web client boot binds explicit Pinia store state and raw runtime inje
 
   const providedByKey = new Map(app.provided.map((entry) => [entry.key, entry.value]));
   assert.equal(providedByKey.get(AUTH_GUARD_RUNTIME_INJECTION_KEY), authGuardRuntime);
+  assert.equal(typeof providedByKey.get(AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY)?.open, "function");
 });
 
 test("auth web client boot refreshes shared bootstrap runtime on auth changes", async () => {
@@ -196,3 +206,35 @@ test("auth web client boot refreshes shared bootstrap runtime on auth changes",
 
   assert.deepEqual(refreshCalls, ["auth.state"]);
 });
+
+test("auth web client boot prefers an explicitly registered OAuth launch client", async () => {
+  const authGuardRuntime = createAuthRuntimeStub({
+    authenticated: false
+  });
+  const launchCalls = [];
+  const oauthLaunchClient = {
+    async open(input = {}) {
+      launchCalls.push(input);
+      return true;
+    }
+  };
+  const app = createAppDouble({
+    authGuardRuntime,
+    oauthLaunchClient
+  });
+
+  await bootAuthClientProvider(app);
+
+  const providedByKey = new Map(app.provided.map((entry) => [entry.key, entry.value]));
+  const injectedLaunchClient = providedByKey.get(AUTH_OAUTH_LAUNCH_CLIENT_INJECTION_KEY);
+  assert.equal(injectedLaunchClient, oauthLaunchClient);
+
+  await injectedLaunchClient.open({
+    url: "/api/oauth/google/start?returnTo=%2Fw%2Facme"
+  });
+  assert.deepEqual(launchCalls, [
+    {
+      url: "/api/oauth/google/start?returnTo=%2Fw%2Facme"
+    }
+  ]);
+});

package/test/useSignOut.test.js

@@ -0,0 +1,96 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { createSignOutAction } from "../src/client/runtime/useSignOut.js";
+
+function createJsonResponse(payload = {}, { status = 200 } = {}) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    headers: {
+      get(name) {
+        return String(name || "").toLowerCase() === "content-type" ? "application/json" : null;
+      }
+    },
+    async json() {
+      return payload;
+    },
+    async text() {
+      return JSON.stringify(payload);
+    }
+  };
+}
+
+test("createSignOutAction clears the session cleanly and routes back to login with returnTo", async () => {
+  const fetchCalls = [];
+  const goToEntryCalls = [];
+  const originalFetch = globalThis.fetch;
+  let sessionReads = 0;
+
+  globalThis.fetch = async (url, options = {}) => {
+    fetchCalls.push({
+      url,
+      method: String(options.method || "GET").toUpperCase()
+    });
+
+    const normalizedUrl = String(url || "");
+    const normalizedMethod = String(options.method || "GET").toUpperCase();
+
+    if (normalizedUrl === "/api/session" && normalizedMethod === "GET") {
+      sessionReads += 1;
+      return createJsonResponse(
+        sessionReads === 1
+          ? { authenticated: true, csrfToken: "csrf-a" }
+          : { authenticated: false, csrfToken: "csrf-b" }
+      );
+    }
+
+    if (normalizedUrl === "/api/logout" && normalizedMethod === "POST") {
+      return createJsonResponse({ ok: true });
+    }
+
+    throw new Error(`Unexpected fetch call: ${normalizedMethod} ${normalizedUrl}`);
+  };
+
+  try {
+    const authGuardRuntime = {
+      async initialize() {
+        return {
+          authenticated: false
+        };
+      },
+      async refresh() {
+        return {
+          authenticated: false
+        };
+      },
+      getState() {
+        return {
+          authenticated: false
+        };
+      }
+    };
+
+    const signOut = createSignOutAction({
+      currentSurface: {
+        value: "/w/acme/workouts/2026-05-07"
+      },
+      goToEntry: async ({ resolvedRoute }) => {
+        goToEntryCalls.push(resolvedRoute);
+      },
+      authGuardRuntime
+    });
+
+    await signOut();
+
+    assert.deepEqual(fetchCalls, [
+      { url: "/api/session", method: "GET" },
+      { url: "/api/logout", method: "POST" },
+      { url: "/api/session", method: "GET" }
+    ]);
+    assert.deepEqual(goToEntryCalls, [
+      "/auth/login?returnTo=%2Fw%2Facme%2Fworkouts%2F2026-05-07"
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});