@velora-cms/server 0.11.0

package/dist/boot/resolve-boot-mode.js

@@ -0,0 +1,206 @@
+import { loadPrismaClient } from "../db/load-prisma-client.js";
+import { resolveClientDir } from "../db/resolve-client-dir.js";
+// How long resolveBootMode waits for countAdmins() before giving up.
+//
+// FAIL CLOSED cuts both ways: a hung probe must not be allowed to hang the
+// whole boot forever, because that trades a wrong-mode security bug for a
+// silent-hang operability bug — no log line, just a process that never
+// reaches app.listen and an orchestrator that restart-loops it with no
+// explanation. This bounds the wait and routes a timeout into the exact
+// same refusal as any other probe failure, so the operator gets the named
+// cause instead of a silent hang.
+export const ADMIN_PROBE_TIMEOUT_MS = 10_000;
+// Exported so routes/setup.ts's request-time re-probe (POST /api/setup/
+// complete, admin-only mode) can bound ITS await on countAdminUsers() the
+// same way this module bounds its own boot-time probe (F4, S164 final
+// review of Session 164's admin-only wizard task) — one bound, one
+// constant, both call sites, instead of a second timeout implementation
+// that could drift from this one.
+export function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`admin probe did not resolve within ${ms}ms`));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}
+// Which of three states this process starts in.
+//
+// It used to be two — index.ts asked only whether DATABASE_URL was set —
+// and that left a hole big enough to brick an instance. routes/setup.ts's
+// admin creation is the ONLY production path that makes a user with
+// role:"admin", and it is registered solely by buildSetupOnlyApp(), which
+// only ran when DATABASE_URL was unset. Inject a DATABASE_URL pointing at
+// an empty database, as every container and systemd deployment does, and
+// you got the full app with no users, no login and no way to create one.
+//
+//   DATABASE_URL unset            -> setup-full        (unchanged)
+//   set, no admin rows            -> setup-admin-only  (new)
+//   set, at least one admin       -> full              (unchanged)
+//
+// FAIL CLOSED, deliberately. The probe is a real query and can fail for
+// reasons that have nothing to do with setup. If an error were treated as
+// "no admin yet", a transient database outage would turn a live public
+// instance into an unauthenticated create-admin endpoint. Only a
+// SUCCESSFUL count of zero selects setup-admin-only; anything else
+// refuses the boot and says why.
+export async function resolveBootMode(env, countAdmins) {
+    if (!env.DATABASE_URL)
+        return "setup-full";
+    // Both a rejected probe and a bad-but-resolved one refuse through this
+    // same shape, so the operator always gets the named cause rather than a
+    // silently wrong mode.
+    const refuse = (cause) => {
+        throw new Error("Refusing to start: DATABASE_URL is set but Velora could not determine whether an administrator " +
+            `exists. Continuing would either lock you out or expose first-run setup on a live instance. Cause: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    };
+    let admins;
+    try {
+        admins = await withTimeout(countAdmins(), ADMIN_PROBE_TIMEOUT_MS);
+    }
+    catch (err) {
+        return refuse(err);
+    }
+    // A resolution is not a rejection. countAdmins is an injected function
+    // with no compile-time guarantee about what it resolves with — NaN, a
+    // negative number, undefined from a caller that forgot to return — and
+    // every one of those makes `admins > 0` false, which is exactly what
+    // used to select "setup-admin-only", the branch that exposes an
+    // unauthenticated create-admin endpoint. Only a SUCCESSFUL count of zero
+    // may select it, so anything else routes through the same refusal a
+    // rejection gets.
+    if (!Number.isInteger(admins) || admins < 0) {
+        return refuse(new Error(`countAdmins() resolved with ${String(admins)}, which is not a non-negative integer`));
+    }
+    // Safe polarity: written so that even if the guard above were ever
+    // removed, the fallthrough is the locked-out branch ("full", requiring a
+    // real admin to already exist) rather than the exposed one.
+    return admins === 0 ? "setup-admin-only" : "full";
+}
+// F1: which Prisma error codes are POSITIVE EVIDENCE that the database has
+// nothing in it yet, as opposed to an unknown/ambiguous failure. Every
+// container and systemd deployment (see resolveBootMode's own header above)
+// commonly injects a DATABASE_URL pointing at a database that exists but
+// has no tables yet, or — less commonly — that doesn't exist as a catalog
+// entry on the server at all. Both are a real, provable "zero admins,"
+// not a probe that merely came back inconclusive.
+//
+// Confirmed against the ACTUAL installed @prisma/client@6.19.3 runtime,
+// two ways:
+//   1. Read node_modules/.pnpm/@prisma+client@6.19.3.../runtime/client.js:
+//      its engine-error-kind switch maps "TableDoesNotExist" -> "P2021"
+//      and "DatabaseDoesNotExist" -> "P1003" verbatim.
+//   2. Reproduced both live against this repo's own generated per-dialect
+//      clients (apps/server/dist/prisma-clients/*), not just the mapping
+//      table: querying a genuinely empty (freshly created, zero-table)
+//      SQLite file throws PrismaClientKnownRequestError with
+//      `.code === "P2021"`; connecting to a Postgres database name that
+//      does not exist on the server at all throws
+//      PrismaClientInitializationError with `.errorCode === "P1003"`.
+//      Deliberately checked BOTH `.code` (PrismaClientKnownRequestError,
+//      the class query-execution failures like P2021 use) and `.errorCode`
+//      (PrismaClientInitializationError, the class connection-time
+//      failures like P1003 use) — they are different classes with the
+//      code on a different property, and matching only one would silently
+//      miss the other. Also confirmed, so this stays fail-closed: an
+//      unrelated failure (wrong password -> P1000, unreachable host ->
+//      P1001) still comes back with neither property matching either code,
+//      so it keeps refusing exactly as before.
+const UNPROVISIONED_DATABASE_ERROR_CODES = new Set(["P2021", "P1003"]);
+function isUnprovisionedDatabaseError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const candidate = err;
+    return ((typeof candidate.code === "string" && UNPROVISIONED_DATABASE_ERROR_CODES.has(candidate.code)) ||
+        (typeof candidate.errorCode === "string" && UNPROVISIONED_DATABASE_ERROR_CODES.has(candidate.errorCode)));
+}
+// F1 (fix wave 2): the non-secret SHAPE of a DATABASE_URL — host, database
+// name/path, and ?schema= if present — for the warning below. Never the
+// password: this is logged, potentially to a place less trusted than the
+// process's own env. Duck-typed parsing (not a Prisma helper) because the
+// three Tier 1 dialects don't share one URL grammar: postgres/mysql are
+// real `scheme://user:pass@host:port/db?query` URLs `new URL()` parses
+// natively; `file:` (SQLite) has no host/credentials at all, just a path,
+// which isn't secret.
+export function describeDatabaseUrlShape(url) {
+    if (!url)
+        return "(no DATABASE_URL set)";
+    if (url.startsWith("file:")) {
+        return `sqlite file "${url.slice("file:".length)}"`;
+    }
+    try {
+        const parsed = new URL(url);
+        const schema = parsed.searchParams.get("schema");
+        const database = parsed.pathname.replace(/^\//, "");
+        return (`host "${parsed.hostname}${parsed.port ? `:${parsed.port}` : ""}", database "${database}"` +
+            (schema ? `, schema "${schema}"` : ""));
+    }
+    catch {
+        return "(DATABASE_URL could not be parsed)";
+    }
+}
+// The real probe. Uses its own short-lived client rather than db/prisma.ts's
+// module-level `prisma` singleton: importing that module connects as a
+// side effect of the import, and the decision this informs is whether to
+// build an app that connects at all.
+export async function countAdminUsers() {
+    const client = await loadPrismaClient(resolveClientDir());
+    let result;
+    try {
+        // Explicit $connect() BEFORE the query, not Prisma's default lazy
+        // connect-on-first-query: confirmed empirically (see above) that a
+        // "database does not exist" failure reached via a bare `user.count()`
+        // call comes back as a PrismaClientInitializationError with
+        // `errorCode: undefined` — Prisma's lazy-connect path drops it — while
+        // the IDENTICAL failure reached via an explicit `$connect()` carries
+        // `errorCode: "P1003"` correctly. Table-not-found (P2021) is a
+        // query-execution error either way, unaffected by this ordering, since
+        // it can only happen after a connection already succeeded.
+        await client.$connect();
+        result = await client.user.count({ where: { role: "admin" } });
+    }
+    catch (err) {
+        // The query's own error (e.g. ECONNREFUSED) is the diagnostic the
+        // operator needs. Without this catch, a $disconnect() failure in a
+        // `finally` below would REPLACE it — JS lets a throw in `finally`
+        // override a pending exception — so the operator would see a
+        // disconnect error instead of the real cause. Swallow the disconnect
+        // failure and let the original win.
+        try {
+            await client.$disconnect();
+        }
+        catch {
+            // Swallowed deliberately: see above.
+        }
+        // A missing table or missing database IS a successful count of zero,
+        // not a failure — see UNPROVISIONED_DATABASE_ERROR_CODES above. Every
+        // other error still refuses by rethrowing, unchanged.
+        if (isUnprovisionedDatabaseError(err)) {
+            // F1 (fix wave 2, S164 review): this conversion is defensible — a
+            // connection that cannot see a `users` table holds no admin
+            // credentials to protect — but it must not be SILENT. Verified
+            // live: a real, populated Postgres reached through a `?schema=`
+            // that lacks the tables throws this same P2021 and, before this
+            // warning, opened the unauthenticated wizard with zero diagnostics.
+            // A mistyped sqlite path and a mistyped database name (P1003) do the
+            // same. Named channel + remedy, same tone as
+            // db/resolve-client-dir.ts's own console.warn.
+            const code = err.code ?? err.errorCode;
+            console.warn(`countAdminUsers: treating ${String(code)} as zero admins (no users table reachable) at ` +
+                `${describeDatabaseUrlShape(process.env.DATABASE_URL)}. This is expected on a genuinely fresh, ` +
+                "unprovisioned database. If this DATABASE_URL is meant to reach an EXISTING, populated database, " +
+                "check for a typo in the host, database name, or ?schema= — getting this wrong opens the " +
+                "unauthenticated setup wizard on an instance whose real admins are just one connection detail away.");
+            return 0;
+        }
+        throw err;
+    }
+    await client.$disconnect();
+    return result;
+}

package/dist/bundled-templates/com.velora.blog/manifest.json

@@ -0,0 +1,39 @@
+{
+  "id": "com.velora.blog",
+  "name": "Blog",
+  "version": "0.1.0",
+  "type": "template",
+  "description": "The official Velora blog template — posts, authors and tags, ready to publish.",
+  "author": "Velora",
+  "license": "MIT",
+  "cmsVersion": "^0.1.0",
+  "databaseCompatibility": {
+    "storageType": "simple",
+    "supported": [
+      "postgresql",
+      "mysql",
+      "sqlite"
+    ]
+  },
+  "permissions": {
+    "needsStructuredData": false,
+    "needsExternalNetwork": false,
+    "needsFileSystemAccess": false
+  },
+  "contributions": {
+    "documentTypes": [
+      {
+        "name": "Author",
+        "icon": "user"
+      },
+      {
+        "name": "Post",
+        "icon": "file-text"
+      },
+      {
+        "name": "Tag",
+        "icon": "tag"
+      }
+    ]
+  }
+}

package/dist/bundled-templates/com.velora.blog/sample-content.json

@@ -0,0 +1,14 @@
+{
+  "nodes": [
+    { "documentType": "Author", "slug": "jane-doe", "parent": null,
+      "data": { "name": "Jane Doe", "bio": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Founding editor of this blog." } ] } ] } } },
+    { "documentType": "Tag", "slug": "announcements", "parent": null,
+      "data": { "label": "Announcements", "description": "Site news." } },
+    { "documentType": "Tag", "slug": "guides", "parent": null,
+      "data": { "label": "Guides", "description": "How-to articles." } },
+    { "documentType": "Post", "slug": "hello-velora", "parent": "jane-doe",
+      "data": { "title": "Hello, Velora", "body": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "This sample post was created by the Blog template. Edit or delete it freely." } ] } ] }, "publishedDate": "2026-08-13", "tags": "announcements" } },
+    { "documentType": "Post", "slug": "writing-your-first-post", "parent": "jane-doe",
+      "data": { "title": "Writing your first post", "body": { "type": "doc", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Open the content tree, pick an author, and add a Post under them." } ] } ] }, "publishedDate": "2026-08-13", "tags": "guides" } }
+  ]
+}

package/dist/config/admin-ui.d.ts

@@ -0,0 +1 @@
+export declare function isAdminUiEnabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/config/admin-ui.js

@@ -0,0 +1,10 @@
+// The /velora admin SPA (S184). ON by default — `VELORA_ADMIN=off`
+// disables serving it (the hosted demo's setting) without touching the
+// API. Same trim/lowercase parsing idiom as public-docs.ts, with one
+// deliberate difference: the docs flag accepts the general "false"/"0"
+// disable spellings, while this one is specified (design doc §2) as the
+// single literal `off` — the value the demo box's env file carries.
+export function isAdminUiEnabled(env = process.env) {
+    // Default ON: only an explicit `off` turns it off.
+    return env.VELORA_ADMIN?.trim().toLowerCase() !== "off";
+}

package/dist/config/cors.d.ts

@@ -0,0 +1,7 @@
+export declare function parseCorsOrigins(raw: string | undefined, warn?: (msg: string) => void): string[];
+export declare function corsOptionsFromEnv(warn?: (msg: string) => void): {
+    origin: string[] | false;
+    methods: string[];
+    allowedHeaders: string[];
+    credentials: false;
+};

package/dist/config/cors.js

@@ -0,0 +1,53 @@
+// S160: cross-origin access for plugin routes. A form submission comes
+// from a visitor's browser on the FRONTEND's origin, so the public
+// access tier is only reachable cross-origin when the operator names
+// that origin here. Empty/unset means no CORS headers at all —
+// same-origin only, secure by default; enabling it is a conscious
+// per-deployment act. Deploy-time env, not per-form: the plugin-route
+// dispatcher has no path params, so a preflight can never know which
+// form it is for.
+//
+// `warn`, when given, is called once per dropped entry (non-empty but
+// not an absolute origin — e.g. a trailing slash, a bare host, a path)
+// so a misconfigured `VELORA_CORS_ORIGINS` doesn't fail in total
+// silence; optional (and defaulted to a no-op by corsOptionsFromEnv
+// below) so the existing single-argument call shape keeps working.
+export function parseCorsOrigins(raw, warn) {
+    if (!raw)
+        return [];
+    const valid = [];
+    for (const entry of raw.split(",").map((e) => e.trim())) {
+        if (!entry)
+            continue;
+        try {
+            const url = new URL(entry);
+            if (url.origin === entry) {
+                valid.push(entry);
+                continue;
+            }
+        }
+        catch {
+            // falls through to the dropped-entry warning below
+        }
+        warn?.(`VELORA_CORS_ORIGINS: dropping "${entry}" — not an absolute origin (scheme://host[:port], no path)`);
+    }
+    return valid;
+}
+export function corsOptionsFromEnv(warn = () => { }) {
+    const origins = parseCorsOrigins(process.env.VELORA_CORS_ORIGINS, warn);
+    return {
+        // `false` disables CORS headers entirely rather than echoing "*".
+        origin: origins.length > 0 ? origins : false,
+        // GET/POST/OPTIONS only — a manifest can declare a "public" apiRoute
+        // on PUT/PATCH/DELETE too, but it's deliberately not reachable
+        // cross-origin: those verbs aren't part of this allowlist's browser
+        // contract, only same-origin (or apiKey/admin, credentialed) callers
+        // can reach them. Widen this list only as a deliberate, reviewed
+        // decision, not to unblock one plugin.
+        methods: ["GET", "POST", "OPTIONS"],
+        allowedHeaders: ["content-type", "authorization"],
+        // Plugin routes authenticate via the Authorization header, never
+        // cookies — so no credentialed cross-origin surface is opened.
+        credentials: false,
+    };
+}

package/dist/config/env-file-path.d.ts

@@ -0,0 +1,2 @@
+export declare const DEFAULT_ENV_FILENAME = ".env";
+export declare function resolveEnvFilePath(env?: NodeJS.ProcessEnv, cwd?: string): string;

package/dist/config/env-file-path.js

@@ -0,0 +1,22 @@
+import { isAbsolute, resolve } from "node:path";
+// The filename used when VELORA_ENV_FILE isn't set. Named so it's a
+// config-visible constant, never a magic literal repeated between this
+// module and its tests.
+export const DEFAULT_ENV_FILENAME = ".env";
+// The ONE env-file rule, shared by the loader (load-env.ts) and the
+// wizard's writer (setup/persist-env-config.ts). Because both use this,
+// the file the wizard writes is by construction the file the next boot
+// reads.
+//
+// Deliberately NOT a directory walk. persist-env-config.ts used to build
+// its path by walking four levels up from its own compiled location,
+// which assumes the monorepo's depth and overshoots — potentially to the
+// drive root — on a flattened `pnpm deploy` output. Nothing here reads
+// import.meta.url: where the code lives must not decide where config
+// lives.
+export function resolveEnvFilePath(env = process.env, cwd = process.cwd()) {
+    const override = env.VELORA_ENV_FILE?.trim();
+    if (override)
+        return isAbsolute(override) ? override : resolve(cwd, override);
+    return resolve(cwd, DEFAULT_ENV_FILENAME);
+}

package/dist/config/graphql-limits.d.ts

@@ -0,0 +1,2 @@
+export declare function maxQueryDepth(): number;
+export declare function maxQueryComplexity(): number;

package/dist/config/graphql-limits.js

@@ -0,0 +1,26 @@
+// Depth + complexity guards for the public GraphQL surface (Session 115,
+// Task 2) — wired into mercurius' registration in public-api.ts. Same idiom
+// as rate-limit.ts's configuredMax(): read fresh at call time, not frozen
+// at module-import time, since this module is statically imported (via
+// app.ts) well before a test's env override gets a chance to take effect.
+//
+// GraphiQL's own introspection query is depth 7 and measures at complexity
+// 220 against this schema (see src/graphql/field-count-rule.ts for the
+// fragment-aware field-count calculation). 500 clears it with a >2x margin.
+// Decided during the Session 115 GraphQL search protection design work.
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_COMPLEXITY = 500;
+// Number(raw ?? fallback) is rate-limit.ts's exact expression shape; the
+// only addition here is validation that the value is a positive integer.
+// Reject NaN, 0 (which silently disables mercurius' depth check), and
+// negative values — all fall back to the default.
+function readPositiveInt(raw, fallback) {
+    const value = Number(raw ?? fallback);
+    return !Number.isInteger(value) || value <= 0 ? fallback : value;
+}
+export function maxQueryDepth() {
+    return readPositiveInt(process.env.VELORA_GRAPHQL_MAX_DEPTH, DEFAULT_MAX_DEPTH);
+}
+export function maxQueryComplexity() {
+    return readPositiveInt(process.env.VELORA_GRAPHQL_MAX_COMPLEXITY, DEFAULT_MAX_COMPLEXITY);
+}

package/dist/config/headless.d.ts

@@ -0,0 +1 @@
+export declare function isHeadlessEnabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/config/headless.js

@@ -0,0 +1,8 @@
+// The deploy-time headless switch (Month 9): config-file-only by design,
+// like the DB dialect — no runtime admin toggle exists or should. Only
+// "true"/"1" opt in; anything else (including unset) keeps the public
+// /api/v1 namespace unregistered entirely.
+export function isHeadlessEnabled(env = process.env) {
+    const value = env.VELORA_HEADLESS?.trim().toLowerCase();
+    return value === "true" || value === "1";
+}

package/dist/config/license-revalidation.d.ts

@@ -0,0 +1,2 @@
+export declare function licenseCheckIntervalHours(env?: NodeJS.ProcessEnv): number;
+export declare function licenseStaleWarnDays(env?: NodeJS.ProcessEnv): number;

package/dist/config/license-revalidation.js

@@ -0,0 +1,16 @@
+/** How often installed paid plugins are re-validated against the license
+ * server, and how long an unreachable license server may go unheard from
+ * before the admin sees a warning. Both read fresh at call time so a test
+ * (or an operator) can change them without a restart of the module graph. */
+function readPositiveInt(raw, fallback) {
+    const parsed = Number(raw);
+    if (!raw || !Number.isInteger(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+export function licenseCheckIntervalHours(env = process.env) {
+    return readPositiveInt(env.VELORA_LICENSE_CHECK_INTERVAL_HOURS, 24);
+}
+export function licenseStaleWarnDays(env = process.env) {
+    return readPositiveInt(env.VELORA_LICENSE_STALE_WARN_DAYS, 7);
+}

package/dist/config/load-env.d.ts

@@ -0,0 +1 @@
+export declare function loadEnvFile(env?: NodeJS.ProcessEnv, cwd?: string): void;

package/dist/config/load-env.js

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { parse } from "dotenv";
+import { resolveEnvFilePath } from "./env-file-path.js";
+// Loads the env file in-process, so the production `start` script is a
+// plain `node dist/index.js` with no devDependency on its path.
+//
+// This replaces `dotenv -e ../../.env --` in package.json's start script.
+// dotenv-cli is a devDependency, so `pnpm deploy --prod` produced a
+// target where `start` failed before Node ran — the same defect class as
+// Session 155's @velora-cms/prisma-variants misclassification.
+//
+// Two behaviours are preserved deliberately, both measured against the
+// installed dotenv-cli@11.0.0 before this was written:
+//   1. A real environment variable BEATS a file value. Everything in
+//      apps/server/src/config/*.ts reads process.env directly, so this is
+//      the only place precedence is decided.
+//   2. A missing file is normal, not an error — a deploy target
+//      configured entirely by injected env vars has no file at all.
+//
+// Parsing is dotenv's own, the same parser dotenv-cli used. Note honestly
+// what that does NOT give us: dotenv.parse silently skips individual
+// malformed lines and reports no per-line error. We detect a file that
+// cannot be read, and a file with content that yields zero keys; we do
+// NOT detect one bad line among good ones. A hand-rolled line scanner
+// would false-positive on legitimate multi-line quoted values.
+export function loadEnvFile(env = process.env, cwd = process.cwd()) {
+    const path = resolveEnvFilePath(env, cwd);
+    if (!existsSync(path))
+        return;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        throw new Error(`Could not read the environment file at ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = parse(raw);
+    if (Object.keys(parsed).length === 0 && raw.trim().length > 0 && hasNonCommentContent(raw)) {
+        throw new Error(`The environment file at ${path} has content but no readable KEY=value pairs. ` +
+            "Refusing to boot half-configured — fix the file or delete it.");
+    }
+    for (const [key, value] of Object.entries(parsed)) {
+        if (key in env)
+            continue;
+        env[key] = value;
+    }
+}
+function hasNonCommentContent(raw) {
+    return raw.split(/\r?\n/).some((line) => {
+        const trimmed = line.trim();
+        return trimmed.length > 0 && !trimmed.startsWith("#");
+    });
+}

package/dist/config/marketplace.d.ts

@@ -0,0 +1,11 @@
+/** The hosted marketplace a fresh install browses out of the box (Session
+ * 180) — no setup step required for the common case. Deploy-time knob,
+ * like the headless flag: an operator who wants a different (or no)
+ * marketplace overrides it via VELORA_MARKETPLACE_URL. `off`
+ * (case-insensitive) or a blank value opts all the way out — the in-CMS
+ * marketplace browse/detail proxy routes go structurally absent (app.ts),
+ * same as the old unset-means-disabled behavior — for air-gapped or
+ * no-marketplace installs. Any other value is treated as a custom
+ * marketplace origin (e.g. a private/self-hosted marketplace). */
+export declare const DEFAULT_MARKETPLACE_URL = "https://marketplace.velora-cms.com";
+export declare function getMarketplaceBaseUrl(env?: NodeJS.ProcessEnv): string | undefined;

package/dist/config/marketplace.js

@@ -0,0 +1,19 @@
+/** The hosted marketplace a fresh install browses out of the box (Session
+ * 180) — no setup step required for the common case. Deploy-time knob,
+ * like the headless flag: an operator who wants a different (or no)
+ * marketplace overrides it via VELORA_MARKETPLACE_URL. `off`
+ * (case-insensitive) or a blank value opts all the way out — the in-CMS
+ * marketplace browse/detail proxy routes go structurally absent (app.ts),
+ * same as the old unset-means-disabled behavior — for air-gapped or
+ * no-marketplace installs. Any other value is treated as a custom
+ * marketplace origin (e.g. a private/self-hosted marketplace). */
+export const DEFAULT_MARKETPLACE_URL = "https://marketplace.velora-cms.com";
+export function getMarketplaceBaseUrl(env = process.env) {
+    const raw = env.VELORA_MARKETPLACE_URL;
+    if (raw === undefined)
+        return DEFAULT_MARKETPLACE_URL;
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.toLowerCase() === "off")
+        return undefined;
+    return trimmed.replace(/\/+$/, "");
+}

package/dist/config/preview.d.ts

@@ -0,0 +1,3 @@
+export declare function previewTokenTtlSeconds(): number;
+export declare function previewBaseUrl(): string | null;
+export declare function buildPreviewUrl(token: string, contentId: string): string | null;

package/dist/config/preview.js

@@ -0,0 +1,39 @@
+// Preview-token TTL (Session 116, Task 1) — separate file from
+// graphql-limits.ts since this is a different feature, but mirrors its
+// exact idiom: read fresh at call time (not frozen at module-import time)
+// so a test's env override always takes effect, and reject non-positive/
+// NaN/garbage input by falling back to the default rather than throwing.
+const DEFAULT_TTL_SECONDS = 1800;
+function readPositiveInt(raw, fallback) {
+    const value = Number(raw ?? fallback);
+    return !Number.isInteger(value) || value <= 0 ? fallback : value;
+}
+export function previewTokenTtlSeconds() {
+    return readPositiveInt(process.env.VELORA_PREVIEW_TOKEN_TTL, DEFAULT_TTL_SECONDS);
+}
+// Preview base URL (Session 117, Task 1) — returns the configured base URL
+// for preview links, or null if not configured. Empty/whitespace-only values
+// are treated as unset. Trailing slashes are stripped.
+export function previewBaseUrl() {
+    const raw = process.env.VELORA_PREVIEW_BASE_URL;
+    if (!raw) {
+        return null;
+    }
+    const trimmed = raw.trim();
+    if (!trimmed) {
+        return null;
+    }
+    // Strip trailing slashes
+    return trimmed.replace(/\/+$/, "");
+}
+// Builds a preview URL from the base and a token, or null if base is not
+// configured. Both token and contentId are URL-encoded.
+export function buildPreviewUrl(token, contentId) {
+    const base = previewBaseUrl();
+    if (!base) {
+        return null;
+    }
+    const encodedToken = encodeURIComponent(token);
+    const encodedId = encodeURIComponent(contentId);
+    return `${base}/api/preview?token=${encodedToken}&id=${encodedId}`;
+}

package/dist/config/public-docs.d.ts

@@ -0,0 +1 @@
+export declare function isPublicDocsEnabled(env?: NodeJS.ProcessEnv): boolean;

package/dist/config/public-docs.js

@@ -0,0 +1,9 @@
+// The public OpenAPI docs surface (Month 9, Session 109). ON by default —
+// an owner turns it OFF for post-launch hardening ("false"/"0"), which
+// 404s the docs URL without touching the /api/v1 API itself. Config-file
+// only, same shape as VELORA_HEADLESS.
+export function isPublicDocsEnabled(env = process.env) {
+    const value = env.VELORA_PUBLIC_DOCS?.trim().toLowerCase();
+    // Default ON: only an explicit disable turns it off.
+    return value !== "false" && value !== "0";
+}

package/dist/config/site.d.ts

@@ -0,0 +1,7 @@
+/** This instance's own domain, as the OPERATOR declares it — never the
+ * request's Host header. A license binds to this value once, on first
+ * validation, so it must be stable and unspoofable; an admin browsing
+ * via localhost, an IP, or a proxy must not be able to burn a buyer's
+ * one-shot binding on the wrong domain. Scheme and trailing slash are
+ * tolerated so a URL-shaped value still yields a bare host. */
+export declare function getSiteDomain(env?: NodeJS.ProcessEnv): string | undefined;

package/dist/config/site.js

@@ -0,0 +1,12 @@
+/** This instance's own domain, as the OPERATOR declares it — never the
+ * request's Host header. A license binds to this value once, on first
+ * validation, so it must be stable and unspoofable; an admin browsing
+ * via localhost, an IP, or a proxy must not be able to burn a buyer's
+ * one-shot binding on the wrong domain. Scheme and trailing slash are
+ * tolerated so a URL-shaped value still yields a bare host. */
+export function getSiteDomain(env = process.env) {
+    const raw = env.VELORA_SITE_DOMAIN?.trim().toLowerCase();
+    if (!raw)
+        return undefined;
+    return raw.replace(/^https?:\/\//, "").replace(/\/+$/, "");
+}

package/dist/config/trust-proxy.d.ts

@@ -0,0 +1,2 @@
+export declare function parseTrustProxy(raw: string | undefined): boolean | number | string | undefined;
+export declare function trustProxyFromEnv(env?: NodeJS.ProcessEnv): boolean | number | string | undefined;