From 54fa54212395587450ef719738f2376e8567736f Mon Sep 17 00:00:00 2001 From: Brandon Corbett Date: Mon, 20 Jul 2026 22:05:15 -0400 Subject: [PATCH] docs: pre-release documentation and metadata sweep Correct the release-notes summary for the adapter usage docs changeset, which still listed the removed issuer option and would have told adopters to add and remove issuer in the same release. Fix the requireRole JSDoc example, which called requireAuth() with no arguments (does not compile, throws at construction), left its code fence unclosed, and carried a stray comment marker. In the README, align the Quick Start startup log with its listen port, add the resolveClientIp option to the createSeamlessAuthServer options block, and reference the real webAuthn/login/finish route in the end-to-end flow. Declare keywords on both packages for npm discoverability. --- .changeset/adapter-usage-docs.md | 2 +- .changeset/pre-release-doc-sweep.md | 6 ++++++ packages/core/package.json | 8 ++++++++ packages/express/README.md | 5 +++-- packages/express/package.json | 10 ++++++++++ packages/express/src/middleware/requireRole.ts | 11 +++++++---- 6 files changed, 35 insertions(+), 7 deletions(-) create mode 100644 .changeset/pre-release-doc-sweep.md diff --git a/.changeset/adapter-usage-docs.md b/.changeset/adapter-usage-docs.md index 5e2509d..fd1d22f 100644 --- a/.changeset/adapter-usage-docs.md +++ b/.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. diff --git a/.changeset/pre-release-doc-sweep.md b/.changeset/pre-release-doc-sweep.md new file mode 100644 index 0000000..5530c9f --- /dev/null +++ b/.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. diff --git a/packages/core/package.json b/packages/core/package.json index f624bf3..2e67706 100644 --- a/packages/core/package.json +++ b/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, diff --git a/packages/express/README.md b/packages/express/README.md index 5003545..b45e85b 100644 --- a/packages/express/README.md +++ b/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/*` diff --git a/packages/express/package.json b/packages/express/package.json index aabc14d..24a3031 100644 --- a/packages/express/package.json +++ b/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", diff --git a/packages/express/src/middleware/requireRole.ts b/packages/express/src/middleware/requireRole.ts index df1b7fb..758ba35 100644 --- a/packages/express/src/middleware/requireRole.ts +++ b/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 */