release: WRNexusJS 0.5.0

docs/AUTH-SCHEMA-CONFIG.md

@@ -0,0 +1,84 @@
+# Auth schemas and route configuration
+
+`@wrnexus/auth` registers its browser validation schemas automatically. Applications using packaged components do not create default files under `app/schemas` and do not duplicate package API routes.
+
+## Default use
+
+```ts
+import type { AuthConfig } from "@wrnexus/auth";
+import type { AppConfig } from "@wrnexus/styles";
+import { auth } from "./app/lib/auth.ts";
+
+const config = {
+  auth: {
+    engine: auth,
+    routes: true,
+    middleware: true,
+    migrations: false,
+  },
+} satisfies AppConfig & { auth: AuthConfig };
+
+export default config;
+```
+
+Keep behavioral hooks such as `delivery`, `tokenUrl`, `onSignedIn`, and
+`onSignedOut` in the application's `createAuthEngine(...)` call. `config.auth`
+selects framework integration features such as routes, middleware, migrations,
+components, schemas, base URL, CSRF, and passkey HTTP settings.
+
+Components such as `<SignUp />`, `<SignIn />`, and `<ForgotPassword />` use built-in schemas in the browser and the same resolved schemas on the server.
+
+## Route groups
+
+```ts
+routes: {
+  enabled: true,
+  registration: true,
+  login: true,
+  verification: true,
+  password: true,
+  invitations: true,
+  magicLink: true,
+  otp: true,
+  mfa: true,
+  sessions: true,
+  impersonation: false,
+  passkeys: true,
+}
+```
+
+Set `routes: false` to disable every package route. Set a route group to `false` only when the application intentionally owns that feature's endpoints. No explicit exclusion list is required.
+
+## Customize one schema
+
+Create a file only when application behavior differs from the package default:
+
+```ts
+// app/schemas/custom-password-request.ts
+import { authSchemas } from "@wrnexus/auth";
+import { v } from "@wrnexus/validation";
+
+export default authSchemas.passwordResetRequest.extend({
+  identifier: v
+    .string()
+    .trim()
+    .required("Enter your registered email address")
+    .email("Enter a valid registered email address"),
+});
+```
+
+```ts
+// wrnexus.config.ts
+import customPasswordRequest from "./app/schemas/custom-password-request.ts";
+
+export default {
+  auth: {
+    engine: auth,
+    schemas: {
+      passwordResetRequest: customPasswordRequest,
+    },
+  },
+};
+```
+
+The override is used by both the package API handler and the package browser runtime. `<ForgotPassword />` keeps its normal `schema="auth-password-request"`; all other auth schemas continue using package defaults.

docs/AUTH-SYSTEM-0.5.md

@@ -0,0 +1,28 @@
+# WRNexusJS authentication system 0.5 alpha
+
+`@wrnexus/auth` is a framework-native system built on the WRNexusJS package-runtime architecture.
+
+## Architecture
+
+- `AuthEngine` owns identity, credentials, tokens, sessions, recovery, MFA, invitations, OAuth, passkeys, risk, and auditing.
+- `AuthStore` isolates persistence. `MemoryAuthStore` is for development and `SqlAuthStore` targets WRNexusJS database drivers.
+- `config.auth` activates package routes, auth-session middleware, components, browser schemas, client runtime, ordered migrations, and DevToolbar checks.
+- Every package endpoint has a route-specific module; path rewriting cannot make an endpoint fall through a shared dispatcher.
+- `createAuthHttpHandlers()` remains available for intentionally custom HTTP surfaces.
+- `createAuthSecretProtector()` protects TOTP and OAuth secrets with a versioned encryption keyring.
+
+## Security boundaries
+
+- Password, OTP, token, CAPTCHA, passkey, and MFA verification are server-side.
+- Browser schemas improve usability; resolved server schemas remain authoritative.
+- Unsafe package routes verify CSRF by default.
+- CAPTCHA success is accepted only from server-populated request locals.
+- OAuth email linking requires a verified provider email and can be disabled.
+- Impersonation is deny-by-default and requires an application policy.
+- One-time credentials are expiring, purpose-bound, and single-use.
+- Sessions rotate at establishment and support idle and absolute expiration.
+- Multi-process passkey deployments provide a shared `PasskeyChallengeStore`.
+
+## Development version
+
+The package is `0.5.0`. Run `bun run validate:auth` before publishing and read `packages/auth/SECURITY.md` before production deployment.