diff --git a/CHANGELOG.md b/CHANGELOG.md index cc2a9d9..2281811 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,12 @@ at boot. Entries start at 0.3.0. ## Unreleased +### A malformed URL variable's boot error no longer prints the value + +When a URL variable such as `PLUGIN_DB_URL`, `PLUGIN_DB_ADMIN_URL` or `OTLP_ENDPOINT` can't be parsed, +the boot error names the variable and not its value, so a DSN whose password breaks parsing doesn't +put the password in the log. + ### A secret plugin setting's bad value stays out of the boot error When a `secret` setting's value fails validation, the boot error no longer prints it, so a malformed diff --git a/docs/comprehension-history.md b/docs/comprehension-history.md index 9e4e47f..49719f0 100644 --- a/docs/comprehension-history.md +++ b/docs/comprehension-history.md @@ -222,3 +222,71 @@ Inherited architect, would restructure first: - Locality, Overall: `src/http/app.ts:185` `handleRequest`: the most concerns and the highest complexity, already grandfathered, and every request-wide concern lands in it - Shape, Navigation: `src/ui/stylesheet-floor.ts:15` `FLOOR`: the 3am rule's home is a test-only module under `ui/` - Shape: `src/auth/routes.ts:275` `buildAuthRoutes`: the 19-module `src/auth/` mixes six concerns, and this file with `flow-view.ts` is where the next flow lands + +## 2026-10-31T13:06:16Z, PR #202 at 8e73d16 + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Junior A | 7 | 6 | 6.5 | 6.5 | 6.5 | +| Mid A | 7 | 6 | 6 | 6.5 | 6.5 | +| Maintainability senior | 7 | 6 | 6 | 6.5 | 6.5 | +| Inherited architect | 6.5 | 6 | 6 | 6.5 | 6.5 | +| Mean | 6.88 | 6.00 | 6.13 | 6.50 | 6.50 | + +Junior A, hardest first: + +- Locality, Overall: `src/http/app.ts:185` `handleRequest`: about 165 lines in a fixed order that only a top-to-bottom read shows +- Self-sufficiency, Shape: `src/auth/login.ts:40` `readPermissions`: the comment says `#members` where the code uses `granted` +- Self-sufficiency: `src/plugin-host/settings.ts:35` `SettingsOf`: nested conditional types that need the charter's rule to decode + +Mid A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: complexity 43 inside the 318-line `createApp` closure, and `switchBase` reads `builtinRoutes` declared 60 lines later +- Locality, Shape: `src/ui/stylesheet-floor.ts:119` `positive`: a regex CSS walker whose how stayed opaque +- Self-sufficiency: `src/auth/bootstrap.ts:31` `permissionTuple`: the comment says `#members` where the code uses `granted` + +Maintainability senior, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: 167 lines and complexity 43 mixing twelve concerns whose order no type expresses +- Locality: `src/ui/stylesheet-floor.ts:119` `positive`: a hand-rolled regex CSS scanner traced by hand +- Self-sufficiency: `src/auth/gate.ts:13` `allows`: an empty gate is allowed, and the reason lives only in AGENTS.md + +Inherited architect, would restructure first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: the largest hub, where every request-wide concern lands +- Shape, Navigation: `src/auth/routes.ts:275` `buildAuthRoutes`: the 19-module `src/auth/` mixes four concerns with no sub-folder +- Shape, Navigation: `src/ui/stylesheet-floor.ts:30` `floorViolations`: test tooling sits among the runtime UI modules + +## 2026-10-31T13:06:21Z, PR #202 rerun at 8e73d16 + +| Seat | Navigation | Locality | Shape | Self-sufficiency | Overall | +|---|---|---|---|---|---| +| Junior A | 7 | 5.5 | 6 | 6 | 6 | +| Mid A | 7 | 6 | 6 | 6 | 6.5 | +| Maintainability senior | 7 | 6 | 6 | 6 | 6.5 | +| Inherited architect | 7 | 5.5 | 6 | 7 | 6.5 | +| Mean | 7.00 | 5.75 | 6.00 | 6.25 | 6.38 | + +Junior A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: closures over request state in a 318-line `createApp`, and it stayed opaque +- Self-sufficiency: `src/auth/routes.ts:58` `flowFailure`: the Kratos status semantics live outside the repo +- Self-sufficiency, Shape: `src/auth/login.ts:45` `readPermissions`: the comment says `#members` where the code uses `granted` + +Mid A, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: one pipeline whose steps mutate what later steps read +- Locality: `src/ui/stylesheet-floor.ts:119` `positive`: traced by hand +- Self-sufficiency, Shape: `src/auth/login.ts:45` `readPermissions`: the comment says `#members` where the code uses `granted` + +Maintainability senior, hardest first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: an unstated, load-bearing step order in shared closure state +- Locality: `src/ui/stylesheet-floor.ts:119` `positive`: a hand-rolled CSS scanner built on lookbehind regexes +- Self-sufficiency, Shape: `src/auth/bootstrap.ts:31` `permissionTuple`: the comment is false on the security-relevant path + +Inherited architect, would restructure first: + +- Locality, Shape, Overall: `src/http/app.ts:185` `handleRequest`: stage order lives only in line order, in a grandfathered complexity-43 function +- Shape, Navigation: `src/auth/routes.ts:275` `buildAuthRoutes`: 19 flat modules in `src/auth/`, and the next flow lands here +- Shape, Navigation: `src/ui/stylesheet-floor.ts:15` `FLOOR`: the 3am rule's home is a test-only module under `ui/` diff --git a/docs/reading-cost.md b/docs/reading-cost.md index c3d477d..2e1aaa0 100644 --- a/docs/reading-cost.md +++ b/docs/reading-cost.md @@ -291,3 +291,16 @@ Read most (opens and searches): - `e2e-tests/full-flow.spec.ts` 1 - `examples/plugins/admin/admin-users.test.ts` 1 - `examples/plugins/admin/admin-users.ts` 1 + +## Reading cost, chunk f0a49c300aac, finished 2026-10-31T12:47:27Z + +63526 new input tokens before the first commit. + +Read most (opens and searches): + +- `README.md` 4 +- `src/plugin-host/settings.test.ts` 3 +- `todo.md` 3 +- `CHANGELOG.md` 2 +- `src/plugin-host/settings.ts` 2 +- `AGENTS.md` 1 diff --git a/src/config.test.ts b/src/config.test.ts index 62a00d5..87a591a 100644 --- a/src/config.test.ts +++ b/src/config.test.ts @@ -39,6 +39,23 @@ test("PLUGIN_DB_URL carrying credentials is refused, not silently overwritten", assert.equal(loadConfig({}).pluginDbUrl, undefined); // unset ⇒ storage off }); +test("a malformed URL value is refused by naming the variable, never echoing the value", () => { + // PLUGIN_DB_URL and OTLP_ENDPOINT can carry credentials; APP_URL and KRATOS_PUBLIC_URL stand for the other keys, one per reader. + const bad: Record = { + APP_URL: "https://acme:pa/ss@[host", + KRATOS_PUBLIC_URL: "http://u:pa/ss@[kratos:4433", + OTLP_ENDPOINT: "http://otel:pa/ss@[collector:4318", + PLUGIN_DB_URL: "postgres://admin:pa/ss@db:5432/plugins", + }; + for (const [key, value] of Object.entries(bad)) { + assert.throws( + () => loadConfig({ [key]: value }), + (err: Error) => err.message.includes(key) && !err.message.includes("pa/ss") && !err.message.includes(value), + key, + ); + } +}); + test("the per-role connection ceiling defaults to 10 and rejects nonsense", () => { assert.equal(resolvePluginDbConnectionLimit({}), 10); assert.equal(resolvePluginDbConnectionLimit({ PLUGIN_DB_CONNECTION_LIMIT: "25" }), 25); diff --git a/src/config.ts b/src/config.ts index dcceb5d..b14dde7 100644 --- a/src/config.ts +++ b/src/config.ts @@ -98,26 +98,27 @@ function readEnum(env: Env, key: string, allowed: readonly T[] throw new Error(`config: ${key} must be one of ${allowed.join(", ")}, got "${value}"`); } -// An optional absolute URL: unset/empty ⇒ undefined; a set-but-malformed value fails at boot. -function readOptionalUrl(env: Env, key: string): string | undefined { - const value = env[key] || undefined; - if (value === undefined) return undefined; +// Never echoes the value: a DSN whose password breaks URL parsing (a bare "/") would put the +// password in the boot error and the log. +function assertUrl(key: string, value: string): void { try { new URL(value); } catch { - throw new Error(`config: ${key} is not a valid URL: ${value}`); + throw new Error(`config: ${key} must be an absolute URL (its value is not shown; percent-encode special characters in a password)`); } +} + +// An optional absolute URL: unset/empty ⇒ undefined; a set-but-malformed value fails at boot. +function readOptionalUrl(env: Env, key: string): string | undefined { + const value = env[key] || undefined; + if (value !== undefined) assertUrl(key, value); return value; } // An absolute URL: defaults to the Ory service; validated so a typo fails at boot. function readUrl(env: Env, key: string, devDefault: string): string { const value = env[key] ?? devDefault; - try { - new URL(value); - } catch { - throw new Error(`config: ${key} is not a valid URL: ${value}`); - } + assertUrl(key, value); return value; } diff --git a/src/plugin-host/storage-provisioning.ts b/src/plugin-host/storage-provisioning.ts index c58d422..4c89b52 100644 --- a/src/plugin-host/storage-provisioning.ts +++ b/src/plugin-host/storage-provisioning.ts @@ -16,10 +16,20 @@ export interface ProvisionResult { provisioned: string[]; } +// The driver's error for a DSN it can't parse carries the whole string (`input`) — password included — +// so it is swallowed here. The driver, not `new URL`, decides what parses: it takes a multi-host DSN. +function connect(adminUrl: string): ReturnType { + try { + return postgres(adminUrl, { connect_timeout: 10, max: 1 }); + } catch { + throw new Error("PLUGIN_DB_ADMIN_URL must be a Postgres URL (its value is not shown; percent-encode special characters in a password)"); + } +} + export async function provisionStorage(options: ProvisionOptions): Promise { // Notices are left to surface: a REVOKE the account cannot perform only *warns*, and silencing // that would mean reporting a locked-down database that is still open to PUBLIC. - const sql = postgres(options.adminUrl, { connect_timeout: 10, max: 1 }); + const sql = connect(options.adminUrl); try { const provisioned: string[] = []; for (const pluginId of options.pluginIds) { diff --git a/src/plugin-host/storage.test.ts b/src/plugin-host/storage.test.ts index 3bc49c1..e34714d 100644 --- a/src/plugin-host/storage.test.ts +++ b/src/plugin-host/storage.test.ts @@ -108,6 +108,13 @@ test("a connection limit that is not a positive integer is refused, not interpol } }); +test("a malformed admin DSN is refused by name, without echoing its password", async () => { + await assert.rejects( + provisionStorage({ adminUrl: "postgres://admin:pa/ss@db:5432/plugins", connectionLimit: 10, pluginIds: [], secret: SECRET }), + (err: Error) => err.message.includes("PLUGIN_DB_ADMIN_URL") && !err.message.includes("pa/ss"), + ); +}); + // --- Integration: the statements above, against a real Postgres ----------------------- // Opt-in via PLUGIN_DB_ADMIN_URL (a superuser DSN); the unit gate runs no Postgres. What the unit // tests cannot prove lives here: the owner may create tables, and a peer role is locked out. diff --git a/todo.md b/todo.md index c52b36d..ec3053a 100644 --- a/todo.md +++ b/todo.md @@ -6,13 +6,13 @@ `Bar = 1` -`Next ID = 56` +`Next ID = 57` ## Items | ID | Release | Blocked by | Exempt | Item | L | E | I | R | S | Moves | Score | |---|---|---|---|---|---|---|---|---|---|---|---| -| 55 | 0.4.21 | | security | **Keep a URL config value out of the boot error that rejects it.** | 1 | 1 | 4 | 5 | 2 | | 0.0 | +| 56 | 0.4.22 | | | **Correct the README's two statements that `REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`.** | 1 | 2 | 1 | 2 | 1 | code health by 2 | 14.4 | | 19 | 0.5.0 | | question | **Run the documented Docker commands on macOS and fix whatever misbehaves.** | 2 | 2 | 1 | 3 | 3 | 1 by 3 | 3.3 | | 16 | 0.5.0 | | question | **Decide whether the single Keto `Resource` namespace splits into per-domain namespaces.** | 3 | 2 | 3 | 6 | 6 | 7 by 2 | 0.5 | | 48 | 0.5.0 | | | **Correct the Keto tuple in the `login.ts` and `bootstrap.ts` comments to the `granted` relation the code writes.** | 1 | 1 | 1 | 1 | 1 | code health by 4 | 28.7 | @@ -34,19 +34,16 @@ ## Details -### 55. Keep a URL config value out of the boot error that rejects it. +### 56. Correct the README's two statements that `REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`. -`readOptionalUrl` and `readUrl` in `src/config.ts` throw `config: ${key} is not a valid URL: ${value}`, -so a malformed value reaches the boot error and the log. A DSN whose password breaks parsing, such as -`postgres://admin:pa/ss@db:5432/plugins`, leaks that password. The keys that can carry credentials: -`PLUGIN_DB_URL` (`readCredentiallessUrl` refuses userinfo only after `readOptionalUrl` has parsed it, -so a pasted admin DSN that fails to parse is echoed), and `OTLP_ENDPOINT`, whose collector URL may -embed basic-auth userinfo. The other URL keys, `APP_URL`, `HYDRA_ADMIN_URL`, `JWKS_URL`, -`KETO_READ_URL`, `KETO_WRITE_URL`, `KRATOS_ADMIN_URL` and `KRATOS_PUBLIC_URL`, pass through the same -two readers, so the fix covers them too. Name the variable and what it accepts, never the value, and -add a test per credential-bearing key. The other readers in `config.ts` echo only non-credential -values. `PLUGIN_DB_ADMIN_URL` isn't read in `config.ts`: `bootstrap.ts` hands it straight to -`postgres()`. Check whether the driver echoes a malformed one. +README → What you must supply (about `:1275`: "refuses to boot on a missing or throwaway +`CSRF_SECRET` and **nothing else**") and README → Security model (about `:1442`: +"`REQUIRE_SECURE_SECRETS` guards only `CSRF_SECRET`") contradict the Configuration table row (about +`:1216`), `src/config.ts:59` and `:190`, and `src/plugin-host/settings.ts`. The flag also refuses a +missing or throwaway `PLUGIN_DB_SECRET` once `PLUGIN_DB_URL` is set, and every plugin setting +declared `secret`. An operator following the checklist underrates the toggle. Make both passages say +what the flag enforces by pointing to the table row, its one home. Four comprehension seats raised it +independently. Markdown only. ### 19. Run the documented Docker commands on macOS and fix whatever misbehaves.