@aooth/auth 0.1.6 → 0.1.8

package/dist/index.mjs

@@ -1,4 +1,6 @@
-import { createCipheriv, createDecipheriv, createHash, randomBytes, randomUUID, scryptSync } from "node:crypto";
+import { t as defaultClock } from "./clock-Bdsep_1j.mjs";
+import { t as credentialPayloadOf } from "./payload-D-DzH5-J.mjs";
+import { createCipheriv, createDecipheriv, createHash, hkdfSync, randomBytes, randomUUID, scryptSync } from "node:crypto";
 import { SignJWT, jwtVerify } from "jose";
 //#region src/errors.ts
 const defaultMessages = {
@@ -11,6 +13,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]);
@@ -19,9 +23,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.
@@ -78,6 +79,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;
@@ -168,6 +174,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(hkdfSync("sha256", ikm, SUBKEY_SALT, Buffer.from(label, "utf8"), 32));
+}
+//#endregion
 //#region src/stores/jwt.ts
 const HS_ALGS = new Set([
 	"HS256",
@@ -226,7 +239,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 = 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;
@@ -272,6 +286,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;
@@ -317,10 +335,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;
 	}
 };
@@ -431,6 +449,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
@@ -448,7 +469,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);
@@ -488,6 +509,30 @@ function fingerprint(token) {
 	return 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}.
 *
@@ -500,9 +545,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;
@@ -512,6 +558,7 @@ var AuthCredential = class {
 	denylist;
 	maxConcurrent;
 	onLimit;
+	trackLastSeen;
 	clock;
 	/**
 	* Recently-consumed refresh tokens, keyed by the raw refresh token string.
@@ -530,6 +577,7 @@ var AuthCredential = class {
 		this.denylist = opts.denylist;
 		this.maxConcurrent = opts.maxConcurrent;
 		this.onLimit = opts.onLimit ?? "reject";
+		this.trackLastSeen = opts.trackLastSeen ?? false;
 		this.clock = opts.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})`);
@@ -537,33 +585,43 @@ var AuthCredential = class {
 	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 ?? 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
 		};
 	}
@@ -573,12 +631,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 {
+			...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) {
@@ -594,14 +654,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)}`);
 		}
@@ -615,19 +668,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);
@@ -638,13 +729,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) => ({
+			...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");
@@ -659,32 +854,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(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(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,
@@ -696,7 +902,7 @@ var AuthCredential = class {
 			accessToken: access.token,
 			accessExpiresAt: access.expiresAt,
 			refreshToken: newRefreshToken,
-			refreshExpiresAt: now + this.refreshConfig.ttl
+			refreshExpiresAt
 		};
 	}
 	lookupConsumedRefresh(token) {
@@ -709,15 +915,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

package/dist/payload-BJjvj8AH.cjs

@@ -0,0 +1,32 @@
+//#region src/credential/payload.ts
+const ENVELOPE_KEYS = new Set(Object.keys({
+	userId: true,
+	issuedAt: true,
+	expiresAt: true,
+	metadata: true,
+	kind: true,
+	parentCredentialId: true,
+	rotatedAt: true,
+	sessionId: true,
+	lastSeenAt: true,
+	token: true
+}));
+/**
+* Extract a credential's typed payload — every own enumerable key that is not a
+* reserved {@link CredentialState} envelope key. Used by the field-mapping
+* stores (JWT codec, atscript-db row adapter) to round-trip customer root
+* fields, and by the orchestrator to surface them on `AuthContext` without
+* leaking envelope internals (e.g. `parentCredentialId`).
+*/
+function credentialPayloadOf(state) {
+	const out = {};
+	for (const [key, value] of Object.entries(state)) if (!ENVELOPE_KEYS.has(key)) out[key] = value;
+	return out;
+}
+//#endregion
+Object.defineProperty(exports, "credentialPayloadOf", {
+	enumerable: true,
+	get: function() {
+		return credentialPayloadOf;
+	}
+});

package/dist/payload-D-DzH5-J.mjs

@@ -0,0 +1,27 @@
+//#region src/credential/payload.ts
+const ENVELOPE_KEYS = new Set(Object.keys({
+	userId: true,
+	issuedAt: true,
+	expiresAt: true,
+	metadata: true,
+	kind: true,
+	parentCredentialId: true,
+	rotatedAt: true,
+	sessionId: true,
+	lastSeenAt: true,
+	token: true
+}));
+/**
+* Extract a credential's typed payload — every own enumerable key that is not a
+* reserved {@link CredentialState} envelope key. Used by the field-mapping
+* stores (JWT codec, atscript-db row adapter) to round-trip customer root
+* fields, and by the orchestrator to surface them on `AuthContext` without
+* leaking envelope internals (e.g. `parentCredentialId`).
+*/
+function credentialPayloadOf(state) {
+	const out = {};
+	for (const [key, value] of Object.entries(state)) if (!ENVELOPE_KEYS.has(key)) out[key] = value;
+	return out;
+}
+//#endregion
+export { credentialPayloadOf as t };

package/dist/redis.cjs

@@ -74,6 +74,15 @@ var CredentialStoreRedis = class {
 		await this.redis.del(this.tokenKey(token));
 		await this.redis.srem(this.userKey(state.userId), token);
 	}
+	async touch(token, at) {
+		const raw = await this.redis.get(this.tokenKey(token));
+		if (raw === null) return;
+		const state = JSON.parse(raw);
+		state.lastSeenAt = at;
+		const ttlMs = Math.max(0, state.expiresAt - Date.now());
+		if (ttlMs <= 0) return;
+		await this.redis.set(this.tokenKey(token), JSON.stringify(state), "PX", ttlMs);
+	}
 	async revokeAllForUser(userId) {
 		const setKey = this.userKey(userId);
 		const tokens = await this.redis.smembers(setKey);

package/dist/redis.d.cts

@@ -1,4 +1,4 @@
-import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-untAtWQz.cjs";
+import { a as CredentialState, n as DenylistStore, t as CredentialStore } from "./store-BG6m6oSJ.cjs";
 
 //#region src/redis/index.d.ts
 /**
@@ -52,19 +52,20 @@ interface RedisCredentialStoreOptions {
  * so Redis evicts it on expiry. The user-index set is NOT TTL-bounded — we
  * lazily prune dead members on `listForUser` and `revokeAllForUser`.
  */
-declare class CredentialStoreRedis<TClaims extends object = object> implements CredentialStore<TClaims> {
+declare class CredentialStoreRedis<TPayload extends object = object> implements CredentialStore<TPayload> {
   private readonly redis;
   private readonly prefix;
   constructor(opts: RedisCredentialStoreOptions);
   private tokenKey;
   private userKey;
-  persist(state: CredentialState<TClaims>, ttl?: number): Promise<string>;
-  retrieve(token: string): Promise<CredentialState<TClaims> | null>;
-  consume(token: string): Promise<CredentialState<TClaims> | null>;
-  update(token: string, state: CredentialState<TClaims>): Promise<string>;
+  persist(state: CredentialState & TPayload, ttl?: number): Promise<string>;
+  retrieve(token: string): Promise<(CredentialState & TPayload) | null>;
+  consume(token: string): Promise<(CredentialState & TPayload) | null>;
+  update(token: string, state: CredentialState & TPayload): Promise<string>;
   revoke(token: string): Promise<void>;
+  touch(token: string, at: number): Promise<void>;
   revokeAllForUser(userId: string): Promise<number>;
-  listForUser(userId: string): Promise<Array<CredentialState<TClaims> & {
+  listForUser(userId: string): Promise<Array<CredentialState & TPayload & {
     token: string;
   }>>;
 }