jskelet 0.5.2 → 0.5.4

package/src/client/index.js

@@ -33,3 +33,13 @@ export {
   getOverlayRoot,
 } from "./dom.js";
 export { startSafeImages } from "./safe-image.js";
+export {
+  clearSharedCookie,
+  consumeWindowNameHandoff,
+  createHandoffUrl,
+  handoffViaWindowName,
+  readCookie,
+  resolveSharedCookieDomain,
+  SHARED_COOKIE_WARN_BYTES,
+  writeSharedCookie,
+} from "./shared-cookie.js";

package/src/client/shared-cookie.js

@@ -0,0 +1,225 @@
+/**
+ * Tarayıcıda paylaşımlı cookie yazma + read-back.
+ *
+ * `document.cookie` ile Domain=.example.com yazmak bazı tarayıcılarda
+ * (Public Suffix, ITP) sessizce başarısız olur. Yazımdan sonra okunamazsa
+ * `{ handoff: true }` döner — çağıran `createHandoffUrl` veya
+ * `handoffViaWindowName` kullanır.
+ *
+ * `roots` verilmezse `document.documentElement.dataset.jskeletCookieRoots`
+ * (virgülle ayrılmış) okunur; layout'ta
+ * `data-jskelet-cookie-roots=".investvio.com,.localhost"` basılabilir.
+ */
+import {
+  SHARED_COOKIE_WARN_BYTES,
+  resolveSharedCookieDomain,
+} from "../shared/cookie-domain.js";
+
+export {
+  SHARED_COOKIE_WARN_BYTES,
+  resolveSharedCookieDomain,
+  stripHostPort,
+} from "../shared/cookie-domain.js";
+
+/**
+ * @returns {string[]}
+ */
+function rootsFromDom() {
+  if (typeof document === "undefined") return [];
+  const raw = document.documentElement?.dataset?.jskeletCookieRoots ?? "";
+  return raw
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {string} name
+ * @returns {string | null}
+ */
+export function readCookie(name) {
+  if (typeof document === "undefined") return null;
+  const prefix = `${encodeURIComponent(name)}=`;
+  for (const part of document.cookie.split(";")) {
+    const trimmed = part.trim();
+    if (!trimmed.startsWith(prefix)) continue;
+    try {
+      return decodeURIComponent(trimmed.slice(prefix.length));
+    } catch {
+      return trimmed.slice(prefix.length);
+    }
+  }
+  return null;
+}
+
+/**
+ * @typedef {object} ClientSharedCookieResult
+ * @property {boolean} ok
+ * @property {string | null} domain
+ * @property {boolean} handoff
+ * @property {string} [reason]
+ */
+
+/**
+ * @param {string} name
+ * @param {string} value
+ * @param {{ roots?: string[], maxAge?: number, path?: string, sameSite?: string,
+ *   secure?: boolean }} [options]
+ * @returns {ClientSharedCookieResult}
+ */
+export function writeSharedCookie(name, value, options = {}) {
+  if (typeof document === "undefined") {
+    return { ok: false, domain: null, handoff: true, reason: "no-document" };
+  }
+
+  const roots = options.roots ?? rootsFromDom();
+  const domain = resolveSharedCookieDomain(location.hostname, roots);
+  if (!domain) {
+    return { ok: false, domain: null, handoff: true, reason: "no-matching-root" };
+  }
+
+  const text = String(value ?? "");
+  if (new TextEncoder().encode(text).length > SHARED_COOKIE_WARN_BYTES) {
+    return { ok: false, domain, handoff: true, reason: "value-too-large" };
+  }
+
+  const secure = options.secure ?? location.protocol === "https:";
+  const parts = [
+    `${encodeURIComponent(name)}=${encodeURIComponent(text)}`,
+    `Path=${options.path ?? "/"}`,
+    `Domain=${domain}`,
+    `SameSite=${options.sameSite ?? "Lax"}`,
+  ];
+  if (options.maxAge !== undefined) {
+    parts.push(`Max-Age=${Math.floor(Number(options.maxAge))}`);
+  }
+  if (secure) parts.push("Secure");
+
+  document.cookie = parts.join("; ");
+
+  // Read-back: tarayıcı Domain'i reddettiyse cookie görünmez.
+  if (readCookie(name) !== text) {
+    return { ok: false, domain, handoff: true, reason: "readback-failed" };
+  }
+
+  return { ok: true, domain, handoff: false };
+}
+
+/**
+ * @param {string} name
+ * @param {{ roots?: string[], path?: string, secure?: boolean, sameSite?: string }} [options]
+ * @returns {ClientSharedCookieResult}
+ */
+export function clearSharedCookie(name, options = {}) {
+  if (typeof document === "undefined") {
+    return { ok: false, domain: null, handoff: false, reason: "no-document" };
+  }
+
+  const roots = options.roots ?? rootsFromDom();
+  const domain = resolveSharedCookieDomain(location.hostname, roots);
+  if (!domain) {
+    return { ok: false, domain: null, handoff: false, reason: "no-matching-root" };
+  }
+
+  const secure = options.secure ?? location.protocol === "https:";
+  const parts = [
+    `${encodeURIComponent(name)}=`,
+    `Path=${options.path ?? "/"}`,
+    `Domain=${domain}`,
+    "Max-Age=0",
+    `SameSite=${options.sameSite ?? "Lax"}`,
+  ];
+  if (secure) parts.push("Secure");
+  document.cookie = parts.join("; ");
+
+  return { ok: true, domain, handoff: false };
+}
+
+/**
+ * Handoff bileti ister; dönen URL'ye gidilir (`?handoff=` taşır).
+ *
+ * @param {{ name: string, value: string, next: string }} body
+ * @param {{ path?: string }} [options]
+ * @returns {Promise<string | null>}
+ */
+export async function createHandoffUrl(body, options = {}) {
+  const path = options.path ?? "/_jskelet/auth/handoff";
+  const response = await fetch(path, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      accept: "application/json",
+    },
+    credentials: "same-origin",
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) return null;
+  /** @type {{ ok?: boolean, url?: string }} */
+  const data = await response.json().catch(() => ({}));
+  return typeof data.url === "string" ? data.url : null;
+}
+
+/**
+ * first-party `window.name` köprüsü — cookie Domain reddedilince yedek.
+ * Kaynak sayfada hedefe gitmeden önce çağırın; hedefte
+ * `consumeWindowNameHandoff` okur.
+ *
+ * @param {string} targetUrl
+ * @param {{ name: string, value: string, maxAge?: number }} cookie
+ * @returns {void}
+ */
+export function handoffViaWindowName(targetUrl, cookie) {
+  if (typeof window === "undefined") return;
+  window.name = JSON.stringify({
+    jskeletHandoff: 1,
+    cookie: {
+      name: cookie.name,
+      value: cookie.value,
+      maxAge: cookie.maxAge,
+    },
+  });
+  location.assign(targetUrl);
+}
+
+/**
+ * Hedef host'ta `window.name` içindeki handoff'u host-only cookie olarak yazar.
+ *
+ * @param {{ write?: typeof writeSharedCookie }} [options]
+ *   Varsayılan: Domain denemeden host-only `document.cookie`.
+ * @returns {boolean} Bir şey yazıldı mı.
+ */
+export function consumeWindowNameHandoff(options = {}) {
+  if (typeof window === "undefined") return false;
+
+  let payload;
+  try {
+    payload = JSON.parse(window.name || "");
+  } catch {
+    return false;
+  }
+
+  if (!payload || payload.jskeletHandoff !== 1 || !payload.cookie?.name) {
+    return false;
+  }
+
+  window.name = "";
+
+  const { name, value, maxAge } = payload.cookie;
+  const text = String(value ?? "");
+  const secure = location.protocol === "https:";
+  const parts = [
+    `${encodeURIComponent(name)}=${encodeURIComponent(text)}`,
+    "Path=/",
+    "SameSite=Lax",
+  ];
+  if (maxAge !== undefined) parts.push(`Max-Age=${Math.floor(Number(maxAge))}`);
+  if (secure) parts.push("Secure");
+  document.cookie = parts.join("; ");
+
+  if (typeof options.write === "function") {
+    options.write(name, text, { maxAge });
+  }
+
+  return readCookie(name) === text;
+}

package/src/config/defaults.js

@@ -87,6 +87,13 @@ export const DEFAULT_PREWARM = {
    * @type {(string | RegExp)[]}
    */
   priority: [],
+  /**
+   * Klasik turda ısıtılacak origin listesi. Boşsa `http://127.0.0.1:<port>`.
+   * `cache().vary.host` açıkken locale host'ları buraya yazılmazsa yalnızca
+   * loopback anahtarı ısınır.
+   * @type {string[]}
+   */
+  origins: [],
 };
 
 /**
@@ -122,6 +129,7 @@ export const CLASSIC_PREWARM_KEYS = [
   "retryDelayMs",
   "rotate",
   "priority",
+  "origins",
 ];
 
 /**
@@ -445,4 +453,23 @@ export const DEFAULT_BRAND = {
   devBasePath: "/__jskelet/dev",
   prewarmUserAgent: "jskelet-prewarm",
   devTokenCookie: "dev_token",
+  /**
+   * Paylaşımlı cookie Domain kökleri (örn. `.investvio.com`, `.localhost`).
+   * `writeSharedCookie` host bunlardan birine uyuyorsa Domain olarak yazar.
+   * @type {string[]}
+   */
+  sharedCookieRoots: [],
+};
+
+/**
+ * Kimlik / alt alan handoff. Framework oturum vermez; yalnızca çapraz-subdomain
+ * cookie köprüsü opsiyoneldir.
+ */
+export const DEFAULT_AUTH = {
+  /**
+   * `true` veya `{ ttlSeconds?, path?, maxValueBytes? }`.
+   * Açıkken `POST /_jskelet/auth/handoff` ve `?handoff=` redeem middleware'i.
+   * @type {boolean | { enabled?: boolean, ttlSeconds?: number, path?: string, maxValueBytes?: number }}
+   */
+  crossSubdomainHandoff: false,
 };

package/src/config/index.js

@@ -16,9 +16,12 @@
  *   redirects() → [{ source, destination, permanent?, statusCode? }]
  *   rewrites()  → [{ source, destination }] | { beforeFiles?, afterFiles? }
  *   cache()     → { html?: { [source]: saniye },
- *                   query?: { [source]: string[] | true }, maxEntries?: number,
+ *                   query?: { [source]: string[] | true },
+ *                   vary?: { host?: boolean, headers?: string[], fn?: Function },
+ *                   maxEntries?: number,
  *                   data?: {...}, redis?: {...}, prewarm?: {...} }
  *   admin()     → { enabled?, basePath?, allowIps?, blockBots?, … }
+ *   auth        → { crossSubdomainHandoff?: boolean | object }
  *   logs        → { console?, kinds?, file?, s3? }
  *
  * Fonksiyon olmayan bölümler (`brand`, `security`, `static`, `navigation`…)
@@ -31,6 +34,7 @@ import { pathToFileURL } from "node:url";
 import { compilePattern, matchPattern } from "./pattern.js";
 import {
   DEFAULT_ADMIN,
+  DEFAULT_AUTH,
   DEFAULT_BRAND,
   DEFAULT_CLOUDFLARE,
   DEFAULT_DATA_CACHE,
@@ -107,6 +111,10 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {{ pattern: CompiledPattern, allow: true | string[] }[]} cacheQuery
  *   Yol deseni başına, HTML cache anahtarına girmesine izin verilen query
  *   parametreleri. Eşleşen kural yoksa query'li istek cache'lenmez.
+ * @property {{ host: boolean, headers: string[],
+ *   fn: ((req: import('express').Request) => string | null | undefined) | null }} cacheVary
+ *   Anahtara eklenen sabit parçalar (query allowlist'ten bağımsız). Host'tan
+ *   locale üreten sitelerde `host: true` zorunlu.
  * @property {number} htmlMaxEntries HTML önbelleğinin girdi sınırı.
  * @property {Record<string, unknown>} data Upstream veri önbelleği ayarları.
  * @property {boolean} trackUpstream `fetch` sarılıp geçici hatalar otomatik bildirilsin mi.
@@ -120,6 +128,7 @@ const CONFIG_FILE = "jskelet.config.mjs";
  * @property {Record<string, unknown>} prewarm
  * @property {{ source: string, test: (pathname: string) => boolean }[]} prewarmPriority
  * @property {Record<string, unknown>} brand
+ * @property {{ crossSubdomainHandoff: boolean | Record<string, unknown> }} auth
  * @property {Record<string, Function>} hooks
  * @property {string} layout Layout `.ejs` dosyasının mutlak yolu.
  * @property {string[] | null} routes Açık route modülü listesi.
@@ -633,10 +642,42 @@ function normalizeQueryRules(raw) {
   return out;
 }
 
+/**
+ * `cache().vary` → HTML anahtarına host / header / özel fn parçası.
+ *
+ * @param {unknown} raw
+ * @returns {ResolvedConfig["cacheVary"]}
+ */
+function normalizeVary(raw) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    return { host: false, headers: [], fn: null };
+  }
+
+  const source = /** @type {Record<string, unknown>} */ (raw);
+  const headers = asArray(source.headers, "cache().vary.headers")
+    .filter((name) => typeof name === "string" && name)
+    .map((name) => String(name).toLowerCase());
+
+  /** @type {ResolvedConfig["cacheVary"]["fn"]} */
+  let fn = null;
+  if (typeof source.fn === "function") {
+    fn = /** @type {ResolvedConfig["cacheVary"]["fn"]} */ (source.fn);
+  } else if (source.fn != null) {
+    console.warn("[config] cache().vary.fn must be a function, ignoring it");
+  }
+
+  return {
+    host: source.host === true,
+    headers,
+    fn,
+  };
+}
+
 /**
  * @param {unknown} raw
  * @returns {{ html: ResolvedConfig["html"],
- *   cacheQuery: ResolvedConfig["cacheQuery"], htmlMaxEntries: number,
+ *   cacheQuery: ResolvedConfig["cacheQuery"],
+ *   cacheVary: ResolvedConfig["cacheVary"], htmlMaxEntries: number,
  *   data: Record<string, unknown>, trackUpstream: boolean,
  *   trackDependencies: boolean,
  *   transientRetry: { attempts: number, delayMs: number },
@@ -664,6 +705,7 @@ function normalizeCache(raw) {
   return {
     html,
     cacheQuery: queryRules,
+    cacheVary: normalizeVary(raw?.vary),
     htmlMaxEntries:
       Number.isFinite(maxEntries) && maxEntries > 0
         ? Math.floor(maxEntries)
@@ -775,6 +817,12 @@ function normalizePrewarm(raw) {
   // birleşir. `onVisit` anahtarı çözülmüş nesnede her zaman durur.
   const classic = { ...source };
   delete classic.onVisit;
+
+  const origins = asArray(classic.origins, "cache().prewarm.origins")
+    .filter((value) => typeof value === "string" && /^https?:\/\//i.test(value))
+    .map(String);
+  classic.origins = origins;
+
   return {
     ...DEFAULT_PREWARM,
     ...classic,
@@ -851,6 +899,59 @@ function normalizeNavigation(raw, brand) {
  *   headerName: string }} csrf
  */
 
+/**
+ * @param {unknown} raw
+ * @returns {Record<string, unknown>}
+ */
+function normalizeBrand(raw) {
+  const source = /** @type {Record<string, unknown>} */ (raw ?? {});
+  const roots = asArray(
+    source.sharedCookieRoots ?? DEFAULT_BRAND.sharedCookieRoots,
+    "brand.sharedCookieRoots",
+  )
+    .filter((entry) => typeof entry === "string")
+    .map((entry) => {
+      const trimmed = String(entry).trim().toLowerCase();
+      if (!trimmed) return null;
+      return trimmed.startsWith(".") ? trimmed : `.${trimmed}`;
+    })
+    .filter((entry) => entry !== null);
+
+  return {
+    ...DEFAULT_BRAND,
+    ...source,
+    sharedCookieRoots: roots,
+  };
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {{ crossSubdomainHandoff: boolean | Record<string, unknown> }}
+ */
+function normalizeAuth(raw) {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) {
+    return { ...DEFAULT_AUTH };
+  }
+
+  const source = /** @type {Record<string, unknown>} */ (raw);
+  const handoff = source.crossSubdomainHandoff;
+
+  if (handoff === true || handoff === false || handoff == null) {
+    return {
+      crossSubdomainHandoff: handoff === true,
+    };
+  }
+
+  if (typeof handoff === "object" && !Array.isArray(handoff)) {
+    return { crossSubdomainHandoff: { ...handoff } };
+  }
+
+  console.warn(
+    "[config] auth.crossSubdomainHandoff must be boolean or object, ignoring it",
+  );
+  return { ...DEFAULT_AUTH };
+}
+
 /**
  * Güvenlik bölümü. `csrf.exclude` desenleri burada derlenir: her istekte
  * yeniden derlemek gereksiz, ve bozuk bir desen sunucuyu düşürmemeli.
@@ -1074,6 +1175,7 @@ export async function loadConfig(options = {}) {
   const {
     html,
     cacheQuery,
+    cacheVary,
     htmlMaxEntries,
     data,
     trackUpstream,
@@ -1086,7 +1188,8 @@ export async function loadConfig(options = {}) {
     prewarmPriority,
   } = normalizeCache(cache);
   const dirs = resolveDirs(root, source.paths);
-  const brand = { ...DEFAULT_BRAND, ...(source.brand ?? {}) };
+  const brand = normalizeBrand(source.brand);
+  const auth = normalizeAuth(source.auth);
 
   config = {
     root,
@@ -1097,6 +1200,7 @@ export async function loadConfig(options = {}) {
     rewrites: normalizeRewrites(rewrites),
     html,
     cacheQuery,
+    cacheVary,
     htmlMaxEntries,
     data,
     trackUpstream,
@@ -1110,6 +1214,7 @@ export async function loadConfig(options = {}) {
     prewarm,
     prewarmPriority,
     brand,
+    auth,
     hooks: source.hooks ?? {},
     layout: resolveLayout(dirs, source.layout),
     routes: Array.isArray(source.routes) ? source.routes : null,

package/src/http/cookies-entry.js

@@ -0,0 +1,20 @@
+/**
+ * `jskelet/cookies` paket girişi — imzalı cookie + paylaşımlı Domain yüzeyi.
+ */
+export {
+  clearCookie,
+  getSignedCookie,
+  parseCookies,
+  randomToken,
+  safeEqual,
+  serializeCookie,
+  setCookie,
+  setSignedCookie,
+} from "./cookies.js";
+export {
+  clearSharedCookie,
+  requestIsHttps,
+  resolveSharedCookieDomain,
+  SHARED_COOKIE_WARN_BYTES,
+  writeSharedCookie,
+} from "./shared-cookie.js";

package/src/http/cookies.js

@@ -144,6 +144,7 @@ export function parseCookies(req) {
  * @property {Date} [expires]
  * @property {boolean} [httpOnly] Varsayılan `true`.
  * @property {boolean} [secure] Varsayılan: development dışında `true`.
+ *   `writeSharedCookie` protokole bakarak ezer (`https` → Secure).
  * @property {"Strict" | "Lax" | "None"} [sameSite] Varsayılan `Lax`.
  */
 
@@ -255,3 +256,4 @@ export function getSignedCookie(req, name) {
 export function randomToken(bytes = 32) {
   return crypto.randomBytes(bytes).toString("base64url");
 }
+

package/src/http/shared-cookie.js

@@ -0,0 +1,178 @@
+/**
+ * Alt alan adları arasında paylaşılan cookie yazma.
+ *
+ * `Secure` protokole bakılır (`https` / `x-forwarded-proto`), `NODE_ENV`'e değil —
+ * yerel https veya prod http yanlış bayrak üretmesin.
+ *
+ * Domain `brand.sharedCookieRoots` ile seçilir. Eşleşme yoksa ya da değer çok
+ * büyükse `{ ok: false, handoff: true }` döner; çağıran handoff yoluna düşer.
+ *
+ * JWT'yi paylaşımlı cookie'ye koymayın: kısa session id koyun.
+ */
+import { getConfig } from "../config/index.js";
+import {
+  SHARED_COOKIE_WARN_BYTES,
+  resolveSharedCookieDomain,
+  stripHostPort,
+} from "../shared/cookie-domain.js";
+import { clearCookie, setCookie } from "./cookies.js";
+
+export {
+  SHARED_COOKIE_WARN_BYTES,
+  resolveSharedCookieDomain,
+  stripHostPort,
+} from "../shared/cookie-domain.js";
+
+/**
+ * @param {{ secure?: boolean, protocol?: string,
+ *   headers?: Record<string, unknown>, get?: (name: string) => string | undefined }} [req]
+ * @returns {boolean}
+ */
+export function requestIsHttps(req) {
+  if (!req) return false;
+  if (req.secure === true) return true;
+  if (typeof req.protocol === "string" && req.protocol === "https") return true;
+
+  const forwarded =
+    req.get?.("x-forwarded-proto") ??
+    (typeof req.headers?.["x-forwarded-proto"] === "string"
+      ? req.headers["x-forwarded-proto"]
+      : Array.isArray(req.headers?.["x-forwarded-proto"])
+        ? req.headers["x-forwarded-proto"][0]
+        : "");
+  const first = String(forwarded ?? "")
+    .split(",")[0]
+    .trim()
+    .toLowerCase();
+  return first === "https";
+}
+
+/**
+ * @param {{ headers?: Record<string, unknown>, get?: (name: string) => string | undefined,
+ *   hostname?: string }} [req]
+ * @returns {string}
+ */
+function hostFromReq(req) {
+  if (!req) return "";
+  const forwarded =
+    req.get?.("x-forwarded-host") ??
+    (typeof req.headers?.["x-forwarded-host"] === "string"
+      ? req.headers["x-forwarded-host"]
+      : "");
+  const raw =
+    forwarded ||
+    req.get?.("host") ||
+    (typeof req.headers?.host === "string" ? req.headers.host : "") ||
+    (typeof req.hostname === "string" ? req.hostname : "");
+  return stripHostPort(String(raw).split(",")[0]);
+}
+
+/**
+ * @returns {string[]}
+ */
+function configuredRoots() {
+  try {
+    const roots = getConfig().brand?.sharedCookieRoots;
+    return Array.isArray(roots) ? roots.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * @typedef {import('./cookies.js').CookieOptions} CookieOptions
+ *
+ * @typedef {object} SharedCookieResult
+ * @property {boolean} ok Domain seçildi ve Set-Cookie yazıldı.
+ * @property {string | null} domain Yazılan Domain ya da null.
+ * @property {boolean} handoff ok değilse çağıran handoff denemeli.
+ * @property {string} [reason] Teşhis.
+ */
+
+/**
+ * Paylaşımlı Domain ile cookie yazar.
+ *
+ * @param {import('http').ServerResponse & { req?: import('http').IncomingMessage }} res
+ * @param {string} name
+ * @param {string} value Kısa session id — JWT değil.
+ * @param {CookieOptions & { req?: import('http').IncomingMessage, roots?: string[],
+ *   host?: string }} [options]
+ * @returns {SharedCookieResult}
+ */
+export function writeSharedCookie(res, name, value, options = {}) {
+  const { req: optReq, roots: optRoots, host: optHost, ...cookieOpts } = options;
+  const req = optReq ?? /** @type {{ req?: import('http').IncomingMessage }} */ (res).req;
+  const roots = optRoots ?? configuredRoots();
+  const host = optHost ? stripHostPort(optHost) : hostFromReq(req);
+  const domain = resolveSharedCookieDomain(host, roots);
+
+  if (!domain) {
+    return {
+      ok: false,
+      domain: null,
+      handoff: true,
+      reason: "no-matching-root",
+    };
+  }
+
+  const text = String(value ?? "");
+  if (Buffer.byteLength(text, "utf8") > SHARED_COOKIE_WARN_BYTES) {
+    console.warn(
+      `[cookies] shared cookie "${name}" is ${Buffer.byteLength(text, "utf8")} bytes; ` +
+        `prefer a short session id (≤${SHARED_COOKIE_WARN_BYTES}). Large tokens do not belong in shared cookies.`,
+    );
+    return {
+      ok: false,
+      domain,
+      handoff: true,
+      reason: "value-too-large",
+    };
+  }
+
+  const secure = cookieOpts.secure ?? requestIsHttps(req);
+
+  setCookie(res, name, text, {
+    ...cookieOpts,
+    domain,
+    secure,
+    // Paylaşımlı oturum kimliği JS'ye gerekmez; HttpOnly kalsın.
+    httpOnly: cookieOpts.httpOnly !== false,
+    sameSite: cookieOpts.sameSite ?? "Lax",
+    path: cookieOpts.path ?? "/",
+  });
+
+  // Sunucuda document.cookie read-back yok; Domain seçildiyse yazım başarılı sayılır.
+  // İstemci `writeSharedCookie` read-back yapar; başarısızsa handoff'a düşer.
+  return { ok: true, domain, handoff: false };
+}
+
+/**
+ * Aynı Domain ile cookie siler.
+ *
+ * @param {import('http').ServerResponse & { req?: import('http').IncomingMessage }} res
+ * @param {string} name
+ * @param {CookieOptions & { req?: import('http').IncomingMessage, roots?: string[],
+ *   host?: string }} [options]
+ * @returns {SharedCookieResult}
+ */
+export function clearSharedCookie(res, name, options = {}) {
+  const { req: optReq, roots: optRoots, host: optHost, ...cookieOpts } = options;
+  const req = optReq ?? /** @type {{ req?: import('http').IncomingMessage }} */ (res).req;
+  const roots = optRoots ?? configuredRoots();
+  const host = optHost ? stripHostPort(optHost) : hostFromReq(req);
+  const domain = resolveSharedCookieDomain(host, roots);
+
+  if (!domain) {
+    return { ok: false, domain: null, handoff: false, reason: "no-matching-root" };
+  }
+
+  const secure = cookieOpts.secure ?? requestIsHttps(req);
+  clearCookie(res, name, {
+    ...cookieOpts,
+    domain,
+    secure,
+    path: cookieOpts.path ?? "/",
+  });
+
+  return { ok: true, domain, handoff: false };
+}