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

jskelet 0.5.3 → 0.5.5

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 (20) hide show

package/CHANGELOG.md +292 -377
package/docs/07-yapilandirma.md +38 -8
package/docs/08-build.md +26 -10
package/docs/12-panel-ve-oturum.md +88 -0
package/docs/en/07-configuration.md +41 -8
package/docs/en/08-build.md +28 -12
package/docs/en/12-dashboards-and-sessions.md +91 -0
package/package.json +2 -2
package/src/build/tasks/icons.mjs +141 -17
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 +89 -3
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/docs/07-yapilandirma.md CHANGED Viewed

@@ -88,7 +88,7 @@ export default {
   watch: ["data"],
   fonts: [{ family: "Inter", weights: [400, 600, 700] }],
-  icons: { scan: ["views", "client", "routes", "lib"] },
+  icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["indirmeler"] },
   clientEnv: ["PUBLIC_WS_URL"],
@@ -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)
@@ -463,21 +487,27 @@ fonts: [
 ## `icons`
-**Tip:** `{ scan?: string[] } | false` — **Varsayılan:** `{}`
+**Tip:** `{ scan?: string[], dir?: string } | false` — **Varsayılan:** `{ dir: "icons" }`
-Phosphor SVG sprite üretimi.
+SVG ikon sprite üretimi. Kaynak **XOR** seçilir: `icons.dir` dizini varsa
+yalnızca oradaki düz SVG'ler; yoksa `@phosphor-icons/core` (kuruluysa).
 | Değer | Sonuç |
 | --- | --- |
-| `{}` (varsayılan) | Sprite üretilir; taranan dizinler `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{}` (varsayılan) | `dir: "icons"`; taranan dizinler `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{ dir: "assets/icons" }` | Yerel SVG kökü değiştirilir |
 | `{ scan: [...] }` | Taranan dizinler değiştirilir |
 | `false` | Sprite adımı tamamen atlanır |
-`@phosphor-icons/core` uygulamanın `node_modules`'ünde yoksa adım sessizce
-atlanır. Ayrıntı: [08-build.md](./08-build.md).
+Yerel dizin (varsa) düz dosya adları kullanır: `house.svg` → `house:regular`,
+`house-bold.svg` → `house:bold`. Boş bir `icons/` dizini Phosphor'a düşmez —
+dizini silmek fallback'i açar. Ayrıntı: [08-build.md](./08-build.md).
 ```js
-icons: { scan: ["views", "client", "routes", "lib", "content"] }
+icons: {
+  dir: "icons",
+  scan: ["views", "client", "routes", "lib", "content"],
+}
 ```
 ## `images`

package/docs/08-build.md CHANGED Viewed

@@ -249,16 +249,32 @@ bu dosyalara otomatik olarak `immutable` cache yazılır.
 ## İkon sprite
-`@phosphor-icons/core` içindeki tek tek SVG'lerden, **yalnızca kaynakta
-kullanılan** ikonlar için `<symbol>` seti üretir. Tüm seti göndermek 1500+ ikon,
-yani birkaç megabayt; kullanım taraması sprite'ı tipik olarak 10-30 sembolde
-tutuyor.
+**Yalnızca kaynakta kullanılan** ikonlar için bir `<symbol>` seti üretir. Tüm
+seti göndermek 1500+ ikon, yani birkaç megabayt; kullanım taraması sprite'ı
+tipik olarak 10-30 sembolde tutuyor. Çıktı hash'li `sprite.svg` olarak
+`public/assets/` altına yazılır ve precompress kapsamına girer.
+Kaynak **XOR** seçilir — ikisi birleştirilmez:
+1. `icons.dir` (varsayılan `icons/`) **dizin olarak varsa** yalnızca oradaki
+   düz SVG'ler. Boş dizin Phosphor'a düşmez; fallback için dizini silin.
+2. Aksi hâlde `@phosphor-icons/core` (uygulamanın `node_modules`'ünden). Kurulu
+   değilse adım sessizce atlanır.
+Yerel dosya adları:
+| Dosya | Sprite anahtarı |
+| --- | --- |
+| `icons/house.svg` | `house:regular` |
+| `icons/house-regular.svg` | `house:regular` |
+| `icons/arrow-right-bold.svg` | `arrow-right:bold` |
 - Sembol id'si: `<kebab-ad>-<weight>`, örn. `arrow-right-bold`.
-- Paket **uygulamanın** `node_modules`'ünden çözülür (ikon seti uygulamanın
-  devDependency'si); kurulu değilse adım sessizce atlanır.
-- Taranan dizinler varsayılan olarak `views`, `client`, `routes`, `lib`;
-  `icons.scan` ile değiştirilebilir. Taranan uzantılar: `.ejs`, `.js`, `.mjs`.
+- `viewBox` kaynak SVG'den `<symbol>`'e taşınır; yoksa `0 0 256 256`
+  (Phosphor ve `icon()` ile uyum için önerilen kutu).
+- Taranan dizinler varsayılan olarak `views`, `client`, `routes`, `lib`,
+  `features`, `shared`; `icons.scan` ile değiştirilebilir. Taranan uzantılar:
+  `.ejs`, `.jsk`, `.js`, `.mjs`.
 - Ağırlıklar: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. Tanınmayan
   bir ağırlık `regular` sayılır.
@@ -285,7 +301,7 @@ Bu uyarıyı görürseniz ya adı sabit yazın, ya `icons.scan` listesine ilgili
 dizini ekleyin, ya da adı bir yapılandırma alanında `icon: "XLogo"` biçiminde
 tutun.
-Phosphor'da bulunamayan adlar build sonunda özet olarak uyarılır:
+Kaynakta bulunamayan adlar build sonunda özet olarak uyarılır:
 `N icons missing → …`
 ## Görsel optimizasyonu
@@ -355,7 +371,7 @@ Bu dosyaları `staticPrecompressed` middleware'i servis eder; kopya yoksa istek
 | `tailwindcss` | CSS (peer) | Tailwind direktifleri çözülemez |
 | `lightningcss` | CSS minifikasyonu | Tailwind çıktısı kullanılır, birkaç kB daha büyük |
 | `sharp` | Görsel optimizasyonu | Adım atlanır; `image()` orijinali kullanır |
-| `@phosphor-icons/core` | İkon sprite | Adım atlanır; `icon()` boş `<use>` üretir |
+| `@phosphor-icons/core` | İkon sprite (yerel `icons/` yoksa) | Adım atlanır; `icon()` boş `<use>` üretir |
 CSS kullanmayacaksanız `paths.styles` dosyasını hiç oluşturmayın: adım uyarıyla
 atlanır ve postcss'e ihtiyaç kalmaz.

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

@@ -92,7 +92,7 @@ export default {
   watch: ["data"],
   fonts: [{ family: "Inter", weights: [400, 600, 700] }],
-  icons: { scan: ["views", "client", "routes", "lib"] },
+  icons: { dir: "icons", scan: ["views", "client", "routes", "lib"] },
   images: { widths: [400, 800, 1200], quality: 78, skip: ["downloads"] },
   clientEnv: ["PUBLIC_WS_URL"],
@@ -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)
@@ -475,21 +500,29 @@ fonts: [
 ## `icons`
-**Type:** `{ scan?: string[] } | false` — **Default:** `{}`
+**Type:** `{ scan?: string[], dir?: string } | false` — **Default:** `{ dir: "icons" }`
-Phosphor SVG sprite generation.
+SVG icon sprite generation. The source is chosen **XOR**: if the `icons.dir`
+directory exists, only the flat SVGs there are used; otherwise
+`@phosphor-icons/core` (when installed).
 | Value | Result |
 | --- | --- |
-| `{}` (default) | The sprite is generated; scanned directories are `["views", "client", "routes", "lib"]` |
+| `{}` (default) | `dir: "icons"`; scanned directories are `["views", "client", "routes", "lib", "features", "shared"]` |
+| `{ dir: "assets/icons" }` | Changes the local SVG root |
 | `{ scan: [...] }` | Changes the scanned directories |
 | `false` | The sprite step is skipped entirely |
-If `@phosphor-icons/core` is not in the application's `node_modules`, the step is
-silently skipped. Details: [08-build.md](./08-build.md).
+A local directory (when present) uses flat file names: `house.svg` →
+`house:regular`, `house-bold.svg` → `house:bold`. An empty `icons/` directory
+does not fall back to Phosphor — delete the directory to open the fallback.
+Details: [08-build.md](./08-build.md).
 ```js
-icons: { scan: ["views", "client", "routes", "lib", "content"] }
+icons: {
+  dir: "icons",
+  scan: ["views", "client", "routes", "lib", "content"],
+}
 ```
 ## `images`

package/docs/en/08-build.md CHANGED Viewed

@@ -259,17 +259,33 @@ Because the `.woff2` extension and the `/fonts/` prefix are in the default
 ## Icon sprite
-From the individual SVGs inside `@phosphor-icons/core`, it produces a `<symbol>`
-set for **only the icons actually used in the source**. Shipping the whole set
-means 1500+ icons, i.e. several megabytes; usage scanning typically keeps the
-sprite at 10-30 symbols.
+Produces a `<symbol>` set for **only the icons actually used in the source**.
+Shipping the whole set means 1500+ icons, i.e. several megabytes; usage scanning
+typically keeps the sprite at 10-30 symbols. The hashed `sprite.svg` is written
+under `public/assets/` and is covered by precompress.
+The source is chosen **XOR** — the two are never merged:
+1. If `icons.dir` (default `icons/`) **exists as a directory**, only the flat
+   SVGs there. An empty directory does not fall back to Phosphor; delete the
+   directory to open the fallback.
+2. Otherwise `@phosphor-icons/core` (from the application's `node_modules`). If
+   it is not installed, the step is silently skipped.
+Local file names:
+| File | Sprite key |
+| --- | --- |
+| `icons/house.svg` | `house:regular` |
+| `icons/house-regular.svg` | `house:regular` |
+| `icons/arrow-right-bold.svg` | `arrow-right:bold` |
 - Symbol id: `<kebab-name>-<weight>`, e.g. `arrow-right-bold`.
-- The package is resolved from the **application's** `node_modules` (the icon set
-  is the application's devDependency); if it is not installed, the step is
-  silently skipped.
-- The scanned directories default to `views`, `client`, `routes`, `lib`; they can
-  be changed with `icons.scan`. Scanned extensions: `.ejs`, `.js`, `.mjs`.
+- `viewBox` is copied from the source SVG onto the `<symbol>`; if missing,
+  `0 0 256 256` (recommended for Phosphor / `icon()` compatibility).
+- The scanned directories default to `views`, `client`, `routes`, `lib`,
+  `features`, `shared`; they can be changed with `icons.scan`. Scanned
+  extensions: `.ejs`, `.jsk`, `.js`, `.mjs`.
 - Weights: `thin`, `light`, `regular`, `bold`, `fill`, `duotone`. An
   unrecognised weight counts as `regular`.
@@ -296,8 +312,8 @@ If you see this warning, either write the name as a constant, or add the relevan
 directory to the `icons.scan` list, or keep the name in a configuration field in
 the form `icon: "XLogo"`.
-Names that cannot be found in Phosphor are warned about as a summary at the end
-of the build: `N icons missing → …`
+Names that cannot be found in the chosen source are warned about as a summary at
+the end of the build: `N icons missing → …`
 ## Image optimisation
@@ -373,7 +389,7 @@ copy, the request is handed over to `express.static`
 | `tailwindcss` | CSS (peer) | Tailwind directives cannot be resolved |
 | `lightningcss` | CSS minification | Tailwind's output is used, a few kB bigger |
 | `sharp` | Image optimisation | The step is skipped; `image()` uses the original |
-| `@phosphor-icons/core` | Icon sprite | The step is skipped; `icon()` produces an empty `<use>` |
+| `@phosphor-icons/core` | Icon sprite (when no local `icons/` dir) | The step is skipped; `icon()` produces an empty `<use>` |
 If you are not going to use CSS, simply never create the `paths.styles` file: the
 step is skipped with a warning and postcss is not needed.

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.5",
   "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"