@wenathlan/cobaia 2.0.165 → 2.0.167

package/nginx.conf

@@ -0,0 +1,106 @@
+# cobaia face — the monetization face: the nginx surface of the cobaia container pair.
+# the static theme of the cobaia container pair: the ads and plans console
+# the vite build assembles into the site container, served beside the /api/*
+# proxy lane that carries every platform call to the cobaia container.
+# until this conf the app rode the registry image alone: no compose seated
+# the pair, and every /api call of the theme answered the away rehearsal.
+#
+# the resolver is the docker embedded dns (127.0.0.11) — the vault face law
+# the family standardizes: the engine hostname resolves at request time, so
+# this container starts even while the engine recovers and keeps answering
+# after an engine recreation changes its address (an upstream block would
+# pin the address at config load and die with the first engine restart).
+
+resolver 127.0.0.11 valid=10s ipv6=off;
+
+server {
+    listen 8080;
+    server_name _;
+
+    # the staged theme surface (the shell, the hashed bundles, the fonts,
+    # the icons and the crawler files the build stages).
+    root /usr/share/nginx/html;
+    index index.html;
+
+    # the security header set the netlify _headers file declares — one
+    # header law across every deploy surface of the family.
+    add_header X-Content-Type-Options nosniff always;
+    add_header X-Frame-Options DENY always;
+    add_header Referrer-Policy strict-origin-when-cross-origin always;
+
+    # the transport law: the text faces ride compressed, the proxied
+    # answers included (gzip_proxied any — the engine lanes compress the
+    # same way).
+    gzip on;
+    gzip_vary on;
+    gzip_proxied any;
+    gzip_comp_level 6;
+    gzip_min_length 1024;
+    gzip_types text/plain text/css text/javascript application/javascript application/json application/xml image/svg+xml text/webmanifest;
+
+    # the api lane — every /api/* call rides the engine upstream (the
+    # compose `cobaia-engine` service, port 8080): the ^~ law keeps the lane
+    # ahead of every regex block below (a hashed asset pattern never steals
+    # an api path), the platform headers pass verbatim, the raw bodies ride
+    # un-sized (client_max_body_size 0 — the engine's own quota gate is the
+    # only ceiling a call answers), and the generous read window covers the
+    # slow platform lanes.
+    location ^~ /api/ {
+        set $cobaia_engine http://cobaia-engine:8080;
+        proxy_pass $cobaia_engine;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        client_max_body_size 0;
+        proxy_read_timeout 300s;
+        proxy_send_timeout 300s;
+    }
+
+    # the faun block of the face lane (the vault law): a database face
+    # inside the staged tree answers 403 — the raw store never ships over
+    # the face, the data flows through /api only.
+    location ~* \.(db|sqlite|sqlite3)(-wal|-shm|-journal)?$ {
+        return 403;
+    }
+
+    # the root-emit seal: the staged tree carries the sources beside the
+    # built faces (the family root-emit law), so the faces the platform
+    # lanes never publish answer the refusal here — the engine sources,
+    # the manifests and the lockfiles never leave the tree.
+    location ~* \.(ts|tsx|mts|cts|sql|prisma|lock|gemspec|csproj|java|go|kts|jsonc|json|toml|xml)(-wal|-shm|-journal)?$ {
+        return 403;
+    }
+
+    # the dotfile seal: the environment faces (.env, the editor seats)
+    # never answer over the face.
+    location ~* /\. {
+        return 403;
+    }
+
+    # the tree seal: the source homes the build never assembles refuse the
+    # same way (the modules, the suites, the docs, the sol sources).
+    location ~* ^/(node_modules|tests|docs|sol)(/|$) {
+        return 403;
+    }
+
+    # the hashed-asset cache law: the bundles the build stamps carry the
+    # content hash in the name, so the long lease is honest — the security
+    # header set repeats inside the lease the way the nginx inheritance law
+    # demands (an add_header at the location level would drop the server set).
+    location ~* \.(js|css|svg|woff2?|png|jpg|jpeg|webp|avif|ico|webmanifest)$ {
+        expires 30d;
+        add_header Cache-Control "public, immutable";
+        add_header X-Content-Type-Options nosniff always;
+        add_header X-Frame-Options DENY always;
+        add_header Referrer-Policy strict-origin-when-cross-origin always;
+    }
+
+    # the SPA rewrite the vercel/netlify configs declare: every deep link
+    # serves the shell, the router resolves it (the former site container
+    # had no fallback — a deep link answered 404).
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}

package/onboardingstate.ts

@@ -0,0 +1,211 @@
+/**
+ * onboardingstate.ts — the ONE writer of the visitor's seen flags, the state
+ * of the entry-flow contract (intro → onboarding → the site). The state is
+ * { introseen, onboardingseen } and it is catalogued, not just browser: the
+ * accessor consults the platform database over GET /api/v1/onboarding and
+ * writes it over POST /api/v1/onboarding, both HTTPS only — the base url
+ * arrives through VITE_ONBOARDING_URL and every candidate host is validated
+ * first (localhost, loopback, private, CGNAT, link-local and reserved ranges
+ * are refused, mapped IPv6 is normalized, so the flags never ride a dev or
+ * internal endpoint). The localStorage key cobaia.onboarding.seen is purely
+ * the offline cache of the database (the DB is the source of truth; the
+ * cache avoids replaying the flow while offline) and module memory covers
+ * the client-side re-navigation between the gates. Reads reconcile with a
+ * seen-wins merge — a stage seen anywhere stays seen, the flow is never
+ * forced twice. The page anchors never touch the flags directly: the intro
+ * marks introseen, the onboarding marks onboardingseen, the home entry gate
+ * only reads (the family flow contract the sibling apps already ride —
+ * cobaia joins the standardized intro → onboarding → entrada law).
+ */
+
+/** the visitor state the entry flow consults (the two gates of the site). */
+export type VisitorOnboarding = {
+  /** the presentation intro was seen — the splash never replays */
+  introseen: boolean;
+  /** the first-run onboarding was seen (finish or skip) — never forced again */
+  onboardingseen: boolean;
+};
+
+/** the stages one call can mark seen. */
+export type OnboardingStage = "intro" | "onboarding";
+
+/** the localStorage cache key (the DB mirror, never the source of truth). */
+const CACHE_KEY = "cobaia.onboarding.seen";
+
+/** the anonymous visitor of this surface (the platform gateway may key its own). */
+const VISITOR = "web";
+
+/** the configured platform base (HTTPS self-hosted gateway); empty answers cache-only. */
+const BASE =
+  (typeof import.meta !== "undefined" ? (import.meta.env?.VITE_ONBOARDING_URL as string | undefined) : undefined)
+    ?.trim()
+    .replace(/\/+$/, "") ?? "";
+
+/** the platform route the accessor rides (the gateway serves /api/v1/*). */
+const API_PATH = "/api/v1/onboarding";
+
+/** the abort window of the platform read (ms) — the flow never blocks on a slow gateway. */
+const READ_TIMEOUT_MS = 2500;
+
+/** module memory: the flags of the session, consulted before any i/o. */
+let memory: VisitorOnboarding | null = null;
+
+/**
+ * Validates a platform base url: HTTPS only, and the host must be public —
+ * localhost, loopback, private, link-local, CGNAT, unique-local and
+ * reserved documentation ranges are refused; IPv4-mapped IPv6 literals are
+ * normalized to their IPv4 side and any other IPv6 literal is refused (the
+ * gateway rides a name).
+ *
+ * @param base the configured base url candidate.
+ * @returns true when the base may be consulted.
+ */
+export function hostallowed(base: string): boolean {
+  try {
+    const url = new URL(base);
+    if (url.protocol !== "https:") return false;
+    const host = url.hostname
+      .toLowerCase()
+      .replace(/\.+$/, "")
+      .replace(/^\[|\]$/g, "");
+    if (host.length === 0) return false;
+    if (host === "localhost" || host === "0.0.0.0" || host === "::1") return false;
+    if (host.endsWith(".localhost") || host.endsWith(".local") || host.endsWith(".internal")) return false;
+    // the ipv4-mapped ipv6 form (the url parser normalizes the decimals away)
+    if (host.startsWith("::ffff:")) {
+      const mapped = host.slice("::ffff:".length).match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+      return mapped !== null && publicipv4(Number(mapped[1]), Number(mapped[2]));
+    }
+    const v4 = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) return publicipv4(Number(v4[1]), Number(v4[2]));
+    // every other ipv6 literal: the gateway rides a name, not an address
+    if (host.includes(":")) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** the public side of an ipv4 address (the first two octets decide). */
+function publicipv4(a: number, b: number): boolean {
+  if (a === 0 || a === 10 || a === 127) return false;
+  if (a === 172 && b >= 16 && b <= 31) return false;
+  if (a === 192 && b === 168) return false;
+  if (a === 169 && b === 254) return false;
+  if (a === 100 && b >= 64 && b <= 127) return false;
+  if (a === 192 && b === 0) return false;
+  if (a === 198 && (b === 51 || b === 52)) return false;
+  if (a === 203 && b === 0) return false;
+  return true;
+}
+
+/**
+ * Answers the flags after one stage was marked seen (pure: the writer and
+ * the tests share this merge — seen-wins, a stage never unsees).
+ *
+ * @param state the flags before the write.
+ * @param stage the stage being marked seen.
+ * @returns the flags after the write.
+ */
+export function mergeStage(state: VisitorOnboarding, stage: OnboardingStage): VisitorOnboarding {
+  return stage === "intro" ? { ...state, introseen: true } : { ...state, onboardingseen: true };
+}
+
+/** Reads the localStorage cache; any corruption answers null (the cache is best effort). */
+function readCache(): VisitorOnboarding | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(CACHE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Partial<VisitorOnboarding>;
+    return { introseen: parsed.introseen === true, onboardingseen: parsed.onboardingseen === true };
+  } catch {
+    return null;
+  }
+}
+
+/** Mirrors the flags into the localStorage cache (silently skipped when storage is sealed). */
+function writeCache(state: VisitorOnboarding): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(CACHE_KEY, JSON.stringify(state));
+  } catch {
+    // the cache is best effort: the DB and the memory stay authoritative
+  }
+}
+
+/** Reads the flags off the platform database; unreachable or unconfigured answers null. */
+async function readRemote(): Promise<VisitorOnboarding | null> {
+  if (!BASE || !hostallowed(BASE) || typeof fetch === "undefined") return null;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), READ_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${BASE}${API_PATH}?visitor=${encodeURIComponent(VISITOR)}`, {
+      headers: { accept: "application/json" },
+      signal: controller.signal,
+    });
+    if (!response.ok) return null;
+    const answer = (await response.json()) as Partial<VisitorOnboarding>;
+    return { introseen: answer.introseen === true, onboardingseen: answer.onboardingseen === true };
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Writes the flags to the platform database over POST; failures leave the cache holding them. */
+async function writeRemote(state: VisitorOnboarding): Promise<void> {
+  if (!BASE || !hostallowed(BASE) || typeof fetch === "undefined") return;
+  try {
+    await fetch(`${BASE}${API_PATH}`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ visitor: VISITOR, ...state }),
+    });
+  } catch {
+    // the cache mirrors the flags until the platform answers again
+  }
+}
+
+/**
+ * Reads the visitor state: module memory first, then the platform database
+ * over GET /api/v1/onboarding, then the localStorage cache — reconciled with
+ * the seen-wins merge so a stage seen anywhere stays seen. The session
+ * answer is memoized; re-navigation never refetches.
+ *
+ * @returns the visitor onboarding flags.
+ */
+export async function readOnboardingState(): Promise<VisitorOnboarding> {
+  if (memory) return memory;
+  const cache = readCache();
+  const remote = await readRemote();
+  const state: VisitorOnboarding = {
+    introseen: (cache?.introseen ?? false) || (remote?.introseen ?? false),
+    onboardingseen: (cache?.onboardingseen ?? false) || (remote?.onboardingseen ?? false),
+  };
+  memory = state;
+  if (remote) writeCache(state);
+  return state;
+}
+
+/**
+ * Marks one stage seen and persists it everywhere: module memory, the
+ * localStorage cache and — when a platform base is configured — the
+ * database over POST /api/v1/onboarding. The ONLY writer of the flags.
+ *
+ * @param stage the stage the visitor just saw (or deliberately skipped).
+ * @returns the flags after the write.
+ */
+export async function markOnboardingStage(stage: OnboardingStage): Promise<VisitorOnboarding> {
+  const previous = memory ?? (await readOnboardingState());
+  memory = mergeStage(previous, stage);
+  writeCache(memory);
+  await writeRemote(memory);
+  return memory;
+}
+
+/** Test seam: clears the module memory (the cache and the platform are untouched). */
+export function resetOnboardingMemory(): void {
+  memory = null;
+}