# Design: bound parameters for `` **Status:** phases 1 and 2 implemented (2026-11-20) · **Author:** Brad Arant (drafted with Claude) · **Date:** 2026-10-23 **Applies to:** JetCore (`__sql`, `__mysql`, `Tag.cpp` tag dispatch, `jetc` parser/codegen) ## 1. The problem `` builds its query by rendering its body as text, then sending the finished string to MySQL: ```cpp // __sql.cpp today processContainer(container); // every $[...] substituted as plain text global.getSession(sessionId)->query(out); // mysql_real_query(the whole string) ``` So a request value lands *inside the SQL text*: ```html select id from users where email='$[email]' and secret='$[password]' ``` With `email = x' or '1'='1' -- ` that becomes a different query. There is no escaping function in Jet, so this is the only way to write a query, and it's unsafe everywhere a value comes from a request. Numeric positions are worse: `where id=$[id]` has no quotes, so even escaping wouldn't help (`id = 1 or 1=1`). Measured on 2026-10-23 (`` blocks whose body contains a request/session value other than `$[.column]`, `$[_login_id]` or `$[_session_id]`): | Site | `` blocks | with values pasted in | files | |---|---:|---:|---:| | barant.com | 152 | 117 | 64 | | ClockPlanet | 94 | 83 | 35 | Roughly 80% of all queries. Login, signup, cart, checkout and admin pages are all in that set. ## 2. Goals 1. A way to pass values to `` that **can never change the query's meaning**, whatever they contain. 2. **No change to how results are read** - ``, ``, `$[.column]`, `$[?N]`, `$[#]` keep working exactly as today. 3. Easy, mechanical migration of existing pages; old pages keep running until migrated. 4. A path to *enforcing* it, so new unsafe queries can't be written by accident. Non-goals: an ORM, query builders, or changing ``/`` connection handling. ## 3. Proposed syntax Placeholders are `?` in the query; values come from `` tags inside the ``, in order: ```html select id, name from users where email=? and status=? ``` `` attributes: | attribute | meaning | |---|---| | `value` | the value (any Jet expression - `$[...]` is fine here, that's the point) | | `type` | `string` (default), `int`, `decimal`, `bool`, `date`, `datetime`, `ident` | | `null` | `empty` = bind SQL `NULL` when the value is empty (default: bind `''`) | | `allow` | for `type="ident"` only: comma list of permitted identifiers | Type behaviour (a value that doesn't fit throws a catchable Jet exception - ``/`` works, see §6): - `string` - quoted and escaped (§4). - `int` - must match `^-?[0-9]{1,19}$`; emitted bare. This fixes the unquoted `where id=$[id]` case. - `decimal` - must match `^-?[0-9]{1,30}(\.[0-9]{1,30})?$`; emitted bare. - `bool` - `1/0/true/false/yes/no` → `1`/`0`. - `date` / `datetime` - must parse as `YYYY-MM-DD` / `YYYY-MM-DD HH:MM[:SS]`; quoted. - `ident` - for the things SQL can't parameterise (column in `ORDER BY`, a sort direction, a table name). The value must be in `allow` or it throws; emitted backtick-quoted (`ASC`/`DESC` emitted bare). Example: ```html select * from products order by ? ? ``` Why `` and not ``: `param` is an HTML element (inside ``), and `jetc`'s void-tag list treats it as HTML. A Jet-only name avoids any ambiguity. Why positional `?` and not named (`:email`): `?` is what MySQL and every SQL library uses, it needs no new attribute-name syntax in the parser, and the `` lines sit right under the query so the order is easy to read. Named binds can be added later without breaking this (§9). ## 4. How it works ### Emulated binding (recommended for phase 1) `__sql` collects the `` values while its body renders, then replaces each `?` that is **outside** a string literal, backtick identifier or comment with the bound value, rendered safely - and only then calls `query()` as today. - Strings are escaped with `mysql_real_escape_string_quote(mysql, to, from, len, '\'')` and wrapped in single quotes. This uses the *connection's* character set and respects `NO_BACKSLASH_ESCAPES`, which plain `mysql_real_escape_string` doesn't. - The connection's character set is pinned at connect time (`mysql_options(MYSQL_SET_CHARSET_NAME, "utf8mb4")` in `__mysql`), so escaping and server parsing always agree. `` refuses a `SET NAMES`/`SET CHARACTER SET` statement (the classic way to make escaping and parsing disagree). - Number of `?` must equal number of ``s, otherwise throw `"sql: 3 placeholders but 2 bind values"`. This is the same approach PHP's PDO uses by default. Its big advantage here: **the result path doesn't change at all** - `query()` still runs `mysql_real_query` and `mysql_store_result`, so `MYSQL_ROW`, `getColumnValue()`, ``, `` and the column-index map are untouched. ### Why not real server-side prepared statements (yet) `mysql_stmt_*` returns rows through typed bind buffers, not `MYSQL_ROW`, so `getColumnValue()`, `$[?N]`, `$[#]` and the field-index map would all need a second implementation, and some statements (multi-statements, some DDL) can't be prepared. That's a bigger change for no extra safety over correct emulation. It stays open as a later option (§9), behind the same `` syntax, so pages written now won't need touching again. ### Code shape - **New** `__bind.h/.cpp`: on construction, find the nearest enclosing `__sql` (walk `parent` with `dynamic_cast<__sql*>`; throw `"bind must be inside sql"` if none), resolve `value`/`type`/`null`/`allow`, validate per type, and call `sql->addBind(...)`. Produces no output. - **`__sql`**: a `std::vector` member and `addBind()`. After `processContainer(container)`, run `bindPlaceholders(out)` - a small scanner that tracks `'...'` (with `''` and `\'`), `"..."`, `` `...` ``, `-- `, `#` and `/* */` so `?` inside them is left alone - then `query(result)`. - **`__mysql`**: `escapeString(const MString&)` wrapper around `mysql_real_escape_string_quote`; pin `utf8mb4` at connect. - **`Tag.cpp`**: add `ifTagName(in, "bind")` next to `sql` (line ~494). - **`jetc` `JetParser.cpp`**: add `"bind"` to the Jet void-tag list (it has no closing tag); **`JetCodegen.cpp`**: emit `__bind` like the other tags. Estimated size: ~200 lines plus tests. ## 5. Existing pages: nothing breaks A `` with no `` runs exactly as today - no `?` replacement at all, so existing queries containing a literal `?` are unaffected. Migration is page by page: ```html select * from users where email="$[email]" and status="CONFIRM" select * from users where email=? and status="CONFIRM" delete from cart_item where session_uuid='$[_session_id]' and sku='$[sku]' delete from cart_item where session_uuid=? and sku=? ``` ## 6. Errors - Bad `` value (wrong type, ident not allowed), placeholder/bind count mismatch, `` outside ``: throw `coreutils::Exception` with a clear message, caught by ``/`` like the MySQL errors fixed on 2026-09-13. - The exception text never includes the bound value itself (it may be a password). ## 7. Enforcement Once pages are migrated, make the unsafe form an error instead of a habit: 1. **`jetc --lint-sql`** - lists every `` whose body contains `$[...]` other than `$[.column]` (row values from an outer query), with file:line. This is the migration worklist (§8) and a CI check. As implemented (`jetc/JetLint.cpp`): `jetc --lint-sql [--strict] ...` scans every file under the given paths. It reports `$[...]` and local `#[...]` references, with the kind of each (`global`, `cgi`, `session`, `env`, `keyword`, `local`). Row values (`$[.col]`, `$[session.col]`, `$[?N]`, `$[#]`, `$[?#]`) are not reported unless `--strict` is given. References in the attributes of ``, ``, ``, ``, ``, ``, ``, `` and `` are not reported, since those never become statement text; nor is anything inside `` or `|> <|`. A custom tag defined as `` (barant.com's ``) takes its statement from the caller's content, so each use of it is checked like an ``. Exit status: 0 nothing found, 1 findings, 2 a path could not be read. Tests: `tests/runlinttests.sh`. 2. **Per-site strict mode** - an APIServer site setting `"sqlInterpolation": "warn" | "error"`. In `error` mode `` refuses to run if its body substituted any `$[...]` except `$[.column]`; `warn` logs it. Default `warn` for existing sites, `error` for new ones. 3. **Escape hatch** - `` for the rare trusted dynamic SQL (generated by the site itself, never from input), so it's visible in review and greppable. ## 8. Migration plan | Phase | What | Notes | |---|---|---| | 1 | Implement ``, escaping, utf8mb4 pinning, tests | JetCore only; no page changes. Done 2026-11-20 | | 2 | `jetc --lint-sql`; run on both sites | produces the worklist (≈200 queries). Done 2026-11-20 on the local copies: see [sql-lint-worklist.md](sql-lint-worklist.md) | | 3 | Convert the high-risk pages first | login/signup/password reset, cart/checkout/payment (`pp.jet`), admin procs, ClockPlanet `mobile_api.jet` and auth | | 4 | Convert the rest; turn on `warn` | logs show anything missed | | 5 | Switch both sites to `error` | unsafe queries can no longer ship | Phase 3 is the one that matters most for security and is a few days' work; each conversion is mechanical and testable page by page. ## 9. Later - Named binds: `where email=:email` + ``. - Real prepared statements (`mysql_stmt_*`) behind the same `` syntax. - The companion fix for output: HTML-escape `$[...]` by default with an explicit raw form - the same "safe unless you say otherwise" rule for the other half of the injection problem (cross-site scripting). ## 10. Tests - Every type: valid values bind correctly; invalid values throw. - Injection strings (`' or '1'='1`, `\'`, multibyte sequences such as `0xbf27`, `--`, `;`, NUL bytes) are stored and read back byte-for-byte unchanged. - `?` inside `'...'`, `"..."`, `` `...` ``, `--`, `#` and `/* */` is never replaced. - Placeholder/bind count mismatch throws; `` outside `` throws. - A `` with no binds produces exactly the same query text as before. - ``/``/`$[.col]`/`$[?N]`/`$[#]` behave identically on bound queries. - `NO_BACKSLASH_ESCAPES` on and off.