or3-provider-basic-auth 0.0.6 → 0.0.8

package/README.md

@@ -6,6 +6,7 @@ This package registers:
 
 - `AuthProvider` (`basic-auth`)
 - `ProviderTokenBroker` (`basic-auth`)
+- admin status adapter (`auth-basic-auth`)
 - provider-owned auth UI adapter + components
 
 ## Installation
@@ -35,22 +36,31 @@ export const or3ProviderModules = [
 
 Required:
 
-- `AUTH_PROVIDER=basic-auth`
+- `AUTH_PROVIDER=basic-auth` (alias: `OR3_AUTH_PROVIDER`)
+- `SSR_AUTH_ENABLED=true`
 - `OR3_BASIC_AUTH_JWT_SECRET`
+- `OR3_BASIC_AUTH_REFRESH_SECRET` (use a separate random value; the provider validates it independently)
 
 Optional:
 
-- `OR3_BASIC_AUTH_REFRESH_SECRET` (falls back to `OR3_BASIC_AUTH_JWT_SECRET`)
 - `OR3_BASIC_AUTH_ACCESS_TTL_SECONDS` (default `900`)
 - `OR3_BASIC_AUTH_REFRESH_TTL_SECONDS` (default `2592000`)
+- `OR3_BASIC_AUTH_ROTATION_GRACE_MS` (default `30000`; concurrent-refresh grace window)
 - `OR3_BASIC_AUTH_DB_PATH` (default `./.data/or3-basic-auth.sqlite`)
 - `OR3_BASIC_AUTH_BOOTSTRAP_EMAIL`
 - `OR3_BASIC_AUTH_BOOTSTRAP_PASSWORD`
+- `OR3_BASIC_AUTH_RATE_LIMIT_BACKEND` (`sqlite` default; `memory` is per-process and intended for single-instance development only)
+- `OR3_BASIC_AUTH_ALLOW_INSECURE_DEV` (`true` in non-production to start with missing secrets instead of failing)
+
+Registration mode is a core-auth policy, not a provider setting:
+
+- `OR3_AUTH_REGISTRATION_MODE=open|invite_only|disabled`
+- `OR3_AUTH_INVITE_TOKEN_SECRET` and `OR3_AUTH_INVITE_TOKEN_TTL_SECONDS` (required for `invite_only`)
 
 Strict-mode behavior:
 
-- `NODE_ENV=production` or `OR3_STRICT_CONFIG=true` fails startup if required secrets are missing.
-- non-strict mode logs diagnostics and leaves provider registration disabled.
+- `NODE_ENV=production`, `OR3_STRICT_CONFIG=true`, or runtime config `auth.strict=true` fails startup if required secrets are missing.
+- In non-strict (development) mode, missing secrets also fail startup unless `OR3_BASIC_AUTH_ALLOW_INSECURE_DEV=true` is set — then diagnostics are logged and provider registration is left disabled.
 
 ## Architecture notes
 
@@ -61,16 +71,35 @@ Strict-mode behavior:
 - 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.
+- The refresh cookie is scoped to `/api` so `/api/auth/session` can transparently rotate expired access tokens during session resolution.
+- The SQLite DB file and directory are hardened to mode `0600`/`0700`; the DB uses WAL journaling.
+
+## Runtime entrypoints
+
+| File | Purpose |
+|---|---|
+| `src/module.ts` | Nuxt module entry — wires `/api/basic-auth/*` handlers, server plugin, and client plugins |
+| `src/runtime/server/plugins/register.ts` | Registers auth provider + token broker + admin adapter into core registries; bootstraps account |
+| `src/runtime/server/auth/basic-auth-provider.ts` | Auth provider — session resolution from access tokens with refresh-token recovery |
+| `src/runtime/server/token-broker/basic-auth-token-broker.ts` | Token broker for direct-mode providers |
+| `src/runtime/server/admin/adapters/auth-basic-auth.ts` | Admin status adapter (config diagnostics) |
+| `src/runtime/server/api/basic-auth/*.post.ts` | Sign-in / register / sign-out / refresh / change-password endpoints |
+| `src/runtime/server/db/client.ts` | SQLite client + migrations (`basic_auth_accounts`, `basic_auth_sessions`, `basic_auth_rate_limits`) |
+| `src/runtime/server/lib/*.ts` | Config, JWT, cookies, password, rate-limit, session store, refresh rotation |
+| `src/runtime/plugins/basic-auth-ui.client.ts` | Registers auth UI adapter + lock-page adapter |
+| `src/runtime/plugins/auth-status.client.ts` | Client auth-status resolver + silent-refresh recovery |
+| `src/runtime/components/*.client.vue` | Provider-owned auth UI (modals, user menu, sidebar button, lock page) |
 
 ## Troubleshooting
 
 - `Authentication provider is not configured`
   - Ensure `AUTH_PROVIDER=basic-auth` and `SSR_AUTH_ENABLED=true`.
-  - Ensure `OR3_BASIC_AUTH_JWT_SECRET` is set.
+  - Ensure `OR3_BASIC_AUTH_JWT_SECRET` and `OR3_BASIC_AUTH_REFRESH_SECRET` are set.
 
-- `Missing OR3_BASIC_AUTH_JWT_SECRET`
+- `Missing OR3_BASIC_AUTH_JWT_SECRET` / `Missing OR3_BASIC_AUTH_REFRESH_SECRET`
   - In strict mode (`NODE_ENV=production` or `OR3_STRICT_CONFIG=true`), startup fails intentionally.
-  - Add the missing secret and restart.
+  - In development, set `OR3_BASIC_AUTH_ALLOW_INSECURE_DEV=true` to start with registration disabled instead.
+  - Add the missing secret(s) and restart.
 
 - `Invalid credentials` on known user
   - Verify the bootstrap account values.

package/dist/module.json

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

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

@@ -2,8 +2,8 @@
   <UPopover
     v-model:open="isOpen"
     portal
-    :content="{ side: 'right', align: 'end', sideOffset: 10 }"
-    :ui="{ content: 'z-[260] max-w-[240px] p-0 border-none bg-transparent shadow-none' }"
+    :content="popoverContent"
+    :ui="{ content: 'z-[280] max-w-[240px] p-0 border-none bg-transparent shadow-none' }"
   >
     <UButton
       v-bind="triggerButtonProps"
@@ -12,8 +12,8 @@
     >
       <template #default>
         <span class="flex flex-col items-center gap-1 w-full">
-          <UIcon name="i-lucide-user-check" class="h-[18px] w-[18px]" />
-          <span class="text-[7px] uppercase tracking-wider whitespace-nowrap">
+          <UIcon name="lucide:user" class="h-[18px] w-[18px]" />
+          <span class="sidebar-rail-caption text-[7px] uppercase tracking-wider whitespace-nowrap">
             Account
           </span>
         </span>
@@ -22,13 +22,13 @@
 
     <template #content>
       <div
-        class="w-[220px] rounded-[var(--md-border-radius)] border-[length:var(--md-border-width)] border-[color:var(--md-border-color)] bg-[var(--md-surface)] overflow-hidden theme-shadow"
+        class="basic-auth-account-menu w-[220px] rounded-[var(--md-border-radius)] border-[length:var(--md-border-width)] border-[color:var(--md-border-color)] bg-[var(--md-surface)] overflow-hidden theme-shadow"
       >
         <!-- User identity section -->
         <div class="px-4 pt-4 pb-3">
           <div class="flex items-center gap-3">
             <div class="flex items-center justify-center w-8 h-8 rounded-full bg-[var(--md-success)]/15 text-[var(--md-success)] shrink-0">
-              <UIcon name="i-lucide-user" class="w-4 h-4" />
+              <UIcon name="lucide:user" class="w-4 h-4" />
             </div>
             <div class="min-w-0">
               <p class="text-[10px] uppercase tracking-wider text-[var(--md-on-surface)]/50 mb-0.5">
@@ -50,7 +50,7 @@
             class="w-full flex items-center gap-2.5 px-3 py-2 text-sm text-[var(--md-on-surface)] rounded-[var(--md-border-radius)] hover:bg-[var(--md-surface-hover)] active:bg-[var(--md-surface-active)] transition-colors text-left"
             @click="onChangePassword"
           >
-            <UIcon name="i-lucide-key-round" class="w-4 h-4 text-[var(--md-on-surface)]/60 shrink-0" />
+            <UIcon name="lucide:key-round" class="w-4 h-4 text-[var(--md-on-surface)]/60 shrink-0" />
             Change Password
           </button>
 
@@ -60,7 +60,7 @@
             class="w-full flex items-center gap-2.5 px-3 py-2 text-sm rounded-[var(--md-border-radius)] text-[var(--md-error)] hover:bg-[var(--md-error)]/10 active:bg-[var(--md-error)]/18 transition-colors text-left disabled:opacity-50"
             @click="onSignOut"
           >
-            <UIcon name="i-lucide-log-out" class="w-4 h-4 shrink-0" />
+            <UIcon name="lucide:log-out" class="w-4 h-4 shrink-0" />
             {{ pending ? "Signing out\u2026" : "Sign Out" }}
           </button>
         </div>
@@ -70,7 +70,10 @@
 </template>
 
 <script setup>
-import { ref } from "vue";
+import { computed, inject, ref, unref } from "vue";
+import {
+  AUTH_UI_POPOVER_CONTENT_KEY
+} from "../lib/auth-ui-popover";
 defineProps({
   email: { type: String, required: false },
   displayName: { type: String, required: false }
@@ -78,6 +81,20 @@ defineProps({
 const emit = defineEmits(["signed-out", "change-password"]);
 const isOpen = ref(false);
 const pending = ref(false);
+const DEFAULT_POPOVER_CONTENT = {
+  side: "right",
+  align: "end",
+  sideOffset: 10,
+  collisionPadding: 12
+};
+const injectedPopoverContent = inject(
+  AUTH_UI_POPOVER_CONTENT_KEY,
+  null
+);
+const popoverContent = computed(() => ({
+  ...DEFAULT_POPOVER_CONTENT,
+  ...injectedPopoverContent ? unref(injectedPopoverContent) : null
+}));
 const triggerButtonProps = {
   block: true,
   variant: "ghost",

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

@@ -17,8 +17,8 @@
     >
       <template #default>
         <span class="flex flex-col items-center gap-1 w-full">
-          <UIcon name="i-lucide-log-in" class="h-[18px] w-[18px]" />
-          <span class="text-[7px] uppercase tracking-wider whitespace-nowrap">
+          <UIcon name="lucide:log-in" class="h-[18px] w-[18px]" />
+          <span class="sidebar-rail-caption text-[7px] uppercase tracking-wider whitespace-nowrap">
             Login
           </span>
         </span>

package/dist/runtime/lib/auth-ui-popover.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Floating UI content options for auth UI popovers.
+ * Hosts (e.g. mobile More menu) can inject overrides so nested menus
+ * stay on-screen instead of defaulting to rail `side: 'right'`.
+ */
+export interface AuthUiPopoverContent {
+    side?: 'top' | 'right' | 'bottom' | 'left';
+    align?: 'start' | 'center' | 'end';
+    sideOffset?: number;
+    alignOffset?: number;
+    collisionPadding?: number | Partial<Record<'top' | 'right' | 'bottom' | 'left', number>>;
+}
+/** String key so host app + provider package can share without a linked import. */
+export declare const AUTH_UI_POPOVER_CONTENT_KEY = "or3:auth-ui-popover-content";

package/dist/runtime/lib/auth-ui-popover.js

@@ -0,0 +1 @@
+export const AUTH_UI_POPOVER_CONTENT_KEY = "or3:auth-ui-popover-content";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "or3-provider-basic-auth",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Saluana/or3-provider-basic-auth.git"
@@ -40,6 +40,7 @@
     "build": "nuxt-module-build build",
     "lint": "eslint \"src/**/*.{ts,d.ts,vue}\"",
     "type-check": "tsc -p tsconfig.typecheck.json --noEmit",
+    "type-check:standalone": "tsc -p tsconfig.typecheck.json --noEmit",
     "test": "vitest run"
   },
   "publishConfig": {
@@ -47,7 +48,7 @@
   },
   "dependencies": {
     "bcryptjs": "^3.0.3",
-    "better-sqlite3": "^12.4.1",
+    "better-sqlite3": "^13.0.3",
     "jsonwebtoken": "^9.0.2",
     "zod": "^4.1.12"
   },