@aooth/auth 0.1.7 → 0.1.8

package/dist/index.cjs

@@ -1,4 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_clock = require("./clock-Bl-H3eqE.cjs");
+const require_payload = require("./payload-BJjvj8AH.cjs");
 let node_crypto = require("node:crypto");
 let jose = require("jose");
 //#region src/errors.ts
@@ -12,6 +14,8 @@ const defaultMessages = {
 	INVALID_CONFIG: "Invalid auth configuration"
 };
 var AuthError = class extends Error {
+	type;
+	details;
 	name = "AuthError";
 	constructor(type, message, details) {
 		super(message ?? defaultMessages[type]);
@@ -20,9 +24,6 @@ var AuthError = class extends Error {
 	}
 };
 //#endregion
-//#region src/utils/clock.ts
-const defaultClock = { now: () => Date.now() };
-//#endregion
 //#region src/stores/memory.ts
 /**
 * In-memory implementation of CredentialStore using random opaque token IDs.
@@ -37,7 +38,7 @@ var CredentialStoreMemory = class {
 	byUser = /* @__PURE__ */ new Map();
 	clock;
 	constructor(opts) {
-		this.clock = opts?.clock ?? defaultClock;
+		this.clock = opts?.clock ?? require_clock.defaultClock;
 	}
 	async persist(state, ttl) {
 		const token = (0, node_crypto.randomUUID)();
@@ -79,6 +80,11 @@ var CredentialStoreMemory = class {
 		this.states.delete(token);
 		this.indexRemove(state.userId, token);
 	}
+	async touch(token, at) {
+		const state = this.states.get(token);
+		if (!state) return;
+		state.lastSeenAt = at;
+	}
 	async revokeAllForUser(userId) {
 		const tokens = this.byUser.get(userId);
 		if (!tokens || tokens.size === 0) return 0;
@@ -144,7 +150,7 @@ var DenylistStoreMemory = class {
 	entries = /* @__PURE__ */ new Map();
 	clock;
 	constructor(opts) {
-		this.clock = opts?.clock ?? defaultClock;
+		this.clock = opts?.clock ?? require_clock.defaultClock;
 	}
 	async add(jti, expiresAt) {
 		this.entries.set(jti, expiresAt);
@@ -169,6 +175,13 @@ var DenylistStoreMemory = class {
 	}
 };
 //#endregion
+//#region src/stores/derive-subkey.ts
+const SUBKEY_SALT = Buffer.from("aooth/credential-store/subkey-v1");
+/** HKDF-SHA256 a stable 32-byte subkey from symmetric key material + a label. */
+function hkdfSubkey(ikm, label) {
+	return Buffer.from((0, node_crypto.hkdfSync)("sha256", ikm, SUBKEY_SALT, Buffer.from(label, "utf8"), 32));
+}
+//#endregion
 //#region src/stores/jwt.ts
 const HS_ALGS = new Set([
 	"HS256",
@@ -206,7 +219,7 @@ var CredentialStoreJwt = class {
 		this.issuer = opts.issuer;
 		this.audience = opts.audience;
 		this.denylist = opts.denylist;
-		this.clock = opts.clock ?? defaultClock;
+		this.clock = opts.clock ?? require_clock.defaultClock;
 		if (HS_ALGS.has(this.algorithm)) {
 			if (opts.secret == null) throw new AuthError("INVALID_CONFIG", `Algorithm ${this.algorithm} requires a 'secret' option`);
 			const key = normalizeSecret(opts.secret);
@@ -227,7 +240,8 @@ var CredentialStoreJwt = class {
 			expMs: expiresAtMs
 		};
 		if (state.kind !== void 0) stateClaim.kind = state.kind;
-		if (state.claims !== void 0) stateClaim.claims = state.claims;
+		const payload = require_payload.credentialPayloadOf(state);
+		if (Object.keys(payload).length > 0) stateClaim.payload = payload;
 		if (state.metadata !== void 0) stateClaim.metadata = state.metadata;
 		if (state.parentCredentialId !== void 0) stateClaim.parentCredentialId = state.parentCredentialId;
 		if (state.rotatedAt !== void 0) stateClaim.rotatedAt = state.rotatedAt;
@@ -273,6 +287,10 @@ var CredentialStoreJwt = class {
 		this.epochs.set(userId, this.clock.now());
 		return 1;
 	}
+	deriveSubkey(label) {
+		if (this.signingKey instanceof Uint8Array) return hkdfSubkey(this.signingKey, label);
+		throw new AuthError("INVALID_CONFIG", "deriveSubkey requires a symmetric (HS*) secret; this JWT store uses an asymmetric key — provide an explicit wfStateSecret");
+	}
 	requireDenylist(op) {
 		if (!this.denylist) throw new AuthError("STATELESS_OPERATION_UNSUPPORTED", `${op} requires a denylist on stateless JWT store`);
 		return this.denylist;
@@ -318,10 +336,10 @@ var CredentialStoreJwt = class {
 			expiresAt
 		};
 		if (stateClaim.kind !== void 0) out.kind = stateClaim.kind;
-		if (stateClaim.claims !== void 0) out.claims = stateClaim.claims;
 		if (stateClaim.metadata !== void 0) out.metadata = stateClaim.metadata;
 		if (stateClaim.parentCredentialId !== void 0) out.parentCredentialId = stateClaim.parentCredentialId;
 		if (stateClaim.rotatedAt !== void 0) out.rotatedAt = stateClaim.rotatedAt;
+		if (stateClaim.payload && typeof stateClaim.payload === "object") Object.assign(out, stateClaim.payload);
 		return out;
 	}
 };
@@ -377,7 +395,7 @@ var CredentialStoreEncapsulated = class {
 		if (opts.secret == null) throw new AuthError("INVALID_CONFIG", "CredentialStoreEncapsulated requires a 'secret'");
 		this.key = deriveKey(opts.secret);
 		this.denylist = opts.denylist;
-		this.clock = opts.clock ?? defaultClock;
+		this.clock = opts.clock ?? require_clock.defaultClock;
 	}
 	async persist(state, ttl) {
 		const jti = (0, node_crypto.randomUUID)();
@@ -432,6 +450,9 @@ var CredentialStoreEncapsulated = class {
 		this.epochs.set(userId, this.clock.now());
 		return 1;
 	}
+	deriveSubkey(label) {
+		return hkdfSubkey(this.key, label);
+	}
 	/**
 	* Reject decrypted payloads whose `issuedAt` predates the user's revocation
 	* epoch. Same-ms mints (`issuedAt === epoch`) are accepted so a workflow can
@@ -449,7 +470,7 @@ var CredentialStoreEncapsulated = class {
 	decrypt(token) {
 		try {
 			const blob = Buffer.from(token, "base64url");
-			if (blob.length < IV_LEN + 1 + TAG_LEN) return null;
+			if (blob.length < 29) return null;
 			const iv = blob.subarray(0, IV_LEN);
 			const authTag = blob.subarray(blob.length - TAG_LEN);
 			const ciphertext = blob.subarray(IV_LEN, blob.length - TAG_LEN);
@@ -489,6 +510,30 @@ function fingerprint(token) {
 	return (0, node_crypto.createHash)("sha256").update(token).digest("hex");
 }
 /**
+* Merge a credential's typed payload under the fixed {@link CredentialState}
+* envelope, asserting the `CredentialState & TPayload` shape in ONE place. The
+* payload is spread first so an envelope field always wins a name clash. Every
+* issue / rotation state builder routes through here so the spread-order
+* invariant and the (irreducible, generic-spread) boundary cast live once.
+*/
+function stateWithPayload(payload, envelope) {
+	return {
+		...payload,
+		...envelope
+	};
+}
+/**
+* Match a session family's semantic kind against a `listSessions({ kind })`
+* filter. No filter ⇒ only ordinary interactive sessions (`"session"`), keeping
+* `cli-session` / `pat` credentials out of the default "active sessions" view.
+* A `"*"` value (a bare string or anywhere in the array) matches every kind.
+*/
+function matchesSessionKind(kind, filter) {
+	if (filter === void 0) return kind === "session";
+	const wanted = Array.isArray(filter) ? filter : [filter];
+	return wanted.includes("*") || wanted.includes(kind);
+}
+/**
 * Orchestrates credential issuance, validation, refresh, and revocation
 * on top of a pluggable {@link CredentialStore}.
 *
@@ -501,9 +546,10 @@ function fingerprint(token) {
 *   tokens stored side-by-side in the same store.
 * - `listForUser` and `maxConcurrent` consider only access-kind credentials,
 *   matching how callers typically display "active sessions".
-* - On detected refresh-reuse-after-grace, the orchestrator best-effort
-*   revokes ALL credentials for the affected user (access + refresh).
-*   This is OAuth-best-practice theft response; documented and intentional.
+* - On detected refresh-reuse, the orchestrator best-effort revokes the
+*   compromised token family (the OAuth-best-practice theft response). Set
+*   `refresh.reuseResponse: 'user'` to escalate to revoking ALL of the user's
+*   sessions. See {@link RefreshConfig.reuseResponse}.
 */
 var AuthCredential = class {
 	store;
@@ -513,6 +559,7 @@ var AuthCredential = class {
 	denylist;
 	maxConcurrent;
 	onLimit;
+	trackLastSeen;
 	clock;
 	/**
 	* Recently-consumed refresh tokens, keyed by the raw refresh token string.
@@ -531,40 +578,51 @@ var AuthCredential = class {
 		this.denylist = opts.denylist;
 		this.maxConcurrent = opts.maxConcurrent;
 		this.onLimit = opts.onLimit ?? "reject";
-		this.clock = opts.clock ?? defaultClock;
+		this.trackLastSeen = opts.trackLastSeen ?? false;
+		this.clock = opts.clock ?? require_clock.defaultClock;
 		if (this.accessTtl <= 0) throw new AuthError("INVALID_CONFIG", `accessTtl must be > 0 (got ${this.accessTtl})`);
 		if (this.refreshConfig && this.refreshConfig.ttl <= 0) throw new AuthError("INVALID_CONFIG", `refresh.ttl must be > 0 (got ${this.refreshConfig.ttl})`);
 	}
 	async issue(userId, options) {
 		if (this.maxConcurrent !== void 0 && this.store.listForUser) await this.enforceConcurrencyLimit(userId);
 		const now = this.clock.now();
-		const accessState = {
+		const { metadata, sessionId: providedSessionId, ttl, expiresAt, kind, ...payload } = options ?? {};
+		const effectiveMetadata = kind !== void 0 ? {
+			...metadata,
+			credentialKind: kind
+		} : metadata;
+		if (ttl !== void 0 && expiresAt !== void 0) throw new AuthError("INVALID_CONFIG", "issue: pass either `ttl` or `expiresAt`, not both");
+		if (ttl !== void 0 && ttl <= 0) throw new AuthError("INVALID_CONFIG", `issue: ttl must be > 0 (got ${ttl})`);
+		const accessExpiresAt = expiresAt ?? now + (ttl ?? this.accessTtl);
+		const accessStoreTtl = accessExpiresAt - now;
+		const sessionId = providedSessionId ?? (0, node_crypto.randomUUID)();
+		const accessState = stateWithPayload(payload, {
 			userId,
 			issuedAt: now,
-			expiresAt: now + this.accessTtl,
+			expiresAt: accessExpiresAt,
 			kind: "access",
-			claims: options?.claims,
-			metadata: options?.metadata
-		};
-		const accessToken = await this.store.persist(accessState, this.accessTtl);
+			metadata: effectiveMetadata,
+			sessionId
+		});
+		const accessToken = await this.store.persist(accessState, accessStoreTtl);
 		let refreshToken;
 		let refreshExpiresAt;
 		if (this.refreshConfig) {
-			const refreshState = {
+			const refreshState = stateWithPayload(payload, {
 				userId,
 				issuedAt: now,
 				expiresAt: now + this.refreshConfig.ttl,
 				kind: "refresh",
-				claims: options?.claims,
-				metadata: options?.metadata
-			};
+				metadata: effectiveMetadata,
+				sessionId
+			});
 			refreshToken = await this.store.persist(refreshState, this.refreshConfig.ttl);
 			refreshExpiresAt = now + this.refreshConfig.ttl;
 		}
 		return {
 			accessToken,
 			refreshToken,
-			accessExpiresAt: now + this.accessTtl,
+			accessExpiresAt,
 			refreshExpiresAt
 		};
 	}
@@ -574,12 +632,14 @@ var AuthCredential = class {
 		if (!state) return null;
 		if (state.expiresAt <= this.clock.now()) return null;
 		if (state.kind === "refresh") return null;
+		if (this.trackLastSeen === "validate" && this.store.touch) await this.store.touch(accessToken, this.clock.now());
 		return {
+			...require_payload.credentialPayloadOf(state),
 			userId: state.userId,
 			method: this.method,
 			credentialId: fingerprint(accessToken),
-			expiresAt: state.expiresAt,
-			claims: state.claims
+			sessionId: this.sessionIdOf(state.sessionId, accessToken),
+			expiresAt: state.expiresAt
 		};
 	}
 	async refresh(refreshToken) {
@@ -595,14 +655,7 @@ var AuthCredential = class {
 		if (oldState.kind !== "refresh") throw new AuthError("INVALID_TOKEN", "Token is not a refresh credential");
 		switch (rotation) {
 			case "none": return await this.refreshNone(oldState, refreshToken, now);
-			case "always":
-				await this.store.consume(refreshToken);
-				this.consumedRefreshes.set(refreshToken, {
-					userId: oldState.userId,
-					iat: oldState.issuedAt,
-					exp: oldState.expiresAt
-				});
-				return await this.issueRotatedPair(oldState, refreshToken, false, now);
+			case "always": return await this.refreshAlways(oldState, refreshToken, now);
 			case "sliding": return await this.refreshSliding(oldState, refreshToken, now);
 			default: throw new AuthError("INVALID_CONFIG", `Unknown rotation: ${String(rotation)}`);
 		}
@@ -616,19 +669,57 @@ var AuthCredential = class {
 			refreshExpiresAt: oldState.expiresAt
 		};
 	}
+	/**
+	* `sliding` rotation: rotate on every use and slide the refresh expiry
+	* forward (rolling session). Grace-tolerant via the shared store-backed
+	* window.
+	*/
 	async refreshSliding(oldState, refreshToken, now) {
-		if (!this.refreshConfig) throw new AuthError("INVALID_CONFIG", "Refresh not enabled");
-		const graceMs = this.refreshConfig.rotationGraceMs ?? DEFAULT_ROTATION_GRACE_MS;
-		if (typeof oldState.rotatedAt !== "number") return await this.issueRotatedPair(oldState, refreshToken, true, now);
-		if (now - oldState.rotatedAt > graceMs) {
-			this.refreshConfig.onRotationReuse?.(oldState);
-			await this.store.revokeAllForUser(oldState.userId);
-			throw new AuthError("REFRESH_REUSE_DETECTED", void 0, {
+		return await this.rotateWithGrace(oldState, refreshToken, now, false);
+	}
+	/**
+	* `always` rotation: rotate on every use but keep a FIXED session ceiling —
+	* each rotated token inherits the family's original `expiresAt` (no sliding).
+	*
+	* On a stateful store this reuses the same store-backed grace window as
+	* `sliding` (so a benign concurrent refresh within grace is NOT mistaken for
+	* theft, even across instances). On a stateless store the old token cannot be
+	* kept valid (`update` re-issues), so it falls back to single-use semantics
+	* with a process-local reuse signal — the only mechanism possible there.
+	*/
+	async refreshAlways(oldState, refreshToken, now) {
+		if (!this.store.listForUser) {
+			await this.store.consume(refreshToken);
+			this.consumedRefreshes.set(refreshToken, {
 				userId: oldState.userId,
-				rotatedAt: oldState.rotatedAt
+				iat: oldState.issuedAt,
+				exp: oldState.expiresAt,
+				...oldState.sessionId !== void 0 && { sessionId: oldState.sessionId }
 			});
+			return await this.issueRotatedPair(oldState, refreshToken, false, now, true);
 		}
-		return await this.issueRotatedPair(oldState, refreshToken, false, now);
+		return await this.rotateWithGrace(oldState, refreshToken, now, true);
+	}
+	/**
+	* Shared rotation-with-grace mechanism for `sliding` and `always` on stateful
+	* stores. Keeps the old refresh valid + stamps `rotatedAt` on first rotation;
+	* within `rotationGraceMs` of that stamp it re-issues a fresh pair WITHOUT
+	* re-rotating (replay-tolerant); beyond grace it treats the re-presentation
+	* as theft. `preserveExpiry` selects fixed-ceiling (`always`) vs sliding
+	* (`sliding`) expiry for the new refresh token.
+	*/
+	async rotateWithGrace(oldState, refreshToken, now, preserveExpiry) {
+		if (!this.refreshConfig) throw new AuthError("INVALID_CONFIG", "Refresh not enabled");
+		const graceMs = this.refreshConfig.rotationGraceMs ?? DEFAULT_ROTATION_GRACE_MS;
+		if (typeof oldState.rotatedAt !== "number") return await this.issueRotatedPair(oldState, refreshToken, true, now, preserveExpiry);
+		if (now - oldState.rotatedAt > graceMs) await this.respondToRefreshReuse({
+			userId: oldState.userId,
+			sessionId: oldState.sessionId,
+			issuedAt: oldState.issuedAt,
+			expiresAt: oldState.expiresAt,
+			rotatedAt: oldState.rotatedAt
+		});
+		return await this.issueRotatedPair(oldState, refreshToken, false, now, preserveExpiry);
 	}
 	async revoke(token) {
 		await this.store.revoke(token);
@@ -639,13 +730,117 @@ var AuthCredential = class {
 	async listForUser(userId) {
 		if (!this.store.listForUser) return [];
 		return (await this.store.listForUser(userId)).filter((entry) => entry.kind !== "refresh").map((entry) => ({
+			...require_payload.credentialPayloadOf(entry),
 			userId: entry.userId,
 			method: this.method,
 			credentialId: fingerprint(entry.token),
-			expiresAt: entry.expiresAt,
-			claims: entry.claims
+			sessionId: this.sessionKeyOf(entry),
+			expiresAt: entry.expiresAt
 		}));
 	}
+	/**
+	* The session id for a credential: its stored `sessionId`, or the token
+	* fingerprint for legacy rows predating sessionId (so they surface as
+	* singleton sessions). The ONE place this fallback rule lives — shared by
+	* `validate()`, `listForUser()`, and the session-family methods so "this
+	* device" matching stays consistent across all of them.
+	*/
+	sessionIdOf(sessionId, token) {
+		return sessionId ?? fingerprint(token);
+	}
+	/** Session-grouping key for a stored credential entry (token attached). */
+	sessionKeyOf(entry) {
+		return this.sessionIdOf(entry.sessionId, entry.token);
+	}
+	/**
+	* List the user's active sessions, one row per token family (access +
+	* refresh + every rotation collapsed by `sessionId`). Newest first by
+	* `lastSeenAt` (or `createdAt` when activity isn't tracked). Returns `[]` for
+	* stores that can't enumerate (stateless JWT/encapsulated). Pass `enrich` to
+	* map each row through a {@link SessionEnricher} (device/location labels).
+	*/
+	async listSessions(userId, opts) {
+		if (!this.store.listForUser) return [];
+		const all = await this.store.listForUser(userId);
+		const families = /* @__PURE__ */ new Map();
+		for (const entry of all) {
+			const key = this.sessionKeyOf(entry);
+			const bucket = families.get(key);
+			if (bucket) bucket.push(entry);
+			else families.set(key, [entry]);
+		}
+		const sessions = [];
+		for (const [sessionId, entries] of families) {
+			let createdAt = Infinity;
+			let lastSeenAt;
+			let refreshExpiresAt;
+			let accessExpiresAt;
+			let metadata;
+			for (const e of entries) {
+				if (e.issuedAt < createdAt) createdAt = e.issuedAt;
+				if (typeof e.lastSeenAt === "number" && (lastSeenAt === void 0 || e.lastSeenAt > lastSeenAt)) lastSeenAt = e.lastSeenAt;
+				if (e.kind === "refresh") {
+					if (refreshExpiresAt === void 0 || e.expiresAt > refreshExpiresAt) refreshExpiresAt = e.expiresAt;
+				} else if (accessExpiresAt === void 0 || e.expiresAt > accessExpiresAt) accessExpiresAt = e.expiresAt;
+				if (!metadata && e.metadata) metadata = e.metadata;
+			}
+			const credentialKind = metadata?.credentialKind;
+			if (!matchesSessionKind(credentialKind ?? "session", opts?.kind)) continue;
+			sessions.push({
+				sessionId,
+				userId,
+				createdAt: createdAt === Infinity ? this.clock.now() : createdAt,
+				expiresAt: refreshExpiresAt ?? accessExpiresAt ?? 0,
+				...lastSeenAt !== void 0 && { lastSeenAt },
+				...metadata && { metadata },
+				...credentialKind !== void 0 && { kind: credentialKind }
+			});
+		}
+		sessions.sort((a, b) => (b.lastSeenAt ?? b.createdAt) - (a.lastSeenAt ?? a.createdAt));
+		if (!opts?.enrich) return sessions;
+		const enrich = opts.enrich;
+		return Promise.all(sessions.map((s) => Promise.resolve(enrich(s))));
+	}
+	/**
+	* Revoke a single session — every token in its family (access + refresh +
+	* rotations). No-op for stores that can't enumerate. Other sessions keep
+	* validating.
+	*/
+	async revokeSession(userId, sessionId) {
+		if (!this.store.listForUser) return;
+		const all = await this.store.listForUser(userId);
+		await Promise.all(all.filter((entry) => this.sessionKeyOf(entry) === sessionId).map((entry) => this.store.revoke(entry.token)));
+	}
+	/**
+	* Revoke every session for the user EXCEPT `keepSessionId` ("log out
+	* everywhere else"). Returns the number of distinct sessions revoked. No-op
+	* (returns 0) for stores that can't enumerate.
+	*/
+	async revokeOtherSessions(userId, keepSessionId) {
+		if (!this.store.listForUser) return 0;
+		const all = await this.store.listForUser(userId);
+		const revokedSessions = /* @__PURE__ */ new Set();
+		const revokes = [];
+		for (const entry of all) {
+			const key = this.sessionKeyOf(entry);
+			if (key === keepSessionId) continue;
+			revokedSessions.add(key);
+			revokes.push(this.store.revoke(entry.token));
+		}
+		await Promise.all(revokes);
+		return revokedSessions.size;
+	}
+	/**
+	* Derive a stable 32-byte key from this credential's underlying store secret,
+	* domain-separated by `label`. Lets adjacent subsystems (e.g. workflow-state
+	* encryption) reuse the auth secret without managing a second one. Throws if
+	* the store has no reusable symmetric secret (stateful/asymmetric) — callers
+	* should then require an explicit secret.
+	*/
+	deriveStateKey(label = "wf-state") {
+		if (!this.store.deriveSubkey) throw new AuthError("INVALID_CONFIG", "credential store has no reusable secret; provide an explicit wfStateSecret");
+		return this.store.deriveSubkey(label);
+	}
 	async enforceConcurrencyLimit(userId) {
 		if (!this.store.listForUser || this.maxConcurrent === void 0) return;
 		const accessOnly = (await this.store.listForUser(userId)).filter((entry) => entry.kind !== "refresh");
@@ -660,32 +855,43 @@ var AuthCredential = class {
 		for (let i = 0; i < toEvict && i < sorted.length; i++) await this.store.revoke(sorted[i].token);
 	}
 	async issueAccessFromRefresh(refreshState, now) {
-		const accessState = {
+		const accessState = stateWithPayload(require_payload.credentialPayloadOf(refreshState), {
 			userId: refreshState.userId,
 			issuedAt: now,
 			expiresAt: now + this.accessTtl,
 			kind: "access",
-			claims: refreshState.claims,
-			metadata: refreshState.metadata
-		};
+			metadata: refreshState.metadata,
+			sessionId: refreshState.sessionId,
+			...this.trackLastSeen === "refresh" && { lastSeenAt: now }
+		});
 		return {
 			token: await this.store.persist(accessState, this.accessTtl),
 			expiresAt: now + this.accessTtl
 		};
 	}
-	async issueRotatedPair(oldRefreshState, oldRefreshToken, rotateOld, now) {
+	/**
+	* Issue a fresh access + refresh pair off an existing refresh credential.
+	* `preserveExpiry` keeps the family's original refresh `expiresAt` (a fixed
+	* session ceiling, used by `always`); otherwise the new refresh slides to
+	* `now + ttl` (used by `sliding`). `rotateOld` stamps the old refresh as
+	* rotated (keeping it valid through the grace window) instead of consuming it.
+	*/
+	async issueRotatedPair(oldRefreshState, oldRefreshToken, rotateOld, now, preserveExpiry = false) {
 		if (!this.refreshConfig) throw new AuthError("INVALID_CONFIG", "Refresh not enabled");
 		const access = await this.issueAccessFromRefresh(oldRefreshState, now);
-		const newRefreshState = {
+		const refreshExpiresAt = preserveExpiry ? oldRefreshState.expiresAt : now + this.refreshConfig.ttl;
+		const refreshTtl = preserveExpiry ? Math.max(0, oldRefreshState.expiresAt - now) : this.refreshConfig.ttl;
+		const newRefreshState = stateWithPayload(require_payload.credentialPayloadOf(oldRefreshState), {
 			userId: oldRefreshState.userId,
 			issuedAt: now,
-			expiresAt: now + this.refreshConfig.ttl,
+			expiresAt: refreshExpiresAt,
 			kind: "refresh",
-			claims: oldRefreshState.claims,
 			metadata: oldRefreshState.metadata,
-			parentCredentialId: oldRefreshToken
-		};
-		const newRefreshToken = await this.store.persist(newRefreshState, this.refreshConfig.ttl);
+			parentCredentialId: oldRefreshToken,
+			sessionId: oldRefreshState.sessionId,
+			...this.trackLastSeen === "refresh" && { lastSeenAt: now }
+		});
+		const newRefreshToken = await this.store.persist(newRefreshState, refreshTtl);
 		if (rotateOld) {
 			const rotatedState = {
 				...oldRefreshState,
@@ -697,7 +903,7 @@ var AuthCredential = class {
 			accessToken: access.token,
 			accessExpiresAt: access.expiresAt,
 			refreshToken: newRefreshToken,
-			refreshExpiresAt: now + this.refreshConfig.ttl
+			refreshExpiresAt
 		};
 	}
 	lookupConsumedRefresh(token) {
@@ -710,15 +916,38 @@ var AuthCredential = class {
 		return entry;
 	}
 	async fireRefreshReuseTheftResponse(consumed, refreshToken) {
-		this.refreshConfig?.onRotationReuse?.({
+		this.consumedRefreshes.delete(refreshToken);
+		await this.respondToRefreshReuse({
 			userId: consumed.userId,
+			sessionId: consumed.sessionId,
 			issuedAt: consumed.iat,
-			expiresAt: consumed.exp,
-			kind: "refresh"
+			expiresAt: consumed.exp
+		});
+	}
+	/**
+	* Best-effort theft response for a detected refresh-token reuse. Fires the
+	* `onRotationReuse` hook, then revokes per {@link RefreshConfig.reuseResponse}:
+	* the compromised token family (`'session'`, default) or every session for
+	* the user (`'user'`). Falls back to user-wide revocation when the session
+	* can't be targeted (no `sessionId`, or a store that can't enumerate
+	* sessions). Always throws `REFRESH_REUSE_DETECTED`.
+	*/
+	async respondToRefreshReuse(reuse) {
+		this.refreshConfig?.onRotationReuse?.({
+			userId: reuse.userId,
+			issuedAt: reuse.issuedAt,
+			expiresAt: reuse.expiresAt,
+			kind: "refresh",
+			...reuse.sessionId !== void 0 && { sessionId: reuse.sessionId },
+			...reuse.rotatedAt !== void 0 && { rotatedAt: reuse.rotatedAt }
+		});
+		if ((this.refreshConfig?.reuseResponse ?? "session") === "session" && reuse.sessionId !== void 0 && this.store.listForUser) await this.revokeSession(reuse.userId, reuse.sessionId);
+		else await this.store.revokeAllForUser(reuse.userId);
+		throw new AuthError("REFRESH_REUSE_DETECTED", void 0, {
+			userId: reuse.userId,
+			...reuse.sessionId !== void 0 && { sessionId: reuse.sessionId },
+			...reuse.rotatedAt !== void 0 && { rotatedAt: reuse.rotatedAt }
 		});
-		await this.store.revokeAllForUser(consumed.userId);
-		this.consumedRefreshes.delete(refreshToken);
-		throw new AuthError("REFRESH_REUSE_DETECTED", void 0, { userId: consumed.userId });
 	}
 };
 //#endregion
@@ -737,5 +966,5 @@ exports.CredentialStoreEncapsulated = CredentialStoreEncapsulated;
 exports.CredentialStoreJwt = CredentialStoreJwt;
 exports.CredentialStoreMemory = CredentialStoreMemory;
 exports.DenylistStoreMemory = DenylistStoreMemory;
-exports.defaultClock = defaultClock;
+exports.defaultClock = require_clock.defaultClock;
 exports.generateMagicLinkToken = generateMagicLinkToken;