Update hivegrid-cloud reference to latest main

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
davidandClaude Fable 5 committed 2026-07-08 16:15:37 +02:00
1 parent e98d38e716
commit 7b21524c86
3781 files changed
+373484 -225607

No files matched your search

@@ -1,4 +1,4 @@
# @toolctrl/config
# @hivegrid/config
Typed environment catalog and lightweight validation helpers for the `apps/web`, `apps/api` and `apps/worker` runtime split.
@@ -15,7 +15,7 @@ This package is now partially wired into runtime loaders for web/API/worker conf
## Current Inventory
The catalog is verified against `.env.example`, `.env.local.example`, `.env.production.example`, `.env.fly.example`, `.env.test`, Prisma `env(...)` usage, and active web/API/worker/package environment reads.
The catalog is verified against `.env.example`, `.env.local.example`, `.env.production.example`, `.env.test`, Prisma `env(...)` usage, and active web/API/worker/package environment reads.
| Variable | Classification | Targets | Source |
| ----------------------------------- | ---------------------- | ------------------------ | ---------------- |
@@ -34,9 +34,6 @@ The catalog is verified against `.env.example`, `.env.local.example`, `.env.prod
| `WEBHOOKS_URL` | optional-provider | web, api | code-and-example |
| `SUPABASE_API_URL` | optional-provider | web, api | code-and-example |
| `SUPABASE_KEY` | optional-provider | web, api | code-and-example |
| `STRIPE_SK` | optional-provider | web, api | code-and-example |
| `STRIPE_WEBHOOK_SIGNING_SECRET` | optional-provider | web, api | code-and-example |
| `STRIPE_ACCOUNT_COUNTRY` | production-only | web, api | example |
| `MAILJET_API_KEY` | optional-provider | web, api, worker | code-and-example |
| `MAILJET_FROM_EMAIL` | optional-provider | web, api, worker | code-and-example |
| `MAILJET_FROM_NAME` | optional-provider | web, api, worker | example |
@@ -1,5 +1,5 @@
{
"name": "@toolctrl/config",
"name": "@hivegrid/config",
"version": "0.0.0",
"private": true,
"type": "module",
@@ -120,7 +120,7 @@ describe("loadApiConfig", () => {
expect(result.ok).toBe(false);
expect(result.config).toMatchObject({
appName: "ToolController",
appName: "HiveGrid",
nodeEnv: "development",
listen: {
port: 3001,
@@ -135,7 +135,6 @@ describe("loadApiConfig", () => {
origins: {},
analytics: {},
mailjet: {},
stripe: {},
storage: {},
});
});
@@ -204,8 +203,13 @@ describe("loadApiConfig", () => {
JWT_SECRET: " jwt-secret-value ",
ANALYTICS_TOKEN: " analytics-token-value ",
MAILJET_WEBHOOK_SECRET: " mailjet-webhook-secret-value ",
STRIPE_SK: " stripe-secret-value ",
STRIPE_WEBHOOK_SIGNING_SECRET: " stripe-webhook-secret-value ",
LAGO_API_URL: " http://lago.internal:3000 ",
LAGO_API_KEY: " lago-api-key-value ",
LAGO_WEBHOOK_SECRET: " lago-webhook-secret-value ",
LAGO_TIMEOUT_MS: " 5000 ",
MOLLIE_API_KEY: " mollie-api-key-value ",
MOLLIE_PROFILE_ID: " mollie-profile-id-value ",
MOLLIE_TIMEOUT_MS: " 6000 ",
STORAGE_ENDPOINT: " https://storage.example.com ",
STORAGE_REGION: " us-east-1 ",
STORAGE_BUCKET: " uploads ",
@@ -238,9 +242,16 @@ describe("loadApiConfig", () => {
mailjet: {
webhookSecret: "mailjet-webhook-secret-value",
},
stripe: {
secretKey: "stripe-secret-value",
webhookSigningSecret: "stripe-webhook-secret-value",
lago: {
apiUrl: "http://lago.internal:3000",
apiKey: "lago-api-key-value",
webhookSecret: "lago-webhook-secret-value",
timeoutMs: 5000,
},
mollie: {
apiKey: "mollie-api-key-value",
profileId: "mollie-profile-id-value",
timeoutMs: 6000,
},
storage: {
endpoint: "https://storage.example.com",
@@ -266,6 +277,43 @@ describe("loadApiConfig", () => {
expect(loadApiConfig({ API_KEY_LEGACY_PLAINTEXT_FALLBACK: "invalid" }).config.apiKeys.allowLegacyPlaintextFallback).toBe(false);
});
test("defaults invalid Lago timeout without leaking Lago secrets into diagnostics", () => {
const result = loadApiConfig({
API_PORT: "not-a-port",
LAGO_API_URL: " https://lago.example.test ",
LAGO_API_KEY: " lago-secret-value ",
LAGO_WEBHOOK_SECRET: " lago-webhook-secret-value ",
LAGO_TIMEOUT_MS: "invalid",
});
expect(result.config.lago).toEqual({
apiUrl: "https://lago.example.test",
apiKey: "lago-secret-value",
webhookSecret: "lago-webhook-secret-value",
timeoutMs: 10_000,
});
const diagnosticText = JSON.stringify(result.diagnostics);
expect(diagnosticText).not.toContain("lago-secret-value");
expect(diagnosticText).not.toContain("lago-webhook-secret-value");
});
test("defaults invalid Mollie timeout without leaking Mollie secrets into diagnostics", () => {
const result = loadApiConfig({
API_PORT: "not-a-port",
MOLLIE_API_KEY: " mollie-secret-value ",
MOLLIE_PROFILE_ID: " mollie-profile-value ",
MOLLIE_TIMEOUT_MS: "invalid",
});
expect(result.config.mollie).toEqual({
apiKey: "mollie-secret-value",
profileId: "mollie-profile-value",
timeoutMs: 10_000,
});
const diagnosticText = JSON.stringify(result.diagnostics);
expect(diagnosticText).not.toContain("mollie-secret-value");
});
test("normalizes empty storage strings to undefined and redacts storage secrets from diagnostics", () => {
const storageSecretValues = ["storage-access-key-id-value", "storage-secret-access-key-value", "storage-session-token-value"];
const result = loadApiConfig({
@@ -2,9 +2,11 @@ import { getEnvVariableDefinition, validateEnv } from "./index.js";
import { getDomainRoutingConfig } from "./routing.js";
import type { ApiConfig, ApiConfigDiagnostic, ApiConfigErrorDetails, ApiConfigOptions, ApiConfigResult, EnvRecord, RequiredApiConfigOptions } from "./types.js";
const DEFAULT_APP_NAME = "ToolController";
const DEFAULT_APP_NAME = "HiveGrid";
const DEFAULT_NODE_ENV = "development";
const DEFAULT_LISTEN_PORT = 3001;
const DEFAULT_LAGO_TIMEOUT_MS = 10_000;
const DEFAULT_MOLLIE_TIMEOUT_MS = 10_000;
const MIN_PORT = 1;
const MAX_PORT = 65535;
@@ -72,9 +74,16 @@ export function loadApiConfig(env: EnvRecord = process.env, options: ApiConfigOp
mailjet: {
webhookSecret: present(env.MAILJET_WEBHOOK_SECRET),
},
stripe: {
secretKey: present(env.STRIPE_SK),
webhookSigningSecret: present(env.STRIPE_WEBHOOK_SIGNING_SECRET),
lago: {
apiUrl: present(env.LAGO_API_URL),
apiKey: present(env.LAGO_API_KEY),
webhookSecret: present(env.LAGO_WEBHOOK_SECRET),
timeoutMs: normalizePositiveInteger(env.LAGO_TIMEOUT_MS, DEFAULT_LAGO_TIMEOUT_MS),
},
mollie: {
apiKey: present(env.MOLLIE_API_KEY),
profileId: present(env.MOLLIE_PROFILE_ID),
timeoutMs: normalizePositiveInteger(env.MOLLIE_TIMEOUT_MS, DEFAULT_MOLLIE_TIMEOUT_MS),
},
storage: {
endpoint: present(env.STORAGE_ENDPOINT),
@@ -115,6 +124,15 @@ function parseBooleanFlag(value: string | undefined, defaultValue: boolean): boo
return defaultValue;
}
function normalizePositiveInteger(value: string | undefined, defaultValue: number): number {
const trimmed = present(value);
if (trimmed === undefined) {
return defaultValue;
}
const parsed = Number(trimmed);
return Number.isInteger(parsed) && parsed > 0 ? parsed : defaultValue;
}
function normalizeListenPort(apiPort: string | undefined, port: string | undefined): { port: number; diagnostic?: ApiConfigDiagnostic } {
const selected = present(apiPort) !== undefined ? { name: "API_PORT", value: apiPort } : { name: "PORT", value: port };
const trimmed = selected.value?.trim();
@@ -27,7 +27,7 @@ describe("env catalog", () => {
expect(getEnvVariableDefinition("REDIS_URL")).toMatchObject({
classification: "optional-provider",
targets: ["web", "api", "worker"],
targets: ["web", "api", "mcp", "worker"],
source: "code",
});
@@ -35,14 +35,14 @@ describe("env catalog", () => {
classification: "optional-provider",
targets: ["worker"],
source: "code",
defaultValue: "toolctrl.email",
defaultValue: "hivegrid.email",
});
expect(getEnvVariableDefinition("WORKFLOW_QUEUE_NAME")).toMatchObject({
classification: "optional-provider",
targets: ["worker"],
source: "code",
defaultValue: "toolctrl.workflows",
defaultValue: "hivegrid.workflows",
});
expect(getEnvVariableDefinition("WORKER_QUEUE_GROUP")?.description).toContain("plugin");
@@ -64,7 +64,7 @@ describe("env catalog", () => {
});
test("catalogs active operational runtime toggles", () => {
expect(getEnvVariableDefinition("TOOLCTRL_API_MAINTENANCE_MODE")).toMatchObject({
expect(getEnvVariableDefinition("HIVEGRID_API_MAINTENANCE_MODE")).toMatchObject({
classification: "production-only",
targets: ["api"],
source: "code",
@@ -102,8 +102,6 @@ describe("env catalog", () => {
}
for (const key of [
"STRIPE_SK",
"STRIPE_WEBHOOK_SIGNING_SECRET",
"PORTAL_SERVER_URL",
"PORTAL_SERVER_FLY_TOKEN",
"IMPORT_QUEUE_ENABLED",
@@ -114,7 +112,7 @@ describe("env catalog", () => {
});
test("targets provider keys consumed by web config to the web runtime", () => {
for (const key of ["STRIPE_WEBHOOK_SIGNING_SECRET", "MAILJET_API_KEY", "MAILJET_SECRET_KEY", "MAILJET_FROM_EMAIL", "MAILJET_FROM_NAME"]) {
for (const key of ["MAILJET_API_KEY", "MAILJET_SECRET_KEY", "MAILJET_FROM_EMAIL", "MAILJET_FROM_NAME"]) {
expect(getEnvVariableDefinition(key)?.targets, `${key} must include web because loadWebConfig consumes it`).toContain("web");
}
});
@@ -1,9 +1,10 @@
import type { EnvVariableDefinition, RuntimeTarget } from "./types.js";
const allTargets = ["shared", "web", "api", "worker"] as const satisfies readonly RuntimeTarget[];
const allTargets = ["shared", "web", "api", "mcp", "worker"] as const satisfies readonly RuntimeTarget[];
const webApiTargets = ["web", "api"] as const satisfies readonly RuntimeTarget[];
const apiWorkerTargets = ["api", "worker"] as const satisfies readonly RuntimeTarget[];
const webApiWorkerTargets = ["web", "api", "worker"] as const satisfies readonly RuntimeTarget[];
const webApiMcpWorkerTargets = ["web", "api", "mcp", "worker"] as const satisfies readonly RuntimeTarget[];
export const envVariableDefinitions = [
{
@@ -136,12 +137,81 @@ export const envVariableDefinitions = [
name: "API_KEY_LEGACY_PLAINTEXT_FALLBACK",
description: "Temporary cutover switch for legacy plaintext API-key lookup after hash metadata backfill.",
classification: "production-only",
targets: webApiTargets,
targets: ["web", "api", "mcp"],
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to true only for a bounded migration window while validating pre-backfill API keys.",
},
{
name: "API_KEY_HASH_SECRET",
description: "Optional HMAC secret used to hash legacy API keys during lookup and migration.",
classification: "production-only",
targets: ["web", "api", "mcp"],
kind: "secret",
source: "code-and-example",
notes: "When unset, legacy lookup falls back to the built-in v1 key namespace; set this during the API-key hash backfill and keep it stable afterward.",
},
{
name: "LAGO_API_URL",
description: "Base URL for the self-hosted Lago API used by HiveGrid billing sync.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "url",
source: "code-and-example",
notes: "Staging uses the Lago API service reachable from the deployment network or SSH tunnel. Do not include /api/v1; the Lago gateway appends it.",
},
{
name: "LAGO_API_KEY",
description: "Bearer token for the Lago API.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "LAGO_WEBHOOK_SECRET",
description: "Shared secret used to validate Lago webhook delivery once BILL-05 enables inbound sync.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "LAGO_TIMEOUT_MS",
description: "HTTP timeout for Lago API calls.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
defaultValue: "10000",
},
{
name: "MOLLIE_API_KEY",
description: "Mollie API key used for payment checkout and webhook verification.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
notes: "Use a Mollie testmode key in staging. Webhooks and admin manual sync are verified by refetching the payment through Mollie with this key.",
},
{
name: "MOLLIE_PROFILE_ID",
description: "Optional Mollie website profile id used when creating payments.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
},
{
name: "MOLLIE_TIMEOUT_MS",
description: "HTTP timeout for Mollie API calls.",
classification: "optional-provider",
targets: webApiWorkerTargets,
kind: "string",
source: "code-and-example",
defaultValue: "10000",
},
{
name: "NODE_ENV",
description: "Runtime mode supplied by Node, React Router or deployment platform.",
@@ -177,6 +247,75 @@ export const envVariableDefinitions = [
source: "runtime",
defaultValue: "3001",
},
{
name: "MCP_HOST",
description: "HTTP listen host for the standalone MCP runtime.",
classification: "production-only",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
defaultValue: "0.0.0.0",
},
{
name: "MCP_PORT",
description: "HTTP listen port for the standalone MCP runtime.",
classification: "production-only",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
defaultValue: "8080",
},
{
name: "MCP_ALLOWED_HOSTS",
description: "Comma-separated host allowlist for Streamable HTTP DNS rebinding protection.",
classification: "required-per-app",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "mcp.hivegrid.de,staging-mcp.hivegrid.de,localhost,127.0.0.1,::1",
},
{
name: "MCP_ALLOWED_ORIGINS",
description: "Comma-separated Origin allowlist for Streamable HTTP DNS rebinding protection.",
classification: "required-per-app",
targets: ["mcp"],
kind: "string",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "https://mcp.hivegrid.de,https://staging-mcp.hivegrid.de,http://localhost,http://127.0.0.1",
},
{
name: "MCP_RESOURCE_URL",
description: "Public OAuth protected-resource origin for the standalone MCP runtime.",
classification: "required-per-app",
targets: ["web", "mcp"],
kind: "url",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "https://mcp.hivegrid.de",
notes: "Use https://staging-mcp.hivegrid.de in staging. MCP is host-root only; do not append /mcp.",
},
{
name: "MCP_AUTHORIZATION_SERVER_URL",
description: "Public OAuth authorization-server origin for MCP client onboarding.",
classification: "required-per-app",
targets: ["web", "mcp"],
kind: "url",
source: "code-and-example",
requiredInProduction: true,
defaultValue: "https://app.hivegrid.de",
notes: "Use https://staging-app.hivegrid.de in staging.",
},
{
name: "MCP_OAUTH_TOKEN_HASH_SECRET",
description: "Optional HMAC secret for hash-only MCP OAuth authorization codes and bearer tokens.",
classification: "production-only",
targets: ["web", "mcp"],
kind: "secret",
source: "code-and-example",
notes: "When unset, MCP OAuth reuses API_KEY_HASH_SECRET so web and mcp can validate the same token hashes.",
},
{
name: "WEB_ORIGIN",
description: "Optional explicit web application origin allowed by API CORS and used as a worker workflow bridge fallback.",
@@ -251,7 +390,7 @@ export const envVariableDefinitions = [
name: "STORAGE_PROVIDER",
description: "Primary storage provider for runtime uploads.",
classification: "optional-provider",
targets: webApiWorkerTargets,
targets: webApiMcpWorkerTargets,
kind: "string",
source: "code-and-example",
notes: "Use s3 in production. Local is intended for explicit development or staging fallback only.",
@@ -344,32 +483,6 @@ export const envVariableDefinitions = [
kind: "url",
source: "code-and-example",
},
{
name: "STRIPE_SK",
description: "Stripe secret key for billing and portal integrations.",
classification: "optional-provider",
targets: webApiTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "STRIPE_WEBHOOK_SIGNING_SECRET",
description: "Stripe webhook signature secret.",
classification: "optional-provider",
targets: webApiTargets,
kind: "secret",
source: "code-and-example",
},
{
name: "STRIPE_ACCOUNT_COUNTRY",
description: "Expected Stripe account country for billing operations.",
classification: "production-only",
targets: webApiTargets,
kind: "string",
source: "example",
defaultValue: "US",
notes: "Set this to the country configured for the production Stripe account.",
},
{
name: "MAILJET_WEBHOOK_SECRET",
description: "Shared secret for Basic-Auth authentication of inbound Mailjet event webhook attempts.",
@@ -478,6 +591,79 @@ export const envVariableDefinitions = [
kind: "string",
source: "code-and-example",
},
{
name: "CAPTCHA_PROVIDER",
description: "Self-hosted captcha provider. Defaults to mcaptcha; set to cap to use Cap Standalone.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
defaultValue: "mcaptcha",
},
{
name: "CAP_INSTANCE_URL",
description: "Base URL of the self-hosted Cap Standalone instance (e.g. https://captcha.hivegrid.de).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET",
description: "Fallback Cap site secret for server-side siteverify when per-surface secrets are not set.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET_LOGIN",
description: "Cap site secret for the login surface.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET_FORMS",
description: "Cap site secret for public form submissions.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITE_SECRET_BOOKING",
description: "Cap site secret for public booking pages.",
classification: "optional-provider",
targets: ["web"],
kind: "secret",
source: "code-and-example",
},
{
name: "CAP_SITEKEY_LOGIN",
description: "Cap public sitekey for the login surface.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "CAP_SITEKEY_FORMS",
description: "Cap public sitekey for public form submissions.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "CAP_SITEKEY_BOOKING",
description: "Cap public sitekey for public booking pages.",
classification: "optional-provider",
targets: ["web"],
kind: "string",
source: "code-and-example",
},
{
name: "MCAPTCHA_INSTANCE_URL",
description: "Base URL of the self-hosted mCaptcha instance (e.g. https://captcha.tool-ctrl.de).",
@@ -642,7 +828,7 @@ export const envVariableDefinitions = [
targets: ["worker"],
kind: "string",
source: "code",
defaultValue: "toolctrl.email",
defaultValue: "hivegrid.email",
notes: "Leave unset unless the worker and enqueue side are intentionally deployed with a non-default queue name.",
},
{
@@ -652,7 +838,7 @@ export const envVariableDefinitions = [
targets: ["worker"],
kind: "string",
source: "code",
defaultValue: "toolctrl.workflows",
defaultValue: "hivegrid.workflows",
notes: "Leave unset unless the worker and enqueue side are intentionally deployed with a non-default queue name.",
},
{
@@ -741,7 +927,7 @@ export const envVariableDefinitions = [
kind: "string",
source: "code-and-example",
defaultValue: "false",
notes: "Set to exactly true only with IMPORT_QUEUE_ENABLED=true after the worker runtime can process toolctrl.imports/toolctrl.exports end to end.",
notes: "Set to exactly true only with IMPORT_QUEUE_ENABLED=true after the worker runtime can process hivegrid.imports/hivegrid.exports end to end.",
},
{
name: "OUTBOX_DISPATCHER_ENABLED",
@@ -845,12 +1031,12 @@ export const envVariableDefinitions = [
},
{
name: "REDIS_URL",
description: "Fallback Redis connection URL for queue-backed web/API enqueue and worker processing.",
description: "Fallback Redis connection URL for queue-backed web/API enqueue, MCP rate limits and worker processing.",
classification: "optional-provider",
targets: webApiWorkerTargets,
targets: webApiMcpWorkerTargets,
kind: "url",
source: "code",
notes: "Used only when BULLMQ_REDIS_URL is absent; supports deployment platforms that already provide REDIS_URL.",
notes: "Used when BULLMQ_REDIS_URL is absent for queue code and directly by shared-store runtimes such as MCP rate limiting.",
},
{
name: "CACHE_INVALIDATION_ENABLED",
@@ -907,7 +1093,7 @@ export const envVariableDefinitions = [
source: "code-and-example",
},
{
name: "TOOLCTRL_API_MAINTENANCE_MODE",
name: "HIVEGRID_API_MAINTENANCE_MODE",
description: "API maintenance-mode switch; set to 1 to return a maintenance response from non-health API routes.",
classification: "production-only",
targets: ["api"],
@@ -916,7 +1102,7 @@ export const envVariableDefinitions = [
defaultValue: "0",
},
{
name: "TOOLCTRL_API_MAINTENANCE_RETRY_AFTER_SECONDS",
name: "HIVEGRID_API_MAINTENANCE_RETRY_AFTER_SECONDS",
description: "Optional Retry-After value for API maintenance responses.",
classification: "production-only",
targets: ["api"],
@@ -1151,7 +1337,7 @@ export const envVariableDefinitions = [
},
{
name: "SENTRY_DSN_API",
description: "Optional Sentry DSN dedicated to the API process (boilerplate-api project).",
description: "Optional Sentry DSN dedicated to the API process (hivegrid-api project).",
classification: "optional-provider",
targets: ["api"],
kind: "secret",
@@ -1160,7 +1346,7 @@ export const envVariableDefinitions = [
},
{
name: "SENTRY_DSN_WORKER",
description: "Optional Sentry DSN dedicated to the BullMQ worker process (boilerplate-worker project).",
description: "Optional Sentry DSN dedicated to the BullMQ worker process (hivegrid-worker project).",
classification: "optional-provider",
targets: ["worker"],
kind: "secret",
@@ -1329,7 +1515,7 @@ export const envVariableDefinitions = [
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Defaults to boilerplate-web when omitted.",
notes: "Defaults to hivegrid-web when omitted.",
},
{
name: "SENTRY_DSN_WEB",
@@ -1360,7 +1546,7 @@ export const envVariableDefinitions = [
},
{
name: "SENTRY_PROJECT",
description: "Sentry project slug for the web app (default: boilerplate-web).",
description: "Sentry project slug for the web app (default: hivegrid-web).",
classification: "optional-provider",
targets: ["web"],
kind: "string",
@@ -1475,7 +1661,7 @@ export const envVariableDefinitions = [
targets: ["shared"],
kind: "url",
source: "code-and-example",
notes: "Consumed by @toolctrl/cli only.",
notes: "Consumed by @hivegrid/cli only.",
},
{
name: "BACKUP_S3_REGION",
@@ -1487,7 +1673,7 @@ export const envVariableDefinitions = [
},
{
name: "BACKUP_S3_BUCKET",
description: "Destination bucket for @toolctrl/cli backup archives.",
description: "Destination bucket for @hivegrid/cli backup archives.",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
@@ -1496,7 +1682,7 @@ export const envVariableDefinitions = [
},
{
name: "BACKUP_S3_ACCESS_KEY_ID",
description: "S3 access key id used by @toolctrl/cli (separate from the app STORAGE_* credentials).",
description: "S3 access key id used by @hivegrid/cli (separate from the app STORAGE_* credentials).",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
@@ -1504,7 +1690,7 @@ export const envVariableDefinitions = [
},
{
name: "BACKUP_S3_SECRET_ACCESS_KEY",
description: "S3 secret access key used by @toolctrl/cli.",
description: "S3 secret access key used by @hivegrid/cli.",
classification: "optional-provider",
targets: ["shared"],
kind: "secret",
@@ -1563,7 +1749,7 @@ export const envVariableDefinitions = [
},
{
name: "BACKUP_RETENTION_DAILY",
description: "Number of daily backups @toolctrl/cli backup:rotate keeps (default 7).",
description: "Number of daily backups @hivegrid/cli backup:rotate keeps (default 7).",
classification: "optional-provider",
targets: ["shared"],
kind: "string",
@@ -1637,7 +1823,7 @@ export const envVariableDefinitions = [
targets: webApiWorkerTargets,
kind: "secret",
source: "code-and-example",
notes: "Never expose to browsers. Scoped to the SaaS index prefix (e.g. boilerplate-*), minted from the master key per infra STANDARDS §4. Local docker-compose may use the documented dev key.",
notes: "Never expose to browsers. Scoped to the SaaS index prefix (e.g. hivegrid-*), minted from the master key per infra STANDARDS §4. Local docker-compose may use the documented dev key.",
},
{
name: "MEILI_ENV",
@@ -1972,13 +2158,13 @@ export const envVariableDefinitions = [
// ------------------------------------------------------------------
{
name: "AUTHENTIK_ISSUER_URL",
description: "OIDC issuer URL published by the Authentik `toolctrl-admin-panel` provider (Phase 09 #82).",
description: "OIDC issuer URL published by the Authentik `hivegrid-admin-panel` provider (Phase 09 #82).",
classification: "optional-provider",
targets: ["web"],
kind: "url",
source: "code-and-example",
notes:
"Typically https://auth.<base-domain>/application/o/toolctrl-admin-panel/. Must match the `iss` claim in Authentik ID-tokens; openid-client uses it for Issuer.discover().",
"Typically https://auth.<base-domain>/application/o/hivegrid-admin-panel/. Must match the `iss` claim in Authentik ID-tokens; openid-client uses it for Issuer.discover().",
},
{
name: "AUTHENTIK_ADMIN_CLIENT_ID",
@@ -1987,7 +2173,7 @@ export const envVariableDefinitions = [
targets: ["web"],
kind: "string",
source: "code-and-example",
notes: "Matches the blueprint client_id (defaults to `toolctrl-admin-panel`).",
notes: "Matches the blueprint client_id (defaults to `hivegrid-admin-panel`).",
},
{
name: "AUTHENTIK_ADMIN_CLIENT_SECRET",
@@ -2014,7 +2200,7 @@ export const envVariableDefinitions = [
targets: ["web"],
kind: "url",
source: "code-and-example",
notes: "Typically https://admin.<base-domain>/admin/login?logged_out=1 — must be allowlisted in Authentik's post_logout_redirect_uris.",
notes: "Typically https://admin.<base-domain>/login?logged_out=1 — must be allowlisted in Authentik's post_logout_redirect_uris.",
},
{
name: "ADMIN_FALLBACK_LOGIN_ENABLED",
@@ -2035,58 +2221,6 @@ export const envVariableDefinitions = [
source: "code-and-example",
notes: "Keep this short (1-2 bootstrap accounts max). Every fallback success/failure emits an admin.login.fallback.* audit event tagged severity=warn.",
},
{
name: "FCM_SERVICE_ACCOUNT_JSON",
description: "Firebase Cloud Messaging service-account credentials used by the worker push job to dispatch Android notifications (Phase 08 #65).",
classification: "optional-provider",
targets: ["worker"],
kind: "secret",
source: "code-and-example",
notes: "Accepted formats: raw JSON or base64-encoded JSON. Generated via Firebase console → Project settings → Service accounts. Never commit; grants full FCM send rights for the project.",
},
{
name: "APNS_KEY",
description: "Apple Push Notification Service signing key (PEM contents of the .p8 file). Used by the worker push job for iOS notifications (Phase 08 #65).",
classification: "optional-provider",
targets: ["worker"],
kind: "secret",
source: "code-and-example",
notes: "Standard PKCS#8 PEM block (full contents of the downloaded .p8). Rotate every 12 months — Apple does not auto-expire .p8 keys but rotation contains compromise blast-radius.",
},
{
name: "APNS_KEY_ID",
description: "10-character Apple key id displayed alongside the .p8 file in the Apple Developer console (Phase 08 #65).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
},
{
name: "APNS_TEAM_ID",
description: "10-character Apple Developer team id used as the APNs JWT issuer claim (Phase 08 #65).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
},
{
name: "APNS_BUNDLE_ID",
description: "iOS bundle id passed as the APNs topic. Defaults to de.toolctrl.app — override only when shipping a re-branded fork (Phase 08 #65).",
classification: "optional-provider",
targets: ["worker"],
kind: "string",
source: "code-and-example",
defaultValue: "de.toolctrl.app",
},
{
name: "MOBILE_LIVE_RELOAD_URL",
description: "Dev-only: when set, apps/mobile/capacitor.config.ts emits `server.url` so the native shell loads from this URL instead of the bundled webDir (Phase 08 #65).",
classification: "optional-provider",
targets: ["worker"],
kind: "url",
source: "code-and-example",
notes: "Leave empty in production builds. Typical dev value: `http://192.168.x.x:3000` (the host machine's LAN IP running `pnpm --filter @toolctrl/web dev`).",
},
] as const satisfies readonly EnvVariableDefinition[];
export type KnownEnvVariableName = (typeof envVariableDefinitions)[number]["name"];
@@ -4,23 +4,23 @@ import { describe, expect, test } from "vitest";
import { getEnvVariableDefinition, getRequiredEnvVariableNames, listEnvVariables, validateEnv } from "./index.js";
const representativeDefinitions = {
APP_NAME: { classification: "required-core", targets: ["shared", "web", "api", "worker"], source: "code-and-example" },
DATABASE_URL: { classification: "required-core", targets: ["shared", "web", "api", "worker"], source: "code-and-example" },
APP_NAME: { classification: "required-core", targets: ["shared", "web", "api", "mcp", "worker"], source: "code-and-example" },
DATABASE_URL: { classification: "required-core", targets: ["shared", "web", "api", "mcp", "worker"], source: "code-and-example" },
SESSION_SECRET: { classification: "required-core", targets: ["web", "api"], source: "code-and-example" },
API_ACCESS_TOKEN: { classification: "required-per-app", targets: ["web", "api"], source: "code-and-example" },
JWT_SECRET: { classification: "required-per-app", targets: ["web", "api"], source: "code-and-example" },
ANALYTICS_TOKEN: { classification: "required-per-app", targets: ["api"], source: "code" },
APP_REVISION: { classification: "production-only", targets: ["shared", "web", "api", "worker"], source: "runtime" },
APP_REVISION: { classification: "production-only", targets: ["shared", "web", "api", "mcp", "worker"], source: "runtime" },
WORKER_ENABLED: { classification: "optional-provider", targets: ["worker"], source: "code-and-example" },
EMAIL_QUEUE_NAME: { classification: "optional-provider", targets: ["worker"], source: "code" },
WORKFLOW_QUEUE_NAME: { classification: "optional-provider", targets: ["worker"], source: "code" },
BULLMQ_REDIS_URL: { classification: "optional-provider", targets: ["web", "api", "worker"], source: "code-and-example" },
REDIS_URL: { classification: "optional-provider", targets: ["web", "api", "worker"], source: "code" },
REDIS_URL: { classification: "optional-provider", targets: ["web", "api", "mcp", "worker"], source: "code" },
BROWSER_RUNTIME_URL: { classification: "optional-provider", targets: ["api", "worker"], source: "code-and-example" },
BROWSER_RUNTIME_API_KEY: { classification: "optional-provider", targets: ["api", "worker"], source: "code-and-example" },
BROWSER_SESSION_TIMEOUT_MS: { classification: "optional-provider", targets: ["api", "worker"], source: "code-and-example" },
TOOLCTRL_API_MAINTENANCE_MODE: { classification: "production-only", targets: ["api"], source: "code" },
TOOLCTRL_API_MAINTENANCE_RETRY_AFTER_SECONDS: { classification: "production-only", targets: ["api"], source: "code" },
HIVEGRID_API_MAINTENANCE_MODE: { classification: "production-only", targets: ["api"], source: "code" },
HIVEGRID_API_MAINTENANCE_RETRY_AFTER_SECONDS: { classification: "production-only", targets: ["api"], source: "code" },
WEB_BUILD_DIRECTORY: { classification: "production-only", targets: ["web"], source: "code" },
CRISP_CHAT_WEBSITE_ID: { classification: "optional-provider", targets: ["web"], source: "code-and-example" },
WEB_ORIGIN: { classification: "optional-provider", targets: ["api", "worker"], source: "code" },
@@ -137,7 +137,7 @@ describe("env access inventory contract", () => {
API_ACCESS_TOKEN: "api-token",
API_HOST: "api.example.com",
APP_BASE_DOMAIN: "example.com",
APP_NAME: "Boilerplate",
APP_NAME: "HiveGrid",
CRYPTO_SECRET: "crypto-secret",
DATABASE_URL: "postgresql://user:pass@localhost:5432/app",
JWT_SECRET: "jwt-secret",
@@ -186,7 +186,7 @@ describe("env access inventory contract", () => {
expect(inventoryDocument).toContain("`pnpm run verify:env-drift`");
expect(inventoryDocument).toContain("`scripts/check-env-drift.mjs`");
expect(inventoryDocument).toContain("`.env.test`");
for (const fixturePath of [".env.example", ".env.local.example", ".env.production.example", ".env.fly.example", ".env.test"]) {
for (const fixturePath of [".env.example", ".env.local.example", ".env.production.example", ".env.test"]) {
expect(inventoryDocument).toContain(`\`${fixturePath}\``);
}
expect(inventoryDocument).toContain("immediately after `pnpm run verify:ci-baseline` and before `pnpm typecheck`");
@@ -4,8 +4,8 @@ import { describe, expect, test } from "vitest";
import { envVariableDefinitions, getEnvVariableDefinition } from "./index.js";
import type { EnvVariableDefinition } from "./types.js";
const examplePaths = [".env.example", ".env.local.example", ".env.production.example", ".env.fly.example", ".env.test"] as const;
const safeEnvFixturePaths = [".env.example", ".env.local.example", ".env.production.example", ".env.fly.example", ".env.test"] as const;
const examplePaths = [".env.example", ".env.local.example", ".env.production.example", ".env.test"] as const;
const safeEnvFixturePaths = [".env.example", ".env.local.example", ".env.production.example", ".env.test"] as const;
const rootPath = (...segments: string[]) => resolve(process.cwd(), ...segments);
@@ -59,7 +59,7 @@ const exampleOnlyBaseline = new Set<string>([
const catalogedOrDynamicSiteKey = (key: string) =>
Boolean(getEnvVariableDefinition(key as EnvVariableDefinition["name"])) || key.startsWith("SITE_KEY_") || exampleOnlyBaseline.has(key);
const secretLikeKeyPattern = /(?:SECRET|TOKEN|KEY|PASSWORD|WEBHOOK_SIGNING_SECRET|ACCESS_TOKEN|JWT)/i;
const safePlaceholderValuePattern = /^(?:|test[-\w.:@/?=&]+|replace-with[-\w.]+|<[-\w]+>|\{[A-Z_]+\}|YOUR_[A-Z_]+|https:\/\/\.\.\.ngrok-free\.app|https:\/\/your-project\.supabase\.co|https:\/\/formspree\.io\/f\/example|G-XXXXXXXXXX|FlyV1 <portal-token>)$/;
const safePlaceholderValuePattern = /^(?:|test[-\w.:@/?=&]+|replace-with[-\w.]+|<[-\w]+>|\{[A-Z_]+\}|YOUR_[A-Z_]+|https:\/\/\.\.\.ngrok-free\.app|https:\/\/your-project\.supabase\.co|https:\/\/formspree\.io\/f\/example|G-XXXXXXXXXX)$/;
describe("env example drift contract", () => {
test.each(examplePaths)("catalogs every example key in %s", (path) => {
@@ -123,7 +123,6 @@ describe("env example drift contract", () => {
"MAILJET_API_KEY",
"MAILJET_SECRET_KEY",
"MAILJET_FROM_EMAIL",
"STRIPE_ACCOUNT_COUNTRY",
"WORKER_ENABLED",
"WORKER_QUEUE_GROUP",
"WORKER_CONCURRENCY_PLUGIN",
@@ -137,7 +136,8 @@ describe("env example drift contract", () => {
expect(contents).not.toContain("CRISP_CHAT_WEBSITE_ID");
});
test.each([".env.production.example", ".env.fly.example"] as const)("documents worker runtime keys in %s without required REDIS_URL", (path) => {
test("documents worker runtime keys in .env.production.example without required REDIS_URL", () => {
const path = ".env.production.example";
const contents = readProjectFile(path);
const keys = parseEnvExampleKeys(contents);
const requiredKeys = parseUncommentedEnvExampleKeys(contents);
@@ -148,11 +148,7 @@ describe("env example drift contract", () => {
])
);
expect(requiredKeys, `${path} must not make REDIS_URL an uncommented required key`).not.toContain("REDIS_URL");
if (path === ".env.fly.example") {
expect(requiredKeys, `${path} must not pin worker enablement in shared Fly secrets`).not.toContain("WORKER_ENABLED");
} else {
expect(keys).toContain("WORKER_ENABLED");
}
expect(keys).toContain("WORKER_ENABLED");
});
test("documents REDIS_URL as a fallback and keeps S05/S06 inventory owners visible", () => {
@@ -0,0 +1,148 @@
import { describe, expect, test } from "vitest";
import {
envVariableDefinitions,
getEnvVariableDefinition,
getRequiredEnvVariableNames,
groupEnvVariablesByClassification,
listEnvVariables,
validateEnv,
} from "./index.js";
const EnvClassifications = [
"required-core",
"required-per-app",
"optional-provider",
"local-development-only",
"production-only",
"deprecated-remove",
] as const;
describe("listEnvVariables", () => {
test("returns the full catalog when no filters are supplied", () => {
expect(listEnvVariables()).toHaveLength(envVariableDefinitions.length);
});
test("filters by classification", () => {
const requiredCore = listEnvVariables({ classification: "required-core" });
expect(requiredCore.length).toBeGreaterThan(0);
expect(requiredCore.every((definition) => definition.classification === "required-core")).toBe(true);
expect(requiredCore.map((definition) => definition.name)).toContain("APP_NAME");
});
test("filters by runtime target", () => {
const workerVars = listEnvVariables({ target: "worker" });
expect(workerVars.every((definition) => definition.targets.includes("worker"))).toBe(true);
expect(workerVars.map((definition) => definition.name)).toContain("WORKER_ENABLED");
// PORT is web-only, so it must be excluded from the worker view.
expect(workerVars.map((definition) => definition.name)).not.toContain("PORT");
});
test("combines classification and target filters", () => {
const result = listEnvVariables({ classification: "required-core", target: "api" });
expect(result.every((definition) => definition.classification === "required-core" && definition.targets.includes("api"))).toBe(true);
});
});
describe("getEnvVariableDefinition", () => {
test("resolves an exact catalog match", () => {
expect(getEnvVariableDefinition("APP_NAME")).toMatchObject({ name: "APP_NAME", classification: "required-core" });
});
test("resolves dynamic-prefix names to their wildcard definition", () => {
expect(getEnvVariableDefinition("SITE_KEY_ACME")).toMatchObject({ name: "SITE_KEY_*", dynamicPrefix: "SITE_KEY_" });
});
test("returns undefined for unknown names", () => {
expect(getEnvVariableDefinition("TOTALLY_UNKNOWN_VARIABLE")).toBeUndefined();
});
});
describe("groupEnvVariablesByClassification", () => {
test("buckets every definition exactly once under all known classifications", () => {
const groups = groupEnvVariablesByClassification();
expect(Object.keys(groups).sort()).toEqual([...EnvClassifications].sort());
const total = EnvClassifications.reduce((sum, classification) => sum + groups[classification].length, 0);
expect(total).toBe(envVariableDefinitions.length);
expect(groups["required-core"].map((definition) => definition.name)).toContain("APP_NAME");
expect(groups["optional-provider"].map((definition) => definition.name)).toContain("MAILJET_API_KEY");
});
});
describe("getRequiredEnvVariableNames", () => {
test("requires only secrets without dev defaults for web in development", () => {
expect(getRequiredEnvVariableNames()).toEqual(["API_ACCESS_TOKEN", "APP_NAME", "CRYPTO_SECRET", "DATABASE_URL", "JWT_SECRET", "SESSION_SECRET"]);
});
test("promotes default-bearing required vars to mandatory in production", () => {
const required = getRequiredEnvVariableNames({ nodeEnv: "production", target: "web" });
// APP_BASE_DOMAIN / WEB_APP_HOST carry dev defaults, so they are skipped in
// development but become hard requirements once NODE_ENV is production.
expect(required).toContain("APP_BASE_DOMAIN");
expect(required).toContain("WEB_APP_HOST");
expect(required).toContain("SESSION_SECRET");
});
test("pulls in optional providers only when explicitly requested", () => {
const baseline = getRequiredEnvVariableNames({ target: "web" });
const withProviders = getRequiredEnvVariableNames({ target: "web", includeOptionalProviders: true });
expect(baseline).not.toContain("MAILJET_API_KEY");
expect(withProviders).toContain("MAILJET_API_KEY");
});
test("merges caller-supplied extraRequired names and returns a sorted unique list", () => {
const required = getRequiredEnvVariableNames({ extraRequired: ["ZZZ_CUSTOM", "APP_NAME"] });
expect(required).toContain("ZZZ_CUSTOM");
// APP_NAME is already required and must not be duplicated.
expect(required.filter((name) => name === "APP_NAME")).toHaveLength(1);
expect([...required]).toEqual([...required].sort());
});
});
describe("validateEnv", () => {
const WEB_DEV_REQUIRED = {
APP_NAME: "HiveGrid",
DATABASE_URL: "postgresql://user:pass@localhost:5432/app",
SESSION_SECRET: "session-secret-value",
CRYPTO_SECRET: "crypto-secret-value",
API_ACCESS_TOKEN: "api-access-token-value",
JWT_SECRET: "jwt-secret-value",
};
test("reports each missing required variable with its catalog classification", () => {
const result = validateEnv({});
expect(result.ok).toBe(false);
expect(result.missing).toContainEqual({
name: "SESSION_SECRET",
classification: "required-core",
message: "SESSION_SECRET is required.",
});
});
test("includes the target in the message when a target is provided", () => {
const result = validateEnv({}, { target: "web" });
expect(result.missing).toContainEqual(expect.objectContaining({ name: "SESSION_SECRET", message: "SESSION_SECRET is required for web." }));
});
test("passes once every required variable is present", () => {
const result = validateEnv(WEB_DEV_REQUIRED);
expect(result).toEqual({ ok: true, missing: [] });
});
test("never surfaces wildcard dynamic names as missing entries", () => {
const result = validateEnv({}, { target: "api", includeOptionalProviders: true });
expect(result.missing.some((issue) => issue.name.includes("*"))).toBe(false);
});
});
@@ -20,8 +20,10 @@ export type {
ApiConfigDiagnostic,
ApiConfigDiagnosticCode,
ApiConfigErrorDetails,
ApiConfigLago,
ApiConfigListen,
ApiConfigMailjet,
ApiConfigMollie,
ApiConfigOptions,
ApiConfigOrigins,
ApiConfigResult,
@@ -0,0 +1,39 @@
import { describe, expect, test } from "vitest";
import { resolvePluginLifecycleRuntimeEnv } from "./index.js";
describe("resolvePluginLifecycleRuntimeEnv", () => {
test("defaults to development with capability consent required when env is empty", () => {
expect(resolvePluginLifecycleRuntimeEnv()).toEqual({
nodeEnv: "development",
requireCapabilityConsent: true,
});
});
test("passes NODE_ENV through without altering consent default", () => {
expect(resolvePluginLifecycleRuntimeEnv({ NODE_ENV: "production" })).toEqual({
nodeEnv: "production",
requireCapabilityConsent: true,
});
});
test("only the literal string 'false' opts out of capability consent (fail-closed)", () => {
expect(resolvePluginLifecycleRuntimeEnv({ PLUGIN_REQUIRE_CAPABILITY_CONSENT: "false" }).requireCapabilityConsent).toBe(false);
// Any non-"false" value keeps consent enabled — the gate fails closed.
for (const value of ["true", "1", "0", "no", "off", "FALSE", " false ", ""]) {
expect(resolvePluginLifecycleRuntimeEnv({ PLUGIN_REQUIRE_CAPABILITY_CONSENT: value }).requireCapabilityConsent).toBe(true);
}
});
test("resolves both fields together for a fully configured env", () => {
expect(
resolvePluginLifecycleRuntimeEnv({
NODE_ENV: "test",
PLUGIN_REQUIRE_CAPABILITY_CONSENT: "false",
})
).toEqual({
nodeEnv: "test",
requireCapabilityConsent: false,
});
});
});
@@ -0,0 +1,40 @@
import { describe, expect, test } from "vitest";
import { getDomainRoutingConfig, hostMatches } from "./routing.js";
describe("getDomainRoutingConfig non-local subdomain derivation", () => {
test("preserves an explicit port when deriving canonical subdomains", () => {
expect(getDomainRoutingConfig({ APP_BASE_DOMAIN: "example.com:8443" })).toMatchObject({
appBaseDomain: "example.com:8443",
webAppHost: "app.example.com:8443",
adminAppHost: "admin.example.com:8443",
apiHost: "api.example.com:8443",
protocol: "https",
});
});
});
describe("hostMatches edge cases", () => {
test("returns false when either host normalizes to nothing", () => {
expect(hostMatches(undefined, "app.example.com")).toBe(false);
expect(hostMatches("app.example.com", " ")).toBe(false);
expect(hostMatches(undefined, undefined)).toBe(false);
});
test("treats local hosts as matching when only one carries a dev port", () => {
expect(hostMatches("app.localhost:3000", "app.localhost")).toBe(true);
expect(hostMatches("app.localhost", "app.localhost:3000")).toBe(true);
});
test("rejects two local hosts that both pin different dev ports", () => {
expect(hostMatches("app.localhost:3000", "app.localhost:4000")).toBe(false);
});
test("rejects local hosts with different hostnames even without ports", () => {
expect(hostMatches("app.localhost", "api.localhost")).toBe(false);
});
test("rejects non-equal hosts that are not both local", () => {
expect(hostMatches("app.example.com", "app.example.org")).toBe(false);
expect(hostMatches("app.localhost:3000", "app.example.com:3000")).toBe(false);
});
});
@@ -0,0 +1,30 @@
import { describe, expect, test } from "vitest";
import { validateBooleanFlag, validateOptionalSecretUrl } from "./secret-validator.js";
describe("validateOptionalSecretUrl protocol normalization", () => {
test("accepts allowed protocols supplied with a trailing colon", () => {
const result = validateOptionalSecretUrl("BULLMQ_REDIS_URL", "redis://redis.internal:6379/0", { allowedProtocols: ["redis:", "rediss:"] });
expect(result).toMatchObject({ ok: true, configured: true, value: "redis://redis.internal:6379/0" });
});
test("normalizes colon-less and colon-suffixed protocols to the same allowlist", () => {
const withColon = validateOptionalSecretUrl("BULLMQ_REDIS_URL", "http://example.test/x", { allowedProtocols: ["https:"] });
expect(withColon).toMatchObject({ ok: false, diagnostics: [expect.objectContaining({ code: "invalid-url-protocol" })] });
});
});
describe("validateBooleanFlag accepted aliases", () => {
test("maps every truthy alias to true", () => {
for (const value of ["true", "1", "yes", "on", "TRUE", " On "]) {
expect(validateBooleanFlag("WORKER_ENABLED", value)).toMatchObject({ ok: true, configured: true, value: true });
}
});
test("maps every falsy alias to false", () => {
for (const value of ["false", "0", "no", "off", "FALSE", " Off "]) {
expect(validateBooleanFlag("WORKER_ENABLED", value)).toMatchObject({ ok: true, configured: true, value: false });
}
});
});
@@ -0,0 +1,23 @@
import { describe, expect, test } from "vitest";
import { resolveSessionCookiePolicy } from "./session-cookie.js";
describe("session cookie domain resolution for bracketed IPv6 hosts", () => {
test("keeps loopback IPv6 cookies domainless", () => {
const policy = resolveSessionCookiePolicy({
nodeEnv: "development",
routing: { appBaseDomain: "[::1]:3000", protocol: "http" },
});
expect(policy).not.toHaveProperty("domain");
expect(policy).toMatchObject({ sameSite: "lax", secure: false, httpOnly: true, path: "/" });
});
test("derives the bracket-stripped hostname for routable IPv6 base domains", () => {
const policy = resolveSessionCookiePolicy({
nodeEnv: "production",
routing: { appBaseDomain: "[2001:db8::1]:8443", protocol: "https" },
});
expect(policy).toMatchObject({ domain: "2001:db8::1", secure: true });
});
});
@@ -80,7 +80,7 @@ describe("session cookie policy", () => {
});
expect(policy).toEqual({
name: "RJ_api_session",
name: "hivegrid_api_session",
maxAge: 900,
domain: "example.com",
sameSite: "lax",
@@ -88,7 +88,7 @@ describe("session cookie policy", () => {
httpOnly: true,
path: "/",
});
expect(policy.name).not.toBe("RJ_session");
expect(policy.name).not.toBe("hivegrid_session");
expect(JSON.stringify(policy)).not.toContain("secret");
});
@@ -102,7 +102,7 @@ describe("session cookie policy", () => {
});
expect(policy).toEqual({
name: "RJ_api_session",
name: "hivegrid_api_session",
sameSite: "lax",
secure: false,
httpOnly: true,
@@ -21,7 +21,7 @@ export type ResolveSessionCookiePolicyOptions = {
export type ResolveApiSessionCookiePolicyOptions = Omit<ResolveSessionCookiePolicyOptions, "name">;
const API_SESSION_COOKIE_NAME = "RJ_api_session";
const API_SESSION_COOKIE_NAME = "hivegrid_api_session";
export function resolveSessionCookiePolicy({ nodeEnv, routing, name, maxAge }: ResolveSessionCookiePolicyOptions): SessionCookiePolicy {
return {
@@ -1,4 +1,4 @@
export type RuntimeTarget = "shared" | "web" | "api" | "worker";
export type RuntimeTarget = "shared" | "web" | "api" | "mcp" | "worker";
export type EnvClassification = "required-core" | "required-per-app" | "optional-provider" | "local-development-only" | "production-only" | "deprecated-remove";
@@ -88,14 +88,11 @@ export type WebConfig = {
listen: WebConfigListen;
routing: WebConfigRouting;
webhooksUrl?: string;
stripe: {
secretKey?: string;
webhookSigningSecret?: string;
};
crisp: {
chatWebsiteId?: string;
};
captcha: {
provider: "mcaptcha" | "cap";
instanceUrl?: string;
loginSiteKey?: string;
};
@@ -124,6 +121,8 @@ export type WebConfig = {
url?: string;
flyToken?: string;
};
lago: ApiConfigLago;
mollie: ApiConfigMollie;
magicLink: {
enabled: boolean;
tokenTtlMinutes?: number;
@@ -196,9 +195,17 @@ export type ApiConfigMailjet = {
webhookSecret?: string;
};
export type ApiConfigStripe = {
secretKey?: string;
webhookSigningSecret?: string;
export type ApiConfigLago = {
apiUrl?: string;
apiKey?: string;
webhookSecret?: string;
timeoutMs: number;
};
export type ApiConfigMollie = {
apiKey?: string;
profileId?: string;
timeoutMs: number;
};
export type ApiConfig = {
@@ -212,7 +219,8 @@ export type ApiConfig = {
jwtSecret?: string;
analytics: ApiConfigAnalytics;
mailjet: ApiConfigMailjet;
stripe: ApiConfigStripe;
lago: ApiConfigLago;
mollie: ApiConfigMollie;
storage: ApiConfigStorage;
apiKeys: ApiConfigApiKeys;
};
@@ -0,0 +1,14 @@
import { describe, expect, test } from "vitest";
import { loadWebConfig } from "./web.js";
describe("loadWebConfig magic-link explicit-disable handling", () => {
test("treats falsy boolean aliases as a clean disable without a diagnostic", () => {
for (const value of ["false", "0", "no", "off"]) {
const result = loadWebConfig({ AUTH_MAGIC_LINK_ENABLED: value, AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "15" });
expect(result.config.magicLink).toEqual({ enabled: false, tokenTtlMinutes: undefined });
// An explicit disable must not raise the invalid-boolean diagnostic.
expect(result.diagnostics.some((diagnostic) => diagnostic.name === "AUTH_MAGIC_LINK_ENABLED")).toBe(false);
}
});
});
@@ -12,6 +12,8 @@ const REQUIRED_PRODUCTION_ENV = {
CRYPTO_SECRET: "crypto-secret-value-prod-0123456789",
API_ACCESS_TOKEN: "api-access-token-value-prod-0123456789",
JWT_SECRET: "jwt-secret-value-prod-0123456789abcd",
MCP_RESOURCE_URL: "https://mcp.example.com",
MCP_AUTHORIZATION_SERVER_URL: "https://app.example.com",
};
describe("loadRequiredWebConfig", () => {
@@ -139,7 +141,7 @@ describe("loadWebConfig", () => {
expect(result.ok).toBe(false);
expect(result.config).toMatchObject({
appName: "ToolController",
appName: "HiveGrid",
nodeEnv: "development",
listen: {
host: "0.0.0.0",
@@ -162,8 +164,6 @@ describe("loadWebConfig", () => {
HOST: "127.0.0.1",
PORT: "8080",
WEBHOOKS_URL: "https://hooks.example.com",
STRIPE_SK: "stripe-secret-value",
STRIPE_WEBHOOK_SIGNING_SECRET: "stripe-webhook-secret-value",
CRISP_CHAT_WEBSITE_ID: "crisp-id",
MCAPTCHA_INSTANCE_URL: "https://captcha.example.test",
MCAPTCHA_SITEKEY_LOGIN: "login-key",
@@ -177,6 +177,10 @@ describe("loadWebConfig", () => {
IPAPIIS_API_KEY: "ipapiis-api-key",
PORTAL_SERVER_URL: "https://portals.example.com",
PORTAL_SERVER_FLY_TOKEN: "portal-fly-token-value",
LAGO_API_URL: "https://lago.example.test",
LAGO_API_KEY: "lago-secret-value",
LAGO_WEBHOOK_SECRET: "lago-webhook-secret-value",
LAGO_TIMEOUT_MS: "5000",
AUTH_MAGIC_LINK_ENABLED: "true",
AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "15",
STORAGE_PROVIDER: "s3",
@@ -189,7 +193,7 @@ describe("loadWebConfig", () => {
STORAGE_SESSION_TOKEN: "storage-session-token",
STORAGE_PUBLIC_BASE_URL: "https://cdn.example.com",
STORAGE_FORCE_PATH_STYLE: "true",
STORAGE_LOCAL_ROOT: "/tmp/toolctrl-storage",
STORAGE_LOCAL_ROOT: "/tmp/hivegrid-storage",
STORAGE_LOCAL_PUBLIC_BASE_URL: "http://localhost:3000/storage",
DEMO_USER: "demo@example.com:password",
});
@@ -212,14 +216,11 @@ describe("loadWebConfig", () => {
protocol: "https",
},
webhooksUrl: "https://hooks.example.com",
stripe: {
secretKey: "stripe-secret-value",
webhookSigningSecret: "stripe-webhook-secret-value",
},
crisp: {
chatWebsiteId: "crisp-id",
},
captcha: {
provider: "mcaptcha",
instanceUrl: "https://captcha.example.test",
loginSiteKey: "login-key",
},
@@ -243,6 +244,12 @@ describe("loadWebConfig", () => {
url: "https://portals.example.com",
flyToken: "portal-fly-token-value",
},
lago: {
apiUrl: "https://lago.example.test",
apiKey: "lago-secret-value",
webhookSecret: "lago-webhook-secret-value",
timeoutMs: 5000,
},
magicLink: {
enabled: true,
tokenTtlMinutes: 15,
@@ -258,7 +265,7 @@ describe("loadWebConfig", () => {
sessionToken: "storage-session-token",
publicBaseUrl: "https://cdn.example.com",
forcePathStyle: "true",
localRoot: "/tmp/toolctrl-storage",
localRoot: "/tmp/hivegrid-storage",
localPublicBaseUrl: "http://localhost:3000/storage",
},
cryptoSecret: "crypto-secret-value-prod-0123456789",
@@ -268,6 +275,22 @@ describe("loadWebConfig", () => {
});
});
test("normalizes Cap captcha provider values", () => {
const result = loadWebConfig({
...REQUIRED_PRODUCTION_ENV,
NODE_ENV: "production",
CAPTCHA_PROVIDER: "cap",
CAP_INSTANCE_URL: "https://captcha.hivegrid.de",
CAP_SITEKEY_LOGIN: "cap-login-key",
});
expect(result.config.captcha).toEqual({
provider: "cap",
instanceUrl: "https://captcha.hivegrid.de",
loginSiteKey: "cap-login-key",
});
});
test("exposes demo login hints only for development config", () => {
expect(loadWebConfig({ NODE_ENV: "development", DEMO_USER: "demo@example.com:password" }).config.demoUser).toBe("demo@example.com:password");
@@ -340,10 +363,10 @@ describe("loadWebConfig", () => {
});
test("falls back for invalid PORT and keeps supplied secret values out of diagnostics", () => {
const secretValues = ["session-secret-value", "stripe-secret-value", "crypto-secret-value", "api-token-value", "jwt-secret-value"];
const secretValues = ["session-secret-value", "billing-secret-value", "crypto-secret-value", "api-token-value", "jwt-secret-value"];
const result = loadWebConfig({
SESSION_SECRET: secretValues[0],
STRIPE_SK: secretValues[1],
MOLLIE_API_KEY: secretValues[1],
CRYPTO_SECRET: secretValues[2],
API_ACCESS_TOKEN: secretValues[3],
JWT_SECRET: secretValues[4],
@@ -387,4 +410,18 @@ describe("loadWebConfig", () => {
fallbackProvider: "s3",
});
});
test("loads Mollie config for server-side admin billing sync", () => {
const result = loadWebConfig({
MOLLIE_API_KEY: " mollie-secret-value ",
MOLLIE_PROFILE_ID: " mollie-profile-value ",
MOLLIE_TIMEOUT_MS: "invalid",
});
expect(result.config.mollie).toEqual({
apiKey: "mollie-secret-value",
profileId: "mollie-profile-value",
timeoutMs: 10_000,
});
});
});
@@ -2,10 +2,12 @@ import { getEnvVariableDefinition, validateEnv } from "./index.js";
import { getDomainRoutingConfig } from "./routing.js";
import type { EnvRecord, RequiredWebConfigOptions, WebConfig, WebConfigDiagnostic, WebConfigErrorDetails, WebConfigOptions, WebConfigResult } from "./types.js";
const DEFAULT_APP_NAME = "ToolController";
const DEFAULT_APP_NAME = "HiveGrid";
const DEFAULT_NODE_ENV = "development";
const DEFAULT_LISTEN_HOST = "0.0.0.0";
const DEFAULT_LISTEN_PORT = 3000;
const DEFAULT_LAGO_TIMEOUT_MS = 10_000;
const DEFAULT_MOLLIE_TIMEOUT_MS = 10_000;
const MIN_PORT = 1;
const MAX_PORT = 65535;
const MIN_MAGIC_LINK_TOKEN_TTL_MINUTES = 1;
@@ -69,16 +71,13 @@ export function loadWebConfig(env: EnvRecord = process.env, options: WebConfigOp
},
routing,
webhooksUrl: present(env.WEBHOOKS_URL),
stripe: {
secretKey: present(env.STRIPE_SK),
webhookSigningSecret: present(env.STRIPE_WEBHOOK_SIGNING_SECRET),
},
crisp: {
chatWebsiteId: present(env.CRISP_CHAT_WEBSITE_ID),
},
captcha: {
instanceUrl: present(env.MCAPTCHA_INSTANCE_URL),
loginSiteKey: present(env.MCAPTCHA_SITEKEY_LOGIN),
provider: present(env.CAPTCHA_PROVIDER)?.toLowerCase() === "cap" ? "cap" : "mcaptcha",
instanceUrl: present(env.CAPTCHA_PROVIDER)?.toLowerCase() === "cap" ? present(env.CAP_INSTANCE_URL) : present(env.MCAPTCHA_INSTANCE_URL),
loginSiteKey: present(env.CAPTCHA_PROVIDER)?.toLowerCase() === "cap" ? present(env.CAP_SITEKEY_LOGIN) : present(env.MCAPTCHA_SITEKEY_LOGIN),
},
analytics: {
// EU-Sterilisation (R-P1a): Google-Analytics-Einbindung entfernt; nur First-Party-Analytics-Token bleibt.
@@ -105,6 +104,17 @@ export function loadWebConfig(env: EnvRecord = process.env, options: WebConfigOp
url: present(env.PORTAL_SERVER_URL),
flyToken: present(env.PORTAL_SERVER_FLY_TOKEN),
},
lago: {
apiUrl: present(env.LAGO_API_URL),
apiKey: present(env.LAGO_API_KEY),
webhookSecret: present(env.LAGO_WEBHOOK_SECRET),
timeoutMs: normalizePositiveInteger(env.LAGO_TIMEOUT_MS, DEFAULT_LAGO_TIMEOUT_MS),
},
mollie: {
apiKey: present(env.MOLLIE_API_KEY),
profileId: present(env.MOLLIE_PROFILE_ID),
timeoutMs: normalizePositiveInteger(env.MOLLIE_TIMEOUT_MS, DEFAULT_MOLLIE_TIMEOUT_MS),
},
magicLink: magicLinkResult.config,
storage: {
provider: normalizeStorageProvider(env.STORAGE_PROVIDER),
@@ -153,6 +163,15 @@ function normalizeStorageFallbackProvider(value: string | undefined): "s3" | "lo
return undefined;
}
function normalizePositiveInteger(value: string | undefined, defaultValue: number): number {
const trimmed = present(value);
if (trimmed === undefined) {
return defaultValue;
}
const parsed = Number(trimmed);
return Number.isInteger(parsed) && parsed > 0 ? parsed : defaultValue;
}
function normalizeListenPort(value: string | undefined): { port: number; diagnostic?: WebConfigDiagnostic } {
const trimmed = value?.trim();
if (!trimmed) {
@@ -0,0 +1,80 @@
import { describe, expect, test } from "vitest";
import { loadWorkerConfig } from "./worker.js";
const DATABASE_URL = "postgresql://user:db-secret@localhost:5432/app";
const REDIS_URL = "redis://localhost:6379/0";
describe("loadWorkerConfig browser session timeout overflow", () => {
test("rejects an all-digit timeout that exceeds the safe-integer range", () => {
const overflowing = `${Number.MAX_SAFE_INTEGER}0`;
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: REDIS_URL,
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
BROWSER_SESSION_TIMEOUT_MS: overflowing,
});
expect(result.ok).toBe(false);
expect(result.config.browserRuntime.sessionTimeoutMs).toBeUndefined();
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-timeout",
name: "BROWSER_SESSION_TIMEOUT_MS",
message: "BROWSER_SESSION_TIMEOUT_MS must be a positive integer in milliseconds.",
})
);
});
});
describe("loadWorkerConfig invalid WORKER_ENABLED flag", () => {
test("fails closed to a disabled worker and reports the invalid flag", () => {
const result = loadWorkerConfig({ WORKER_ENABLED: "maybe" });
expect(result.ok).toBe(false);
expect(result.config.enabled).toBe(false);
expect(result.diagnostics).toContainEqual(expect.objectContaining({ name: "WORKER_ENABLED", code: "invalid-boolean" }));
});
});
describe("loadWorkerConfig redis URL without a database index", () => {
test("accepts a valid redis URL that omits the path/db segment", () => {
const result = loadWorkerConfig({
WORKER_ENABLED: "true",
BULLMQ_REDIS_URL: "redis://localhost:6379",
DATABASE_URL,
WORKER_QUEUE_GROUP: "general",
});
expect(result.ok).toBe(true);
expect(result.config.redis).toMatchObject({ configured: true, parseStatus: "valid" });
expect(result.config.redis.database).toBeUndefined();
});
});
describe("loadWorkerConfig partial Mailjet requiring the api key", () => {
test("flags MAILJET_API_KEY as missing when only the secret key is set", () => {
const result = loadWorkerConfig({ MAILJET_SECRET_KEY: "mailer-secret-key" });
expect(result.ok).toBe(false);
expect(result.config.mailjet).toMatchObject({ configured: false, secretKey: "mailer-secret-key" });
expect(result.diagnostics).toContainEqual(
expect.objectContaining({ code: "missing-required", name: "MAILJET_API_KEY", message: "MAILJET_API_KEY is required." })
);
expect(JSON.stringify(result.diagnostics)).not.toContain("mailer-secret-key");
});
});
describe("loadWorkerConfig production core-env requirements", () => {
test("surfaces default-bearing required core vars as missing in production", () => {
const result = loadWorkerConfig({}, { nodeEnv: "production" });
expect(result.ok).toBe(false);
// APP_NAME and DATABASE_URL are intentionally filtered by the worker loader,
// but APP_BASE_DOMAIN (a required-core var with a dev default) must surface in production.
expect(result.diagnostics).toContainEqual(
expect.objectContaining({ code: "missing-required", name: "APP_BASE_DOMAIN" })
);
expect(result.diagnostics.some((diagnostic) => diagnostic.name === "APP_NAME")).toBe(false);
});
});
@@ -9,7 +9,7 @@ describe("loadRequiredWorkerConfig", () => {
const config = loadRequiredWorkerConfig({});
expect(config).toMatchObject({
appName: "ToolController",
appName: "HiveGrid",
nodeEnv: "development",
enabled: false,
redis: {
@@ -115,7 +115,7 @@ describe("loadWorkerConfig", () => {
expect(result.ok).toBe(true);
expect(result.config).toMatchObject({
appName: "ToolController",
appName: "HiveGrid",
nodeEnv: "development",
enabled: false,
concurrency: 1,
@@ -12,7 +12,7 @@ import type {
WorkerConfigResult,
} from "./types.js";
const DEFAULT_APP_NAME = "ToolController";
const DEFAULT_APP_NAME = "HiveGrid";
const DEFAULT_NODE_ENV = "development";
const DEFAULT_QUEUE_NAMES = {
email: "email",