diff --git a/website/app/docs/auth/page.ts b/website/app/docs/auth/page.ts index 4042fb6e3..dcc59d6ed 100644 --- a/website/app/docs/auth/page.ts +++ b/website/app/docs/auth/page.ts @@ -1,11 +1,16 @@ import { html } from '@webjsdev/core'; -export const metadata = { title: 'Authentication | WebJs' }; +export const metadata = { + title: 'Auth Providers (createAuth) | WebJs', + description: + 'The built-in createAuth() surface: OAuth providers, credentials login, and JWT sessions with no external auth library. Covers setup, the auth API route, reading the session, callbacks, and session strategies.', +}; export default function Auth() { return html` -

Authentication

-

WebJs provides NextAuth-style authentication with OAuth providers, credentials login, and JWT sessions. No external auth library needed.

+

Auth providers (createAuth)

+

WebJs ships createAuth(), a NextAuth-style auth surface with OAuth providers, credentials login, and JWT sessions. Reach for this page when you want providers and sessions handled for you, and no external auth library in the dependency tree.

+

It is not the only route. If you want to own the session format, the password hashing, and the route-protection rules yourself, build on the framework primitives instead, which is what Build your own authentication covers and what the blog example does. Pick createAuth() for OAuth and a batteries-included setup, pick the primitives when you want full control of the session.

Setup

// lib/auth.server.ts: create once
diff --git a/website/app/docs/authentication/page.ts b/website/app/docs/authentication/page.ts
index f4bd618e3..171e3d72f 100644
--- a/website/app/docs/authentication/page.ts
+++ b/website/app/docs/authentication/page.ts
@@ -1,11 +1,16 @@
 import { html } from '@webjsdev/core';
 
-export const metadata = { title: 'Authentication | WebJs' };
+export const metadata = {
+  title: 'Build Your Own Authentication | WebJs',
+  description:
+    'Build session-based authentication on the WebJs primitives when you want to own the session format, scrypt password hashing, and middleware route protection, instead of using the built-in createAuth() providers.',
+};
 
 export default function Authentication() {
   return html`
-    
Authentication

-    
WebJs doesn't ship an auth library. It provides the primitives you need to build session-based authentication cleanly. The blog example demonstrates a complete implementation using scrypt password hashing, session tokens in cookies, and middleware-based route protection.

+    
Build your own authentication

+    
This page is the hand-rolled route: session-based auth built on the framework primitives, where you own the session format, the password hashing, and the route-protection rules. The blog example is a complete implementation of it, using scrypt password hashing, session tokens in cookies, and middleware-based route protection.

+    
WebJs does ship a batteries-included option, so this is a choice rather than a necessity. Auth providers (createAuth) gives you OAuth providers, credentials login, and JWT sessions out of the box. Take that page if you want OAuth or do not want to own the session. Stay here if you want full control over how a session is minted, stored, and checked.

 
     
Architecture

     
lib/
diff --git a/website/app/docs/cache/page.ts b/website/app/docs/cache/page.ts
index 6c215be51..199d0ebcc 100644
--- a/website/app/docs/cache/page.ts
+++ b/website/app/docs/cache/page.ts
@@ -195,7 +195,7 @@ setStore(redisStore({ url: process.env.REDIS_URL }));

     
Next Steps

     
   `;
diff --git a/website/app/docs/layout.ts b/website/app/docs/layout.ts
index 686bc64d4..680a45eea 100644
--- a/website/app/docs/layout.ts
+++ b/website/app/docs/layout.ts
@@ -60,7 +60,7 @@ const NAV_SECTIONS = [
       { href: '/docs/api-routes', label: 'API Routes' },
       { href: '/docs/websockets', label: 'WebSockets' },
       { href: '/docs/database', label: 'Database (Drizzle)' },
-      { href: '/docs/authentication', label: 'Authentication' },
+      { href: '/docs/authentication', label: 'Build your own authentication' },
       { href: '/docs/backend-only', label: 'Backend-Only Mode' },
     ],
   },
@@ -70,7 +70,7 @@ const NAV_SECTIONS = [
       { href: '/docs/cache', label: 'Caching' },
       { href: '/docs/file-storage', label: 'File Storage' },
       { href: '/docs/sessions', label: 'Sessions' },
-      { href: '/docs/auth', label: 'Auth (Providers)' },
+      { href: '/docs/auth', label: 'Auth providers (createAuth)' },
       { href: '/docs/rate-limiting', label: 'Rate Limiting' },
       { href: '/docs/security', label: 'Security' },
       { href: '/docs/metadata-routes', label: 'Metadata Routes' },
diff --git a/website/app/docs/rate-limiting/page.ts b/website/app/docs/rate-limiting/page.ts
index bc62e7e0d..679449eaa 100644
--- a/website/app/docs/rate-limiting/page.ts
+++ b/website/app/docs/rate-limiting/page.ts
@@ -111,7 +111,7 @@ REDIS_URL=redis://localhost:6379
`; } diff --git a/website/app/docs/security/page.ts b/website/app/docs/security/page.ts index be2cdbd23..d178445b1 100644 --- a/website/app/docs/security/page.ts +++ b/website/app/docs/security/page.ts @@ -73,7 +73,7 @@ export default function Security() {

Cross-origin vendor modules (resolved from jspm.io) carry a standard SRI integrity hash so a swapped or compromised CDN response cannot execute unverified. This now applies on both paths: a pinned app (webjs vendor pin) ships the hashes in its committed importmap, and an un-pinned app computes them live at warmup. SRI computation is fail-open: a CDN fetch failure during the live path skips that one hash with a warning rather than taking the app down. For reproducible hashes and zero warmup fetches, pin. See No-Build Model.

Sessions and secret management

-

Session cookies are signed, so set a strong AUTH_SECRET (and SESSION_SECRET where used), 32 or more random characters, in production. Keep all secrets server-only: any process.env name WITHOUT the WEBJS_PUBLIC_ prefix never reaches the browser (reading process.env.DATABASE_URL from a component returns undefined, the same as a typo). The prefix is fail-closed, so a secret cannot leak by accident. Prefer your platform's secret injection over a committed .env file. See Sessions and Auth.

+

Session cookies are signed, so set a strong AUTH_SECRET (and SESSION_SECRET where used), 32 or more random characters, in production. Keep all secrets server-only: any process.env name WITHOUT the WEBJS_PUBLIC_ prefix never reaches the browser (reading process.env.DATABASE_URL from a component returns undefined, the same as a typo). The prefix is fail-closed, so a secret cannot leak by accident. Prefer your platform's secret injection over a committed .env file. See Sessions and Auth providers (createAuth).

Rate limiting

Protect auth endpoints and other abuse-prone routes with the rateLimit({ window, max }) middleware, placed at any route level (it applies to that subtree). Behind a reverse proxy or CDN, set trustProxy: true so it keys on the forwarded client IP, and make sure the proxy strips an inbound X-Forwarded-For before adding its own. See Rate Limiting.

diff --git a/website/app/docs/sessions/page.ts b/website/app/docs/sessions/page.ts index 5ff357fcf..e043e36b2 100644 --- a/website/app/docs/sessions/page.ts +++ b/website/app/docs/sessions/page.ts @@ -152,7 +152,7 @@ const message = s.get('success'); // 'Post published!', only this request

Next Steps

`; diff --git a/website/app/docs/typescript/page.ts b/website/app/docs/typescript/page.ts index 1d2f371c4..5966ab693 100644 --- a/website/app/docs/typescript/page.ts +++ b/website/app/docs/typescript/page.ts @@ -201,7 +201,7 @@ events[0].createdAt.toLocaleDateString(); // works 
const { auth } = createAuth<AppUser>({ secret, providers });
 const session = await auth();
 session?.user.role; // typed, no cast
-

Un-augmented and un-parameterised, AuthUser is empty and resolves back to Record<string, unknown>, so pre-existing untyped code keeps compiling. The declared fields should mirror what the callbacks write onto session.user. See Auth.

+

Un-augmented and un-parameterised, AuthUser is empty and resolves back to Record<string, unknown>, so pre-existing untyped code keeps compiling. The declared fields should mirror what the callbacks write onto session.user. See Auth providers (createAuth).

JSDoc Alternative

If you prefer .js files, you can achieve the same type safety using JSDoc annotations with checkJs: true in your tsconfig:

diff --git a/website/test/ssr/docs-links.test.ts b/website/test/ssr/docs-links.test.ts index 4fac24bfc..d22e0a2e7 100644 --- a/website/test/ssr/docs-links.test.ts +++ b/website/test/ssr/docs-links.test.ts @@ -125,6 +125,75 @@ test('every doc page on disk is reachable from the sidebar', async () => { ); }); +test('no two doc pages declare the same metadata title', async () => { + // Two pages sharing a title compete for the same query on the domain the + // #1098 migration exists to consolidate authority onto, and a reader + // arriving from search cannot tell which one answers their question. That + // is exactly what /docs/auth and /docs/authentication did: both declared + // 'Authentication | WebJs', both rendered

Authentication

, and + // their opening paragraphs contradicted each other about whether WebJs + // ships auth at all. The sitemap and llms.txt enumerate topics from disk, + // so both were submitted to search engines as identically-titled entries. + const byTitle = new Map(); + const pages: string[] = []; + const unparsed: string[] = []; + + for (const d of await readdir(DOCS_ROOT, { withFileTypes: true })) { + if (!d.isDirectory() || d.name.startsWith('.') || d.name.startsWith('_') || d.name.startsWith('[')) continue; + const dir = resolve(DOCS_ROOT, d.name); + const files = await readdir(dir).catch(() => [] as string[]); + const page = files.find((f) => f === 'page.ts' || f === 'page.js'); + if (!page) continue; + pages.push(d.name); + const src = await readFile(resolve(dir, page), 'utf8'); + // `export const metadata = { title: '...' }`, the shape every docs page uses. + // NOT `[^}]*?`: that cannot cross a nested object, so a page growing a + // `jsonLd` or `openGraph` before `title` would silently stop being checked. + const m = src.match(/export\s+const\s+metadata\s*=\s*\{[\s\S]*?\btitle:\s*['"`]([^'"`]+)['"`]/); + if (!m) { unparsed.push(d.name); continue; } + const list = byTitle.get(m[1]) ?? []; + list.push(d.name); + byTitle.set(m[1], list); + } + + // Sanity floor, matching the sibling tests in this file. Without it a parser + // change that yields nothing makes this test pass vacuously, which is the + // failure mode it exists to prevent. + assert.ok(pages.length > 30, `sanity: expected many doc pages, saw ${pages.length}`); + assert.deepEqual(unparsed, [], `these doc pages have a metadata block this test could not parse:\n ${unparsed.join('\n ')}`); + + const collisions = [...byTitle.entries()] + .filter(([, dirs]) => dirs.length > 1) + .map(([title, dirs]) => `${title} <- ${dirs.sort().join(', ')}`); + + assert.deepEqual( + collisions, + [], + `these doc pages share a metadata title, so they compete for the same query:\n ${collisions.join('\n ')}`, + ); +}); + +test('a doc page h1 matches its sidebar label', async () => { + // The pair above also disagreed with their own nav entries ('Auth + // (Providers)' and 'Authentication' over two

Authentication

s), so + // neither entry matched the heading a reader landed on. Scoped to the two + // pages the mismatch was found on rather than all of them, because the rest + // of the docs use a deliberately shorter nav label than their heading. + const layout = await readFile(resolve(DOCS_ROOT, 'layout.ts'), 'utf8'); + const labelFor = (href: string) => { + const m = layout.match(new RegExp(`href:\\s*'${href}',\\s*label:\\s*'([^']+)'`)); + return m?.[1]; + }; + + for (const slug of ['auth', 'authentication']) { + const src = await readFile(resolve(DOCS_ROOT, slug, 'page.ts'), 'utf8').catch( + () => readFile(resolve(DOCS_ROOT, slug, 'page.js'), 'utf8'), + ); + const h1 = src.match(/

([^<]+)<\/h1>/)?.[1]; + assert.equal(h1, labelFor(`/docs/${slug}`), `/docs/${slug}:

and sidebar label must agree`); + } +}); + test('the llms.txt index follows the sidebar order', async () => { // The order used to be a hand-copied list that had already drifted from the // sidebar, so the AI-facing index put Runtime and Security in an