docs: pre-release documentation and metadata sweep

.changeset/adapter-usage-docs.md

@@ -2,4 +2,4 @@
 "@seamless-auth/express": patch
 ---
 
-Correct the adapter usage docs. The README Quick Start now passes every required option (`cookieSecret`, `serviceSecret`, `issuer`, `audience`) and calls `requireAuth({ cookieSecret })`, so the copy-paste example runs. The Environment Variables table, which listed variables the adapter never reads (including unrelated database settings), is replaced with a configuration section stating that all settings are passed as options. The `requireAuth` JSDoc no longer claims the guard performs token refresh or documents a positional signature it does not accept, and its duplicated options interface is removed.
+Correct the adapter usage docs. The README Quick Start now passes every required option (`authServerUrl`, `cookieSecret`, `serviceSecret`, `audience`) and calls `requireAuth({ cookieSecret })`, so the copy-paste example runs. The Environment Variables table, which listed variables the adapter never reads (including unrelated database settings), is replaced with a configuration section stating that all settings are passed as options. The `requireAuth` JSDoc no longer claims the guard performs token refresh or documents a positional signature it does not accept, and its duplicated options interface is removed.

.changeset/pre-release-doc-sweep.md

@@ -0,0 +1,6 @@
+---
+"@seamless-auth/core": patch
+"@seamless-auth/express": patch
+---
+
+Pre-release documentation and metadata corrections. The `requireRole` JSDoc example no longer calls `requireAuth()` with no arguments (which does not compile and throws), its malformed code fence is closed, and it now shares a constructed guard. The README Quick Start startup log matches its listen port, the `createSeamlessAuthServer` options block lists the `resolveClientIp` option, and the end-to-end flow references the real `webAuthn/login/finish` route. Both packages now declare `keywords` for npm discoverability.

packages/core/package.json

@@ -2,6 +2,14 @@
     "name": "@seamless-auth/core",
     "version": "0.7.0",
     "description": "Framework-agnostic core authentication logic for SeamlessAuth",
+    "keywords": [
+        "authentication",
+        "passwordless",
+        "webauthn",
+        "passkeys",
+        "jwt",
+        "seamless-auth"
+    ],
     "license": "AGPL-3.0-only",
     "author": "Fells Code, LLC",
     "sideEffects": false,

packages/express/README.md

@@ -84,7 +84,7 @@ app.get("/admin", requireRole("admin"), (req, res) => {
   res.json({ message: "Welcome admin!" });
 });
 
-app.listen(5000, () => console.log("API running on http://localhost:3000"));
+app.listen(5000, () => console.log("API running on http://localhost:5000"));
 ```
 
 ---
@@ -196,6 +196,7 @@ generate routes instead.
   cookieDomain?: string;  // optional (defaults to host)
   cookieSecure?: boolean;  // optional (defaults to true)
   cookieSameSite?: "lax" | "none" | "strict";  // optional
+  resolveClientIp?: (req) => string | undefined;  // optional (see Client IP forwarding)
   accessCookieName?: string;
   registrationCookieName?: string;
   refreshCookieName?: string;
@@ -560,7 +561,7 @@ This does not affect the `sub` claim inside JWT payloads, which is unchanged.
 1. **Frontend** → `/auth/login`
    API proxies request and sets a short-lived _pre-auth_ cookie.
 
-2. **Frontend** → `/auth/webAuthn/finish`  
+2. **Frontend** → `/auth/webAuthn/login/finish`  
    API verifies response and sets a signed access cookie.
 
 3. **API routes** → `/api/*`  

packages/express/package.json

@@ -2,6 +2,16 @@
   "name": "@seamless-auth/express",
   "version": "0.8.0",
   "description": "Express adapter for Seamless Auth passwordless authentication",
+  "keywords": [
+    "authentication",
+    "passwordless",
+    "express",
+    "webauthn",
+    "passkeys",
+    "session",
+    "cookies",
+    "seamless-auth"
+  ],
   "license": "AGPL-3.0-only",
   "type": "module",
   "main": "dist/index.js",

packages/express/src/middleware/requireRole.ts

@@ -4,7 +4,7 @@ import { Request, Response, NextFunction, RequestHandler } from "express";
 /**
  * Express middleware that enforces role-based authorization for Seamless Auth.
  *
- * This middleware assumes `requireAuth()` has already:
+ * This middleware assumes `requireAuth` has already:
  * - authenticated the request
  * - populated `req.user` with the authenticated session payload
  *
@@ -17,11 +17,13 @@ import { Request, Response, NextFunction, RequestHandler } from "express";
  * `:write` role grants `:read` access.
  * Otherwise, a 403 Forbidden response is returned.
  *
- *  * ### Example
+ * ### Example
  * ```ts
+ * const guard = requireAuth({ cookieSecret: process.env.COOKIE_SECRET! });
+ *
  * // Require a single role
  * app.get("/admin/users",
- *   requireAuth(),
+ *   guard,
  *   requireRole("admin"),
  *   (req, res) => {
  *     res.send("Welcome admin!");
@@ -30,10 +32,11 @@ import { Request, Response, NextFunction, RequestHandler } from "express";
  *
  * // Allow any of multiple roles
  * app.post("/settings",
- *   requireAuth(),
+ *   guard,
  *   requireRole(["admin", "supervisor"]),
  *   updateSettingsHandler
  * );
+ * ```
  *
  * @param requiredRoles - A role or list of roles required to access the route
  */