Compare commits

..
Author SHA1 Message Date
joshuaandClaude Opus 5.5 9e315f199c Merge branch 'fix/trust-proxy-checks'
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:23:49 +02:00
joshuaandClaude Opus 5.5 fd8f6c28b0 Refuse a TRUST_PROXY the apps can't start with; Accounts reads loopback
A server configuration with TRUST_PROXY=TRUE made an Events install build for
minutes, then fail: Express threw "invalid IP address: TRUE" at startup.

- scripts/lib/envtpl.cjs: VALUE_RULES checked before any .env is written
  (exit 4, naming the value and the fix), for every release.
- Contracts 1.6.0: agent.checkEnvValue / agent.invalidValues, the same rules
  for the Hub.
- Accounts 1.0.1: TRUST_PROXY read as Events reads it; loopback used to
  turn proxy trust off.
- Docs: CHANGELOGs, WHATS-NEW, HANDOVER, AGENT-1.0-PLAN, ROLLOUT-1.0, READMEs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 10:23:49 +02:00
joshuaandClaude Opus 5.5 db2e544ed6 docs: VERSIONS.md, the latest version of everything and what's deployed
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 09:23:36 +02:00
joshua ccd1cfff46 Merge branch 'fix/install-keeps-backend-logs' 2026-11-19 09:03:50 +02:00
joshuaandClaude Opus 5.5 7fd699a2fd Release the crosscode script fix: failed installs show their PM2 logs
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 09:03:48 +02:00
joshuaandClaude Opus 5.5 6988b5ce7c Scripts: a failed install shows its PM2 apps' last log lines
Before removing what a failed install made, print each PM2 app's last
30 log lines, so the Hub's job log says why the backend didn't start
instead of only "/health didn't report 2.3.1 within 90s".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-19 08:44:38 +02:00
22 changed files with 327 additions and 18 deletions
+23
View File
@@ -2,6 +2,29 @@
Each package and app has its own section and its own tags (`contracts@1.0.0`, `accounts@1.0.0`, …).
## accounts@1.0.1, contracts@1.6.0, crosscode script - 2026-11-19
A server configuration with `TRUST_PROXY=TRUE` made an Events install build for minutes, then
fail: the backend crashed at startup (`invalid IP address: TRUE`) and the install was removed.
- **Scripts: a value the app can't start with stops the install before the build.**
`lib/envtpl.cjs` checks values against `VALUE_RULES` (so far `TRUST_PROXY`: `loopback`, a hop
count, lowercase `true`/`false`, or proxy IPs/CIDRs) and exits 4 naming the value and the fix,
before any `.env` is written. The rules are in the script, so they apply to every release,
including ones from before them. On deploy, values already in a `.env` aren't checked.
- **Contracts 1.6.0:** `agent.checkEnvValue(name, value)` and `agent.invalidValues(values)`, the
same rules for the Hub (Hub 2.3.3 refuses a bad value when the configuration is saved and before
a job).
- **Accounts 1.0.1:** `TRUST_PROXY=loopback` turned proxy trust off; it's now read as Events reads
it. Details in `apps/accounts/CHANGELOG.md`.
## crosscode script - 2026-11-19 (no tag: servers run `main`)
- **Scripts: a failed install says why its apps didn't start.** Before removing what a failed
install made, `crosscode install` / `crosscode add` print each PM2 app's last 30 log lines. The
logs used to go with the apps, so the Hub only showed "/health didn't report 2.3.1 within 90s
(last answer: none)" and the reason was lost.
## agent@1.1.1 - 2026-11-18
- **Stats keep going while a job runs.** The agent sent stats and polled in one loop, so during
+11
View File
@@ -1,5 +1,16 @@
# Changelog — Accounts
## [1.0.1] - 2026-11-19
### Fixed
- **`TRUST_PROXY=loopback` turned proxy trust off.** Accounts read `TRUST_PROXY` as true/false, so
anything but `true`, including the `loopback` the Hub suggests behind frp, meant off: rate
limiting and the audit log saw every visitor as `127.0.0.1`, and oidc-provider ignored
`X-Forwarded-Proto`. It's now read as Events reads it: `loopback`, a hop count, proxy IP
addresses/CIDRs separated by commas, or `true`/`false` in any case (`true` is one hop, as
before). Unset is still one hop in production.
## [1.0.0] - 2026-11-18
The first release (docs/ACCOUNTS-1.0-PLAN.md), with Hub 2.3.0 and agent 1.1.0. Released before the
+5
View File
@@ -3,6 +3,11 @@
What each version changes for the church, in plain language (read by the Hub like Cross Events'
WHATS-NEW.md; a section shows once its version is tagged).
## 1.0.1
- **Fix:** sign-in limits and the activity log now see each visitor's own address on servers
behind the Cross Code proxy, instead of the proxy's.
## 1.0.0
- **One sign-in for all your church's sites and apps.** People sign in once with their own account
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/accounts-backend",
"version": "1.0.0",
"version": "1.0.1",
"description": "Cross Code Accounts: the church's sign-in (OpenID Connect provider), account pages API and admin API",
"private": true,
"type": "module",
+1 -1
View File
@@ -24,7 +24,7 @@ import { appVersion } from './lib/version.js';
export function createApp(ctx: Ctx, provider: Provider) {
const app = express();
app.disable('x-powered-by');
if (ctx.config.trustProxy) app.set('trust proxy', 1);
if (ctx.config.trustProxySetting !== false) app.set('trust proxy', ctx.config.trustProxySetting);
app.use((_req, res, next) => {
res.setHeader('X-Content-Type-Options', 'nosniff');
+24 -2
View File
@@ -9,8 +9,10 @@ export type Config = {
/** Encrypts secrets at rest and signs cookies. Generated on the server, never sent anywhere. */
secret: string;
production: boolean;
/** Behind nginx/frp: trust X-Forwarded-* (as Events' TRUST_PROXY). */
/** Behind nginx/frp: trust X-Forwarded-* (oidc-provider's `proxy`). */
trustProxy: boolean;
/** Express's "trust proxy" (TRUST_PROXY, read as Events reads it), or false when off. */
trustProxySetting: TrustProxy;
hubUrl: string;
hubLicenceKey: string | null;
hubPublicKey: string | null;
@@ -25,17 +27,37 @@ export type Config = {
const bool = (v: string | undefined, def: boolean) => (v === undefined || v === '' ? def : String(v).toLowerCase() === 'true');
export type TrustProxy = false | number | string | string[];
/**
* TRUST_PROXY as Express's "trust proxy": `loopback` (behind frp, the default the Hub suggests),
* a hop count, IP addresses/CIDRs separated by commas, `true` (one hop: never "trust everyone") or
* `false`. Unset: one hop in production, off otherwise. Before 1.0.1 anything but `true` meant
* off, so `loopback` turned it off.
*/
export function trustProxyFrom(v: string | undefined, production: boolean): TrustProxy {
const raw = (v ?? '').trim();
if (raw === '') return production ? 1 : false;
const lower = raw.toLowerCase();
if (lower === 'true') return 1;
if (lower === 'false') return false;
if (/^\d+$/.test(raw)) return Number(raw) || false;
return raw.includes(',') ? raw.split(',').map((s) => s.trim()).filter(Boolean) : raw;
}
export function loadConfig(env: Record<string, string | undefined> = process.env): Config {
const publicUrl = String(env.ACCOUNTS_URL || env.PUBLIC_URL || 'http://localhost:3200').replace(/\/+$/, '');
const production = env.NODE_ENV === 'production';
const secret = env.ACCOUNTS_SECRET || '';
const trustProxySetting = trustProxyFrom(env.TRUST_PROXY, production);
if (production && secret.length < 32) throw new Error('ACCOUNTS_SECRET must be set (at least 32 characters) in production.');
return {
publicUrl,
port: Number(env.PORT || 5200),
secret: secret || 'development-only-secret-change-me-0123456789',
production,
trustProxy: bool(env.TRUST_PROXY, production),
trustProxy: trustProxySetting !== false,
trustProxySetting,
hubUrl: String(env.HUB_URL || 'https://hub.crosscode.co.za').replace(/\/+$/, ''),
hubLicenceKey: env.HUB_LICENCE_KEY?.trim() || null,
hubPublicKey: env.HUB_PUBLIC_KEY?.trim() || null,
+23
View File
@@ -10,6 +10,29 @@ import { Secrets } from '../src/lib/crypto.js';
import { stateFor, type LicenceClaims } from '../src/hub/licence.js';
import { normalisePhone } from '../src/accounts/service.js';
import { waNumber } from '../src/lib/messages.js';
import { loadConfig, trustProxyFrom } from '../src/lib/config.js';
describe('TRUST_PROXY', () => {
test('read as Events reads it: loopback behind frp is on, not off', () => {
assert.equal(trustProxyFrom('loopback', true), 'loopback');
assert.deepEqual(trustProxyFrom('loopback, 203.0.113.10', true), ['loopback', '203.0.113.10']);
assert.equal(trustProxyFrom('2', true), 2);
assert.equal(trustProxyFrom('TRUE', true), 1);
assert.equal(trustProxyFrom('true', false), 1);
assert.equal(trustProxyFrom('false', true), false);
assert.equal(trustProxyFrom('0', true), false);
assert.equal(trustProxyFrom(undefined, true), 1);
assert.equal(trustProxyFrom('', false), false);
});
test('oidc-provider trusts the proxy whenever Express does', () => {
const on = loadConfig({ NODE_ENV: 'test', TRUST_PROXY: 'loopback' });
assert.equal(on.trustProxy, true);
assert.equal(on.trustProxySetting, 'loopback');
const off = loadConfig({ NODE_ENV: 'test', TRUST_PROXY: 'false' });
assert.equal(off.trustProxy, false);
});
});
describe('passwords', () => {
test('Argon2id hashes verify, wrong passwords don\'t', async () => {
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/accounts-frontend",
"version": "1.0.0",
"version": "1.0.1",
"private": true,
"description": "Cross Code Accounts: the church's sign-in pages, the account page and admin",
"scripts": {
+1 -1
View File
@@ -84,7 +84,7 @@ Create `backend/.env` from `.env.example`. The only variables you must set are:
| `APP_BASE_URL` | — | Public frontend URL — used in email links (fallback if not set via admin panel) |
| `BACKEND_URL` | — | Public backend URL — used to serve ticket PDFs over WhatsApp |
| `PORT` | — | Port to listen on (default `3000`) |
| `TRUST_PROXY` | — | Set when running behind a reverse proxy (e.g. nginx on a separate server), so `req.ip`/`X-Forwarded-For` are read correctly by rate limiting. Accepts a hop count (`1`), `true`/`false`, or comma-separated trusted proxy IP(s)/CIDR(s). |
| `TRUST_PROXY` | — | Set when running behind a reverse proxy (e.g. nginx on a separate server), so `req.ip`/`X-Forwarded-For` are read correctly by rate limiting. Accepts a hop count (`1`), `true`/`false` (lowercase), `loopback` (behind frp), or comma-separated trusted proxy IP(s)/CIDR(s). Anything else (e.g. `TRUE`) stops the backend starting; the Hub and the crosscode script refuse it. |
| `NODE_ENV` | — | `production` or `development` |
| `WAWP_ACCESS_TOKEN` | — | WAWP fallback token (preferred: set via Admin → Site Settings) |
| `WAWP_INSTANCE_ID` | — | WAWP fallback instance ID (preferred: set via Admin → Site Settings) |
+4 -1
View File
@@ -188,7 +188,10 @@ monorepo, listing every variable with its layer, whether it's required, and a de
**For Joshua to set per server before the first install:** the database settings and
`TRUST_PROXY`. Behind frp the app sees every connection from frpc on `127.0.0.1`, and the
visitor's address arrives in `X-Forwarded-For` from FastPanel's nginx, so the expected value is
`loopback` (the Hub suggests it).
`loopback` (the Hub suggests it). A value the apps can't start with (e.g. `TRUE`, which crashed
the Events backend after a whole install's build) is refused when the configuration is saved (Hub
2.3.3), before a job is made, and again by the crosscode script before it writes a `.env`
(`checkEnvValue` in `@crosscode/contracts` 1.6.0, `VALUE_RULES` in `scripts/lib/envtpl.cjs`).
## 6. frp and the central server
+7 -2
View File
@@ -8,7 +8,9 @@ are in [`apps/events/docs/HANDOVER.md`](../apps/events/docs/HANDOVER.md), and th
The docs for every product are here in `docs/`: the roadmap, the Hub protocol
([hub-protocol.md](./hub-protocol.md), with a copy in `events-hub`), this handover, the plans
for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)).
for each phase and the rollout checklist ([ROLLOUT-1.0.md](./ROLLOUT-1.0.md)). The latest
version of everything, and what's deployed, is in [VERSIONS.md](./VERSIONS.md) (update it with
every release).
## Repos
@@ -78,7 +80,10 @@ rollout.
- **The agent pins the Hub's job key** when it joins. Back up `events-hub/backend/keys/` (licence
and job keys); replacing the job key means every server joins again.
- **A new `.env` variable** goes in three env templates: `apps/<product>/env.template.json`,
`scripts/products/<product>.env.template.json` and the Hub's `envTemplates/<product>.json`.
`scripts/products/<product>.env.template.json` and the Hub's `envTemplates/<product>.json`. If
the app refuses some values at startup (as Events does a `TRUST_PROXY` it can't parse), add a
rule to both `checkEnvValue` in `packages/contracts/src/agent.ts` (the Hub) and `VALUE_RULES` in
`scripts/lib/envtpl.cjs` (the server), so a bad value stops before an install's build.
- **A new Events install never takes over an existing database**: moving an existing site is
`adopt`, not a New install pointed at the old database.
- **Prisma in the monorepo:** each app other than Events sets its own generator `output`, so
+2 -1
View File
@@ -43,7 +43,8 @@ Follow `events-hub/deployment.md` → "Upgrading to 2.1":
- [ ] Hub → Servers → Add server → **Church**; run the command as root. It installs Node tools,
the agent (`/opt/crosscode/agent`) and the crosscode script (`/opt/crosscode/tools`, from
main), and starts `crosscode-agent`. The agent listens on nothing.
- [ ] On the server's page: its configuration. `TRUST_PROXY=loopback` behind frp; the database:
- [ ] On the server's page: its configuration. `TRUST_PROXY=loopback` behind frp (lowercase;
`TRUE` stops the Events backend starting, and the Hub refuses it from 2.3.3); the database:
`DB_HOST`/`DB_PORT`/`DB_ADMIN_URL` for a separate PostgreSQL, or nothing for the local one.
- [ ] `systemctl status crosscode-agent` is active; the server's stats show on the Hub.
- [ ] The first time the agent changes `frpc.ini` it adds the admin lines and **restarts frpc once**
+65
View File
@@ -0,0 +1,65 @@
# Versions — the latest release of everything
Last updated: 2026-11-19. Taken from the git tags, which is what a release is here (branch → merge →
tag → push, see [HANDOVER.md](./HANDOVER.md) "Releasing"). **Update this file with every release.**
"Released" means tagged and pushed. Whether a release is **deployed** or rolled out is recorded
separately below; the two often differ.
## Released
| What | Repo | Latest | Tag | Released |
|------|------|--------|-----|----------|
| Cross Events | `crosscode-platform` (`apps/events`) | **2.4.0** | `events@2.4.0` | 2026-11-18 |
| Accounts | `crosscode-platform` (`apps/accounts`) | **1.0.0** | `accounts@1.0.0` | 2026-11-18 |
| Server agent | `crosscode-platform` (`apps/agent`) | **1.1.1** | `agent@1.1.1` | 2026-11-18 |
| Contracts | `crosscode-platform` (`packages/contracts`) | **1.5.0** | `contracts@1.5.0` | 2026-11-18 |
| Cross Code Hub | `events-hub` | **2.3.2** | `v2.3.2` | 2026-11-19 |
| crosscode.co.za | `crosscode-site` | **1.5.0** | `v1.5.0` | 2026-11-18 |
| `crosscode` script | `crosscode-platform` (`scripts/`) | `main` | none | 2026-11-19 (last change) |
The `crosscode` script has no version: every server's copy (`/opt/crosscode/tools`) pulls `main`
on each run, so merging to `main` and pushing releases it. Its changes are listed in
[CHANGELOG.md](../CHANGELOG.md) under "crosscode script".
### Not tagged yet
| What | Where | Version in package.json |
|------|-------|-------------------------|
| `@crosscode/auth-client` | `packages/auth-client` | 1.0.0 (released with Accounts 1.0.0) |
| `@crosscode/seo` | `packages/seo` | 1.0.0 (released with Events 2.4.0) |
| `@crosscode/ui` | `packages/ui` | 0.1.0 |
| Website | `apps/website` | 0.0.0 (not started, phase 4) |
| App | `apps/app` | 0.0.0 (not started, phase 6) |
These shared packages ship inside the apps that use them, from the same checkout, so they don't
need their own tags until something outside this repo depends on them.
## What each latest release was for
- **Events 2.4.0:** protocol v2, Linked products, the event feed, `packages/seo`
([EVENTS-2.4-PLAN.md](./EVENTS-2.4-PLAN.md)). 2.3.1 is the version for churches until 2.4.0's
e2e run on Postgres and VM test are done.
- **Accounts 1.0.0:** the church's sign-in (OpenID Connect provider)
([ACCOUNTS-1.0-PLAN.md](./ACCOUNTS-1.0-PLAN.md)). Needs the VM test and a run on real Postgres
before a church gets it.
- **Agent 1.1.1:** stats keep going while a job runs; reports its real version.
- **Contracts 1.5.0:** the Accounts contracts (OIDC client paths, scopes, church events).
- **Hub 2.3.2:** installs no longer get stuck "Uninstalling" when the export fails; a failed
install's record can be removed (and uninstall is refused for it).
- **crosscode.co.za 1.5.0:** lists Accounts.
- **`crosscode` script (2026-11-19):** a failed install prints each PM2 app's last log lines before
removing it, so the Hub's job log shows why the backend didn't start.
## Deployed / rolled out
What actually runs isn't in git, so this table is kept by hand. Fill in a version and date when
you deploy one.
| What | Running | Since | Notes |
|------|---------|-------|-------|
| Hub | 2.x (exact version not recorded) | | It runs agent jobs (installs on church-server1, 2026-11-18), so it's past 2.1. **2.3.2 not deployed yet** |
| Agent on church-server1 | not recorded | | |
| Agent on the central server | not recorded | | |
| Cross Events (churches) | not recorded | | `hope-events` and `cross-events-demo` heartbeat as 2.1.1 and 2.3.1 |
| crosscode.co.za | not recorded | | Handover: `v1.3.0` was merged and tagged but not deployed |
+3 -3
View File
@@ -46,7 +46,7 @@
},
"apps/accounts/backend": {
"name": "@crosscode/accounts-backend",
"version": "1.0.0",
"version": "1.0.1",
"hasInstallScript": true,
"dependencies": {
"@crosscode/contracts": "*",
@@ -82,7 +82,7 @@
},
"apps/accounts/frontend": {
"name": "@crosscode/accounts-frontend",
"version": "1.0.0",
"version": "1.0.1",
"dependencies": {
"@crosscode/contracts": "*",
"@crosscode/ui": "*",
@@ -21274,7 +21274,7 @@
},
"packages/contracts": {
"name": "@crosscode/contracts",
"version": "1.5.0",
"version": "1.6.0",
"license": "UNLICENSED",
"dependencies": {
"zod": "^4.6.7"
+1
View File
@@ -13,6 +13,7 @@ Events and the Hub, uses it, so the key fields are the same in every product's J
| Sign-in return | — | The return-path check and OIDC `state` every product uses (ROADMAP-v3 §3) | `src/return-to.ts` |
| Product link | `crosscode.link/1` | **Connect** under Settings → Linked products: the signed handshake that sets up a link's secret (`link.connect`, `link.connected`, `link.disconnect`) | `src/link.ts` |
| Hub protocol v2 | `protocolVersion: 2` | Register, heartbeat (stats per product), linked products, update requests, AI, licence token | `src/hub.ts` (exported as `hub`) |
| Env template | `crosscode.env-template/1` | Each product's `.env` variables by layer; `missingRequired` and, from 1.6.0, `checkEnvValue` / `invalidValues` (values an app can't start with, e.g. `TRUST_PROXY=TRUE`), which the Hub checks before a job | `src/agent.ts` (exported as `agent`) |
| Signing | — | HMAC request signing for the Hub and for product links (Node only) | `src/signing.ts` (`@crosscode/contracts/signing`) |
## Using it
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@crosscode/contracts",
"version": "1.5.0",
"version": "1.6.0",
"description": "The shared JSON formats used by every Cross Code product: zod schemas, JSON Schema, TypeScript types and sample payloads",
"license": "UNLICENSED",
"type": "commonjs",
+38
View File
@@ -318,3 +318,41 @@ export function missingRequired(template: EnvTemplate, layer: "server" | "defaul
}
return [...new Set(missing)];
}
// Values the apps check at startup, so a bad one is refused when it's entered instead of
// crashing the app after an install's build. Keep in step with VALUE_RULES in
// scripts/lib/envtpl.cjs (which checks again on the server, for any release).
const PROXY_NAME = /^(loopback|linklocal|uniquelocal)$/;
const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
const isIp = (s: string) => IPV4.test(s) || (s.includes(":") && /^[0-9A-Fa-f:.]+$/.test(s));
function proxyEntry(s: string): boolean {
if (PROXY_NAME.test(s)) return true;
const [ip, bits, extra] = s.split("/");
if (extra !== undefined || ip === undefined || !isIp(ip)) return false;
return bits === undefined || /^\d{1,3}$/.test(bits) || IPV4.test(bits);
}
const ENV_VALUE_RULES: Record<string, { ok: (v: string) => boolean; hint: string }> = {
// Events hands this to Express's "trust proxy" (apps/events/backend/src/app.js).
TRUST_PROXY: {
ok: (v) => v === "true" || v === "false" || /^\d+$/.test(v) || v.split(",").every((s) => proxyEntry(s.trim())),
hint: "Use loopback behind frp, a hop count such as 1, true or false (lowercase), or proxy IP addresses/CIDRs separated by commas.",
},
};
/** Why an app can't start with this value (a sentence for the person who entered it), or null when it can. */
export function checkEnvValue(name: string, value: string): string | null {
const rule = ENV_VALUE_RULES[name];
if (!rule || rule.ok(String(value).trim())) return null;
return `${name} can't be "${value}". ${rule.hint}`;
}
/** The problems with a layer's values ({ NAME: message }), empty when there are none (the Hub's check on save and before a job). */
export function invalidValues(values: Record<string, string | undefined>): Record<string, string> {
const out: Record<string, string> = {};
for (const [name, value] of Object.entries(values)) {
if (value === undefined || value === null || String(value) === "") continue;
const problem = checkEnvValue(name, String(value));
if (problem) out[name] = problem;
}
return out;
}
+14
View File
@@ -171,4 +171,18 @@ describe("env templates", () => {
expect(agent.missingRequired(template, "server", { TRUST_PROXY: "loopback" })).toEqual(["DB_HOST"]);
expect(agent.missingRequired(template, "defaults", {})).toEqual(["HUB_URL"]);
});
it("refuses a TRUST_PROXY the Events backend can't start with", () => {
for (const ok of ["loopback", "1", "true", "false", "loopback, 203.0.113.10", "10.0.0.0/8", "::1", "fd00::/8", "192.168.1.0/255.255.255.0"]) {
expect(agent.checkEnvValue("TRUST_PROXY", ok)).toBeNull();
}
for (const bad of ["TRUE", "True", "yes", "on", "300.1.1.1", "10.0.0.0/8/1", "loopback,"]) {
expect(agent.checkEnvValue("TRUST_PROXY", bad)).toMatch(/^TRUST_PROXY can't be/);
}
expect(agent.checkEnvValue("DB_HOST", "anything")).toBeNull();
expect(agent.invalidValues({ TRUST_PROXY: "TRUE", DB_HOST: "10.0.0.5", DB_PORT: undefined })).toEqual({
TRUST_PROXY: expect.stringContaining("loopback"),
});
expect(agent.invalidValues({ TRUST_PROXY: "loopback" })).toEqual({});
});
});
+43 -3
View File
@@ -12,7 +12,9 @@
// appear in arguments or files other than the .env); server / defaults → the config's layers;
// install → the config's install[product], else the variable's `from` filled with --var values.
// Then --fallback, then the template's `default`. A required variable with no value stops
// everything before any file is written (exit 3, the names on stderr).
// everything before any file is written (exit 3, the names on stderr). So does a value the app
// can't start with (VALUE_RULES, exit 4), e.g. TRUST_PROXY=TRUE, which crashes the Events backend
// only after the long build.
// --check: only says what would be added. Prints names only, never values.
'use strict';
@@ -54,6 +56,33 @@ function keysIn(text) {
return keys;
}
// Values the apps check at startup. The rules live here rather than in the templates so they also
// apply to releases whose templates predate them. Keep in step with checkEnvValue in
// packages/contracts/src/agent.ts. Only for values that aren't secret: the message shows the value.
const PROXY_NAME = /^(loopback|linklocal|uniquelocal)$/;
const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
const isIp = s => IPV4.test(s) || (s.includes(':') && /^[0-9A-Fa-f:.]+$/.test(s));
function proxyEntry(s) {
if (PROXY_NAME.test(s)) return true;
const [ip, bits, extra] = s.split('/');
if (extra !== undefined || !isIp(ip)) return false;
return bits === undefined || /^\d{1,3}$/.test(bits) || IPV4.test(bits);
}
const VALUE_RULES = {
// Events hands this to Express's "trust proxy" (apps/events/backend/src/app.js).
TRUST_PROXY: {
ok: v => v === 'true' || v === 'false' || /^\d+$/.test(v) || v.split(',').every(s => proxyEntry(s.trim())),
hint: 'use loopback behind frp, a hop count such as 1, true or false (lowercase), or proxy IP addresses/CIDRs separated by commas',
},
};
/** Why the app can't use this value, or undefined when it can (or there's no rule for it). */
function checkValue(name, value) {
const rule = VALUE_RULES[name];
if (!rule || rule.ok(String(value).trim())) return undefined;
return `${name}=${JSON.stringify(String(value))} won't work: ${rule.hint}`;
}
function fill(from, vars) {
let missing = false;
const value = from.replace(/\{([A-Za-z]+)\}/g, (_, k) => {
@@ -94,6 +123,7 @@ function plan(opts) {
const ctx = { config, vars: opts.vars, fallback: opts.fallback, product: opts.product || template.product };
const files = [];
const missing = [];
const invalid = [];
for (const [rel, variables] of Object.entries(template.files)) {
if (rel.includes('..') || path.isAbsolute(rel)) throw new Error(`Bad file name in the template: ${rel}`);
const file = path.join(opts.dir, rel);
@@ -107,11 +137,17 @@ function plan(opts) {
if (v.required) missing.push(`${v.name} (${v.layer}, ${rel})`);
continue;
}
const problem = checkValue(v.name, value);
if (problem) {
const where = v.layer === 'server' ? "server, from the server's configuration on the Hub" : v.layer;
invalid.push(`${problem} (${where}, ${rel})`);
continue;
}
add.push({ name: v.name, value });
}
files.push({ rel, file, exists, add });
}
return { files, missing };
return { files, missing, invalid: [...new Set(invalid)] };
}
function write({ files }, release) {
@@ -151,6 +187,10 @@ function main() {
console.error(`Required settings with no value: ${result.missing.join(', ')}`);
process.exit(3);
}
if (result.invalid.length) {
console.error(`Settings the app can't start with:\n ${result.invalid.join('\n ')}`);
process.exit(4);
}
for (const f of result.files) {
if (!f.add.length) continue;
const names = f.add.map(a => a.name).join(', ');
@@ -161,4 +201,4 @@ function main() {
if (require.main === module) main();
module.exports = { parseArgs, keysIn, fill, line, plan, write };
module.exports = { parseArgs, keysIn, fill, line, plan, write, checkValue };
+15 -1
View File
@@ -58,12 +58,26 @@ random_secret() { openssl rand -base64 64 | tr -d '/+=\n' | head -c "${1:-48}";
INSTALL_UNDO=""
undo_add() { [ -z "$INSTALL_UNDO" ] || printf '%s\n' "$*" >> "$INSTALL_UNDO"; }
# pm2_last_logs <user> <name…>: each PM2 app's last 30 log lines (output and errors), indented.
pm2_last_logs() {
local user="$1" name
shift
for name in "$@"; do
info "PM2: last log lines of $name"
run_as "$user" / pm2 logs "$name" --lines 30 --nostream --raw </dev/null 2>&1 | tail -n 60 | sed 's/^/ /' || true
done
}
install_undo() {
local kind a b
step "Removing what this install made"
tac "$INSTALL_UNDO" | while read -r kind a b; do
case "$kind" in
pm2) # shellcheck disable=SC2086 # b is a space-separated list of PM2 names
pm2)
# Their logs go with them, so show why they didn't start first (the Hub gets the log).
# shellcheck disable=SC2086 # b is a space-separated list of PM2 names
pm2_last_logs "$a" $b
# shellcheck disable=SC2086
run_as "$a" / pm2 delete $b >/dev/null 2>&1 || true
run_as "$a" / pm2 save --force >/dev/null 2>&1 || true
info "PM2: $b removed" ;;
+17
View File
@@ -259,3 +259,20 @@ EOF
[ "$(host_from_url "$(env_value "$TMP/.env" FRONTEND_URL)")" = events.hopefamily.co.za ]
[ "$(host_from_url http://localhost:3000/x)" = localhost ]
}
# ── install undo ────────────────────────────────────────────────────────────────────────────
@test "a failed install shows each PM2 app's last log lines before removing it" {
# shellcheck source=../lib/install.sh
source "$BATS_TEST_DIRNAME/../lib/install.sh"
run_as() { shift 2; case "$2" in logs) printf 'Error: %s crashed\n' "$3" ;; esac; echo "$*" >> "$TMP/pm2"; }
INSTALL_UNDO="$TMP/undo"
undo_add pm2 cc-hope "hope-events-backend hope-events-frontend"
run install_undo
[ "$status" -eq 0 ]
[[ "$output" == *"last log lines of hope-events-backend"* ]]
[[ "$output" == *" Error: hope-events-backend crashed"* ]]
[[ "$output" == *" Error: hope-events-frontend crashed"* ]]
# The logs are read before the apps are deleted.
[ "$(grep -n 'logs hope-events-backend' "$TMP/pm2" | cut -d: -f1)" -lt "$(grep -n '^pm2 delete' "$TMP/pm2" | cut -d: -f1)" ]
}
+27
View File
@@ -54,6 +54,33 @@ envtpl() { node "$TPL_JS" --template "$TMP/template.json" --dir "$APP" --product
[ ! -e "$APP/frontend/.env.production" ]
}
@test "a value the app can't start with: nothing is written, the value and the fix are named" {
printf '{ "server": { "TRUST_PROXY": "TRUE" } }\n' > "$TMP/bad.json"
run envtpl --config "$TMP/bad.json" --release events@2.4.0
[ "$status" -eq 4 ]
[[ "$output" == *'TRUST_PROXY="TRUE" won'"'"'t work'* ]]
[[ "$output" == *"loopback behind frp"* ]]
[[ "$output" == *"server's configuration on the Hub"* ]]
[ ! -e "$APP/backend/.env" ]
[ ! -e "$APP/frontend/.env.production" ]
}
@test "TRUST_PROXY: the values Events understands are accepted" {
for v in loopback 1 true false 'loopback, 203.0.113.10' 10.0.0.0/8 '::1'; do
rm -rf "$APP/backend/.env" "$APP/frontend/.env.production"
printf '{ "server": { "TRUST_PROXY": "%s" } }\n' "$v" > "$TMP/ok.json"
run envtpl --config "$TMP/ok.json"
[ "$status" -eq 0 ] || { echo "$v: $output"; false; }
done
}
@test "deploy: a bad value already in a .env is left alone (only new variables are checked)" {
printf 'DATABASE_URL=x\nPORT=1\nFRONTEND_URL=y\nTRUST_PROXY=TRUE\n' > "$APP/backend/.env"
printf '{ "server": { "TRUST_PROXY": "TRUE" } }\n' > "$TMP/bad.json"
run envtpl --config "$TMP/bad.json"
[ "$status" -eq 0 ]
}
@test "--fallback fills a value no layer gives" {
run envtpl --fallback TRUST_PROXY=1
[ "$status" -eq 0 ]