Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,390 @@
import { describe, expect, test } from "vitest";
import { getEnvVariableDefinition, loadRequiredWebConfig, loadWebConfig, WebConfigError } from "./index.js";
const REQUIRED_PRODUCTION_ENV = {
APP_NAME: "Production App",
DATABASE_URL: "postgres://example.invalid/app",
APP_BASE_DOMAIN: "example.com",
WEB_APP_HOST: "app.example.com",
ADMIN_APP_HOST: "admin.example.com",
API_HOST: "api.example.com",
SESSION_SECRET: "session-secret-value-prod-0123456789",
CRYPTO_SECRET: "crypto-secret-value-prod-0123456789",
API_ACCESS_TOKEN: "api-access-token-value-prod-0123456789",
JWT_SECRET: "jwt-secret-value-prod-0123456789abcd",
};
describe("loadRequiredWebConfig", () => {
test("returns production config when required values are valid", () => {
const config = loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
PORT: "8080",
},
{ nodeEnv: "production" }
);
expect(config).toMatchObject({
appName: "Production App",
nodeEnv: "production",
sessionSecret: "session-secret-value-prod-0123456789",
listen: {
port: 8080,
},
routing: {
appBaseDomain: "example.com",
protocol: "https",
},
});
});
test("throws redacted WebConfigError for missing production SESSION_SECRET", () => {
const secretValues = ["crypto-secret-value", "api-access-token-value", "jwt-secret-value"];
expect(() =>
loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
SESSION_SECRET: undefined,
},
{ nodeEnv: "production" }
)
).toThrow(WebConfigError);
try {
loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
SESSION_SECRET: undefined,
},
{ nodeEnv: "production" }
);
} catch (error) {
expect(error).toBeInstanceOf(WebConfigError);
const webConfigError = error as WebConfigError;
expect(webConfigError.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "SESSION_SECRET",
})
);
const errorText = JSON.stringify({ message: webConfigError.message, details: webConfigError.details });
for (const secretValue of secretValues) {
expect(errorText).not.toContain(secretValue);
}
}
});
test("throws redacted WebConfigError for invalid PORT", () => {
const secretValues = ["session-secret-value", "crypto-secret-value", "api-access-token-value", "jwt-secret-value"];
try {
loadRequiredWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
PORT: "secret-like-invalid-port-value",
},
{ nodeEnv: "production" }
);
} catch (error) {
expect(error).toBeInstanceOf(WebConfigError);
const webConfigError = error as WebConfigError;
expect(webConfigError.diagnostics).toEqual([
expect.objectContaining({
code: "invalid-port",
name: "PORT",
}),
]);
const errorText = JSON.stringify({ message: webConfigError.message, details: webConfigError.details });
expect(errorText).not.toContain("secret-like-invalid-port-value");
for (const secretValue of secretValues) {
expect(errorText).not.toContain(secretValue);
}
}
});
test("preserves default development behavior by throwing diagnostics instead of silently succeeding", () => {
expect(() => loadRequiredWebConfig({})).toThrow(WebConfigError);
});
});
describe("secret strength (production)", () => {
test("rejects a present-but-too-short SESSION_SECRET in production", () => {
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, SESSION_SECRET: "too-short" }, { nodeEnv: "production" });
expect(result.ok).toBe(false);
expect(result.diagnostics).toContainEqual(expect.objectContaining({ code: "weak-secret", name: "SESSION_SECRET" }));
});
test("rejects reusing one value for SESSION_SECRET and CRYPTO_SECRET in production", () => {
const shared = "shared-secret-value-prod-0123456789";
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, SESSION_SECRET: shared, CRYPTO_SECRET: shared }, { nodeEnv: "production" });
expect(result.ok).toBe(false);
expect(result.diagnostics).toContainEqual(expect.objectContaining({ code: "weak-secret", name: "CRYPTO_SECRET" }));
});
test("does not leak the weak secret value in diagnostics", () => {
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, JWT_SECRET: "short-jwt-secret" }, { nodeEnv: "production" });
expect(JSON.stringify(result.diagnostics)).not.toContain("short-jwt-secret");
});
test("does not enforce secret length outside production (placeholders allowed)", () => {
const result = loadWebConfig({ ...REQUIRED_PRODUCTION_ENV, NODE_ENV: "test", SESSION_SECRET: "short" }, { nodeEnv: "test" });
expect(result.diagnostics).not.toContainEqual(expect.objectContaining({ code: "weak-secret" }));
});
});
describe("loadWebConfig", () => {
test("returns local defaults and domain routing defaults", () => {
const result = loadWebConfig({});
expect(result.ok).toBe(false);
expect(result.config).toMatchObject({
appName: "ToolController",
nodeEnv: "development",
listen: {
host: "0.0.0.0",
port: 3000,
},
routing: {
appBaseDomain: "localhost",
webAppHost: "app.localhost",
adminAppHost: "admin.localhost",
apiHost: "api.localhost",
protocol: "http",
},
});
});
test("normalizes explicit listen and server-side provider values", () => {
const result = loadWebConfig({
...REQUIRED_PRODUCTION_ENV,
NODE_ENV: "production",
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",
ANALYTICS_TOKEN: "analytics-token-value",
NOTIFICATIONS_NOVU_API_KEY: "novu-secret-value",
MAILJET_API_KEY: "mailjet-public-value",
MAILJET_SECRET_KEY: "mailjet-secret-value",
MAILJET_FROM_EMAIL: "sender@example.com",
MAILJET_FROM_NAME: "Example Support",
IPSTACK_API_KEY: "ipstack-api-key",
IPAPIIS_API_KEY: "ipapiis-api-key",
PORTAL_SERVER_URL: "https://portals.example.com",
PORTAL_SERVER_FLY_TOKEN: "portal-fly-token-value",
AUTH_MAGIC_LINK_ENABLED: "true",
AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "15",
STORAGE_PROVIDER: "s3",
STORAGE_FALLBACK_PROVIDER: "local",
STORAGE_ENDPOINT: "https://storage.example.com",
STORAGE_REGION: "eu-central-1",
STORAGE_BUCKET: "uploads",
STORAGE_ACCESS_KEY_ID: "storage-access-key",
STORAGE_SECRET_ACCESS_KEY: "storage-secret-key",
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_PUBLIC_BASE_URL: "http://localhost:3000/storage",
DEMO_USER: "demo@example.com:password",
});
expect(result.ok).toBe(true);
expect(result.diagnostics).toEqual([]);
expect(result.config).toMatchObject({
appName: "Production App",
nodeEnv: "production",
sessionSecret: "session-secret-value-prod-0123456789",
listen: {
host: "127.0.0.1",
port: 8080,
},
routing: {
appBaseDomain: "example.com",
webAppHost: "app.example.com",
adminAppHost: "admin.example.com",
apiHost: "api.example.com",
protocol: "https",
},
webhooksUrl: "https://hooks.example.com",
stripe: {
secretKey: "stripe-secret-value",
webhookSigningSecret: "stripe-webhook-secret-value",
},
crisp: {
chatWebsiteId: "crisp-id",
},
captcha: {
instanceUrl: "https://captcha.example.test",
loginSiteKey: "login-key",
},
analytics: {
token: "analytics-token-value",
},
novu: {
apiKey: "novu-secret-value",
},
mailjet: {
apiKey: "mailjet-public-value",
secretKey: "mailjet-secret-value",
fromEmail: "sender@example.com",
fromName: "Example Support",
},
ipProviders: {
ipstackApiKey: "ipstack-api-key",
ipapiIsApiKey: "ipapiis-api-key",
},
portalServer: {
url: "https://portals.example.com",
flyToken: "portal-fly-token-value",
},
magicLink: {
enabled: true,
tokenTtlMinutes: 15,
},
storage: {
provider: "s3",
fallbackProvider: "local",
endpoint: "https://storage.example.com",
region: "eu-central-1",
bucket: "uploads",
accessKeyId: "storage-access-key",
secretAccessKey: "storage-secret-key",
sessionToken: "storage-session-token",
publicBaseUrl: "https://cdn.example.com",
forcePathStyle: "true",
localRoot: "/tmp/toolctrl-storage",
localPublicBaseUrl: "http://localhost:3000/storage",
},
cryptoSecret: "crypto-secret-value-prod-0123456789",
apiAccessToken: "api-access-token-value-prod-0123456789",
jwtSecret: "jwt-secret-value-prod-0123456789abcd",
demoUser: undefined,
});
});
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");
expect(loadWebConfig({ NODE_ENV: "test", DEMO_USER: "demo@example.com:password" }).config.demoUser).toBeUndefined();
expect(loadWebConfig({ NODE_ENV: "production", DEMO_USER: "demo@example.com:password" }).config.demoUser).toBeUndefined();
});
test("keeps Magic-Link provider capability safely disabled by default", () => {
const result = loadWebConfig({});
expect(result.config.magicLink).toEqual({
enabled: false,
tokenTtlMinutes: undefined,
});
expect(result.diagnostics).not.toContainEqual(
expect.objectContaining({
name: expect.stringMatching(/^AUTH_MAGIC_LINK_/),
})
);
});
test("does not enable Magic-Link auth for malformed env values", () => {
const invalidEnabled = loadWebConfig({ AUTH_MAGIC_LINK_ENABLED: "sometimes", AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "15" });
const invalidTtl = loadWebConfig({ AUTH_MAGIC_LINK_ENABLED: "true", AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES: "0" });
expect(invalidEnabled.config.magicLink).toEqual({ enabled: false, tokenTtlMinutes: undefined });
expect(invalidEnabled.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-boolean",
name: "AUTH_MAGIC_LINK_ENABLED",
})
);
expect(JSON.stringify(invalidEnabled.diagnostics)).not.toContain("sometimes");
expect(invalidTtl.config.magicLink).toEqual({ enabled: false, tokenTtlMinutes: undefined });
expect(invalidTtl.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-duration",
name: "AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES",
})
);
expect(JSON.stringify(invalidTtl.diagnostics)).not.toContain("0");
});
test("catalogs Magic-Link provider env inputs", () => {
expect(getEnvVariableDefinition("AUTH_MAGIC_LINK_ENABLED")).toMatchObject({
classification: "optional-provider",
defaultValue: "false",
targets: ["web", "api"],
});
});
test("reports missing production session secret with redacted diagnostics", () => {
const result = loadWebConfig(
{
...REQUIRED_PRODUCTION_ENV,
SESSION_SECRET: undefined,
},
{ nodeEnv: "production" }
);
expect(result.ok).toBe(false);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "missing-required",
name: "SESSION_SECRET",
})
);
expect(JSON.stringify(result.diagnostics)).not.toContain("session-secret-value");
});
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 result = loadWebConfig({
SESSION_SECRET: secretValues[0],
STRIPE_SK: secretValues[1],
CRYPTO_SECRET: secretValues[2],
API_ACCESS_TOKEN: secretValues[3],
JWT_SECRET: secretValues[4],
PORT: "not-a-port",
});
expect(result.ok).toBe(false);
expect(result.config.listen.port).toBe(3000);
expect(result.diagnostics).toContainEqual(
expect.objectContaining({
code: "invalid-port",
name: "PORT",
})
);
const diagnosticText = JSON.stringify(result.diagnostics);
for (const secretValue of secretValues) {
expect(diagnosticText).not.toContain(secretValue);
}
});
test("keeps web-owned PORT and HOST in the catalog", () => {
expect(getEnvVariableDefinition("PORT")).toMatchObject({
targets: ["web"],
defaultValue: "3000",
});
expect(getEnvVariableDefinition("HOST")).toMatchObject({
targets: ["web"],
defaultValue: "0.0.0.0",
});
});
test("allows S3 as an explicit storage fallback provider", () => {
const result = loadWebConfig({
STORAGE_PROVIDER: "local",
STORAGE_FALLBACK_PROVIDER: "s3",
});
expect(result.config.storage).toMatchObject({
provider: "local",
fallbackProvider: "s3",
});
});
});