rst-auth 0.0.0-stage → 0.2.0

package/docs/installation.md

@@ -0,0 +1,39 @@
+# Installation and integration model
+
+## Requirements and package entries
+
+The package targets Node.js 22 and newer and ships ESM JavaScript plus TypeScript declarations. Install the core package with `npm install rst-auth`. Core imports are `rst-auth` and `rst-auth/testing`.
+
+Express and Zod are optional peers, isolated behind `rst-auth/express` and `rst-auth/zod`:
+
+```sh
+npm install rst-auth express zod
+npm install --save-dev @types/express
+```
+
+Express 4 and 5 are supported by the adapter. The application should use a compatible `@types/express` version when typechecking Express routes.
+
+## Minimal app setup
+
+```ts
+import { createAuth } from "rst-auth";
+import { expressAuth } from "rst-auth/express";
+import { zodAdapter } from "rst-auth/zod";
+
+const auth = createAuth({
+  accessToken: {
+    key: new TextEncoder().encode(config.accessTokenSecret),
+    issuer: "service-name",
+    audience: "service-api",
+  },
+});
+const middleware = expressAuth(auth, { validator: zodAdapter() });
+```
+
+Read secrets in the application's configuration layer and pass them into `createAuth`; the library itself does not read environment variables.
+
+## Database integration model
+
+The application owns user records, unique email constraints, queries, transactions, and user status rules. For repeated password/token work, optionally configure `accounts` with your model and a `findByEmail` callback; this adds `auth.accounts.register()` and `auth.accounts.login()` without choosing your database or routes. The package accepts a `RefreshTokenStore` when refresh support is enabled. Production implementations should store token hashes and make consume/revocation operations atomic and shared across application instances. The example app uses an in-memory user repository and refresh store only to demonstrate the controller boundaries; neither is suitable for deployed state.
+
+Use `rst-auth/testing` to register the refresh-store conformance suite with your test runner. A passing suite does not replace reviewing the backend's transactional and consistency guarantees.

package/docs/middleware.md

@@ -0,0 +1,24 @@
+# Express middleware
+
+Install the Express peer and import the adapter subpath:
+
+```ts
+import { expressAuth, fromAny, fromCookie, fromHeader } from "rst-auth/express";
+
+const middleware = expressAuth(auth);
+app.get("/me", middleware.authenticate(), meController);
+app.delete(
+  "/users/:id",
+  middleware.authenticate(),
+  middleware.authorize({ roles: ["admin"] }),
+  deleteUserController,
+);
+```
+
+The default extractor strictly parses `Authorization: Bearer <token>`. `getToken` can be a synchronous or asynchronous extractor; helpers include `fromHeader()`, `fromCookie(name)`, and `fromAny([...])`. There is intentionally no built-in query-string extractor because URLs often enter logs, browser history, and referrers.
+
+`authenticate({ required: false })` continues without `req.auth` when no token is present. A present malformed, invalid, expired, or revoked token still fails with 401. `authorize({ roles })` returns 401 when there is no authenticated request and 403 when role data is missing or does not match. Role claims can be stale; the optional `lookupIdentity(claims, req)` hook can load current app-specific identity data. No user lookup happens automatically.
+
+`isRevoked` receives the Express request as its context when verification goes through this middleware. The adapter catches its own asynchronous failures on Express 4 and 5. Application controllers remain responsible for their own async error forwarding (Express 4 does not forward returned rejected promises automatically).
+
+There is no `onExpired` grace hook. Letting an expired access token through during a grace window weakens the configured expiry boundary; clients should refresh through the application's refresh flow instead.

package/docs/migration.md

@@ -0,0 +1,17 @@
+# Migration notes
+
+## From stateless refresh JWTs
+
+Stateless re-issuance does not invalidate the presented token. To use this package's rotation and reuse detection, configure a persistent `RefreshTokenStore` with atomic consume before enabling refresh support. Existing JWT refresh credentials cannot be imported as active opaque-token families. Plan a session cutover: require users to authenticate again or maintain a separately designed transition window, then remove old verification after it expires. Do not label stateless re-issuance as rotation.
+
+## From application-owned access JWTs
+
+Map the current subject and authorization data into `generateAccessToken` claims while respecting reserved names. Configure issuer, audience, lifetime, and a pinned algorithm allowlist to match intended consumers. Review key format and key rotation before switching. The library uses `token_use: "access"`; old tokens without that claim will not verify as access tokens.
+
+## From another password-hash format
+
+This version supports bcryptjs only. Keep existing verification in your application during a staged migration if needed, then rehash after a successful verification. Do not downgrade a hash or silently accept bcrypt inputs above its 72-byte boundary. Plan password resets where a safe migration is not possible.
+
+## HTTP middleware
+
+The default source is strict `Authorization: Bearer`. If the old app used cookies or another source, configure `getToken` explicitly and add CSRF protection when using browser cookies. Validation now returns parsed data through `req.validated`; update controllers to read that property rather than expecting request fields to be replaced.

package/docs/passwords.md

@@ -0,0 +1,23 @@
+# Password utilities
+
+The package uses `bcryptjs`; it does not silently switch to another password hash. `auth.password.hash(password)` and `verify(password, hash)` validate inputs. Bcrypt only uses 72 input bytes, so this API rejects longer UTF-8 password inputs rather than allowing truncation. Malformed hashes fail safely.
+
+```ts
+const hash = await auth.password.hash(password);
+const valid = await auth.password.verify(password, hash);
+```
+
+Do not return or log hashes. When a login identifier has no matching user, `verifyDummy(password)` compares against a process-local dummy hash so the unknown-user path does password-hash work too:
+
+```ts
+const user = await users.findByEmail(email);
+if (!user) {
+  await auth.password.verifyDummy(password);
+  throw new AuthError("UNAUTHORIZED", "Invalid email or password");
+}
+if (!(await auth.password.verify(password, user.passwordHash))) {
+  throw new AuthError("UNAUTHORIZED", "Invalid email or password");
+}
+```
+
+This helps reduce timing differences; it is not a rate limiter and does not guarantee identical response timing. The default work factor is 12. Higher factors increase offline-guessing cost and CPU time for each operation, including synchronous dummy-hash setup in `createAuth()`. Benchmark a value on production-like hardware and tune capacity controls in the application.

package/docs/refresh-tokens.md

@@ -0,0 +1,47 @@
+# Refresh-token architecture
+
+Refresh tokens are opaque bearer secrets, not JWTs. `auth.refresh.issue()` creates 32 random bytes with Node's `crypto.randomBytes()` and returns their base64url encoding. The configured store receives only the SHA-256 hash, never the raw token. A database leak therefore does not directly reveal usable refresh tokens.
+
+Refresh support is opt-in. Configure `refreshToken.store`, `refreshToken.refreshTokenTtl`, and `refreshToken.absoluteLifetime` when calling `createAuth()`. If no refresh configuration is supplied, `auth.refresh` is absent. A partial configuration or missing store fails validation; the library never pretends stateless token re-issuance is rotation.
+
+## Rotation and lifetimes
+
+Each issue starts a family with an absolute expiry. Rotation atomically consumes the presented token, then creates a replacement in that same family. The replacement's idle expiry is `min(now + refreshTokenTtl, family absolute expiry)`. Rotation cannot extend the family past `absoluteLifetime`.
+
+The refresh service returns a rotated refresh token, its subject and family metadata. It does not mint an access token pair: application code can use the returned subject and its own current identity/authorization data to call `auth.tokens.generateAccessToken()`. Unknown, expired, revoked, or reused tokens raise an `AuthError` and never produce a replacement token.
+
+Presenting a previously consumed token reports `REFRESH_TOKEN_REUSED` and revokes every token in that family. `revoke(token)` revokes one active token. `revokeFamily(familyId)` revokes a family, and `revokeAllForSubject(subject)` revokes all of that subject's refresh tokens.
+
+## Store contract and atomicity
+
+Implement `RefreshTokenStore` with `create`, `consume`, `revokeToken`, `revokeFamily`, and `revokeAllForSubject`. Store records contain the SHA-256 token hash, family ID, subject, timestamps, and status. `consume(hash, now)` returns a discriminated result: `ok`, `not_found`, `expired`, `revoked`, or `reused`.
+
+`consume` must be an atomic compare-and-swap. Exactly one concurrent call for an active token may return `ok`; a later or concurrent loser must observe the consumed state, report reuse, and revoke the family. A read-then-write implementation without a transaction, conditional update, or equivalent atomic primitive cannot provide this guarantee and must not claim reuse protection. Backends must also make family and subject revocation cover all currently stored members of those scopes.
+
+Stores must preserve revoked-family tombstones through the family's absolute expiry and make `create` refuse to add a successor to a revoked family. Otherwise a rotation already in progress could create a usable child after a concurrent replay revoked the family. Concurrent refresh attempts can therefore both fail: one detects reuse, and the other is prevented from creating a successor after family revocation.
+
+The `rst-auth/testing` subpath exports `registerRefreshTokenStoreConformanceTests()`. Register the suite with your test runner and provide a factory for a fresh store. It checks rotation behavior, replay and family revocation, expiry, explicit revocation, and concurrent consume. The suite exercises the contract but does not prove a distributed backend's atomicity under every deployment or failure mode; review the backend's transaction/consistency guarantees as well.
+
+## Memory store
+
+`MemoryRefreshTokenStore` is only for tests and local examples. It provides atomic consume within one JavaScript process by changing state before its async method yields. It is not safe across processes, restarts, or multiple application instances. Use a persistent store with an atomic consume operation for deployed services.
+
+## Example
+
+```ts
+import { createAuth, MemoryRefreshTokenStore } from "rst-auth";
+
+const auth = createAuth({
+  accessToken: { key: new TextEncoder().encode(process.env.ACCESS_TOKEN_KEY!) },
+  refreshToken: {
+    store: new MemoryRefreshTokenStore(), // local example only
+    refreshTokenTtl: 60 * 60 * 24 * 7,
+    absoluteLifetime: 60 * 60 * 24 * 30,
+  },
+});
+
+const refresh = await auth.refresh!.issue({ subject: "user-123" });
+const access = await auth.tokens.generateAccessToken({ sub: refresh.subject });
+```
+
+The sample reads the secret in application configuration; the library itself never reads `process.env`. A production application should inject a persistent store and keep raw refresh tokens out of logs and persistent records.

package/docs/security.md

@@ -0,0 +1,16 @@
+# Security responsibilities
+
+This package supplies auth primitives; it does not replace application security controls or an independent security review. Keep dependencies current, protect signing keys, avoid logging credentials/tokens/hashes, validate inputs, and review the threat model of the deployed refresh store.
+
+The application remains responsible for:
+
+- **CORS:** allow only required origins and methods. CORS is not authentication and is not a CSRF defense by itself.
+- **Rate limiting:** limit login, signup, refresh, password reset, and other sensitive endpoints by appropriate identifiers and network context.
+- **CSRF:** browser cookies are attached automatically in some cross-site contexts. Use CSRF defenses appropriate to the routes and cookie policy; SameSite helps but is not a universal replacement. See [cookies versus Bearer](cookies-vs-bearer.md).
+- **Account lockout and abuse policy:** define throttling, lockout, recovery, and monitoring without creating trivial denial-of-service paths.
+- **Password reset:** design single-use, expiring, securely stored reset credentials and account notification yourself.
+- **Email verification, account status, user lookup, and current permissions:** a signed token alone does not show that an account remains active or current.
+- **Signing key lifecycle, backup, rotation, and deployment secret access.**
+- **Refresh persistence:** provide a shared store whose consume and family revocation operations are atomic for your database/consistency model. Memory store is test/local only.
+
+`isRevoked` can provide access-token denylist/session checks, at the cost of making verification stateful and dependent on that check. A valid JWT without current lookup may outlive a deleted or disabled user until its expiry. Choose access-token lifetime and current authorization checks accordingly.

package/docs/validation.md

@@ -0,0 +1,24 @@
+# Request validation
+
+The Express adapter accepts a framework-independent `ValidatorAdapter`. `rst-auth/zod` provides `zodAdapter()` and supports async Zod parsing. Apps can implement the same small interface for another validator.
+
+```ts
+const middleware = expressAuth(auth, { validator: zodAdapter() });
+app.post(
+  "/users/:id",
+  middleware.validate({
+    body: bodySchema,
+    params: paramsSchema,
+    query: querySchema,
+  }),
+  (req, res) => {
+    const body = req.validated?.body;
+    const params = req.validated?.params;
+    res.json({ body, params });
+  },
+);
+```
+
+Only configured targets are parsed. Parsed data is assigned to `req.validated.body`, `.params`, and `.query`; source request properties are not replaced. This is important for Express 5, whose `req.query` is a getter. A validation failure becomes `VALIDATION_ERROR` (HTTP 400) by default. Provide `formatError` on the validation schema options for target-specific mapping, or configure the Express `errorFormatter` for the public response shape. Formatters should emit only information safe for clients.
+
+Zod output types are inferred by Zod itself. For a schema-specific request view, the Express subpath exports `ValidatedRequest<TSchemas>`; global request augmentation stays broad so different routes can use different schemas.

package/package.json

@@ -1,6 +1,93 @@
 {
   "name": "rst-auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "A modular authentication toolkit for Node.js applications",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "CODE_OF_CONDUCT.md",
+    "SECURITY.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./express": {
+      "types": "./dist/express/index.d.ts",
+      "import": "./dist/express/index.js"
+    },
+    "./zod": {
+      "types": "./dist/zod/index.d.ts",
+      "import": "./dist/zod/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@types/express": ">=4.17.21 <6",
+    "express": ">=4.18 <6",
+    "zod": ">=3.22 <5"
+  },
+  "peerDependenciesMeta": {
+    "@types/express": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
+    "zod": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "format:check": "prettier --check .",
+    "example:install": "node scripts/install-example.mjs"
+  },
+  "dependencies": {
+    "bcryptjs": "^3.0.2",
+    "jose": "^6.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/bcryptjs": "^2.4.6",
+    "@types/express": "^5.0.6",
+    "@types/node": "^24.10.0",
+    "@types/supertest": "^7.2.1",
+    "eslint": "^10.12.0",
+    "express": "^5.3.0",
+    "express4": "npm:express@^4.21.2",
+    "globals": "^16.5.0",
+    "prettier": "^3.6.2",
+    "supertest": "^7.3.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.0",
+    "vitest": "^5.0.5",
+    "zod": "^4.6.5"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sayedrisat/rst-auth.git"
+  },
+  "homepage": "https://sayedrisat.github.io/rst-auth/",
+  "bugs": {
+    "url": "https://github.com/sayedrisat/rst-auth/issues"
+  }
+}