@opengeni/api-router 0.30.3 → 1.0.0

package/src/artifact-catalog-cursor.ts

@@ -0,0 +1,60 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import { ArtifactCatalogKind } from "@opengeni/contracts";
+import { HTTPException } from "hono/http-exception";
+import { z } from "zod";
+
+const Cursor = z
+  .object({
+    version: z.literal(1),
+    snapshotAt: z.string().datetime(),
+    expiresAt: z.number().int().positive(),
+    after: z
+      .object({
+        key: z.string().max(4096),
+        kind: ArtifactCatalogKind,
+        id: z.string().min(1).max(128),
+      })
+      .strict(),
+  })
+  .strict();
+export type ArtifactCatalogCursor = z.infer<typeof Cursor>;
+
+/** Encrypted as well as authenticated: a scan frontier may name a denied row.
+ * Binding includes principal, workspace, owner context, permissions and filters.
+ */
+export function artifactCatalogCursorCodec(secret: string, binding: string) {
+  const key = createHash("sha256").update("opengeni:artifact-catalog:v1\0").update(secret).digest();
+  const aad = createHash("sha256").update(binding).digest();
+  return {
+    encode(value: ArtifactCatalogCursor): string {
+      const iv = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", key, iv);
+      cipher.setAAD(aad);
+      const bytes = Buffer.concat([
+        cipher.update(JSON.stringify(Cursor.parse(value)), "utf8"),
+        cipher.final(),
+      ]);
+      return Buffer.concat([iv, cipher.getAuthTag(), bytes]).toString("base64url");
+    },
+    decode(value: string): ArtifactCatalogCursor {
+      try {
+        if (value.length > 8192 || !/^[A-Za-z0-9_-]+$/.test(value)) throw new Error();
+        const bytes = Buffer.from(value, "base64url");
+        if (bytes.length < 29 || bytes.toString("base64url") !== value) throw new Error();
+        const decipher = createDecipheriv("aes-256-gcm", key, bytes.subarray(0, 12));
+        decipher.setAAD(aad);
+        decipher.setAuthTag(bytes.subarray(12, 28));
+        const parsed = Cursor.parse(
+          JSON.parse(
+            Buffer.concat([decipher.update(bytes.subarray(28)), decipher.final()]).toString("utf8"),
+          ),
+        );
+        if (parsed.expiresAt <= Date.now() || Date.parse(parsed.snapshotAt) > Date.now() + 60_000)
+          throw new Error();
+        return parsed;
+      } catch {
+        throw new HTTPException(422, { message: "Invalid or expired artifact catalog cursor" });
+      }
+    },
+  };
+}

package/src/auth/managed-auth-attempt-context.ts

@@ -0,0 +1,70 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+type ManagedAuthAttemptContext =
+  | {
+      kind: "isolated_transaction";
+      transactionId: string;
+      providerId: "credential" | "google" | "github";
+      createdAuthSessionId: string | null;
+    }
+  | { kind: "provider"; providerId: "credential" | "google" | "github" }
+  | { kind: "discard_provider_session" };
+
+const managedAuthAttemptStorage = new AsyncLocalStorage<ManagedAuthAttemptContext>();
+const managedLinkIntentStorage = new AsyncLocalStorage<string>();
+
+export function runManagedSignInConnect<T>(intentId: string, action: () => T): T {
+  return managedLinkIntentStorage.run(intentId, action);
+}
+
+export function currentManagedSignInConnectIntent(): string | undefined {
+  return managedLinkIntentStorage.getStore();
+}
+
+export function runManagedAuthAttempt<T>(
+  transactionId: string,
+  providerId: "credential" | "google" | "github",
+  action: () => T,
+): T {
+  return managedAuthAttemptStorage.run(
+    { kind: "isolated_transaction", transactionId, providerId, createdAuthSessionId: null },
+    action,
+  );
+}
+
+export function runManagedAuthProvider<T>(
+  providerId: "credential" | "google" | "github",
+  action: () => T,
+): T {
+  return managedAuthAttemptStorage.run({ kind: "provider", providerId }, action);
+}
+
+export function runManagedAuthDiscardedProviderSession<T>(action: () => T): T {
+  return managedAuthAttemptStorage.run({ kind: "discard_provider_session" }, action);
+}
+
+export function currentManagedAuthAttemptId(): string | null {
+  const context = managedAuthAttemptStorage.getStore();
+  return context?.kind === "isolated_transaction" ? context.transactionId : null;
+}
+
+export function currentManagedAuthProviderId(): "credential" | "google" | "github" {
+  const context = managedAuthAttemptStorage.getStore();
+  return context?.kind === "isolated_transaction" || context?.kind === "provider"
+    ? context.providerId
+    : "credential";
+}
+
+export function recordCurrentManagedAuthSession(authSessionId: string): void {
+  const context = managedAuthAttemptStorage.getStore();
+  if (context?.kind === "isolated_transaction") context.createdAuthSessionId = authSessionId;
+}
+
+export function currentManagedAuthCreatedSessionId(): string | null {
+  const context = managedAuthAttemptStorage.getStore();
+  return context?.kind === "isolated_transaction" ? context.createdAuthSessionId : null;
+}
+
+export function shouldDiscardCurrentManagedAuthProviderSession(): boolean {
+  return managedAuthAttemptStorage.getStore()?.kind === "discard_provider_session";
+}

package/src/auth/managed-auth-rate-limits.ts

@@ -0,0 +1,252 @@
+import { createHmac } from "node:crypto";
+import { isIP } from "node:net";
+import type { Database } from "@opengeni/db";
+import { APIError, createAuthMiddleware } from "better-auth/api";
+import { sql } from "drizzle-orm";
+
+import {
+  requestSourceRateLimitKey,
+  TRUSTED_CLIENT_ADDRESS_HEADER,
+  UNKNOWN_REQUEST_SOURCE_ADDRESS,
+} from "../http/request-source";
+
+export type ManagedAuthClientRateLimitRule = { window: number; max: number };
+
+/**
+ * Better Auth's per-client-address limits, keyed by endpoint path relative to
+ * `/v1/auth`. The client address is the trusted source address stamped by the
+ * API (see `TRUSTED_CLIENT_ADDRESS_HEADER`), never a caller-supplied header.
+ *
+ * Better Auth keys each counter on `(client address, path)` and resets it only
+ * after `window` seconds pass without an admitted request. Its database store
+ * prunes rows idle for longer than 60 s, so no window here exceeds 60 s; a
+ * longer window would silently shrink to that pruning horizon. The limits are
+ * sized for launch traffic that shares one address (office and carrier NAT)
+ * while bounding scripted credential guessing and mail sending from one
+ * source. Per-email throttles below cap the same abuse across many addresses.
+ *
+ * Email sign-in and sign-up allow 20 per minute, at least Better Auth's
+ * previous default (3 per 10 s, about 18 per minute). Until the edge forwards
+ * real client addresses (for example ingress-nginx behind a cloud load
+ * balancer with `externalTrafficPolicy: Cluster`), every user shares a few
+ * node addresses, and these two limits then bound the whole deployment's
+ * email sign-in and sign-up rate; they must not fall below that default.
+ */
+export const MANAGED_AUTH_CLIENT_RATE_LIMIT_RULES = {
+  "/sign-in/email": { window: 60, max: 20 },
+  "/sign-up/email": { window: 60, max: 20 },
+  "/sign-in/social": { window: 60, max: 20 },
+  "/callback/*": { window: 60, max: 30 },
+  "/request-password-reset": { window: 60, max: 5 },
+  "/send-verification-email": { window: 60, max: 5 },
+  "/verify-email": { window: 60, max: 20 },
+  "/reset-password": { window: 60, max: 10 },
+  "/reset-password/*": { window: 60, max: 20 },
+} as const satisfies Record<string, ManagedAuthClientRateLimitRule>;
+
+export type ManagedAuthEmailThrottle = {
+  purpose: "sign_in" | "sign_up" | "password_reset" | "verification_email";
+  windowSeconds: number;
+  /** Attempts one client address (an IPv6 /64) may make against one email. */
+  perSourceMax: number;
+  /** Attempts all client addresses together may make against one email. */
+  perEmailMax: number;
+};
+
+/**
+ * Per-email throttles for the endpoints that verify a password or send mail
+ * to an address. They bound password guessing against one account and mail
+ * bombing of one inbox regardless of how many client addresses an attacker
+ * rotates through. Every attempt counts, including successful sign-ins.
+ *
+ * Each email has two fixed windows. The tight one is per (email, client
+ * address); an attempt it refuses never reaches the looser per-email window.
+ * One source can therefore spend only its own share of an email's budget:
+ * locking a person out of email/password sign-in, sign-up, password reset, or
+ * verification mail takes at least `perEmailMax / perSourceMax` (5) distinct
+ * client addresses (IPv6: /64 blocks) inside the window, while one address
+ * can exhaust that email's budget only for requests from the same address.
+ * Social sign-in is never throttled per email. The accepted cost is that a
+ * distributed attacker may make up to `perEmailMax` attempts per window
+ * against one email, and can deny that email's password sign-in for the rest
+ * of the window once it spends them.
+ */
+export const MANAGED_AUTH_EMAIL_THROTTLES = {
+  "/sign-in/email": {
+    purpose: "sign_in",
+    windowSeconds: 15 * 60,
+    perSourceMax: 10,
+    perEmailMax: 50,
+  },
+  "/sign-up/email": {
+    purpose: "sign_up",
+    windowSeconds: 60 * 60,
+    perSourceMax: 5,
+    perEmailMax: 25,
+  },
+  "/request-password-reset": {
+    purpose: "password_reset",
+    windowSeconds: 60 * 60,
+    perSourceMax: 5,
+    perEmailMax: 25,
+  },
+  "/send-verification-email": {
+    purpose: "verification_email",
+    windowSeconds: 60 * 60,
+    perSourceMax: 5,
+    perEmailMax: 25,
+  },
+} as const satisfies Record<string, ManagedAuthEmailThrottle>;
+
+export const MANAGED_AUTH_EMAIL_THROTTLE_KEY_PREFIX = "opengeni:email-throttle:v1:";
+
+/** A per-email throttle refusal; an ordinary Better Auth 429 on the wire. */
+export class ManagedAuthEmailThrottleError extends APIError {
+  readonly retryAfterSeconds: number;
+
+  constructor(retryAfterSeconds: number) {
+    super(
+      "TOO_MANY_REQUESTS",
+      { code: "TOO_MANY_REQUESTS", message: "Too many requests. Please try again later." },
+      { "X-Retry-After": String(retryAfterSeconds) },
+    );
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+}
+
+export function managedAuthEmailThrottleFor(path: string): ManagedAuthEmailThrottle | null {
+  return Object.hasOwn(MANAGED_AUTH_EMAIL_THROTTLES, path)
+    ? MANAGED_AUTH_EMAIL_THROTTLES[path as keyof typeof MANAGED_AUTH_EMAIL_THROTTLES]
+    : null;
+}
+
+/**
+ * Content-free counter key for one email. The address is normalized the way
+ * Better Auth stores it and keyed-hashed so the rate-limit table never holds
+ * an email.
+ */
+export function managedAuthEmailThrottleKey(
+  secret: string,
+  purpose: ManagedAuthEmailThrottle["purpose"],
+  email: string,
+): string {
+  const digest = createHmac("sha256", secret)
+    .update(`opengeni:managed-auth:email-throttle:v1\n${purpose}\n${normalizedEmail(email)}`)
+    .digest("hex");
+  return `${MANAGED_AUTH_EMAIL_THROTTLE_KEY_PREFIX}${purpose}:${digest}`;
+}
+
+/**
+ * Content-free counter key for one (email, client address) pair; `source` is
+ * a {@link requestSourceRateLimitKey}. Neither value is stored.
+ */
+export function managedAuthEmailSourceThrottleKey(
+  secret: string,
+  purpose: ManagedAuthEmailThrottle["purpose"],
+  email: string,
+  source: string,
+): string {
+  const digest = createHmac("sha256", secret)
+    .update(
+      `opengeni:managed-auth:email-source-throttle:v1\n${purpose}\n${normalizedEmail(email)}\n${source}`,
+    )
+    .digest("hex");
+  return `${MANAGED_AUTH_EMAIL_THROTTLE_KEY_PREFIX}${purpose}:source:${digest}`;
+}
+
+/**
+ * The limiter source for a Better Auth request: the trusted address the API
+ * stamped on it, as a rate-limit key. The API strips caller-supplied copies,
+ * so a request without one (an in-process call without a transport peer)
+ * shares the unknown-source bucket.
+ */
+export function managedAuthThrottleSource(headers: Headers | null | undefined): string {
+  const stamped = headers?.get(TRUSTED_CLIENT_ADDRESS_HEADER)?.trim();
+  return stamped && isIP(stamped) !== 0
+    ? requestSourceRateLimitKey(stamped.toLowerCase())
+    : UNKNOWN_REQUEST_SOURCE_ADDRESS;
+}
+
+function normalizedEmail(email: string): string {
+  return email.trim().toLowerCase();
+}
+
+/**
+ * Atomically count one attempt in a fixed window shared by every API replica.
+ *
+ * Rows live in Better Auth's `auth_rate_limits` table. For these keys
+ * `last_request` holds the window deadline (epoch milliseconds) rather than
+ * the last request time: Better Auth prunes rows whose `last_request` is more
+ * than 60 s in the past, so storing the deadline keeps an active window alive
+ * and lets pruning reclaim it 60 s after it expires. Database time is the only
+ * clock, so replicas with skewed clocks agree.
+ */
+export async function consumeManagedAuthEmailThrottle(
+  db: Pick<Database, "execute">,
+  input: { key: string; windowSeconds: number; max: number },
+): Promise<{ allowed: boolean; retryAfterSeconds: number }> {
+  const windowMs = input.windowSeconds * 1_000;
+  const result = await db.execute(sql`
+    insert into auth_rate_limits as bucket (id, key, count, last_request)
+    values (
+      ${input.key},
+      ${input.key},
+      1,
+      floor(extract(epoch from clock_timestamp()) * 1000)::bigint + ${windowMs}::bigint
+    )
+    on conflict (key) do update set
+      count = case
+        when bucket.last_request <= excluded.last_request - ${windowMs}::bigint then 1
+        else least(bucket.count + 1, ${input.max + 1}::integer)
+      end,
+      last_request = case
+        when bucket.last_request <= excluded.last_request - ${windowMs}::bigint
+          then excluded.last_request
+        else bucket.last_request
+      end
+    returning
+      bucket.count as count,
+      greatest(
+        1,
+        ceil((bucket.last_request - extract(epoch from clock_timestamp()) * 1000) / 1000.0)
+      )::integer as retry_after_seconds
+  `);
+  const rows = (Array.isArray(result) ? result : (result as { rows?: unknown[] }).rows) as
+    | Array<{ count: number | string; retry_after_seconds: number | string }>
+    | undefined;
+  const row = rows?.[0];
+  if (!row) throw new Error("managed auth email throttle returned no row");
+  return {
+    allowed: Number(row.count) <= input.max,
+    retryAfterSeconds: Number(row.retry_after_seconds),
+  };
+}
+
+/**
+ * Better Auth `hooks.before` middleware. It runs after Better Auth's own
+ * per-client-address limiter and for both HTTP requests and server-side
+ * `auth.api.*` calls, so the product session-set sign-in is covered too. The
+ * per-(email, address) window is consumed first; only an attempt it admits
+ * counts toward the email's shared window.
+ */
+export function createManagedAuthEmailThrottleHook(db: Pick<Database, "execute">, secret: string) {
+  return createAuthMiddleware(async (ctx) => {
+    const throttle = managedAuthEmailThrottleFor(ctx.path);
+    if (!throttle) return;
+    const email = (ctx.body as { email?: unknown } | undefined)?.email;
+    if (typeof email !== "string" || !email.trim()) return;
+    const source = managedAuthThrottleSource(ctx.headers);
+    const perSource = await consumeManagedAuthEmailThrottle(db, {
+      key: managedAuthEmailSourceThrottleKey(secret, throttle.purpose, email, source),
+      windowSeconds: throttle.windowSeconds,
+      max: throttle.perSourceMax,
+    });
+    if (!perSource.allowed) throw new ManagedAuthEmailThrottleError(perSource.retryAfterSeconds);
+    const perEmail = await consumeManagedAuthEmailThrottle(db, {
+      key: managedAuthEmailThrottleKey(secret, throttle.purpose, email),
+      windowSeconds: throttle.windowSeconds,
+      max: throttle.perEmailMax,
+    });
+    if (!perEmail.allowed) throw new ManagedAuthEmailThrottleError(perEmail.retryAfterSeconds);
+  });
+}

package/src/auth/managed-auth-session-adapter.ts

@@ -0,0 +1,222 @@
+import type {
+  ManagedAuthResolvedSession,
+  ManagedAuthSessionAdapter,
+} from "@opengeni/core/managed-auth-session-sets";
+import { sql } from "drizzle-orm";
+import type { Database } from "@opengeni/db";
+import { assertManagedUserAdmission, type ManagedAuth } from "@opengeni/core";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { runManagedAuthAttempt } from "./managed-auth-attempt-context";
+
+/** Server-only proof for a product-owned endpoint; never returned to a browser. */
+export async function managedAuthSelectedProofHeaders(
+  auth: ManagedAuth,
+  token: string,
+): Promise<Headers> {
+  const context = await auth.$context;
+  return new Headers({
+    cookie: `${context.authCookies.sessionToken.name}=${signedCookieValue(token, context.secret)}`,
+  });
+}
+
+export function createBetterAuthSessionAdapter(
+  auth: ManagedAuth,
+  db: Database,
+): ManagedAuthSessionAdapter {
+  return {
+    async authenticate(input) {
+      if (input.provider !== "email_password") {
+        throw new Error("unsupported managed authentication provider");
+      }
+      const result = await runManagedAuthAttempt(
+        input.transactionId,
+        "credential",
+        async () =>
+          await auth.api.signInEmail({
+            body: {
+              email: input.credentials.email,
+              password: input.credentials.password,
+              rememberMe: true,
+            },
+            headers: input.headers,
+            returnHeaders: true,
+          }),
+      );
+      const token = result.response?.token;
+      if (typeof token !== "string") {
+        throw new Error("managed authentication did not create an isolated session");
+      }
+      const resolved = await (await auth.$context).internalAdapter.findSession(token);
+      if (!resolved?.session?.id) {
+        throw new Error("managed authentication session could not be resolved");
+      }
+      return { authSessionId: resolved.session.id };
+    },
+
+    async resolveSelectedSession(input): Promise<ManagedAuthResolvedSession | null> {
+      const resolved = await (await auth.$context).internalAdapter.findSession(input.token);
+      const session = liveResolvedSession(resolved);
+      assertManagedUserAdmission(auth, session?.user);
+      return session;
+    },
+
+    async resolveAmbientSession(headers): Promise<ManagedAuthResolvedSession | null> {
+      const context = await auth.$context;
+      const signed = cookieValue(headers.get("cookie"), context.authCookies.sessionToken.name);
+      const token = signed ? verifiedSignedCookieValue(signed, context.secret) : null;
+      if (!token) return null;
+      const resolved = await context.internalAdapter.findSession(token);
+      const session = liveResolvedSession(resolved);
+      assertManagedUserAdmission(auth, session?.user);
+      return session;
+    },
+
+    async refreshSelectedSession(input): Promise<ManagedAuthResolvedSession | null> {
+      const context = await auth.$context;
+      const cookie = context.authCookies.sessionToken;
+      const headers = new Headers({
+        cookie: `${cookie.name}=${signedCookieValue(input.token, context.secret)}`,
+      });
+      const resolved = await auth.api.getSession({ headers, returnHeaders: true });
+      if (!resolved.response) return null;
+      assertManagedUserAdmission(auth, resolved.response.user);
+      // The provider may renew its durable expiry and emit token/cache cookies;
+      // this server-side selected-slot resolution intentionally discards them.
+      return resolved.response as ManagedAuthResolvedSession;
+    },
+
+    async revokeSession(input) {
+      await db.execute(sql`delete from auth_sessions where id = ${input.authSessionId}`);
+    },
+
+    async createLegacySelectedSessionCookies(input, currentCookieHeader) {
+      const context = await auth.$context;
+      const cookie = context.authCookies.sessionToken;
+      const value = input ? signedCookieValue(input.token, context.secret) : "";
+      const headers = [
+        serializeCookieHeader(cookie.name, value, {
+          ...cookie.attributes,
+          ...(input ? {} : { maxAge: 0, expires: new Date(0) }),
+        }),
+      ];
+      for (const cacheCookie of [
+        context.authCookies.sessionData,
+        context.authCookies.accountData,
+        context.authCookies.dontRememberToken,
+      ]) {
+        for (const name of cacheCookieNames(cacheCookie.name, currentCookieHeader)) {
+          headers.push(
+            serializeCookieHeader(name, "", {
+              ...cacheCookie.attributes,
+              maxAge: 0,
+              expires: new Date(0),
+            }),
+          );
+        }
+      }
+      return headers;
+    },
+  };
+}
+
+function liveResolvedSession(value: unknown): ManagedAuthResolvedSession | null {
+  if (!value || typeof value !== "object") return null;
+  const session = (value as { session?: { expiresAt?: unknown } }).session;
+  const expiresAt = session?.expiresAt;
+  const expiryMillis =
+    expiresAt instanceof Date
+      ? expiresAt.getTime()
+      : typeof expiresAt === "string" || typeof expiresAt === "number"
+        ? new Date(expiresAt).getTime()
+        : Number.NaN;
+  if (!Number.isFinite(expiryMillis) || expiryMillis <= Date.now()) return null;
+  return value as ManagedAuthResolvedSession;
+}
+
+function cookieValue(header: string | null, name: string): string | null {
+  if (!header) return null;
+  for (const part of header.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator < 0 || part.slice(0, separator).trim() !== name) continue;
+    return part.slice(separator + 1).trim() || null;
+  }
+  return null;
+}
+
+function verifiedSignedCookieValue(value: string, secret: string): string | null {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(value);
+  } catch {
+    return null;
+  }
+  const separator = decoded.lastIndexOf(".");
+  if (separator <= 0) return null;
+  const token = decoded.slice(0, separator);
+  const signature = decoded.slice(separator + 1);
+  const expected = createHmac("sha256", secret).update(token, "utf8").digest("base64");
+  const actualBytes = Buffer.from(signature, "utf8");
+  const expectedBytes = Buffer.from(expected, "utf8");
+  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes)
+    ? token
+    : null;
+}
+
+function signedCookieValue(value: string, secret: string): string {
+  return encodeURIComponent(
+    `${value}.${createHmac("sha256", secret).update(value, "utf8").digest("base64")}`,
+  );
+}
+
+function serializeCookieHeader(
+  name: string,
+  value: string,
+  attributes: {
+    domain?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    maxAge?: number;
+    path?: string;
+    partitioned?: boolean;
+    prefix?: "secure" | "host";
+    sameSite?: string;
+    secure?: boolean;
+  },
+): string {
+  let cookieName = name;
+  if (attributes.prefix === "secure" && !cookieName.startsWith("__Secure-")) {
+    cookieName = `__Secure-${cookieName}`;
+  } else if (attributes.prefix === "host" && !cookieName.startsWith("__Host-")) {
+    cookieName = `__Host-${cookieName}`;
+  }
+  if (cookieName.startsWith("__Secure-")) attributes.secure = true;
+  if (cookieName.startsWith("__Host-")) {
+    attributes.secure = true;
+    attributes.path = "/";
+    delete attributes.domain;
+  }
+  let header = `${cookieName}=${value}`;
+  if (attributes.maxAge !== undefined)
+    header += `; Max-Age=${Math.max(0, Math.floor(attributes.maxAge))}`;
+  if (attributes.domain) header += `; Domain=${attributes.domain}`;
+  if (attributes.path) header += `; Path=${attributes.path}`;
+  if (attributes.expires) header += `; Expires=${attributes.expires.toUTCString()}`;
+  if (attributes.httpOnly) header += "; HttpOnly";
+  if (attributes.secure) header += "; Secure";
+  if (attributes.sameSite) {
+    header += `; SameSite=${attributes.sameSite[0]?.toUpperCase()}${attributes.sameSite.slice(1)}`;
+  }
+  if (attributes.partitioned) header += "; Partitioned";
+  return header;
+}
+
+function cacheCookieNames(baseName: string, cookieHeader?: string | null): string[] {
+  const names = new Set([baseName]);
+  for (const part of cookieHeader?.split(";") ?? []) {
+    const separator = part.indexOf("=");
+    if (separator < 0) continue;
+    const name = part.slice(0, separator).trim();
+    if (name === baseName || name.startsWith(`${baseName}.`)) names.add(name);
+  }
+  return [...names].sort();
+}