npm - jskelet - Versions diffs - 0.5.3 → 0.5.4 - Mend

jskelet 0.5.3 → 0.5.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/CHANGELOG.md +8 -0
package/docs/07-yapilandirma.md +25 -1
package/docs/12-panel-ve-oturum.md +88 -0
package/docs/en/07-configuration.md +26 -1
package/docs/en/12-dashboards-and-sessions.md +91 -0
package/package.json +2 -2
package/src/client/index.js +10 -0
package/src/client/shared-cookie.js +225 -0
package/src/config/defaults.js +19 -0
package/src/config/index.js +59 -1
package/src/http/cookies-entry.js +20 -0
package/src/http/cookies.js +2 -0
package/src/http/shared-cookie.js +178 -0
package/src/index.js +7 -0
package/src/server/auth/handoff.js +226 -0
package/src/server/create-app.js +14 -0
package/src/shared/cookie-domain.js +66 -0

package/CHANGELOG.md CHANGED Viewed

@@ -10,6 +10,14 @@ one is listed under a **Breaking** heading.
 ### Added
+- Shared cross-subdomain cookies: `brand.sharedCookieRoots` plus
+  `writeSharedCookie` / `clearSharedCookie` on server (`jskelet/cookies`) and
+  client (`jskelet/client`). `Secure` follows https / `x-forwarded-proto` (not
+  `NODE_ENV`); the client read-back fails into handoff when the browser rejects
+  `Domain`. Optional `auth.crossSubdomainHandoff` mounts
+  `POST /_jskelet/auth/handoff` (one-time ticket → `?handoff=`) and documents a
+  `window.name` bridge. Large tokens are refused — put a short session id in the
+  cookie, not a JWT.
 - HTML cache key vary (`cache().vary`): `host: true` adds the public Host
   (`x-forwarded-host` or `Host`, lowercase, no port) as `h=…|` before the path;
   optional `headers` and `fn(req)` add further segments. Required on host-based

package/docs/07-yapilandirma.md CHANGED Viewed

@@ -186,14 +186,38 @@ birleştirilir.
 | `prewarmUserAgent` | `string` | `"jskelet-prewarm"` | Isıtma isteklerinin UA'sı; dev paneli bunu filtreler |
 | `devTokenCookie` | `string` | `"dev_token"` | Dev gate'in çerez ve query parametresi adı |
 | `lang` | `string` | — | `<html lang>` varsayılanı. Verilmezse layout `"en"` kullanır. |
+| `sharedCookieRoots` | `string[]` | `[]` | Paylaşımlı cookie Domain kökleri (örn. `.investvio.com`, `.localhost`). [12](./12-panel-ve-oturum.md) |
 `lang` için öncelik sırası: `hooks.layoutContext()` → `lang` **>** `brand.lang`
 **>** `"en"`.
 ```js
-brand: { lang: "tr", poweredBy: "Örnek", cacheHeader: "X-Ornek-Cache" }
+brand: {
+  lang: "tr",
+  poweredBy: "Örnek",
+  sharedCookieRoots: [".investvio.com", ".localhost"],
+}
 ```
+## `auth`
+**Tip:** `object` — **Varsayılan:** `{ crossSubdomainHandoff: false }`
+Kimlik framework'te yok; bu bölüm yalnızca alt alan adları arasında kısa
+session id taşımak için handoff köprüsünü açar.
+| Alan | Tip | Varsayılan | Anlamı |
+| --- | --- | --- | --- |
+| `crossSubdomainHandoff` | `boolean \| object` | `false` | `true` veya `{ ttlSeconds?, path?, maxValueBytes? }` → `POST /_jskelet/auth/handoff` + `?handoff=` redeem |
+```js
+auth: {
+  crossSubdomainHandoff: { ttlSeconds: 60 },
+},
+```
+Ayrıntı ve `window.name` yedeği: [12-panel-ve-oturum.md](./12-panel-ve-oturum.md).
 ## `layout`
 **Tip:** `string` — **Varsayılan:** yok (otomatik çözüm)

package/docs/12-panel-ve-oturum.md CHANGED Viewed

@@ -129,6 +129,94 @@ kapatıyor — cookie çapraz site POST'larında hiç gönderilmiyor.
 Cookie **şifrelenmiyor**, imzalanıyor. Değer okunabilir; gizli kalması gereken
 veriyi değil, onun kimliğini koyun.
+## Alt alan adları: paylaşımlı cookie
+Host tabanlı i18n (`tr.example.com` / `en.example.com`) oturumu alt alanlar
+arasında paylaşmak ister. Çözüm **kısa session id** + isteğe bağlı
+`Domain=.example.com` — JWT veya büyük access token paylaşımlı cookie'ye
+konmaz (`large token ≠ shared cookie`).
+```js
+// jskelet.config.mjs
+export default {
+  brand: {
+    sharedCookieRoots: [".investvio.com", ".localhost"],
+  },
+  auth: {
+    crossSubdomainHandoff: true, // POST /_jskelet/auth/handoff
+  },
+};
+```
+### Sunucu
+```js
+import { writeSharedCookie } from "jskelet/cookies";
+export function startSession(res, req, sessionId) {
+  const result = writeSharedCookie(res, "sid", sessionId, {
+    req,
+    maxAge: 60 * 60 * 8,
+  });
+  // result.ok === false → result.handoff; istemci handoff denemeli
+  return result;
+}
+```
+`Secure` **protokole** bakılır (`https` / `x-forwarded-proto`), `NODE_ENV`'e
+değil. Domain, isteğin Host'u `sharedCookieRoots` ile eşleşince yazılır.
+Değer ~512 baytı aşarsa yazım reddedilir ve `handoff: true` döner.
+### İstemci
+```js
+import {
+  writeSharedCookie,
+  createHandoffUrl,
+  handoffViaWindowName,
+  consumeWindowNameHandoff,
+} from "jskelet/client";
+const result = writeSharedCookie("sid", sessionId, {
+  roots: [".investvio.com", ".localhost"],
+  maxAge: 60 * 60 * 8,
+});
+if (!result.ok && result.handoff) {
+  const url = await createHandoffUrl({
+    name: "sid",
+    value: sessionId,
+    next: "https://tr.investvio.com/panel",
+  });
+  if (url) location.assign(url);
+  else handoffViaWindowName("https://tr.investvio.com/panel", {
+    name: "sid",
+    value: sessionId,
+  });
+}
+// Hedef host'ta (layout / island bootstrap):
+consumeWindowNameHandoff();
+```
+`roots` verilmezse `<html data-jskelet-cookie-roots=".investvio.com,.localhost">`
+okunur. Yazımdan sonra **read-back** yapılır; tarayıcı Domain'i reddettiyse
+`handoff: true`.
+### Handoff bileti
+`auth.crossSubdomainHandoff` açıkken:
+1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (`?handoff=` ekli)
+2. Hedef host'ta GET middleware bileti tek kullanımlık tüketir, cookie yazar
+   (önce shared Domain, olmazsa host-only), `handoff` query'siz 303
+`next` yalnızca aynı `sharedCookieRoots` altındaki host'lara izinli. Bilet
+~60 sn, süreç belleğinde. JWT URL'ye konmaz.
+`window.name` köprüsü cookie'siz yedek: kaynakta `handoffViaWindowName`,
+hedeefte `consumeWindowNameHandoff`.
 ## CSRF
 Gövdeyi framework ayrıştırıyor (`express.urlencoded` + `express.json`), yani

package/docs/en/07-configuration.md CHANGED Viewed

@@ -191,14 +191,39 @@ shallow-merged with the defaults.
 | `prewarmUserAgent` | `string` | `"jskelet-prewarm"` | UA of prewarm requests; the dev panel filters on it |
 | `devTokenCookie` | `string` | `"dev_token"` | Name of the dev gate's cookie and query parameter |
 | `lang` | `string` | — | Default for `<html lang>`. If not given, the layout uses `"en"`. |
+| `sharedCookieRoots` | `string[]` | `[]` | Shared cookie Domain roots (e.g. `.investvio.com`, `.localhost`). [12](./12-dashboards-and-sessions.md) |
 Precedence for `lang`: `hooks.layoutContext()` → `lang` **>** `brand.lang`
 **>** `"en"`.
 ```js
-brand: { lang: "tr", poweredBy: "Example", cacheHeader: "X-Example-Cache" }
+brand: {
+  lang: "tr",
+  poweredBy: "Example",
+  sharedCookieRoots: [".investvio.com", ".localhost"],
+}
 ```
+## `auth`
+**Type:** `object` — **Default:** `{ crossSubdomainHandoff: false }`
+The framework does not provide identity; this section only opens the
+cross-subdomain handoff bridge for a short session id.
+| Field | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `crossSubdomainHandoff` | `boolean \| object` | `false` | `true` or `{ ttlSeconds?, path?, maxValueBytes? }` → `POST /_jskelet/auth/handoff` + `?handoff=` redeem |
+```js
+auth: {
+  crossSubdomainHandoff: { ttlSeconds: 60 },
+},
+```
+Details and the `window.name` fallback:
+[12-dashboards-and-sessions.md](./12-dashboards-and-sessions.md).
 ## `layout`
 **Type:** `string` — **Default:** none (automatic resolution)

package/docs/en/12-dashboards-and-sessions.md CHANGED Viewed

@@ -131,6 +131,97 @@ cookie is simply not sent on cross-site POSTs.
 Cookies are **signed, not encrypted**. The value is readable, so store the
 identifier of a secret rather than the secret itself.
+## Cross-subdomain: shared cookies
+Host-based i18n (`tr.example.com` / `en.example.com`) often needs a session on
+every locale host. The supported pattern is a **short session id** plus an
+optional `Domain=.example.com` — do not put a JWT or a large access token in a
+shared cookie (`large token ≠ shared cookie`).
+```js
+// jskelet.config.mjs
+export default {
+  brand: {
+    sharedCookieRoots: [".investvio.com", ".localhost"],
+  },
+  auth: {
+    crossSubdomainHandoff: true, // POST /_jskelet/auth/handoff
+  },
+};
+```
+### Server
+```js
+import { writeSharedCookie } from "jskelet/cookies";
+export function startSession(res, req, sessionId) {
+  const result = writeSharedCookie(res, "sid", sessionId, {
+    req,
+    maxAge: 60 * 60 * 8,
+  });
+  // result.ok === false → result.handoff; the client should use handoff
+  return result;
+}
+```
+`Secure` follows the **protocol** (`https` / `x-forwarded-proto`), not
+`NODE_ENV`. The Domain is set when the request Host matches
+`sharedCookieRoots`. Values larger than ~512 bytes are refused with
+`handoff: true`.
+### Client
+```js
+import {
+  writeSharedCookie,
+  createHandoffUrl,
+  handoffViaWindowName,
+  consumeWindowNameHandoff,
+} from "jskelet/client";
+const result = writeSharedCookie("sid", sessionId, {
+  roots: [".investvio.com", ".localhost"],
+  maxAge: 60 * 60 * 8,
+});
+if (!result.ok && result.handoff) {
+  const url = await createHandoffUrl({
+    name: "sid",
+    value: sessionId,
+    next: "https://tr.investvio.com/panel",
+  });
+  if (url) location.assign(url);
+  else handoffViaWindowName("https://tr.investvio.com/panel", {
+    name: "sid",
+    value: sessionId,
+  });
+}
+// On the target host (layout / island bootstrap):
+consumeWindowNameHandoff();
+```
+If `roots` is omitted, the client reads
+`<html data-jskelet-cookie-roots=".investvio.com,.localhost">`. After writing,
+a **read-back** runs; if the browser rejected the Domain, `handoff: true`.
+### Handoff ticket
+With `auth.crossSubdomainHandoff` on:
+1. `POST /_jskelet/auth/handoff` `{ name, value, next }` → `{ url }` (with `?handoff=`)
+2. On the target host a GET middleware redeems the one-time ticket, sets the
+   cookie (shared Domain first, else host-only), and 303-redirects without
+   `handoff`
+`next` must be under the same `sharedCookieRoots`. Tickets live ~60s in process
+memory. Do not put a JWT in the URL.
+The `window.name` bridge is the cookie-less fallback:
+`handoffViaWindowName` on the source page, `consumeWindowNameHandoff` on the
+target.
 ## CSRF
 The framework parses the request body (`express.urlencoded` + `express.json`),

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "jskelet",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "A framework that feels like no framework: Express 5 + build-time .jsk (or EJS) SSR, vanilla JS islands, Tailwind v4 and an in-process HTML TTL cache.",
   "type": "module",
   "license": "MIT",
@@ -33,7 +33,7 @@
     "./client": "./src/client/index.js",
     "./html": "./src/views/helpers/html.js",
     "./tags": "./src/views/helpers/tags.js",
-    "./cookies": "./src/http/cookies.js",
+    "./cookies": "./src/http/cookies-entry.js",
     "./log": "./src/log.mjs",
     "./register": "./src/runtime/register.mjs",
     "./layout": "./src/templates/layout.ejs"

package/src/client/index.js CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -453,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 CHANGED Viewed

@@ -21,6 +21,7 @@
  *                   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`…)
@@ -33,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,
@@ -126,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.
@@ -896,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.
@@ -1132,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,
@@ -1157,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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 };
+}

package/src/index.js CHANGED Viewed

@@ -35,6 +35,13 @@ export {
   setCookie,
   setSignedCookie,
 } from "./http/cookies.js";
+export {
+  clearSharedCookie,
+  requestIsHttps,
+  resolveSharedCookieDomain,
+  SHARED_COOKIE_WARN_BYTES,
+  writeSharedCookie,
+} from "./http/shared-cookie.js";
 export { reportUpstreamFailure } from "./server/upstream-tracking.js";
 export { asset, hasAsset, optimizedImage, getSpriteIds } from "./server/assets.js";
 export { remoteImageUrl, parseAllowedRemoteUrl } from "./server/image-optimizer.js";

package/src/server/auth/handoff.js ADDED Viewed

@@ -0,0 +1,226 @@
+/**
+ * Alt alan adı handoff: kısa ömürlü tek kullanımlık bilet.
+ *
+ * Akış:
+ *   1. Paylaşımlı cookie yazımı başarısız (istemci read-back fail)
+ *   2. POST /_jskelet/auth/handoff { name, value, next }
+ *   3. Yanıt { url: "https://tr.…/path?handoff=TICKET" }
+ *   4. Hedef host'ta GET middleware bileti tüketir → Set-Cookie + 303
+ *
+ * Bilet süreç belleğinde; tek süreçte tüm locale host'ları servis eden
+ * kurulumlar için yeterli. Değer kısa session id olmalı.
+ */
+import { getConfig } from "../../config/index.js";
+import { randomToken, setCookie } from "../../http/cookies.js";
+import {
+  SHARED_COOKIE_WARN_BYTES,
+  requestIsHttps,
+  writeSharedCookie,
+} from "../../http/shared-cookie.js";
+import { resolveSharedCookieDomain } from "../../shared/cookie-domain.js";
+/** @type {Map<string, { name: string, value: string, maxAge?: number, exp: number }>} */
+const tickets = new Map();
+const DEFAULT_TTL_SECONDS = 60;
+const HANDOFF_PATH = "/_jskelet/auth/handoff";
+/**
+ * @returns {{ enabled: boolean, ttlSeconds: number, path: string, maxValueBytes: number }}
+ */
+function settings() {
+  const auth = getConfig().auth ?? {};
+  const raw = auth.crossSubdomainHandoff;
+  if (raw === false || raw == null) {
+    return {
+      enabled: false,
+      ttlSeconds: DEFAULT_TTL_SECONDS,
+      path: HANDOFF_PATH,
+      maxValueBytes: SHARED_COOKIE_WARN_BYTES,
+    };
+  }
+  if (raw === true) {
+    return {
+      enabled: true,
+      ttlSeconds: DEFAULT_TTL_SECONDS,
+      path: HANDOFF_PATH,
+      maxValueBytes: SHARED_COOKIE_WARN_BYTES,
+    };
+  }
+  const source = /** @type {Record<string, unknown>} */ (raw);
+  const ttl = Number(source.ttlSeconds);
+  const maxBytes = Number(source.maxValueBytes);
+  return {
+    enabled: source.enabled !== false,
+    ttlSeconds:
+      Number.isFinite(ttl) && ttl > 0 ? Math.min(300, Math.floor(ttl)) : DEFAULT_TTL_SECONDS,
+    path:
+      typeof source.path === "string" && source.path.startsWith("/")
+        ? source.path
+        : HANDOFF_PATH,
+    maxValueBytes:
+      Number.isFinite(maxBytes) && maxBytes > 0
+        ? Math.floor(maxBytes)
+        : SHARED_COOKIE_WARN_BYTES,
+  };
+}
+function sweep() {
+  const now = Date.now();
+  for (const [id, entry] of tickets) {
+    if (entry.exp <= now) tickets.delete(id);
+  }
+}
+/**
+ * @param {string} next
+ * @param {import('express').Request} req
+ * @returns {URL | null}
+ */
+function parseNext(next, req) {
+  try {
+    return new URL(next, `${req.protocol}://${req.get("host")}`);
+  } catch {
+    return null;
+  }
+}
+/**
+ * @param {URL} url
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+function nextAllowed(url, req) {
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  const roots = getConfig().brand?.sharedCookieRoots ?? [];
+  const targetHost = url.hostname.toLowerCase();
+  const sourceHost = String(req.hostname || "")
+    .toLowerCase()
+    .replace(/:\d+$/, "");
+  if (targetHost === sourceHost) return true;
+  const sourceRoot = resolveSharedCookieDomain(sourceHost, roots);
+  const targetRoot = resolveSharedCookieDomain(targetHost, roots);
+  return Boolean(sourceRoot && targetRoot && sourceRoot === targetRoot);
+}
+/**
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {{ name: string, value: string, maxAge?: number }} payload
+ * @returns {void}
+ */
+function issueCookie(req, res, payload) {
+  const shared = writeSharedCookie(res, payload.name, payload.value, {
+    req,
+    maxAge: payload.maxAge,
+  });
+  if (shared.ok) return;
+  setCookie(res, payload.name, payload.value, {
+    path: "/",
+    httpOnly: true,
+    sameSite: "Lax",
+    secure: requestIsHttps(req),
+    maxAge: payload.maxAge,
+  });
+}
+/**
+ * @param {string} ticketId
+ * @returns {{ name: string, value: string, maxAge?: number } | null}
+ */
+function redeem(ticketId) {
+  sweep();
+  const entry = tickets.get(ticketId);
+  if (!entry) return null;
+  tickets.delete(ticketId);
+  if (entry.exp <= Date.now()) return null;
+  return { name: entry.name, value: entry.value, maxAge: entry.maxAge };
+}
+/**
+ * Handoff uçlarını mount eder. `auth.crossSubdomainHandoff` kapalıysa no-op.
+ *
+ * @param {import('express').Express} app
+ * @returns {void}
+ */
+export function mountAuthHandoff(app) {
+  const cfg = settings();
+  if (!cfg.enabled) return;
+  app.post(cfg.path, (req, res) => {
+    sweep();
+    const name = typeof req.body?.name === "string" ? req.body.name.trim() : "";
+    const value = typeof req.body?.value === "string" ? req.body.value : "";
+    const next = typeof req.body?.next === "string" ? req.body.next.trim() : "";
+    const maxAge =
+      req.body?.maxAge != null && Number.isFinite(Number(req.body.maxAge))
+        ? Math.floor(Number(req.body.maxAge))
+        : undefined;
+    if (!name || !next) {
+      res.status(400).json({ ok: false, error: "name and next are required" });
+      return;
+    }
+    if (Buffer.byteLength(value, "utf8") > cfg.maxValueBytes) {
+      res.status(400).json({
+        ok: false,
+        error: `value exceeds ${cfg.maxValueBytes} bytes; use a short session id`,
+      });
+      return;
+    }
+    const nextUrl = parseNext(next, req);
+    if (!nextUrl || !nextAllowed(nextUrl, req)) {
+      res.status(400).json({ ok: false, error: "next is not an allowed URL" });
+      return;
+    }
+    const id = randomToken(24);
+    tickets.set(id, {
+      name,
+      value,
+      maxAge,
+      exp: Date.now() + cfg.ttlSeconds * 1000,
+    });
+    nextUrl.searchParams.set("handoff", id);
+    res.setHeader("Cache-Control", "no-store");
+    res.json({ ok: true, url: nextUrl.href });
+  });
+  // Hedef host'ta `?handoff=` yakala — route render'ından önce.
+  app.use((req, res, next) => {
+    if (req.method !== "GET" && req.method !== "HEAD") return next();
+    const ticket = typeof req.query?.handoff === "string" ? req.query.handoff : "";
+    if (!ticket) return next();
+    const payload = redeem(ticket);
+    if (!payload) return next();
+    issueCookie(req, res, payload);
+    const url = new URL(req.originalUrl || req.url, `${req.protocol}://${req.get("host")}`);
+    url.searchParams.delete("handoff");
+    res.setHeader("Cache-Control", "no-store");
+    res.redirect(303, url.pathname + url.search + url.hash);
+  });
+}
+/** @returns {void} */
+export function _resetHandoffTickets() {
+  tickets.clear();
+}
+/** @returns {number} */
+export function _handoffTicketCount() {
+  return tickets.size;
+}

package/src/server/create-app.js CHANGED Viewed

@@ -21,6 +21,9 @@
  *      body parser'dan önce, admin ile aynı katmanda.
  *   5. body parser'lar — statikten sonra: görsel isteklerinde gövde ayrıştırma
  *      maliyeti ödenmesin.
+ *   5b. auth handoff (açıksa) — POST bilet + `?handoff=` redeem; csrf'den
+ *      önce değil sonra: JSON gövde parser'ı hazır olsun. Redeem GET route
+ *      render'ından önce olmalı.
  *   6. csrf — body parser'lardan sonra olmalı: token form alanından okunuyor.
  *      Rewrite'lardan önce, çünkü kontrol istemcinin gördüğü yola bakar.
  *   7. rewrites(afterFiles) — statik denendikten sonra, sayfalardan önce.
@@ -149,6 +152,17 @@ export async function createApp(options = {}) {
   app.use(express.urlencoded({ extended: false, limit: "64kb" }));
   app.use(express.json({ limit: "256kb" }));
+  const handoff = config.auth?.crossSubdomainHandoff;
+  if (
+    handoff === true ||
+    (handoff &&
+      typeof handoff === "object" &&
+      /** @type {{ enabled?: boolean }} */ (handoff).enabled !== false)
+  ) {
+    const { mountAuthHandoff } = await import("./auth/handoff.js");
+    mountAuthHandoff(app);
+  }
   app.use(csrf());
   app.use(configRewrites("afterFiles"));

package/src/shared/cookie-domain.js ADDED Viewed

@@ -0,0 +1,66 @@
+/**
+ * Paylaşımlı cookie Domain seçimi — sunucu ve istemci aynı kuralları kullanır.
+ *
+ * `brand.sharedCookieRoots` örn. `[".investvio.com", ".localhost"]`.
+ * Host bu köklerden birine uyuyorsa Domain olarak o kök yazılır.
+ */
+/**
+ * @param {string} host Host veya Host:port.
+ * @returns {string} Lowercase, portsuz.
+ */
+export function stripHostPort(host) {
+  const raw = String(host ?? "")
+    .split(",")[0]
+    .trim()
+    .toLowerCase();
+  if (!raw) return "";
+  if (raw.startsWith("[")) {
+    const end = raw.indexOf("]");
+    return end === -1 ? raw : raw.slice(0, end + 1);
+  }
+  const colon = raw.lastIndexOf(":");
+  if (colon === -1) return raw;
+  if (raw.indexOf(":") !== colon) return raw;
+  return raw.slice(0, colon);
+}
+/**
+ * Kökü `Domain=` biçimine getirir (başında nokta).
+ *
+ * @param {unknown} root
+ * @returns {string | null}
+ */
+export function normalizeCookieRoot(root) {
+  if (typeof root !== "string") return null;
+  const trimmed = root.trim().toLowerCase();
+  if (!trimmed || trimmed === ".") return null;
+  const bare = trimmed.replace(/^\./, "");
+  if (!bare || bare.includes("/") || bare.includes(":")) return null;
+  return `.${bare}`;
+}
+/**
+ * @param {string} hostname Portsuz hostname.
+ * @param {Iterable<string>} roots `brand.sharedCookieRoots`.
+ * @returns {string | null} `Domain` değeri (başında nokta) ya da eşleşme yoksa null.
+ */
+export function resolveSharedCookieDomain(hostname, roots) {
+  const host = stripHostPort(hostname);
+  if (!host) return null;
+  for (const entry of roots ?? []) {
+    const root = normalizeCookieRoot(entry);
+    if (!root) continue;
+    const bare = root.slice(1);
+    if (host === bare || host.endsWith(`.${bare}`)) return root;
+  }
+  return null;
+}
+/**
+ * Paylaşımlı cookie için önerilen üst sınır. JWT / büyük token buraya
+ * sığmaz — kısa session id koyun; aksi halde handoff veya host-only cookie.
+ */
+export const SHARED_COOKIE_WARN_BYTES = 512;