or3-provider-basic-auth 0.0.1 → 0.0.2

package/README.md

@@ -56,6 +56,9 @@ Strict-mode behavior:
 
 - Credentials/session state is stored in a provider-owned SQLite DB.
 - Canonical OR3 users/workspaces are still resolved by the selected `AuthWorkspaceStore`.
+- In `invite_only` mode, signed-token, expiry, persisted invite state/token hash, and normalized-email validation runs before Basic Auth creates an account or session.
+- The selected `AuthWorkspaceStore` must support atomic invite provisioning; internal user/auth mapping, membership, and invite consumption are committed together by that provider.
+- Basic Auth account and initial refresh-session rows are created in one local SQLite transaction.
 - Access JWTs are short-lived and validated by `basicAuthProvider.getSession(event)`.
 - Refresh tokens are rotated and hashed at rest; replay attempts revoke active sessions.
 

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "or3-provider-basic-auth",
   "configKey": "or3-provider-basic-auth",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "builder": {
     "@nuxt/module-builder": "1.0.2",
     "unbuild": "3.6.1"

package/dist/runtime/components/BasicAuthLockPage.client.d.vue.ts

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

package/dist/runtime/components/BasicAuthLockPage.client.vue

@@ -0,0 +1,55 @@
+<template>
+  <div class="space-y-3">
+    <UButton
+      block
+      size="xl"
+      color="primary"
+      :icon="loginIcon"
+      class="theme-shadow"
+      @click="signInModalOpen = true"
+    >
+      Sign in
+    </UButton>
+
+    <p class="text-sm text-[var(--md-on-surface-variant)] text-center">
+      Use your email and password to continue.
+    </p>
+
+    <BasicAuthSignInModal
+      v-model="signInModalOpen"
+      @signed-in="handleSignedIn"
+      @open-register="openRegisterFromSignIn"
+    />
+
+    <BasicAuthRegisterModal
+      v-model="registerModalOpen"
+      @registered="handleRegistered"
+    />
+  </div>
+</template>
+
+<script setup>
+import { nextTick, ref } from "vue";
+import BasicAuthRegisterModal from "./BasicAuthRegisterModal.client.vue";
+import BasicAuthSignInModal from "./BasicAuthSignInModal.client.vue";
+const loginIcon = "i-lucide-log-in";
+const signInModalOpen = ref(false);
+const registerModalOpen = ref(false);
+function notifyAuthSessionChanged() {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent("or3:auth-session-changed"));
+}
+function handleSignedIn() {
+  notifyAuthSessionChanged();
+}
+function handleRegistered() {
+  notifyAuthSessionChanged();
+}
+async function openRegisterFromSignIn() {
+  signInModalOpen.value = false;
+  await nextTick();
+  setTimeout(() => {
+    registerModalOpen.value = true;
+  }, 0);
+}
+</script>

package/dist/runtime/components/BasicAuthLockPage.client.vue.d.ts

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

package/dist/runtime/components/BasicAuthRegisterModal.client.vue

@@ -43,12 +43,18 @@
             />
           </UFormField>
 
-          <UFormField label="Password" name="password">
+          <UFormField
+            label="Password"
+            name="password"
+            hint="At least 8 characters"
+          >
             <UInput
               v-model="state.password"
               type="password"
               placeholder="••••••••"
               autocomplete="new-password"
+              minlength="8"
+              maxlength="512"
               required
               class="w-full"
             />
@@ -60,6 +66,8 @@
               type="password"
               placeholder="••••••••"
               autocomplete="new-password"
+              minlength="8"
+              maxlength="512"
               required
               class="w-full"
             />
@@ -130,9 +138,36 @@ function close() {
   errorMessage.value = "";
   emit("update:modelValue", false);
 }
+function validateClientSide() {
+  const email = state.email.trim();
+  if (!email || !email.includes("@")) {
+    return "Enter a valid email address.";
+  }
+  if (state.password.length < 8) {
+    return "Password must be at least 8 characters.";
+  }
+  if (state.password.length > 512) {
+    return "Password is too long.";
+  }
+  if (state.password !== state.confirmPassword) {
+    return "Passwords must match.";
+  }
+  return null;
+}
+function readFetchErrorMessage(error) {
+  if (typeof error !== "object" || error === null) return null;
+  const data = error.data;
+  return data?.statusMessage || data?.message || null;
+}
 async function onSubmit() {
   pending.value = true;
   errorMessage.value = "";
+  const clientError = validateClientSide();
+  if (clientError) {
+    errorMessage.value = clientError;
+    pending.value = false;
+    return;
+  }
   try {
     await $fetch("/api/basic-auth/register", {
       method: "POST",
@@ -148,14 +183,17 @@ async function onSubmit() {
     close();
   } catch (error) {
     const statusCode = typeof error === "object" && error !== null && "statusCode" in error ? Number(error.statusCode) : null;
+    const serverMessage = readFetchErrorMessage(error);
     if (statusCode === 400) {
-      errorMessage.value = "Please check your input and try again.";
+      errorMessage.value = serverMessage || "Please check your email and password (min 8 characters).";
     } else if (statusCode === 403) {
-      errorMessage.value = "Registration is restricted for this instance.";
+      errorMessage.value = serverMessage || "Registration is restricted for this instance.";
+    } else if (statusCode === 401) {
+      errorMessage.value = "Email is already in use.";
     } else if (statusCode === 409) {
       errorMessage.value = "Email is already in use.";
     } else {
-      errorMessage.value = "Unable to register right now. Please try again.";
+      errorMessage.value = serverMessage || "Unable to register right now. Please try again.";
     }
   } finally {
     pending.value = false;

package/dist/runtime/components/SidebarAuthButtonBasic.client.vue

@@ -47,6 +47,7 @@
 <script setup>
 import { computed, nextTick, onMounted, ref } from "vue";
 import { BASIC_AUTH_PROVIDER_ID } from "../lib/constants";
+import { silentRefreshOnce } from "../lib/silent-refresh.client";
 import BasicAuthSignInModal from "./BasicAuthSignInModal.client.vue";
 import BasicAuthRegisterModal from "./BasicAuthRegisterModal.client.vue";
 import BasicAuthUserMenu from "./BasicAuthUserMenu.client.vue";
@@ -55,31 +56,12 @@ const runtimeConfig = useRuntimeConfig();
 const signInModalOpen = ref(false);
 const registerModalOpen = ref(false);
 const changePasswordModalOpen = ref(false);
-let refreshRequest = null;
 const session = ref(null);
 async function fetchSessionPayload() {
   return await $fetch("/api/auth/session", {
     cache: "no-store"
   });
 }
-async function tryRefreshTokens() {
-  if (refreshRequest) {
-    return refreshRequest;
-  }
-  refreshRequest = (async () => {
-    try {
-      const response = await $fetch("/api/basic-auth/refresh?silent=1", {
-        method: "POST"
-      });
-      return response?.ok === true;
-    } catch {
-      return false;
-    }
-  })().finally(() => {
-    refreshRequest = null;
-  });
-  return refreshRequest;
-}
 async function refreshSession(options = {}) {
   const allowSilentRefresh = options.allowSilentRefresh ?? true;
   try {
@@ -92,7 +74,7 @@ async function refreshSession(options = {}) {
   if (session.value || !allowSilentRefresh) {
     return;
   }
-  const didRefresh = await tryRefreshTokens();
+  const didRefresh = await silentRefreshOnce();
   if (!didRefresh) {
     return;
   }

package/dist/runtime/lib/constants.d.ts

@@ -4,4 +4,16 @@ export declare const REFRESH_COOKIE_NAME = "or3_refresh";
 export declare const DEFAULT_ACCESS_TTL_SECONDS = 900;
 export declare const DEFAULT_REFRESH_TTL_SECONDS: number;
 export declare const ACCESS_COOKIE_PATH = "/";
-export declare const REFRESH_COOKIE_PATH = "/api/basic-auth";
+/**
+ * Refresh cookies are scoped to `/api` so session resolution (`/api/auth/session`)
+ * can transparently rotate expired access tokens. Previously `/api/basic-auth`
+ * prevented that recovery path.
+ */
+export declare const REFRESH_COOKIE_PATH = "/api";
+/** Legacy path from earlier builds; cleared on set/clear for migration. */
+export declare const LEGACY_REFRESH_COOKIE_PATH = "/api/basic-auth";
+/**
+ * Concurrent refresh requests within this window reuse the successor tokens
+ * instead of being treated as replay attacks (common under HMR remounts).
+ */
+export declare const REFRESH_ROTATION_GRACE_MS = 30000;

package/dist/runtime/lib/constants.js

@@ -4,4 +4,6 @@ export const REFRESH_COOKIE_NAME = "or3_refresh";
 export const DEFAULT_ACCESS_TTL_SECONDS = 900;
 export const DEFAULT_REFRESH_TTL_SECONDS = 60 * 60 * 24 * 30;
 export const ACCESS_COOKIE_PATH = "/";
-export const REFRESH_COOKIE_PATH = "/api/basic-auth";
+export const REFRESH_COOKIE_PATH = "/api";
+export const LEGACY_REFRESH_COOKIE_PATH = "/api/basic-auth";
+export const REFRESH_ROTATION_GRACE_MS = 3e4;

package/dist/runtime/lib/silent-refresh.client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Process-wide single-flight for silent refresh.
+ *
+ * HMR remounts and auth-status checks can otherwise POST /refresh concurrently,
+ * which races token rotation. All callers share one in-flight promise.
+ */
+/** Deduplicated silent refresh — safe to call from many HMR remount paths. */
+export declare function silentRefreshOnce(): Promise<boolean>;
+/** Test helper — clears the shared in-flight promise. */
+export declare function resetSilentRefreshForTests(): void;

package/dist/runtime/lib/silent-refresh.client.js

@@ -0,0 +1,31 @@
+const GLOBAL_KEY = "__or3_basic_auth_silent_refresh__";
+function getRegistry() {
+  const globalAny = globalThis;
+  if (!globalAny[GLOBAL_KEY]) {
+    globalAny[GLOBAL_KEY] = { inflight: null };
+  }
+  return globalAny[GLOBAL_KEY];
+}
+async function postSilentRefresh() {
+  try {
+    const response = await $fetch("/api/basic-auth/refresh?silent=1", {
+      method: "POST"
+    });
+    return response?.ok === true;
+  } catch {
+    return false;
+  }
+}
+export function silentRefreshOnce() {
+  const registry = getRegistry();
+  if (registry.inflight) {
+    return registry.inflight;
+  }
+  registry.inflight = postSilentRefresh().finally(() => {
+    registry.inflight = null;
+  });
+  return registry.inflight;
+}
+export function resetSilentRefreshForTests() {
+  getRegistry().inflight = null;
+}

package/dist/runtime/plugins/auth-status.client.js

@@ -1,4 +1,6 @@
 import { registerClientAuthStatusResolver } from "~/composables/auth/useClientAuthStatus.client";
+import { registerClientSessionRecovery } from "~/composables/auth/useClientSessionRecovery";
+import { silentRefreshOnce } from "../lib/silent-refresh.client.js";
 async function fetchSession() {
   try {
     return await $fetch("/api/auth/session", {
@@ -8,25 +10,16 @@ async function fetchSession() {
     return null;
   }
 }
-async function trySilentRefresh() {
-  try {
-    const res = await $fetch("/api/basic-auth/refresh?silent=1", {
-      method: "POST"
-    });
-    return res?.ok === true;
-  } catch {
-    return false;
-  }
-}
 export default defineNuxtPlugin(() => {
   if (import.meta.server) return;
+  registerClientSessionRecovery(async () => silentRefreshOnce());
   registerClientAuthStatusResolver(async () => {
     const first = await fetchSession();
     const firstSession = first?.session;
     if (firstSession?.authenticated === true && firstSession.provider === "basic-auth") {
       return { ready: true, authenticated: true };
     }
-    const refreshed = await trySilentRefresh();
+    const refreshed = await silentRefreshOnce();
     if (!refreshed) {
       return { ready: true, authenticated: false };
     }

package/dist/runtime/plugins/basic-auth-ui.client.js

@@ -29,6 +29,35 @@ function enqueueAuthUiAdapter(component) {
     );
   }
 }
+function tryRegisterLockPageAdapter(component) {
+  const nuxtApp = useNuxtApp();
+  if (typeof nuxtApp.$registerLockPageAdapter !== "function") {
+    return false;
+  }
+  nuxtApp.$registerLockPageAdapter({
+    id: BASIC_AUTH_PROVIDER_ID,
+    component
+  });
+  return true;
+}
+function enqueueLockPageAdapter(component) {
+  const payload = {
+    id: BASIC_AUTH_PROVIDER_ID,
+    component
+  };
+  const globalState = globalThis;
+  if (!Array.isArray(globalState.__or3LockPageAdapterQueue__)) {
+    globalState.__or3LockPageAdapterQueue__ = [];
+  }
+  globalState.__or3LockPageAdapterQueue__.push(payload);
+  if (typeof window !== "undefined") {
+    window.dispatchEvent(
+      new CustomEvent("or3:lock-page-adapter-register", {
+        detail: payload
+      })
+    );
+  }
+}
 export default defineNuxtPlugin(async () => {
   if (import.meta.server) return;
   const runtimeConfig = useRuntimeConfig();
@@ -43,4 +72,10 @@ export default defineNuxtPlugin(async () => {
       enqueueAuthUiAdapter(componentModule.default);
     }
   }
+  const lockPageModule = await import("../components/BasicAuthLockPage.client.vue");
+  if (lockPageModule.default) {
+    if (!tryRegisterLockPageAdapter(lockPageModule.default)) {
+      enqueueLockPageAdapter(lockPageModule.default);
+    }
+  }
 });

package/dist/runtime/server/api/basic-auth/_helpers.js

@@ -14,6 +14,27 @@ export async function parseBodyWithSchema(event, schema) {
   const body = await readBody(event);
   const result = schema.safeParse(body);
   if (!result.success) {
+    const firstIssue = result.error.issues[0];
+    const path = firstIssue?.path?.join(".") || "input";
+    const detail = firstIssue?.message || "Invalid request";
+    if (path === "password" || path === "confirmPassword") {
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Password must be at least 8 characters."
+      });
+    }
+    if (detail === "Passwords must match") {
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Passwords must match."
+      });
+    }
+    if (path === "email") {
+      throw createError({
+        statusCode: 400,
+        statusMessage: "Enter a valid email address."
+      });
+    }
     throw createInvalidRequestError();
   }
   return result.data;

package/dist/runtime/server/api/basic-auth/refresh.post.d.ts

@@ -1,8 +1,12 @@
 import { type H3Event } from 'h3';
 export declare function handleRefresh(event: H3Event): Promise<{
-    ok: boolean;
+    ok: false;
+} | {
+    ok: true;
 }>;
 declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
-    ok: boolean;
+    ok: false;
+} | {
+    ok: true;
 }>>;
 export default _default;

package/dist/runtime/server/api/basic-auth/refresh.post.js

@@ -1,21 +1,7 @@
-import { randomUUID } from "node:crypto";
 import { defineEventHandler, getQuery } from "h3";
-import { clearAuthCookies, setAccessCookie, setRefreshCookie } from "../../lib/cookies.js";
-import { getBasicAuthConfig } from "../../lib/config.js";
 import { createSessionExpiredError } from "../../lib/errors.js";
-import {
-  getRefreshTokenFromEvent,
-  hashRefreshToken,
-  signAccessToken,
-  signRefreshToken,
-  verifyRefreshToken
-} from "../../lib/jwt.js";
+import { refreshAuthSessionAndSetCookies } from "../../lib/refresh-auth-session.js";
 import { enforceBasicAuthRateLimit } from "../../lib/rate-limit.js";
-import {
-  findAccountById,
-  rotateSession,
-  getSessionMetadataFromEvent
-} from "../../lib/session-store.js";
 import { enforceMutationOriginPolicy } from "../../lib/request-security.js";
 import { assertBasicAuthReady, noStore } from "./_helpers.js";
 export async function handleRefresh(event) {
@@ -25,52 +11,13 @@ export async function handleRefresh(event) {
   enforceBasicAuthRateLimit(event, "basic-auth:refresh");
   const query = getQuery(event);
   const silent = query.silent === "1" || query.silent === "true";
-  const failExpired = () => {
-    clearAuthCookies(event);
+  const result = await refreshAuthSessionAndSetCookies(event, { clearOnFailure: true });
+  if (!result.ok) {
     if (silent) {
       return { ok: false };
     }
     throw createSessionExpiredError();
-  };
-  const refreshToken = getRefreshTokenFromEvent(event);
-  if (!refreshToken) {
-    return failExpired();
   }
-  const claims = await verifyRefreshToken(refreshToken);
-  if (!claims) {
-    return failExpired();
-  }
-  const account = findAccountById(claims.sub);
-  if (!account || account.token_version !== claims.ver) {
-    return failExpired();
-  }
-  const config = getBasicAuthConfig();
-  const newSessionId = randomUUID();
-  const newRefreshToken = await signRefreshToken({
-    sub: account.id,
-    sid: newSessionId,
-    ver: account.token_version
-  });
-  const rotation = rotateSession({
-    currentSessionId: claims.sid,
-    currentRefreshHash: hashRefreshToken(refreshToken),
-    newSessionId,
-    newRefreshHash: hashRefreshToken(newRefreshToken),
-    newExpiresAtMs: Date.now() + config.refreshTtlSeconds * 1e3,
-    metadata: getSessionMetadataFromEvent(event)
-  });
-  if (!rotation.ok || rotation.accountId !== account.id) {
-    return failExpired();
-  }
-  const accessToken = await signAccessToken({
-    sub: account.id,
-    sid: newSessionId,
-    ver: account.token_version,
-    email: account.email,
-    display_name: account.display_name
-  });
-  setAccessCookie(event, accessToken, config.accessTtlSeconds);
-  setRefreshCookie(event, newRefreshToken, config.refreshTtlSeconds);
   return { ok: true };
 }
 export default defineEventHandler(async (event) => {

package/dist/runtime/server/api/basic-auth/register.post.js

@@ -1,6 +1,11 @@
 import { randomUUID } from "node:crypto";
 import { createError, defineEventHandler, setCookie } from "h3";
 import { z } from "zod";
+import { getAuthWorkspaceStore } from "~~/server/auth/store/registry";
+import {
+  resolveRegistrationMode,
+  validateInviteRegistration
+} from "~~/server/auth/registration";
 import { clearAuthCookies, setAccessCookie, setRefreshCookie } from "../../lib/cookies.js";
 import { getBasicAuthConfig } from "../../lib/config.js";
 import {
@@ -11,8 +16,7 @@ import { signAccessToken, signRefreshToken, hashRefreshToken } from "../../lib/j
 import { hashPassword } from "../../lib/password.js";
 import { enforceBasicAuthRateLimit } from "../../lib/rate-limit.js";
 import {
-  createAccount,
-  createAuthSession,
+  createAccountAndSession,
   findAccountByEmail,
   normalizeEmail,
   getSessionMetadataFromEvent
@@ -35,6 +39,12 @@ function mapRegistrationErrorToHttp(reason) {
       statusMessage: "Registration is currently disabled. Please contact an administrator."
     });
   }
+  if (reason === "invite_secret_missing" || reason === "invite_unsupported") {
+    throw createError({
+      statusCode: 503,
+      statusMessage: "Invite-only registration is temporarily unavailable."
+    });
+  }
   throw createError({
     statusCode: 403,
     statusMessage: "A valid invite is required to register."
@@ -47,47 +57,69 @@ export async function handleRegister(event) {
   enforceBasicAuthRateLimit(event, "basic-auth:register");
   const body = await parseBodyWithSchema(event, registerSchema);
   const email = normalizeEmail(body.email);
-  const existing = findAccountByEmail(email);
-  if (existing) {
-    throw createInvalidCredentialsError();
-  }
   const runtimeConfig = useRuntimeConfig();
-  const mode = runtimeConfig.auth?.registrationMode ?? (runtimeConfig.auth?.autoProvision === false ? "disabled" : "open");
+  const mode = resolveRegistrationMode(runtimeConfig);
   if (mode === "disabled") {
     mapRegistrationErrorToHttp("disabled");
   }
   if (mode === "invite_only" && !body.inviteToken?.trim()) {
     mapRegistrationErrorToHttp("invite_required");
   }
+  if (mode === "invite_only") {
+    const syncConfig = runtimeConfig;
+    const storeId = syncConfig.sync?.provider ?? syncConfig.public?.sync?.provider ?? "convex";
+    const store = getAuthWorkspaceStore(storeId);
+    if (!store) {
+      mapRegistrationErrorToHttp("invite_unsupported");
+    }
+    const decision = await validateInviteRegistration({
+      event,
+      store,
+      mode,
+      email,
+      inviteToken: body.inviteToken
+    });
+    if (!decision.allowed) {
+      mapRegistrationErrorToHttp(decision.reason);
+    }
+  }
+  const existing = findAccountByEmail(email);
+  if (existing) {
+    throw createInvalidCredentialsError();
+  }
   const passwordHash = await hashPassword(body.password);
-  const account = createAccount({
-    email,
-    passwordHash,
-    displayName: body.displayName?.trim() || null
-  });
   const config = getBasicAuthConfig();
   if (config.refreshTtlSeconds <= 0 || config.accessTtlSeconds <= 0) {
     throw createInvalidRequestError();
   }
+  const accountId = randomUUID();
   const sessionId = randomUUID();
   const refreshToken = await signRefreshToken({
-    sub: account.id,
+    sub: accountId,
     sid: sessionId,
-    ver: account.token_version
-  });
-  createAuthSession({
-    accountId: account.id,
-    sessionId,
-    refreshTokenHash: hashRefreshToken(refreshToken),
-    expiresAtMs: Date.now() + config.refreshTtlSeconds * 1e3,
-    metadata: getSessionMetadataFromEvent(event)
+    ver: 0
   });
   const accessToken = await signAccessToken({
-    sub: account.id,
+    sub: accountId,
     sid: sessionId,
-    ver: account.token_version,
-    email: account.email,
-    display_name: account.display_name
+    ver: 0,
+    email,
+    display_name: body.displayName?.trim() || null
+  });
+  createAccountAndSession({
+    account: {
+      id: accountId,
+      email,
+      passwordHash,
+      displayName: body.displayName?.trim() || null
+    },
+    session: {
+      accountId,
+      sessionId,
+      refreshTokenHash: hashRefreshToken(refreshToken),
+      expiresAtMs: Date.now() + config.refreshTtlSeconds * 1e3,
+      metadata: getSessionMetadataFromEvent(event)
+    }
   });
   setAccessCookie(event, accessToken, config.accessTtlSeconds);
   setRefreshCookie(event, refreshToken, config.refreshTtlSeconds);

package/dist/runtime/server/auth/basic-auth-provider.js

@@ -1,41 +1,71 @@
 import { BASIC_AUTH_PROVIDER_ID } from "../../lib/constants.js";
-import { getAccessTokenFromEvent, verifyAccessToken } from "../lib/jwt.js";
+import {
+  getAccessTokenFromEvent,
+  getRefreshTokenFromEvent,
+  verifyAccessToken
+} from "../lib/jwt.js";
+import { refreshAuthSessionAndSetCookies } from "../lib/refresh-auth-session.js";
 import {
   findAccountById,
   findSessionById,
   isSessionUsable
 } from "../lib/session-store.js";
+function toProviderSession(account, payload) {
+  return {
+    provider: BASIC_AUTH_PROVIDER_ID,
+    user: {
+      id: payload.sub,
+      email: payload.email ?? account.email,
+      displayName: payload.display_name ?? account.display_name ?? void 0
+    },
+    expiresAt: new Date((payload.exp ?? 0) * 1e3),
+    claims: payload
+  };
+}
+async function resolveFromAccessToken(event) {
+  const accessToken = getAccessTokenFromEvent(event);
+  if (!accessToken) {
+    return null;
+  }
+  const payload = await verifyAccessToken(accessToken);
+  if (!payload) {
+    return null;
+  }
+  const session = findSessionById(payload.sid);
+  if (!isSessionUsable(session)) {
+    return null;
+  }
+  const account = findAccountById(payload.sub);
+  if (!account) {
+    return null;
+  }
+  if (account.token_version !== payload.ver) {
+    return null;
+  }
+  return toProviderSession(account, payload);
+}
 export const basicAuthProvider = {
   name: BASIC_AUTH_PROVIDER_ID,
   async getSession(event) {
-    const accessToken = getAccessTokenFromEvent(event);
-    if (!accessToken) {
-      return null;
-    }
-    const payload = await verifyAccessToken(accessToken);
-    if (!payload) {
-      return null;
+    const fromAccess = await resolveFromAccessToken(event);
+    if (fromAccess) {
+      return fromAccess;
     }
-    const session = findSessionById(payload.sid);
-    if (!isSessionUsable(session)) {
+    if (!getRefreshTokenFromEvent(event)) {
       return null;
     }
-    const account = findAccountById(payload.sub);
-    if (!account) {
+    const refreshed = await refreshAuthSessionAndSetCookies(event, {
+      // Do not clear cookies on transient refresh misses during migration
+      // (legacy path cookies may still only be sent to /api/basic-auth/*).
+      clearOnFailure: false
+    });
+    if (!refreshed.ok) {
       return null;
     }
-    if (account.token_version !== payload.ver) {
+    const accessPayload = await verifyAccessToken(refreshed.accessToken);
+    if (!accessPayload) {
       return null;
     }
-    return {
-      provider: BASIC_AUTH_PROVIDER_ID,
-      user: {
-        id: payload.sub,
-        email: payload.email ?? account.email,
-        displayName: payload.display_name ?? account.display_name ?? void 0
-      },
-      expiresAt: new Date((payload.exp ?? 0) * 1e3),
-      claims: payload
-    };
+    return toProviderSession(refreshed.account, accessPayload);
   }
 };

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

@@ -69,6 +69,15 @@ function runMigrations(db) {
     `);
     db.pragma("user_version = 2");
   }
+  if (version < 3) {
+    db.exec(`
+      ALTER TABLE basic_auth_sessions
+        ADD COLUMN rotation_grace_until INTEGER;
+      ALTER TABLE basic_auth_sessions
+        ADD COLUMN rotation_grace_refresh_token TEXT;
+    `);
+    db.pragma("user_version = 3");
+  }
 }
 export function getBasicAuthDb() {
   if (dbSingleton) return dbSingleton;

package/dist/runtime/server/db/schema.d.ts

@@ -16,6 +16,10 @@ export interface BasicAuthSession {
     created_at: number;
     rotated_from_session_id: string | null;
     replaced_by_session_id: string | null;
+    /** Epoch ms until concurrent same-token refresh may reuse successor tokens. */
+    rotation_grace_until: number | null;
+    /** AES-GCM sealed successor refresh token, cleared after grace expires. */
+    rotation_grace_refresh_token: string | null;
     ip_address: string | null;
     user_agent: string | null;
 }

package/dist/runtime/server/lib/config.d.ts

@@ -7,6 +7,7 @@ export interface BasicAuthConfig {
     refreshSecret: string;
     accessTtlSeconds: number;
     refreshTtlSeconds: number;
+    rotationGraceMs: number;
     dbPath: string;
     bootstrapEmail?: string;
     bootstrapPassword?: string;

package/dist/runtime/server/lib/config.js

@@ -2,7 +2,8 @@ import { resolve } from "node:path";
 import {
   BASIC_AUTH_PROVIDER_ID,
   DEFAULT_ACCESS_TTL_SECONDS,
-  DEFAULT_REFRESH_TTL_SECONDS
+  DEFAULT_REFRESH_TTL_SECONDS,
+  REFRESH_ROTATION_GRACE_MS
 } from "../../lib/constants.js";
 export const BASIC_AUTH_INSECURE_DEV_ESCAPE_HATCH_ENV = "OR3_BASIC_AUTH_ALLOW_INSECURE_DEV";
 function parsePositiveInt(input, fallback) {
@@ -44,6 +45,10 @@ export function getBasicAuthConfig(runtimeConfig) {
       process.env.OR3_BASIC_AUTH_REFRESH_TTL_SECONDS,
       DEFAULT_REFRESH_TTL_SECONDS
     ),
+    rotationGraceMs: parsePositiveInt(
+      process.env.OR3_BASIC_AUTH_ROTATION_GRACE_MS,
+      REFRESH_ROTATION_GRACE_MS
+    ),
     dbPath,
     bootstrapEmail: process.env.OR3_BASIC_AUTH_BOOTSTRAP_EMAIL,
     bootstrapPassword: process.env.OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD

package/dist/runtime/server/lib/cookies.js

@@ -2,12 +2,20 @@ import { setCookie, deleteCookie } from "h3";
 import {
   ACCESS_COOKIE_NAME,
   ACCESS_COOKIE_PATH,
+  LEGACY_REFRESH_COOKIE_PATH,
   REFRESH_COOKIE_NAME,
   REFRESH_COOKIE_PATH
 } from "../../lib/constants.js";
 function isProduction() {
   return process.env.NODE_ENV === "production";
 }
+function refreshCookieBase() {
+  return {
+    httpOnly: true,
+    sameSite: "lax",
+    secure: isProduction()
+  };
+}
 export function setAccessCookie(event, token, maxAgeSeconds) {
   setCookie(event, ACCESS_COOKIE_NAME, token, {
     httpOnly: true,
@@ -18,10 +26,12 @@ export function setAccessCookie(event, token, maxAgeSeconds) {
   });
 }
 export function setRefreshCookie(event, token, maxAgeSeconds) {
+  deleteCookie(event, REFRESH_COOKIE_NAME, {
+    ...refreshCookieBase(),
+    path: LEGACY_REFRESH_COOKIE_PATH
+  });
   setCookie(event, REFRESH_COOKIE_NAME, token, {
-    httpOnly: true,
-    sameSite: "lax",
-    secure: isProduction(),
+    ...refreshCookieBase(),
     path: REFRESH_COOKIE_PATH,
     maxAge: maxAgeSeconds
   });
@@ -34,9 +44,11 @@ export function clearAuthCookies(event) {
     path: ACCESS_COOKIE_PATH
   });
   deleteCookie(event, REFRESH_COOKIE_NAME, {
-    httpOnly: true,
-    sameSite: "lax",
-    secure: isProduction(),
+    ...refreshCookieBase(),
     path: REFRESH_COOKIE_PATH
   });
+  deleteCookie(event, REFRESH_COOKIE_NAME, {
+    ...refreshCookieBase(),
+    path: LEGACY_REFRESH_COOKIE_PATH
+  });
 }

package/dist/runtime/server/lib/refresh-auth-session.d.ts

@@ -0,0 +1,23 @@
+import type { H3Event } from 'h3';
+import type { BasicAuthAccount } from '../db/schema.js';
+export type RefreshAuthSessionFailureReason = 'missing_token' | 'invalid_token' | 'account' | 'not_found' | 'expired' | 'revoked' | 'replayed';
+export type RefreshAuthSessionResult = {
+    ok: true;
+    account: BasicAuthAccount;
+    sessionId: string;
+    accessToken: string;
+    refreshToken: string;
+    reused: boolean;
+} | {
+    ok: false;
+    reason: RefreshAuthSessionFailureReason;
+};
+/**
+ * Rotate (or grace-reuse) the refresh session for this request and mint a fresh
+ * access token. Does not set cookies — callers decide whether to write them.
+ */
+export declare function refreshAuthSession(event: H3Event): Promise<RefreshAuthSessionResult>;
+/** Apply refreshed tokens as cookies, or clear auth cookies on failure. */
+export declare function refreshAuthSessionAndSetCookies(event: H3Event, options?: {
+    clearOnFailure?: boolean;
+}): Promise<RefreshAuthSessionResult>;

package/dist/runtime/server/lib/refresh-auth-session.js

@@ -0,0 +1,83 @@
+import { randomUUID } from "node:crypto";
+import { clearAuthCookies, setAccessCookie, setRefreshCookie } from "./cookies.js";
+import { getBasicAuthConfig } from "./config.js";
+import {
+  getRefreshTokenFromEvent,
+  hashRefreshToken,
+  signAccessToken,
+  signRefreshToken,
+  verifyRefreshToken
+} from "./jwt.js";
+import {
+  findAccountById,
+  getSessionMetadataFromEvent,
+  rotateSession
+} from "./session-store.js";
+export async function refreshAuthSession(event) {
+  const refreshToken = getRefreshTokenFromEvent(event);
+  if (!refreshToken) {
+    return { ok: false, reason: "missing_token" };
+  }
+  const claims = await verifyRefreshToken(refreshToken);
+  if (!claims) {
+    return { ok: false, reason: "invalid_token" };
+  }
+  const account = findAccountById(claims.sub);
+  if (!account || account.token_version !== claims.ver) {
+    return { ok: false, reason: "account" };
+  }
+  const config = getBasicAuthConfig();
+  const newSessionId = randomUUID();
+  const newRefreshToken = await signRefreshToken({
+    sub: account.id,
+    sid: newSessionId,
+    ver: account.token_version
+  });
+  const rotation = rotateSession({
+    currentSessionId: claims.sid,
+    currentRefreshHash: hashRefreshToken(refreshToken),
+    newSessionId,
+    newRefreshHash: hashRefreshToken(newRefreshToken),
+    newRefreshToken,
+    newExpiresAtMs: Date.now() + config.refreshTtlSeconds * 1e3,
+    graceMs: config.rotationGraceMs,
+    metadata: getSessionMetadataFromEvent(event)
+  });
+  if (!rotation.ok || rotation.accountId !== account.id) {
+    return {
+      ok: false,
+      reason: rotation.ok ? "account" : rotation.reason
+    };
+  }
+  const effectiveRefreshToken = rotation.reused && rotation.refreshToken ? rotation.refreshToken : newRefreshToken;
+  const effectiveSessionId = rotation.sessionId;
+  const accessToken = await signAccessToken({
+    sub: account.id,
+    sid: effectiveSessionId,
+    ver: account.token_version,
+    email: account.email,
+    display_name: account.display_name
+  });
+  return {
+    ok: true,
+    account,
+    sessionId: effectiveSessionId,
+    accessToken,
+    refreshToken: effectiveRefreshToken,
+    reused: rotation.reused
+  };
+}
+export async function refreshAuthSessionAndSetCookies(event, options = {}) {
+  const clearOnFailure = options.clearOnFailure ?? true;
+  const result = await refreshAuthSession(event);
+  if (!result.ok) {
+    if (clearOnFailure) {
+      clearAuthCookies(event);
+    }
+    return result;
+  }
+  const config = getBasicAuthConfig();
+  setAccessCookie(event, result.accessToken, config.accessTtlSeconds);
+  setRefreshCookie(event, result.refreshToken, config.refreshTtlSeconds);
+  return result;
+}

package/dist/runtime/server/lib/rotation-grace.d.ts

@@ -0,0 +1,4 @@
+/** Encrypt a successor refresh token for short-lived grace storage. */
+export declare function sealRotationGraceToken(token: string): string;
+/** Decrypt a grace-stored successor refresh token. Returns null on failure. */
+export declare function unsealRotationGraceToken(sealed: string): string | null;

package/dist/runtime/server/lib/rotation-grace.js

@@ -0,0 +1,26 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { getBasicAuthConfig } from "./config.js";
+function graceKey() {
+  return createHash("sha256").update(`basic-auth-rotation-grace:${getBasicAuthConfig().refreshSecret}`).digest();
+}
+export function sealRotationGraceToken(token) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", graceKey(), iv);
+  const encrypted = Buffer.concat([cipher.update(token, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, encrypted]).toString("base64url");
+}
+export function unsealRotationGraceToken(sealed) {
+  try {
+    const buf = Buffer.from(sealed, "base64url");
+    if (buf.length < 28) return null;
+    const iv = buf.subarray(0, 12);
+    const tag = buf.subarray(12, 28);
+    const encrypted = buf.subarray(28);
+    const decipher = createDecipheriv("aes-256-gcm", graceKey(), iv);
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(encrypted), decipher.final()]).toString("utf8");
+  } catch {
+    return null;
+  }
+}

package/dist/runtime/server/lib/session-store.d.ts

@@ -1,6 +1,7 @@
 import { type H3Event } from 'h3';
 import type { BasicAuthAccount, BasicAuthSession } from '../db/schema.js';
 export interface CreateAccountInput {
+    id?: string;
     email: string;
     passwordHash: string;
     displayName?: string | null;
@@ -22,20 +23,40 @@ export interface RotationInput {
     currentRefreshHash: string;
     newSessionId: string;
     newRefreshHash: string;
+    /** Plaintext successor refresh token; sealed into the grace window for concurrent reuse. */
+    newRefreshToken: string;
     newExpiresAtMs: number;
     metadata?: SessionMetadata;
+    /** Injectable clock for tests. */
+    nowMs?: number;
+    /** Override grace window length for tests. */
+    graceMs?: number;
 }
-export interface RotationResult {
-    ok: boolean;
-    reason?: 'not_found' | 'expired' | 'revoked' | 'replayed';
-    accountId?: string;
-    sessionId?: string;
-}
+export type RotationResult = {
+    ok: true;
+    accountId: string;
+    sessionId: string;
+    reused: boolean;
+    /** Present when `reused` is true — the already-issued successor refresh token. */
+    refreshToken?: string;
+} | {
+    ok: false;
+    reason: 'not_found' | 'expired' | 'revoked' | 'replayed';
+};
 export declare function normalizeEmail(email: string): string;
 export declare function getSessionMetadataFromEvent(event: H3Event): SessionMetadata;
 export declare function findAccountByEmail(email: string): BasicAuthAccount | null;
 export declare function findAccountById(id: string): BasicAuthAccount | null;
 export declare function createAccount(input: CreateAccountInput): BasicAuthAccount;
+export declare function createAccountAndSession(input: {
+    account: CreateAccountInput & {
+        id: string;
+    };
+    session: CreateSessionInput;
+}): {
+    account: BasicAuthAccount;
+    session: BasicAuthSession;
+};
 export declare function ensureBootstrapAccount(input: CreateAccountInput): BasicAuthAccount;
 export declare function createAuthSession(input: CreateSessionInput): BasicAuthSession;
 export declare function findSessionById(sessionId: string): BasicAuthSession | null;

package/dist/runtime/server/lib/session-store.js

@@ -1,10 +1,12 @@
 import { randomUUID, timingSafeEqual } from "node:crypto";
 import { getRequestHeader } from "h3";
 import { getBasicAuthDb } from "../db/client.js";
+import { REFRESH_ROTATION_GRACE_MS } from "../../lib/constants.js";
 import {
   getClientIp as getProxyClientIp,
   normalizeProxyTrustConfig
 } from "./request-identity.js";
+import { sealRotationGraceToken, unsealRotationGraceToken } from "./rotation-grace.js";
 export function normalizeEmail(email) {
   return email.trim().toLowerCase();
 }
@@ -18,6 +20,14 @@ function safeHexEquals(left, right) {
   if (leftBuffer.length !== rightBuffer.length) return false;
   return timingSafeEqual(leftBuffer, rightBuffer);
 }
+function clearExpiredRotationGrace(sessionId) {
+  const db = getBasicAuthDb();
+  db.prepare(
+    `UPDATE basic_auth_sessions
+     SET rotation_grace_until = NULL, rotation_grace_refresh_token = NULL
+     WHERE id = ?`
+  ).run(sessionId);
+}
 export function getSessionMetadataFromEvent(event) {
   const proxyConfig = normalizeProxyTrustConfig(useRuntimeConfig(event).security?.proxy);
   return {
@@ -39,7 +49,7 @@ export function createAccount(input) {
   const db = getBasicAuthDb();
   const now = Date.now();
   const account = {
-    id: randomUUID(),
+    id: input.id ?? randomUUID(),
     email: normalizeEmail(input.email),
     password_hash: input.passwordHash,
     display_name: input.displayName ?? null,
@@ -62,6 +72,17 @@ export function createAccount(input) {
   );
   return account;
 }
+export function createAccountAndSession(input) {
+  const db = getBasicAuthDb();
+  return db.transaction(() => {
+    const account = createAccount(input.account);
+    if (input.session.accountId !== account.id) {
+      throw new Error("Session account does not match the account being created");
+    }
+    const session = createAuthSession(input.session);
+    return { account, session };
+  })();
+}
 export function ensureBootstrapAccount(input) {
   const existing = findAccountByEmail(input.email);
   if (existing) return existing;
@@ -79,14 +100,18 @@ export function createAuthSession(input) {
     created_at: createdAt,
     rotated_from_session_id: input.rotatedFromSessionId ?? null,
     replaced_by_session_id: null,
+    rotation_grace_until: null,
+    rotation_grace_refresh_token: null,
     ip_address: input.metadata?.ipAddress ?? null,
     user_agent: input.metadata?.userAgent ?? null
   };
   db.prepare(
     `INSERT INTO basic_auth_sessions (
       id, account_id, refresh_token_hash, expires_at, revoked_at, created_at,
-      rotated_from_session_id, replaced_by_session_id, ip_address, user_agent
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+      rotated_from_session_id, replaced_by_session_id,
+      rotation_grace_until, rotation_grace_refresh_token,
+      ip_address, user_agent
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
   ).run(
     row.id,
     row.account_id,
@@ -96,6 +121,8 @@ export function createAuthSession(input) {
     row.created_at,
     row.rotated_from_session_id,
     row.replaced_by_session_id,
+    row.rotation_grace_until,
+    row.rotation_grace_refresh_token,
     row.ip_address,
     row.user_agent
   );
@@ -115,12 +142,39 @@ export function revokeSessionById(sessionId, revokedAtMs = Date.now()) {
 export function revokeAllSessionsForAccount(accountId, revokedAtMs = Date.now()) {
   const db = getBasicAuthDb();
   db.prepare(
-    "UPDATE basic_auth_sessions SET revoked_at = COALESCE(revoked_at, ?) WHERE account_id = ?"
+    `UPDATE basic_auth_sessions
+     SET revoked_at = COALESCE(revoked_at, ?),
+         rotation_grace_until = NULL,
+         rotation_grace_refresh_token = NULL
+     WHERE account_id = ?`
   ).run(revokedAtMs, accountId);
 }
+function tryReuseRotatedSession(currentSession, isSameTokenHash, now) {
+  if (currentSession.replaced_by_session_id === null || !isSameTokenHash) {
+    return null;
+  }
+  const graceUntil = currentSession.rotation_grace_until;
+  const sealedToken = currentSession.rotation_grace_refresh_token;
+  if (typeof graceUntil === "number" && graceUntil > now && typeof sealedToken === "string" && sealedToken.length > 0) {
+    const refreshToken = unsealRotationGraceToken(sealedToken);
+    const successor = findSessionById(currentSession.replaced_by_session_id);
+    if (refreshToken && successor && isSessionUsable(successor)) {
+      return {
+        ok: true,
+        reused: true,
+        accountId: currentSession.account_id,
+        sessionId: successor.id,
+        refreshToken
+      };
+    }
+  }
+  clearExpiredRotationGrace(currentSession.id);
+  return null;
+}
 export function rotateSession(input) {
   const db = getBasicAuthDb();
-  const now = Date.now();
+  const now = input.nowMs ?? Date.now();
+  const graceMs = input.graceMs ?? REFRESH_ROTATION_GRACE_MS;
   const currentSession = findSessionById(input.currentSessionId);
   if (!currentSession) {
     return { ok: false, reason: "not_found" };
@@ -134,8 +188,11 @@ export function rotateSession(input) {
     input.currentRefreshHash
   );
   if (currentSession.revoked_at !== null) {
-    const replayedRotatedToken = currentSession.replaced_by_session_id !== null && isSameTokenHash;
-    if (replayedRotatedToken) {
+    const reused = tryReuseRotatedSession(currentSession, isSameTokenHash, now);
+    if (reused) {
+      return reused;
+    }
+    if (currentSession.replaced_by_session_id !== null && isSameTokenHash) {
       revokeAllSessionsForAccount(currentSession.account_id, now);
       return {
         ok: false,
@@ -151,6 +208,7 @@ export function rotateSession(input) {
       reason: "replayed"
     };
   }
+  const sealedGraceToken = sealRotationGraceToken(input.newRefreshToken);
   db.transaction(() => {
     createAuthSession({
       accountId: currentSession.account_id,
@@ -161,11 +219,17 @@ export function rotateSession(input) {
       metadata: input.metadata
     });
     db.prepare(
-      "UPDATE basic_auth_sessions SET revoked_at = ?, replaced_by_session_id = ? WHERE id = ?"
-    ).run(now, input.newSessionId, currentSession.id);
+      `UPDATE basic_auth_sessions
+       SET revoked_at = ?,
+           replaced_by_session_id = ?,
+           rotation_grace_until = ?,
+           rotation_grace_refresh_token = ?
+       WHERE id = ?`
+    ).run(now, input.newSessionId, now + graceMs, sealedGraceToken, currentSession.id);
   })();
   return {
     ok: true,
+    reused: false,
     accountId: currentSession.account_id,
     sessionId: input.newSessionId
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "or3-provider-basic-auth",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Basic-authentication provider for OR3 Chat with SSR session resolution, secure cookies, and provider-owned auth UI.",
   "license": "MIT",
   "type": "module",