@pithy-sh/auth 0.1.0

package/src/token/rotation.ts

@@ -0,0 +1,104 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { RotatedToken } from "../data/rotatedToken";
+import type { AuthDatabase } from "../data/tables";
+
+/**
+ * Refresh-token rotation primitives: the atomic consume that makes rotation race-safe, and the
+ * reuse-detection ledger that turns a replayed refresh token into a family-wide revocation
+ * (OAuth refresh rotation, RFC 6819 §5.2.2.3). The HTTP route (`http/routes.ts`) composes these; they
+ * stay here as small, directly testable units over the shared Kysely.
+ */
+
+/** The outcome of consuming a session: whether THIS call removed the row, and the consumed family. */
+export interface ConsumeResult {
+  /** True when this call deleted the session row — the single winner of a concurrent rotation. */
+  won: boolean;
+  /** The consumed session's family id, or null when it had none (a fresh, never-rotated session). */
+  familyId: string | null;
+}
+
+/**
+ * Atomically consume a live session by its token. The conditional `DELETE ... RETURNING` is the single
+ * race gate: of N concurrent rotations presenting the same token, exactly one deletes the row and sees
+ * `won: true`; the rest see `won: false` and must not mint a successor. One presented token yields one
+ * successor.
+ */
+export async function consumeSession(db: AuthDatabase, token: string): Promise<ConsumeResult> {
+  const row = await db
+    .deleteFrom("pithyAuthSessions")
+    .where("token", "=", token)
+    .returning("familyId")
+    .executeTakeFirst();
+  return row ? { won: true, familyId: row.familyId ?? null } : { won: false, familyId: null };
+}
+
+/**
+ * Record a consumed token in the reuse-detection ledger, tagged with the family it belonged to. Idempotent
+ * on the token PK — a redundant record (e.g. a retried write) is a no-op, never an error.
+ */
+export async function recordConsumedToken(
+  db: AuthDatabase,
+  entry: { token: string; familyId: string; userId: string; rotatedAt: Date },
+): Promise<void> {
+  await db
+    .insertInto("pithyAuthRotatedTokens")
+    .values(RotatedToken.encode(entry))
+    .onConflict((oc) => oc.column("token").doNothing())
+    .execute();
+}
+
+/**
+ * The family/owner a consumed token belonged to and when it was consumed, or null when the token was
+ * never consumed. `rotatedAt` lets the caller tell a benign concurrent/retried rotation (a fresh
+ * consume) from a genuinely replayed refresh token (an old one).
+ */
+export async function findConsumedToken(
+  db: AuthDatabase,
+  token: string,
+): Promise<{ familyId: string; userId: string; rotatedAt: Date } | null> {
+  const row = await db
+    .selectFrom("pithyAuthRotatedTokens")
+    .select(["familyId", "userId", "rotatedAt"])
+    .where("token", "=", token)
+    .executeTakeFirst();
+  return row ? { familyId: row.familyId, userId: row.userId, rotatedAt: SQLiteDate.parse(row.rotatedAt) } : null;
+}
+
+/** The tokens of every live session in a family — the set a family revocation must sign out. */
+export async function familySessionTokens(db: AuthDatabase, familyId: string): Promise<string[]> {
+  const rows = await db.selectFrom("pithyAuthSessions").select("token").where("familyId", "=", familyId).execute();
+  return rows.map((row) => row.token);
+}
+
+/**
+ * Revoke an entire refresh-token family: sign out every live session sharing the id. Deletion goes
+ * through Better Auth's `deleteSession` (injected) so any adapter-side bookkeeping stays consistent —
+ * the same path device-revoke uses. Returns the number of sessions revoked.
+ */
+export async function revokeFamily(
+  db: AuthDatabase,
+  familyId: string,
+  deleteSession: (token: string) => Promise<unknown>,
+): Promise<number> {
+  const tokens = await familySessionTokens(db, familyId);
+  for (const token of tokens) {
+    await deleteSession(token);
+  }
+  return tokens.length;
+}
+
+/**
+ * Prune ledger entries consumed before `cutoff`, bounding the table's growth. A token consumed longer
+ * ago than a full session lifetime can no longer match any live session, so its reuse-detection value
+ * has lapsed. The `rotatedAt` index keeps this an index range delete. Returns the number of rows removed.
+ */
+export async function pruneConsumedTokens(db: AuthDatabase, cutoff: Date): Promise<number> {
+  const result = await db
+    .deleteFrom("pithyAuthRotatedTokens")
+    .where("rotatedAt", "<", SQLiteDate.encode(cutoff))
+    .executeTakeFirst();
+  return Number(result.numDeletedRows ?? 0n);
+}

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/auth knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/auth";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";