rst-auth 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+Notable changes to rst-auth are recorded here.
+
+## Unreleased
+
+- Added a standalone HTML/CSS/JavaScript documentation site and GitHub Pages deployment workflow.
+- Added a browser-based auth flow demo to the Express example.
+- Added a TypeScript Express API example that is installed from an npm pack tarball.
+- Added usage, security, migration, contribution, reporting, and first-release documentation.
+- Added Node 22/24 CI checks and example integration tests.
+
+## 0.1.0 - 2026-10-16
+
+- Initial alpha API for password hashing, access tokens, and opaque refresh-token rotation.
+- Added Express 4/5 and Zod subpath adapters plus refresh-store conformance utilities.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,73 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people.
+- Being respectful of differing opinions, viewpoints, and experiences.
+- Giving and gracefully accepting constructive feedback.
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience.
+- Focusing on what is best not just for us as individuals, but for the overall community.
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information, such as a physical or email address, without their explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a professional setting.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples include using an official project email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at the private contact route listed in the repository's `SECURITY.md` or repository moderation settings. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces, as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+Thanks for helping improve rst-auth. The project is alpha software and prioritizes clear security boundaries, small APIs, and honest documentation.
+
+## Before opening a change
+
+- Read the relevant design and security documentation in `docs/` before changing behavior.
+- Keep user models, DB queries, routes, controllers, and business rules in the application layer.
+- Do not add real credentials, publish packages, or push directly to the upstream default branch. Use a fork and pull request; do not claim production readiness.
+- Every security or feature claim in README must map to a named test in `docs/claims.md`.
+- Never accept a client-supplied privilege or role during signup.
+
+## Development checks
+
+Use Node 22 or 24 and npm. From the repository root run:
+
+```sh
+npm ci
+npm run build
+npm test
+npm run lint
+npm run typecheck
+npm run format:check
+npm pack --dry-run
+npm run example:install
+npm --prefix examples/express-api run typecheck
+npm --prefix examples/express-api test
+npm --prefix examples/express-api run import-check
+```
+
+The example install command packs this project and installs the generated tarball into the example. Do not change the example to import source files from `src/`.
+
+## Pull requests
+
+Explain the user-visible behavior, security consequences, tests, docs, and compatibility impact. Include focused tests for bug fixes and new claims. Keep PRs small enough to review. Maintainers may request changes or decline work outside the project scope. By contributing, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sayed Risat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,213 @@
-# Temporary Holding Version
+# RST-Auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**[Documentation site](https://sayedrisat.github.io/rst-auth/)** · [GitHub repository](https://github.com/sayedrisat/rst-auth)
+
+**Complex authentication. Simple methods. Full control. Open source.**
+
+## Overview
+
+`RST-Auth` is an alpha TypeScript toolkit for Node.js 22+ applications. It provides password hashing, access tokens, stateful refresh-token rotation, and optional Express and Zod adapters. Your application owns its users, database, routes, business rules, and responses.
+
+## Problem
+
+Authentication code is easy to get subtly wrong, while full authentication frameworks may own user models, database tables, and application flows. This package focuses on reusable security mechanics and leaves application-specific decisions with the developer.
+
+## Features
+
+- `bcryptjs` password hashing, 72-byte input checks, and dummy verification.
+- `jose` access tokens with configured algorithms, issuer/audience checks, key resolution, and optional revocation lookup.
+- Opaque refresh tokens with atomic store consumption, rotation, family revocation, and reuse detection.
+- Express 4 and 5 authentication, role authorization, validation, and safe error middleware.
+- Zod adapter and a framework-agnostic refresh-store conformance suite.
+- Injected configuration; the library does not read `process.env`.
+
+Feature and security claims are mapped to named tests in [docs/claims.md](docs/claims.md).
+
+## Security philosophy
+
+The library handles reusable primitives and validates configuration. The application decides who a user is, what a role means, where data is stored, how sessions are delivered, and which HTTP response to return. Tokens are secrets: keep them out of logs and URLs. A valid access token does not establish that its subject still exists or remains enabled, and token-carried roles may be stale.
+
+## Install
+
+```sh
+npm install rst-auth
+```
+
+Core password, token, and refresh APIs need no framework peer. For the optional integrations, install the peers you use:
+
+```sh
+npm install express zod
+npm install --save-dev @types/express
+```
+
+See [installation](docs/installation.md) for Node and package details.
+
+## Minimal setup
+
+Configuration belongs in your application's config layer. Never commit a real signing secret.
+
+```ts
+import { createAuth } from "rst-auth";
+
+const secret = process.env.ACCESS_TOKEN_SECRET;
+if (!secret || Buffer.byteLength(secret, "utf8") < 32) {
+  throw new Error("Set ACCESS_TOKEN_SECRET to at least 32 bytes");
+}
+
+const auth = createAuth({
+  accessToken: {
+    key: new TextEncoder().encode(secret),
+    issuer: "my-service",
+    audience: "my-api",
+  },
+});
+```
+
+## Passwords
+
+```ts
+const passwordHash = await auth.password.hash(password);
+const matches = await auth.password.verify(password, passwordHash);
+
+// When no user exists, do a dummy comparison before returning the same login error.
+if (!user) await auth.password.verifyDummy(password);
+```
+
+Passwords above 72 UTF-8 bytes are rejected because bcrypt truncates longer inputs. The default work factor is 12; benchmark it on the deployment hardware because hashing and `createAuth()` startup work increase with the setting. See [passwords](docs/passwords.md).
+
+## Access tokens
+
+```ts
+const token = await auth.tokens.generateAccessToken({
+  sub: user.id,
+  role: user.role,
+});
+const verifiedClaims = await auth.tokens.verifyAccessToken(token);
+```
+
+The verifier uses the configured algorithm allowlist and validates signature, expiry, issuer/audience when configured, required claims, and token type. See [access tokens](docs/access-tokens.md).
+
+## Refresh tokens
+
+Refresh support requires a store. The built-in `MemoryRefreshTokenStore` is for tests and local demonstrations only; it is not a production persistence option.
+
+```ts
+import { createAuth, MemoryRefreshTokenStore } from "rst-auth";
+
+const auth = createAuth({
+  accessToken: { key: new TextEncoder().encode(secret) },
+  refreshToken: {
+    store: new MemoryRefreshTokenStore(), // Use a shared persistent store in deployed services.
+    refreshTokenTtl: 60 * 60 * 24 * 7,
+    absoluteLifetime: 60 * 60 * 24 * 30,
+  },
+});
+
+const issued = await auth.refresh!.issue({ subject: user.id });
+const next = await auth.refresh!.rotate(issued.refreshToken);
+```
+
+The application creates an access token from the returned subject and its current user/permission data. Rotation consumes a stored hash atomically; presenting a consumed token revokes its family. Read [refresh tokens](docs/refresh-tokens.md) before implementing a store.
+
+## Express middleware
+
+```ts
+import { expressAuth } from "rst-auth/express";
+
+const middleware = expressAuth(auth);
+app.get("/profile", middleware.authenticate(), profileController);
+app.delete(
+  "/admin/users/:id",
+  middleware.authenticate(),
+  middleware.authorize({ roles: ["admin"] }),
+  deleteUserController,
+);
+```
+
+Authentication defaults to strict `Authorization: Bearer` parsing. Optional auth is available with `authenticate({ required: false })`; a present invalid token still fails. See [middleware](docs/middleware.md).
+
+## Validation
+
+```ts
+import { expressAuth } from "rst-auth/express";
+import { zodAdapter } from "rst-auth/zod";
+
+const middleware = expressAuth(auth, { validator: zodAdapter() });
+app.post(
+  "/items",
+  middleware.validate({ body: itemSchema }),
+  createItemController,
+);
+```
+
+Parsed values are placed on `req.validated`; `req.body`, `req.params`, and `req.query` are not silently replaced. See [validation](docs/validation.md).
+
+## Errors
+
+`AuthError` exposes a stable code, developer message, safe public message, status, and optional cause. The Express error handler emits only safe fields by default; an application may provide a formatter. See [error handling](docs/error-handling.md).
+
+## Configuration reference
+
+| Setting                            | Purpose                        | Default / constraint                                                                 |
+| ---------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------ |
+| `mode`                             | Runtime validation profile     | `development`; `production` requires issuer and audience and access expiry <= 1 hour |
+| `password.workFactor`              | bcrypt cost                    | `12`, integer 4–31                                                                   |
+| `accessToken.key`                  | Signing key                    | Required; HMAC keys need at least 32 bytes                                           |
+| `accessToken.algorithm`            | Signing algorithm              | `HS256`; supported JOSE algorithms are explicitly listed in config types             |
+| `accessToken.algorithms`           | Verification allowlist         | Signing algorithm by default; must contain it                                        |
+| `accessToken.issuer`, `audience`   | JWT issuer/audience checks     | Optional outside production                                                          |
+| `accessToken.expiresInSeconds`     | Access-token lifetime          | `900` seconds                                                                        |
+| `accessToken.keyId`, `keyResolver` | Key rotation support           | Optional; resolver requires a `kid`                                                  |
+| `accessToken.requiredClaims`       | Additional required JWT claims | `sub`, `iat`, and `exp` are required automatically                                   |
+| `accessToken.isRevoked`            | Stateful verification check    | Optional; callback latency/availability is part of each verification                 |
+| `refreshToken.store`               | Atomic refresh-token state     | Omit to disable refresh support                                                      |
+| `refreshToken.refreshTokenTtl`     | Idle refresh expiry            | Required when refresh is enabled, in seconds                                         |
+| `refreshToken.absoluteLifetime`    | Family lifetime cap            | Required when refresh is enabled, in seconds                                         |
+
+See [configuration](docs/configuration.md) for validation details and asymmetric-key examples.
+
+## TypeScript
+
+The package ships declarations and strict public types. `req.auth` and `req.validated` are augmented when the Express subpath is imported. For schema-specific parsed values, use the exported `ValidatedRequest<TSchemas>` type. Install `@types/express` when using the Express integration.
+
+## Database integration model
+
+The toolkit does not create a user table or issue database queries. Your repository/controller code stores password hashes and looks up users. Refresh support uses the `RefreshTokenStore` interface; implement it with your own persistence and atomic compare-and-swap operation, then run the `rst-auth/testing` conformance suite against it. See [installation](docs/installation.md#database-integration-model) and [refresh tokens](docs/refresh-tokens.md).
+
+## Limitations
+
+This is alpha software, not a security audit or a complete identity system. It does not provide a production refresh store, user/session database, OAuth, MFA, account lockout, password reset, email verification, CORS policy, rate limiting, or CSRF protection. The memory refresh store is process-local. A token's roles can be stale unless the app performs current identity/permission checks. See [security](docs/security.md).
+
+## Testing
+
+```sh
+npm ci
+npm run build
+npm test
+npm run lint
+npm run typecheck
+npm run format:check
+npm pack --dry-run
+npm run example:install
+npm --prefix examples/express-api run typecheck
+npm --prefix examples/express-api test
+npm --prefix examples/express-api run import-check
+```
+
+The example installer creates a package tarball and installs that tarball into the example; it does not import source files from this repository. CI checks Node 22 and 24.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md), keep every documented security/feature claim connected to a test, and run all quality gates before proposing changes. The project follows the [Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities using [SECURITY.md](SECURITY.md), not a public issue.
+
+## License
+
+MIT; Copyright (c) 2026 Sayed Risat. See [LICENSE](LICENSE).
+
+## Project status
+
+Version `0.1.0` is an alpha under active development. Public API names, policies, and docs may change before a stable release. No production-readiness claim is made.
+
+## Comparison
+
+This is a README-level comparison based on this project's checked-in competitive review, not an independent source audit. The reviewed JWT utility examples generally describe issuing new stateless JWTs on refresh without documented stored-token reuse detection; this package instead requires server-side refresh state and atomic consume for rotation. Broader authentication frameworks may manage schemas and migrations; this package leaves database schema and queries to the application. `express-jwt` focuses on middleware rather than passwords, refresh rotation, or validation. The reviewed analysis did not verify every package in the market, so these points describe only that review's scope and are not universal claims.

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security policy
+
+## Supported versions
+
+Security reports are accepted for the current alpha release line. Alpha software may change without a migration path and has not received an independent security audit.
+
+## Reporting a vulnerability privately
+
+Please do not open a public issue or pull request for a suspected vulnerability. If GitHub private vulnerability reporting is enabled for this repository, use **Security → Report a vulnerability** to submit a private advisory. If it is not enabled, contact the maintainers through the repository's private contact channel and ask them to provide a secure reporting route; do not include exploit details in a public issue.
+
+Include the affected version/commit, impact, reproduction steps, and any suggested mitigation. Do not include real user data, tokens, or production secrets. The maintainers will acknowledge receipt and coordinate a fix and disclosure timeline with the reporter.
+
+Before the first public release, maintainers must enable and verify a private reporting route in the repository settings.

package/dist/config.d.ts

@@ -0,0 +1,59 @@
+import type { CompactJWSHeaderParameters, KeyInput } from "jose";
+import type { RefreshTokenStore } from "./refresh-store.js";
+export declare const DEFAULT_BCRYPT_ROUNDS = 12;
+export declare const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 900;
+export declare const SUPPORTED_ALGORITHMS: readonly ["HS256", "HS384", "HS512", "RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+export type SupportedAlgorithm = (typeof SUPPORTED_ALGORITHMS)[number];
+export type RuntimeMode = "development" | "production";
+export type TokenKey = KeyInput;
+export type KeyResolver = (header: CompactJWSHeaderParameters) => TokenKey | Promise<TokenKey>;
+export interface AuthConfig {
+    mode?: RuntimeMode;
+    password?: {
+        workFactor?: number;
+    };
+    accessToken: {
+        algorithm?: SupportedAlgorithm;
+        algorithms?: readonly SupportedAlgorithm[];
+        key: TokenKey;
+        keyId?: string;
+        keyResolver?: KeyResolver;
+        issuer?: string;
+        audience?: string | readonly string[];
+        expiresInSeconds?: number;
+        requiredClaims?: readonly string[];
+        isRevoked?: (claims: Readonly<Record<string, unknown>>, context?: unknown) => boolean | Promise<boolean>;
+    };
+    /** Omit to disable refresh-token support. A configured refresh store is mandatory. */
+    refreshToken?: {
+        store: RefreshTokenStore;
+        refreshTokenTtl: number;
+        absoluteLifetime: number;
+    };
+}
+export interface ValidatedAuthConfig {
+    mode: RuntimeMode;
+    password: {
+        workFactor: number;
+    };
+    accessToken: {
+        algorithm: SupportedAlgorithm;
+        algorithms: readonly SupportedAlgorithm[];
+        key: TokenKey;
+        keyId?: string;
+        keyResolver?: KeyResolver;
+        issuer?: string;
+        audience?: string | readonly string[];
+        expiresInSeconds: number;
+        requiredClaims: readonly string[];
+        isRevoked?: AuthConfig["accessToken"]["isRevoked"];
+    };
+    refreshToken?: {
+        store: RefreshTokenStore;
+        refreshTokenTtl: number;
+        absoluteLifetime: number;
+    };
+}
+export declare function isReservedClaim(name: string): boolean;
+export declare function validateAuthConfig(config: AuthConfig): ValidatedAuthConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAEjE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5D,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,gCAAgC,MAAM,CAAC;AAEpD,eAAO,MAAM,oBAAoB,gIAcvB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AACvE,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,YAAY,CAAC;AACvD,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC;AAChC,MAAM,MAAM,WAAW,GAAG,CACxB,MAAM,EAAE,0BAA0B,KAC/B,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;AAElC,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,WAAW,EAAE;QACX,SAAS,CAAC,EAAE,kBAAkB,CAAC;QAC/B,UAAU,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;QAC3C,GAAG,EAAE,QAAQ,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;QACtC,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACnC,SAAS,CAAC,EAAE,CACV,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,CAAC,EAAE,OAAO,KACd,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;KACjC,CAAC;IACF,sFAAsF;IACtF,YAAY,CAAC,EAAE;QACb,KAAK,EAAE,iBAAiB,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IACjC,WAAW,EAAE;QACX,SAAS,EAAE,kBAAkB,CAAC;QAC9B,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;QAC1C,GAAG,EAAE,QAAQ,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,WAAW,CAAC,EAAE,WAAW,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;QACtC,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;QAClC,SAAS,CAAC,EAAE,UAAU,CAAC,aAAa,CAAC,CAAC,WAAW,CAAC,CAAC;KACpD,CAAC;IACF,YAAY,CAAC,EAAE;QACb,KAAK,EAAE,iBAAiB,CAAC;QACzB,eAAe,EAAE,MAAM,CAAC;QACxB,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAYD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAqBD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,UAAU,GAAG,mBAAmB,CAqL1E"}

package/dist/config.js

@@ -0,0 +1,187 @@
+import { AuthError } from "./errors.js";
+export const DEFAULT_BCRYPT_ROUNDS = 12;
+export const DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 900;
+const MAX_REFRESH_LIFETIME_SECONDS = 8_000_000_000_000;
+export const SUPPORTED_ALGORITHMS = [
+    "HS256",
+    "HS384",
+    "HS512",
+    "RS256",
+    "RS384",
+    "RS512",
+    "PS256",
+    "PS384",
+    "PS512",
+    "ES256",
+    "ES384",
+    "ES512",
+    "EdDSA",
+];
+const RESERVED_CLAIMS = new Set([
+    "iss",
+    "aud",
+    "exp",
+    "iat",
+    "nbf",
+    "jti",
+    "token_use",
+]);
+export function isReservedClaim(name) {
+    return RESERVED_CLAIMS.has(name);
+}
+function invalid(message) {
+    throw new AuthError("INVALID_CONFIGURATION", message);
+}
+function validateKey(key, algorithm) {
+    if (algorithm.startsWith("HS")) {
+        if (!(key instanceof Uint8Array) || key.byteLength < 32) {
+            invalid("HMAC access-token keys must be Uint8Array values of at least 32 bytes");
+        }
+        return;
+    }
+    if (key instanceof Uint8Array) {
+        invalid(`${algorithm} requires a CryptoKey or KeyObject, not a byte array`);
+    }
+}
+export function validateAuthConfig(config) {
+    if (!config || typeof config !== "object") {
+        invalid("Configuration must be an object");
+    }
+    const mode = config.mode ?? "development";
+    if (mode !== "development" && mode !== "production") {
+        invalid('mode must be "development" or "production"');
+    }
+    if (config.password !== undefined &&
+        (typeof config.password !== "object" || config.password === null)) {
+        invalid("password must be an object when provided");
+    }
+    const workFactor = config.password?.workFactor ?? DEFAULT_BCRYPT_ROUNDS;
+    if (!Number.isInteger(workFactor) || workFactor < 4 || workFactor > 31) {
+        invalid("password.workFactor must be an integer between 4 and 31");
+    }
+    const tokenConfig = config.accessToken;
+    if (!tokenConfig || typeof tokenConfig !== "object" || !tokenConfig.key) {
+        invalid("accessToken.key is required");
+    }
+    const algorithm = tokenConfig.algorithm ?? "HS256";
+    if (!SUPPORTED_ALGORITHMS.includes(algorithm)) {
+        invalid("accessToken.algorithm is not supported");
+    }
+    const algorithms = [...new Set(tokenConfig.algorithms ?? [algorithm])];
+    if (algorithms.length === 0 ||
+        !algorithms.includes(algorithm) ||
+        algorithms.some((entry) => !SUPPORTED_ALGORITHMS.includes(entry))) {
+        invalid("accessToken.algorithms must be a non-empty allowlist containing the signing algorithm");
+    }
+    validateKey(tokenConfig.key, algorithm);
+    const expiresInSeconds = tokenConfig.expiresInSeconds ?? DEFAULT_ACCESS_TOKEN_TTL_SECONDS;
+    if (!Number.isSafeInteger(expiresInSeconds) || expiresInSeconds <= 0) {
+        invalid("accessToken.expiresInSeconds must be a positive safe integer");
+    }
+    if (tokenConfig.issuer !== undefined &&
+        (typeof tokenConfig.issuer !== "string" || tokenConfig.issuer.length === 0)) {
+        invalid("accessToken.issuer must be a non-empty string when provided");
+    }
+    if (tokenConfig.audience !== undefined) {
+        const audience = tokenConfig.audience;
+        if (!((typeof audience === "string" && audience.length > 0) ||
+            (Array.isArray(audience) &&
+                audience.length > 0 &&
+                audience.every((item) => typeof item === "string" && item.length > 0)))) {
+            invalid("accessToken.audience must contain non-empty string values");
+        }
+    }
+    if (mode === "production") {
+        if (!tokenConfig.issuer || !tokenConfig.audience) {
+            invalid("Production mode requires accessToken.issuer and accessToken.audience");
+        }
+        if (expiresInSeconds > 3600) {
+            invalid("Production access tokens must expire within one hour");
+        }
+    }
+    if (tokenConfig.keyId !== undefined && tokenConfig.keyId.length === 0) {
+        invalid("accessToken.keyId must be non-empty when provided");
+    }
+    if (tokenConfig.keyResolver !== undefined &&
+        typeof tokenConfig.keyResolver !== "function") {
+        invalid("accessToken.keyResolver must be a function");
+    }
+    if (tokenConfig.requiredClaims !== undefined &&
+        !Array.isArray(tokenConfig.requiredClaims)) {
+        invalid("accessToken.requiredClaims must be an array");
+    }
+    if (tokenConfig.isRevoked !== undefined &&
+        typeof tokenConfig.isRevoked !== "function") {
+        invalid("accessToken.isRevoked must be a function");
+    }
+    let refreshToken;
+    if (config.refreshToken !== undefined) {
+        const refreshConfig = config.refreshToken;
+        if (!refreshConfig || typeof refreshConfig !== "object") {
+            invalid("refreshToken must be an object when provided");
+        }
+        const store = refreshConfig.store;
+        if (!store ||
+            typeof store.create !== "function" ||
+            typeof store.consume !== "function" ||
+            typeof store.revokeToken !== "function" ||
+            typeof store.revokeFamily !== "function" ||
+            typeof store.revokeAllForSubject !== "function") {
+            invalid("refreshToken.store must implement the complete RefreshTokenStore interface");
+        }
+        if (!Number.isSafeInteger(refreshConfig.refreshTokenTtl) ||
+            refreshConfig.refreshTokenTtl <= 0 ||
+            refreshConfig.refreshTokenTtl > MAX_REFRESH_LIFETIME_SECONDS) {
+            invalid("refreshToken.refreshTokenTtl must be a positive safe integer in seconds");
+        }
+        if (!Number.isSafeInteger(refreshConfig.absoluteLifetime) ||
+            refreshConfig.absoluteLifetime <= 0 ||
+            refreshConfig.absoluteLifetime > MAX_REFRESH_LIFETIME_SECONDS) {
+            invalid("refreshToken.absoluteLifetime must be a positive safe integer in seconds");
+        }
+        refreshToken = {
+            store,
+            refreshTokenTtl: refreshConfig.refreshTokenTtl,
+            absoluteLifetime: refreshConfig.absoluteLifetime,
+        };
+    }
+    const requiredClaims = [
+        ...new Set([
+            "sub",
+            "iat",
+            "exp",
+            ...(tokenConfig.issuer ? ["iss"] : []),
+            ...(tokenConfig.audience ? ["aud"] : []),
+            ...(tokenConfig.requiredClaims ?? []),
+        ]),
+    ];
+    if (requiredClaims.some((claim) => typeof claim !== "string" || !claim)) {
+        invalid("accessToken.requiredClaims must contain non-empty claim names");
+    }
+    return {
+        mode,
+        password: { workFactor },
+        accessToken: {
+            algorithm,
+            algorithms,
+            key: tokenConfig.key,
+            ...(tokenConfig.keyId === undefined ? {} : { keyId: tokenConfig.keyId }),
+            ...(tokenConfig.keyResolver === undefined
+                ? {}
+                : { keyResolver: tokenConfig.keyResolver }),
+            ...(tokenConfig.issuer === undefined
+                ? {}
+                : { issuer: tokenConfig.issuer }),
+            ...(tokenConfig.audience === undefined
+                ? {}
+                : { audience: tokenConfig.audience }),
+            expiresInSeconds,
+            requiredClaims,
+            ...(tokenConfig.isRevoked === undefined
+                ? {}
+                : { isRevoked: tokenConfig.isRevoked }),
+        },
+        ...(refreshToken === undefined ? {} : { refreshToken }),
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}