rst-auth 0.0.0-stage → 0.2.0

package/dist/testing/refresh-store-conformance.d.ts

@@ -0,0 +1,11 @@
+import type { RefreshTokenStore } from "../refresh-store.js";
+export interface ConformanceTestRegistrar {
+    test(name: string, fn: () => void | Promise<void>): unknown;
+}
+export type RefreshTokenStoreFactory = () => RefreshTokenStore | Promise<RefreshTokenStore>;
+/**
+ * Registers a runner-neutral set of contract tests. Pass an adapter for your
+ * test runner's `test`/`it` function and a factory that creates an empty store.
+ */
+export declare function registerRefreshTokenStoreConformanceTests(registrar: ConformanceTestRegistrar, createStore: RefreshTokenStoreFactory): void;
+//# sourceMappingURL=refresh-store-conformance.d.ts.map

package/dist/testing/refresh-store-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refresh-store-conformance.d.ts","sourceRoot":"","sources":["../../src/testing/refresh-store-conformance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAE7B,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;CAC7D;AAED,MAAM,MAAM,wBAAwB,GAAG,MACrC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;AAyBjD;;;GAGG;AACH,wBAAgB,yCAAyC,CACvD,SAAS,EAAE,wBAAwB,EACnC,WAAW,EAAE,wBAAwB,GACpC,IAAI,CAyIN"}

package/dist/testing/refresh-store-conformance.js

@@ -0,0 +1,110 @@
+const BASE_TIME = new Date("2030-01-01T00:00:00.000Z");
+function record(tokenHash, overrides = {}) {
+    return {
+        tokenHash,
+        familyId: "family-default",
+        subject: "subject-default",
+        createdAt: BASE_TIME,
+        expiresAt: new Date(BASE_TIME.getTime() + 60_000),
+        absoluteExpiresAt: new Date(BASE_TIME.getTime() + 120_000),
+        status: "active",
+        ...overrides,
+    };
+}
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(`RefreshTokenStore conformance failure: ${message}`);
+}
+/**
+ * Registers a runner-neutral set of contract tests. Pass an adapter for your
+ * test runner's `test`/`it` function and a factory that creates an empty store.
+ */
+export function registerRefreshTokenStoreConformanceTests(registrar, createStore) {
+    registrar.test("supports consuming a token and storing its rotated successor", async () => {
+        const store = await createStore();
+        const original = record("a".repeat(64));
+        await store.create(original);
+        const consumed = await store.consume(original.tokenHash, BASE_TIME);
+        assert(consumed.status === "ok", "an active token must be consumed");
+        const successor = record("b".repeat(64), {
+            familyId: original.familyId,
+            subject: original.subject,
+        });
+        await store.create(successor);
+        const next = await store.consume(successor.tokenHash, BASE_TIME);
+        assert(next.status === "ok", "the successor in the same family must be consumable");
+    });
+    registrar.test("detects replay of a consumed token", async () => {
+        const store = await createStore();
+        const token = record("c".repeat(64));
+        await store.create(token);
+        assert((await store.consume(token.tokenHash, BASE_TIME)).status === "ok", "first consume must win");
+        assert((await store.consume(token.tokenHash, BASE_TIME)).status === "reused", "a second consume must report reuse");
+    });
+    registrar.test("revokes the entire family after reuse", async () => {
+        const store = await createStore();
+        const original = record("d".repeat(64), { familyId: "family-reuse" });
+        const sibling = record("e".repeat(64), { familyId: "family-reuse" });
+        await store.create(original);
+        await store.create(sibling);
+        await store.consume(original.tokenHash, BASE_TIME);
+        assert((await store.consume(original.tokenHash, BASE_TIME)).status === "reused", "replay must be detected");
+        assert((await store.consume(sibling.tokenHash, BASE_TIME)).status === "revoked", "all tokens in the family must be revoked");
+        let refusedSuccessor = false;
+        try {
+            await store.create(record("6".repeat(64), { familyId: "family-reuse" }));
+        }
+        catch {
+            refusedSuccessor = true;
+        }
+        assert(refusedSuccessor, "a revoked family must reject a late successor create");
+    });
+    registrar.test("rejects expired tokens", async () => {
+        const store = await createStore();
+        const token = record("f".repeat(64), {
+            expiresAt: BASE_TIME,
+            absoluteExpiresAt: new Date(BASE_TIME.getTime() + 60_000),
+        });
+        await store.create(token);
+        assert((await store.consume(token.tokenHash, BASE_TIME)).status === "expired", "expiry is exclusive at expiresAt");
+    });
+    registrar.test("supports single-token, family, and subject revocation", async () => {
+        const store = await createStore();
+        const single = record("1".repeat(64), { familyId: "family-single" });
+        const familyMember = record("2".repeat(64), { familyId: "family-all" });
+        const otherFamily = record("3".repeat(64), {
+            familyId: "family-other",
+            subject: "subject-all",
+        });
+        for (const item of [single, familyMember, otherFamily])
+            await store.create(item);
+        await store.revokeToken(single.tokenHash, BASE_TIME);
+        assert((await store.consume(single.tokenHash, BASE_TIME)).status === "revoked", "single-token revoke must block that token");
+        await store.revokeFamily("family-all", BASE_TIME);
+        assert((await store.consume(familyMember.tokenHash, BASE_TIME)).status ===
+            "revoked", "family revoke must block family members");
+        let rejectedLateFamilyMember = false;
+        try {
+            await store.create(record("5".repeat(64), { familyId: "family-all" }));
+        }
+        catch {
+            rejectedLateFamilyMember = true;
+        }
+        assert(rejectedLateFamilyMember, "create must not recreate a family after revocation");
+        await store.revokeAllForSubject("subject-all", BASE_TIME);
+        assert((await store.consume(otherFamily.tokenHash, BASE_TIME)).status ===
+            "revoked", "subject revoke must block all of that subject's tokens");
+    });
+    registrar.test("allows only one concurrent consume to win", async () => {
+        const store = await createStore();
+        const token = record("4".repeat(64));
+        await store.create(token);
+        const results = await Promise.all([
+            store.consume(token.tokenHash, BASE_TIME),
+            store.consume(token.tokenHash, BASE_TIME),
+        ]);
+        assert(results.filter((result) => result.status === "ok").length === 1, "exactly one concurrent caller must receive ok");
+        assert(results.some((result) => result.status === "reused"), "the losing concurrent caller must be recognized as reuse");
+    });
+}
+//# sourceMappingURL=refresh-store-conformance.js.map

package/dist/testing/refresh-store-conformance.js.map

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

package/dist/tokens.d.ts

@@ -0,0 +1,15 @@
+import { type JWTPayload } from "jose";
+import type { ValidatedAuthConfig } from "./config.js";
+export type AccessTokenClaims = JWTPayload & {
+    sub: string;
+};
+export type VerifiedAccessClaims = JWTPayload & {
+    sub: string;
+    token_use: "access";
+};
+export interface AccessTokenService {
+    generateAccessToken(claims: AccessTokenClaims): Promise<string>;
+    verifyAccessToken(token: string, context?: unknown): Promise<VerifiedAccessClaims>;
+}
+export declare function createAccessTokenService(config: ValidatedAuthConfig["accessToken"]): AccessTokenService;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIvD,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC;AAC7D,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,QAAQ,CAAC;CACrB,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,mBAAmB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChE,iBAAiB,CACf,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClC;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,mBAAmB,CAAC,aAAa,CAAC,GACzC,kBAAkB,CA+GpB"}

package/dist/tokens.js

@@ -0,0 +1,90 @@
+import { SignJWT, jwtVerify } from "jose";
+import { isReservedClaim } from "./config.js";
+import { AuthError } from "./errors.js";
+export function createAccessTokenService(config) {
+    return {
+        async generateAccessToken(claims) {
+            if (!claims ||
+                typeof claims !== "object" ||
+                typeof claims.sub !== "string" ||
+                !claims.sub) {
+                throw new AuthError("VALIDATION_ERROR", "Access-token claims require a non-empty sub");
+            }
+            for (const claim of Object.keys(claims)) {
+                if (isReservedClaim(claim)) {
+                    throw new AuthError("VALIDATION_ERROR", `Caller-supplied claim ${claim} is reserved by the access-token implementation`);
+                }
+            }
+            let jwt = new SignJWT({ ...claims, token_use: "access" })
+                .setProtectedHeader({
+                alg: config.algorithm,
+                typ: "JWT",
+                ...(config.keyId === undefined ? {} : { kid: config.keyId }),
+            })
+                .setIssuedAt()
+                .setExpirationTime(`${config.expiresInSeconds}s`);
+            if (config.issuer)
+                jwt = jwt.setIssuer(config.issuer);
+            if (config.audience) {
+                jwt = jwt.setAudience(typeof config.audience === "string"
+                    ? config.audience
+                    : [...config.audience]);
+            }
+            return jwt.sign(config.key);
+        },
+        async verifyAccessToken(token, context) {
+            if (typeof token !== "string" || token.length === 0) {
+                throw new AuthError("TOKEN_MISSING", "Access token is required");
+            }
+            try {
+                const verified = await jwtVerify(token, async (header) => {
+                    if (config.keyResolver) {
+                        if (typeof header.kid !== "string" || header.kid.length === 0) {
+                            throw new AuthError("TOKEN_INVALID", "Access token key identifier is missing");
+                        }
+                        return config.keyResolver(header);
+                    }
+                    return config.key;
+                }, {
+                    algorithms: [...config.algorithms],
+                    ...(config.issuer ? { issuer: config.issuer } : {}),
+                    ...(config.audience
+                        ? {
+                            audience: typeof config.audience === "string"
+                                ? config.audience
+                                : [...config.audience],
+                        }
+                        : {}),
+                    requiredClaims: [...config.requiredClaims],
+                });
+                const claims = verified.payload;
+                if (claims.token_use !== "access") {
+                    throw new AuthError("TOKEN_INVALID", "Token is not an access token");
+                }
+                if (config.isRevoked && (await config.isRevoked(claims, context))) {
+                    throw new AuthError("SESSION_REVOKED", "Access token has been revoked");
+                }
+                if (typeof claims.sub !== "string") {
+                    throw new AuthError("TOKEN_INVALID", "Access token has no valid subject");
+                }
+                return claims;
+            }
+            catch (error) {
+                if (error instanceof AuthError)
+                    throw error;
+                if (typeof error === "object" &&
+                    error !== null &&
+                    "code" in error &&
+                    error.code === "ERR_JWT_EXPIRED") {
+                    throw new AuthError("TOKEN_EXPIRED", "Access token has expired", {
+                        cause: error,
+                    });
+                }
+                throw new AuthError("TOKEN_INVALID", "Access token is invalid", {
+                    cause: error,
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,SAAS,EAAmB,MAAM,MAAM,CAAC;AAE3D,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAgBxC,MAAM,UAAU,wBAAwB,CACtC,MAA0C;IAE1C,OAAO;QACL,KAAK,CAAC,mBAAmB,CAAC,MAAM;YAC9B,IACE,CAAC,MAAM;gBACP,OAAO,MAAM,KAAK,QAAQ;gBAC1B,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ;gBAC9B,CAAC,MAAM,CAAC,GAAG,EACX,CAAC;gBACD,MAAM,IAAI,SAAS,CACjB,kBAAkB,EAClB,6CAA6C,CAC9C,CAAC;YACJ,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;gBACxC,IAAI,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;oBAC3B,MAAM,IAAI,SAAS,CACjB,kBAAkB,EAClB,yBAAyB,KAAK,iDAAiD,CAChF,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,IAAI,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;iBACtD,kBAAkB,CAAC;gBAClB,GAAG,EAAE,MAAM,CAAC,SAAS;gBACrB,GAAG,EAAE,KAAK;gBACV,GAAG,CAAC,MAAM,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;aAC7D,CAAC;iBACD,WAAW,EAAE;iBACb,iBAAiB,CAAC,GAAG,MAAM,CAAC,gBAAgB,GAAG,CAAC,CAAC;YACpD,IAAI,MAAM,CAAC,MAAM;gBAAE,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;gBACpB,GAAG,GAAG,GAAG,CAAC,WAAW,CACnB,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;oBACjC,CAAC,CAAC,MAAM,CAAC,QAAQ;oBACjB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CACzB,CAAC;YACJ,CAAC;YACD,OAAO,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,KAAK,EAAE,OAAO;YACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACpD,MAAM,IAAI,SAAS,CAAC,eAAe,EAAE,0BAA0B,CAAC,CAAC;YACnE,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,SAAS,CAC9B,KAAK,EACL,KAAK,EAAE,MAAM,EAAE,EAAE;oBACf,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;wBACvB,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;4BAC9D,MAAM,IAAI,SAAS,CACjB,eAAe,EACf,wCAAwC,CACzC,CAAC;wBACJ,CAAC;wBACD,OAAO,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;oBACpC,CAAC;oBACD,OAAO,MAAM,CAAC,GAAG,CAAC;gBACpB,CAAC,EACD;oBACE,UAAU,EAAE,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC;oBAClC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBACnD,GAAG,CAAC,MAAM,CAAC,QAAQ;wBACjB,CAAC,CAAC;4BACE,QAAQ,EACN,OAAO,MAAM,CAAC,QAAQ,KAAK,QAAQ;gCACjC,CAAC,CAAC,MAAM,CAAC,QAAQ;gCACjB,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC;yBAC3B;wBACH,CAAC,CAAC,EAAE,CAAC;oBACP,cAAc,EAAE,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC;iBAC3C,CACF,CAAC;gBACF,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC;gBAChC,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;oBAClC,MAAM,IAAI,SAAS,CAAC,eAAe,EAAE,8BAA8B,CAAC,CAAC;gBACvE,CAAC;gBACD,IAAI,MAAM,CAAC,SAAS,IAAI,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;oBAClE,MAAM,IAAI,SAAS,CACjB,iBAAiB,EACjB,+BAA+B,CAChC,CAAC;gBACJ,CAAC;gBACD,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;oBACnC,MAAM,IAAI,SAAS,CACjB,eAAe,EACf,mCAAmC,CACpC,CAAC;gBACJ,CAAC;gBACD,OAAO,MAA8B,CAAC;YACxC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,SAAS;oBAAE,MAAM,KAAK,CAAC;gBAC5C,IACE,OAAO,KAAK,KAAK,QAAQ;oBACzB,KAAK,KAAK,IAAI;oBACd,MAAM,IAAI,KAAK;oBACf,KAAK,CAAC,IAAI,KAAK,iBAAiB,EAChC,CAAC;oBACD,MAAM,IAAI,SAAS,CAAC,eAAe,EAAE,0BAA0B,EAAE;wBAC/D,KAAK,EAAE,KAAK;qBACb,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM,IAAI,SAAS,CAAC,eAAe,EAAE,yBAAyB,EAAE;oBAC9D,KAAK,EAAE,KAAK;iBACb,CAAC,CAAC;YACL,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/validation.d.ts

@@ -0,0 +1,7 @@
+/** A framework-independent schema validator used by optional adapters. */
+export interface ValidatorAdapter {
+    parse<TSchema>(schema: TSchema, value: unknown): unknown | Promise<unknown>;
+}
+export type ValidationTarget = "body" | "params" | "query";
+export type ValidationSchemaMap<TSchema = unknown> = Partial<Record<ValidationTarget, TSchema>>;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE3D,MAAM,MAAM,mBAAmB,CAAC,OAAO,GAAG,OAAO,IAAI,OAAO,CAC1D,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAClC,CAAC"}

package/dist/validation.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":""}

package/dist/zod/index.d.ts

@@ -0,0 +1,5 @@
+import type { ValidatorAdapter } from "../validation.js";
+export type ZodAdapter = ValidatorAdapter;
+/** Adapts Zod 3 or 4 schemas to the framework-independent validator interface. */
+export declare function zodAdapter(): ZodAdapter;
+//# sourceMappingURL=index.d.ts.map

package/dist/zod/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/zod/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,MAAM,MAAM,UAAU,GAAG,gBAAgB,CAAC;AAE1C,kFAAkF;AAClF,wBAAgB,UAAU,IAAI,UAAU,CAoBvC"}

package/dist/zod/index.js

@@ -0,0 +1,22 @@
+import { AuthError } from "../errors.js";
+/** Adapts Zod 3 or 4 schemas to the framework-independent validator interface. */
+export function zodAdapter() {
+    return {
+        async parse(schema, value) {
+            if (!schema ||
+                typeof schema !== "object" ||
+                !("safeParseAsync" in schema)) {
+                throw new TypeError("The Zod adapter requires a Zod schema");
+            }
+            const zodSchema = schema;
+            const result = await zodSchema.safeParseAsync(value);
+            if (!result.success) {
+                throw new AuthError("VALIDATION_ERROR", "Request validation failed", {
+                    cause: result.error,
+                });
+            }
+            return result.data;
+        },
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/zod/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/zod/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAKzC,kFAAkF;AAClF,MAAM,UAAU,UAAU;IACxB,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,MAAe,EAAE,KAAc;YACzC,IACE,CAAC,MAAM;gBACP,OAAO,MAAM,KAAK,QAAQ;gBAC1B,CAAC,CAAC,gBAAgB,IAAI,MAAM,CAAC,EAC7B,CAAC;gBACD,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;YAC/D,CAAC;YACD,MAAM,SAAS,GAAG,MAAiB,CAAC;YACpC,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;YACrD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBACpB,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,2BAA2B,EAAE;oBACnE,KAAK,EAAE,MAAM,CAAC,KAAK;iBACpB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,MAAM,CAAC,IAAI,CAAC;QACrB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/docs/access-tokens.md

@@ -0,0 +1,15 @@
+# Access tokens
+
+Access tokens are signed with `jose`. The configured algorithm and allowlist are used; the verifier does not choose an algorithm from the incoming JWT header. Tokens carry `token_use: "access"`. Verification checks signatures, expiry, issued-at time, configured issuer/audience, required claims, subject, and token type.
+
+```ts
+const token = await auth.tokens.generateAccessToken({
+  sub: user.id,
+  role: user.role,
+});
+const claims = await auth.tokens.verifyAccessToken(token);
+```
+
+Reserved claims belong to the library and cannot be supplied as caller payload. Static keys are supported; an optional async `keyResolver(header)` can resolve keys by `kid` during rotation. It does not change the configured algorithm allowlist.
+
+The optional `isRevoked(claims, context?)` hook lets applications consult a denylist or session state. It makes verification stateful and adds a dependency to each verification. Without such a lookup, an otherwise valid token does not prove that the user still exists or is active; roles embedded in a token can be stale. Keep token lifetimes and current-permission checks appropriate for the application. Never log full tokens.

package/docs/accounts.md

@@ -0,0 +1,68 @@
+# Register and login helpers
+
+`createAuth()` can expose `auth.accounts.register()` and `auth.accounts.login()` when you configure `accounts` and a refresh-token store. This is an optional shortcut for the repeated password and token work. Your app still owns the database, model schema, email query, routes, authorization policy, and HTTP response.
+
+## Configure your model and lookup
+
+The model must have a `create(values)` method. Supply the lookup used by your database library. For example, with Mongoose:
+
+```ts
+const auth = createAuth({
+  accessToken: {
+    key: new TextEncoder().encode(config.accessTokenSecret),
+    expiresInSeconds: config.accessTokenTtlSeconds,
+    issuer: "my-api",
+    audience: "my-client",
+  },
+  refreshToken: {
+    store: mongoRefreshTokenStore,
+    refreshTokenTtl: config.refreshTokenTtlSeconds,
+    absoluteLifetime: 30 * 24 * 60 * 60,
+  },
+  accounts: {
+    model: User,
+    findByEmail: (email) => User.findOne({ email }),
+    getSubject: (user) => String(user._id),
+    getAccessClaims: (user) => ({ role: user.role }),
+  },
+});
+```
+
+The app reads environment variables in its own config layer and passes the values above. `rst-auth` never reads `process.env`. `passwordHash` is the default persisted hash field; set `passwordHashField` if your schema uses another name.
+
+## Use it from existing controllers
+
+```ts
+const session = await auth.accounts.register({
+  email: req.body.email,
+  password: req.body.password,
+  profile: { name: req.body.name },
+});
+res.status(201).json({
+  user: session.user,
+  accessToken: session.accessToken,
+});
+// Send session.refreshToken using an HttpOnly cookie or another deliberate channel.
+```
+
+```ts
+const session = await auth.accounts.login({
+  email: req.body.email,
+  password: req.body.password,
+});
+res.json({ user: session.user, accessToken: session.accessToken });
+```
+
+The helper rejects client-provided `role`, `roles`, `permissions`, `scopes`, `admin`, and `isAdmin` fields in `profile`. Assign privileges in trusted application code. The returned user omits the password hash and common legacy raw refresh-token fields. Select the exact response fields your app intends to expose.
+
+For unknown users, login performs a dummy bcrypt comparison and returns the same `UNAUTHORIZED` error as a wrong password. A successful login revokes prior refresh families for that subject by default; set `revokePreviousSessionsOnLogin: false` when concurrent sessions are desired.
+
+## What the app still provides
+
+- A model with a unique email constraint and a `create()` method.
+- `findByEmail(email)` that returns the user record or `null`.
+- A stable subject mapping, and any trusted claims needed by authorization.
+- A persistent, atomic `RefreshTokenStore` for multi-process deployments. `MemoryRefreshTokenStore` is only for tests and local development.
+- Request validation and response shaping, plus rate limits, lockout, email verification, password reset, and CSRF policy.
+
+The helper is not a database adapter and does not make a Mongoose dependency part of the package. See [refresh tokens](refresh-tokens.md) for store requirements and [security](security.md) for application responsibilities.

package/docs/before-first-release.md

@@ -0,0 +1,31 @@
+# Before first release
+
+- [ ] Verify the npm package name is available and intended; `package.json` now uses the selected name `rst-auth`.
+- [ ] Verify the GitHub organization and repository name, default branch, and repository URLs in project metadata.
+- [ ] Complete a trademark/name review for the package and project name.
+- [ ] Verify the copyright attribution and year in `LICENSE` before each release.
+- [ ] Review the documented security limitations, refresh-store implementation, operational controls, and vulnerability-reporting route.
+- [ ] Run the final checks from the repository root and review the tarball contents for accidental files or credentials.
+
+Manual commands to run only after those checks and maintainer approval:
+
+```sh
+npm whoami
+npm view rst-auth name
+git remote -v
+npm ci
+npm run format:check
+npm run lint
+npm run typecheck
+npm test
+npm run build
+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
+npm login
+npm publish --access public
+```
+
+The final two commands require a deliberate maintainer release action. Do not run them as part of routine validation.

package/docs/claims.md

@@ -0,0 +1,42 @@
+# README claim-to-test map
+
+| README claim                                                                                                                                                  | Test                                                                                                                             |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Password hashing and verification work, including wrong-password rejection                                                                                    | `test/password.test.ts` — “hashes and verifies passwords”                                                                        |
+| Password input is non-empty and limited to 72 UTF-8 bytes                                                                                                     | `test/password.test.ts` — “rejects empty and over-72-byte passwords by UTF-8 byte length”                                        |
+| Malformed hashes fail safely and dummy verification is available                                                                                              | `test/password.test.ts` — “fails safely for malformed hashes and supports dummy verification”                                    |
+| Errors expose stable codes, safe public messages, status mappings, custom public messages, and causes                                                         | `test/errors.test.ts`                                                                                                            |
+| Config defaults, secret length, expiry, algorithm, work factor, and production requirements are validated                                                     | `test/config.test.ts`                                                                                                            |
+| Access-token signatures and configured issuer, audience, and required claims are verified                                                                     | `test/tokens.test.ts` — “generates and verifies signed tokens with configured claims”                                            |
+| Algorithms are pinned and `none` or a header-selected alternative is rejected                                                                                 | `test/tokens.test.ts` — “pins the allowed algorithm and rejects none or header-selected alternatives”                            |
+| Caller input cannot override reserved claims                                                                                                                  | `test/tokens.test.ts` — “rejects caller overrides of reserved claims”                                                            |
+| Verification requires `exp` and `iat`                                                                                                                         | `test/tokens.test.ts` — “requires exp and iat on verified tokens”                                                                |
+| A refresh-typed token is rejected as an access token                                                                                                          | `test/tokens.test.ts` — “rejects token-type confusion”                                                                           |
+| Token expiration is enforced                                                                                                                                  | `test/tokens.test.ts` — “uses fake time to enforce expiry”                                                                       |
+| Verification supports async `kid` key resolution and a revocation callback                                                                                    | `test/tokens.test.ts` — “resolves verification keys asynchronously by kid and supports revocation hooks”                         |
+| Asymmetric signing and verification keys work with the configured algorithm                                                                                   | `test/tokens.test.ts` — “supports asymmetric signing and verification keys”                                                      |
+| Store-less configuration cannot enable stateless re-issuance as rotation, and partial config is rejected                                                      | `test/refresh.test.ts` — “refresh-stateless-not-rotation: refuses refresh without a configured store”                            |
+| Issued refresh tokens are opaque random values and only their SHA-256 hashes reach the store                                                                  | `test/refresh.test.ts` — “issues opaque 256-bit tokens and stores only their SHA-256 hashes”                                     |
+| The memory store is instance-local and cannot serve another store instance                                                                                    | `test/refresh.test.ts` — “documents the memory store's instance-local behavior”                                                  |
+| Rotation preserves the family, detects replay, and revokes family descendants                                                                                 | `test/refresh.test.ts` — “rotates into the same family and detects replay by revoking that family”                               |
+| Concurrent replay cannot return a successor after family revocation                                                                                           | `test/refresh.test.ts` — “does not return a rotation result when a concurrent replay revokes the family”                         |
+| Unknown, expired, and revoked refresh tokens cannot rotate                                                                                                    | `test/refresh.test.ts` — “never rotates unknown, expired, or revoked values”                                                     |
+| Rotation is capped at the family's absolute lifetime                                                                                                          | `test/refresh.test.ts` — “caps every rotation at the family's absolute lifetime”                                                 |
+| Rotation renews idle expiry without extending the family absolute lifetime                                                                                    | `test/refresh.test.ts` — “renews idle expiry on rotation without changing the family cap”                                        |
+| Refresh and access tokens cannot be confused                                                                                                                  | `test/refresh.test.ts` — “rejects an access token as refresh and a refresh token as access”                                      |
+| Refresh store rotation, replay, reuse revocation, expiry, revocation, and concurrent consume conform                                                          | `test/refresh-store-conformance.test.ts` — registered conformance cases                                                          |
+| Express 4 and 5 return safe 401s for absent, malformed, invalid, and expired access tokens                                                                    | `test/express.integration.test.ts` — “distinguishes missing and malformed bearer headers and rejects invalid or expired tokens”  |
+| Optional auth accepts absence but rejects present invalid tokens; valid identities and role checks work                                                       | `test/express.integration.test.ts` — “authenticates, supports optional auth, and enforces role access”                           |
+| Express passes the request to the revocation hook and supports application identity lookup                                                                    | `test/express.integration.test.ts` — “passes the request to isRevoked and allows identity lookup”                                |
+| Optional account helpers hash on signup, verify on login, equalize missing-user work, omit hashes from returned user data, and reject client privilege fields | `test/accounts.test.ts` — high-level account helper cases                                                                        |
+| Account helpers reject duplicate accounts and require refresh storage                                                                                         | `test/accounts.test.ts` — duplicate-account and missing-store cases                                                              |
+| Zod validates body, params, and query into `req.validated` without mutating `req.body`                                                                        | `test/express.integration.test.ts` — “validates body, params, and query without mutating Express request fields”                 |
+| Validation and unexpected errors support custom formatting without exposing private details                                                                   | `test/express.integration.test.ts` — “supports a custom schema formatter and keeps unexpected errors private”                    |
+| Cookie and composed token extractors work; refresh cookies default to HttpOnly, Secure, and SameSite=Lax                                                      | `test/express.integration.test.ts` — “supports cookie and composed extractors, and sets secure refresh-cookie defaults”          |
+| Query-string token extraction is not enabled by default, while explicit custom extraction remains possible                                                    | `test/express.integration.test.ts` — “allows a custom token extractor while preserving strict header parsing by default”         |
+| The package is ESM, declares Node 22+, and maps every supported subpath to built files                                                                        | `test/package.test.ts` — “declares ESM, Node 22+, and built targets for every documented subpath”                                |
+| The example assigns roles server-side and rejects a client-supplied signup role                                                                               | `examples/express-api/test/app.test.ts` — “no-role-from-client: rejects a client role and creates no account”                    |
+| The example demonstrates app-owned persistence/controllers, password hashing, token routes, and role checks                                                   | `examples/express-api/test/app.test.ts` — “uses application-owned controllers, hashing, and repository roles”                    |
+| Cookie delivery sets safe cookie flags, and example error responses avoid credential leakage                                                                  | `examples/express-api/test/app.test.ts` — cookie defaults and “maps login failures without returning password hashes or secrets” |
+| Core configuration does not read environment variables                                                                                                        | `test/package.test.ts` — “keeps environment reads out of the injected core configuration layer”                                  |
+| The bcrypt work factor is configurable and defaults to 12                                                                                                     | `test/password.test.ts` — “uses the configured bcrypt work factor and defaults to 12”                                            |

package/docs/configuration.md

@@ -0,0 +1,38 @@
+# Configuration
+
+`createAuth(config)` validates config once and throws `AuthError` with code `INVALID_CONFIGURATION` for invalid settings. Configuration is injected; do not pass secrets per operation or derive algorithms from untrusted token headers.
+
+```ts
+const auth = createAuth({
+  mode: "production",
+  password: { workFactor: 12 },
+  accessToken: {
+    key: hmacKey,
+    algorithm: "HS256",
+    algorithms: ["HS256"],
+    issuer: "billing-api",
+    audience: ["billing-web", "billing-worker"],
+    expiresInSeconds: 900,
+    requiredClaims: ["tenant"],
+  },
+  refreshToken: {
+    store: refreshTokenStore,
+    refreshTokenTtl: 60 * 60 * 24 * 7,
+    absoluteLifetime: 60 * 60 * 24 * 30,
+  },
+  accounts: {
+    model: User,
+    findByEmail: (email) => User.findOne({ email }),
+    getSubject: (user) => String(user._id),
+    getAccessClaims: (user) => ({ role: user.role }),
+  },
+});
+```
+
+HMAC keys are `Uint8Array` values of at least 32 bytes. Asymmetric algorithms require a JOSE `CryptoKey` or Node `KeyObject`. `algorithm` chooses signing; `algorithms` is the pinned verification allowlist and must include the signing algorithm. An optional `keyResolver(header)` supports key lookup by `kid` while the allowlist remains configured. Production mode requires issuer and audience and limits access expiry to one hour.
+
+The default bcrypt work factor is 12 and the default access-token expiry is 900 seconds. Work factor must be an integer from 4 to 31. Refresh support is disabled when `refreshToken` is omitted; enabling it requires a store, idle TTL, and absolute family lifetime, each a positive safe integer in seconds.
+
+`accounts` is optional. When provided, it enables `auth.accounts.register()` and `auth.accounts.login()` and requires refresh support. Pass your own model with `create(values)` and your own `findByEmail(email)` lookup. Optional `getSubject` and `getAccessClaims` callbacks map your user record into token identity and trusted claims. The library does not select or import a database package. See [account helpers](accounts.md).
+
+`isRevoked(claims, context?)` can check application state during verification. Express passes the current request as `context`; direct calls can pass a context themselves. The hook makes verification stateful and adds its latency and availability to protected requests.

package/docs/cookies-vs-bearer.md

@@ -0,0 +1,82 @@
+# Refresh-token delivery: cookies and explicit requests
+
+Refresh tokens are opaque bearer secrets. Keep them out of logs and URLs. Choose a delivery mode based on the client and threat model; the toolkit does not decide the response shape for your application.
+
+## HttpOnly cookie
+
+The Express helper defaults to HttpOnly, Secure, SameSite=Lax and path `/auth/refresh`:
+
+```ts
+import { setRefreshTokenCookie, fromCookie } from "rst-auth/express";
+
+app.post("/login", async (req, res, next) => {
+  try {
+    const user = await users.findByEmail(req.body.email);
+    const refresh = await auth.refresh!.issue({ subject: user.id });
+    const accessToken = await auth.tokens.generateAccessToken({
+      sub: user.id,
+      role: user.role,
+    });
+    setRefreshTokenCookie(res, refresh.refreshToken);
+    res.json({ accessToken });
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.post("/auth/refresh", async (req, res, next) => {
+  try {
+    const oldToken = await fromCookie("refreshToken")(req);
+    const rotated = await auth.refresh!.rotate(oldToken ?? "");
+    const user = await users.findById(rotated.subject);
+    const accessToken = await auth.tokens.generateAccessToken({
+      sub: user.id,
+      role: user.role,
+    });
+    setRefreshTokenCookie(res, rotated.refreshToken);
+    res.json({ accessToken });
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+The helper writes and clears cookies; it does not parse them. Cookie delivery lets the browser attach the refresh secret automatically, which creates CSRF risk. SameSite=Lax helps with common cross-site requests but is not a universal CSRF defense. `SameSite=None` requires Secure and an explicit CSRF defense. Restrict cookie path and domain to the smallest useful scope.
+
+## Authorization header or request body
+
+For clients that can manage the token explicitly, your controller can return the refresh token in a response and require it in a request body or dedicated header:
+
+```ts
+app.post("/login", async (req, res, next) => {
+  try {
+    const user = await users.findByEmail(req.body.email);
+    const refresh = await auth.refresh!.issue({ subject: user.id });
+    const accessToken = await auth.tokens.generateAccessToken({
+      sub: user.id,
+      role: user.role,
+    });
+    res.json({ accessToken, refreshToken: refresh.refreshToken });
+  } catch (error) {
+    next(error);
+  }
+});
+
+app.post("/auth/refresh/body", async (req, res, next) => {
+  try {
+    const rotated = await auth.refresh!.rotate(req.body.refreshToken);
+    const user = await users.findById(rotated.subject);
+    const accessToken = await auth.tokens.generateAccessToken({
+      sub: user.id,
+      role: user.role,
+    });
+    res.json({ accessToken, refreshToken: rotated.refreshToken });
+  } catch (error) {
+    next(error);
+  }
+});
+```
+
+Explicit delivery avoids the browser automatically attaching the secret cross-site, reducing classic CSRF exposure. JavaScript-readable storage can increase exposure to cross-site scripting. Never put tokens in query strings: URLs are commonly copied, logged, cached, and included in referrers.
+
+These are controller sketches. Add application-specific authentication, schema validation, CSRF defense, CORS, rate limiting, user lookup, and response policy. On Express 4, forward async controller rejections to `next(error)` as shown; the middleware only forwards its own async errors.

package/docs/error-handling.md

@@ -0,0 +1,15 @@
+# Error handling
+
+`AuthError` contains a stable code, developer message, safe `publicMessage`, HTTP status, and optional cause. Common status mapping is 401 for missing/invalid/expired/revoked authentication, 403 for forbidden access, and 400 for validation. Configuration errors are server errors and should be caught during startup.
+
+```ts
+const middleware = expressAuth(auth, {
+  errorFormatter: (error) => ({
+    status: error.status,
+    body: { error: { code: error.code, message: error.message } },
+  }),
+});
+app.use(middleware.errorHandler()); // Mount after routes.
+```
+
+The formatter receives only a public projection (`status`, `code`, `message`), not the original exception, stack, cause, or developer message. Unknown failures become a generic 500. Applications can pass another formatter to `errorHandler(formatter)`. Do not include passwords, token values, secrets, database errors, stack traces, or other internal details in custom responses.