Add <bind> bound parameters for <sql> (phase 1)

Implements phase 1 of docs/design-sql-bound-parameters.md: <bind> supplies
the value for the next ? placeholder of the enclosing <sql>, with typed
validation (int, decimal, date, datetime, bool, ident with allow list),
null="empty", and refusal to change the connection character set.

- SqlBind.*: MySQL-free placeholder scanning and binding logic
- __bind.*, __sql, __mysql: runtime wiring
- Tag.cpp, jetc/JetParser.cpp: bind is a void tag in both
- jetc/JetCodegen: emit sized ZString literals for text holding a NUL,
  which previously truncated the compiled page
- tests: unit tests, end-to-end test against MySQL (interpreted and
  jetc-compiled), and the generator for the binary test page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
brad ArantandClaude Opus 5.5 committed 2026-11-20 19:55:23 -08:00
1 parent 9fae14eb96
commit a18d1358b0
18 files changed
+1103 -9

No files matched your search

+225
View File
@@ -0,0 +1,225 @@
# Design: bound parameters for `<sql>`
**Status:** draft for review · **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
`<sql>` 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
<sql>select id from users where email='$[email]' and secret='$[password]'</sql>
```
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 (`<sql>` blocks whose body contains a request/session
value other than `$[.column]`, `$[_login_id]` or `$[_session_id]`):
| Site | `<sql>` 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 `<sql>` that **can never change the query's meaning**,
whatever they contain.
2. **No change to how results are read** - `<ifrow>`, `<whilerow>`, `$[.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 `<database>`/`<mysql>` connection handling.
## 3. Proposed syntax
Placeholders are `?` in the query; values come from `<bind>` tags inside the
`<sql>`, in order:
```html
<sql>
select id, name from users where email=? and status=?
<bind value="$[email]">
<bind value="ACTIVE">
</sql>
```
`<bind>` 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 -
`<try>`/`<catch>` 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
<sql>select * from products order by ? ?
<bind value="$[sort]" type="ident" allow="name,price,created">
<bind value="$[dir]" type="ident" allow="ASC,DESC">
</sql>
```
Why `<bind>` and not `<param>`: `param` is an HTML element (inside `<object>`),
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
`<bind>` 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 `<bind>` 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. `<sql>` refuses a `SET NAMES`/`SET CHARACTER SET`
statement (the classic way to make escaping and parsing disagree).
- Number of `?` must equal number of `<bind>`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()`,
`<ifrow>`, `<whilerow>` 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 `<bind>` 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<BoundValue>` 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 `<sql>` with no `<bind>` runs exactly as today - no `?` replacement at all,
so existing queries containing a literal `?` are unaffected. Migration is
page by page:
```html
<!-- before -->
<sql>select * from users where email="$[email]" and status="CONFIRM"</sql>
<!-- after -->
<sql>select * from users where email=? and status="CONFIRM"
<bind value="$[email]">
</sql>
<!-- before: unquoted number, injectable even with escaping -->
<sql>delete from cart_item where session_uuid='$[_session_id]' and sku='$[sku]'</sql>
<!-- after -->
<sql>delete from cart_item where session_uuid=? and sku=?
<bind value="$[_session_id]">
<bind value="$[sku]">
</sql>
```
## 6. Errors
- Bad `<bind>` value (wrong type, ident not allowed), placeholder/bind count
mismatch, `<bind>` outside `<sql>`: throw `coreutils::Exception` with a clear
message, caught by `<try>`/`<catch>` 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 `<sql>` 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.
2. **Per-site strict mode** - an APIServer site setting
`"sqlInterpolation": "warn" | "error"`. In `error` mode `<sql>` 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** - `<sql raw="yes">` 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 `<bind>`, escaping, utf8mb4 pinning, tests | JetCore only; no page changes |
| 2 | `jetc --lint-sql`; run on both sites | produces the worklist (≈200 queries) |
| 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` + `<bind name="email" value="...">`.
- Real prepared statements (`mysql_stmt_*`) behind the same `<bind>` 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; `<bind>` outside `<sql>` throws.
- A `<sql>` with no binds produces exactly the same query text as before.
- `<ifrow>`/`<whilerow>`/`$[.col]`/`$[?N]`/`$[#]` behave identically on bound queries.
- `NO_BACKSLASH_ESCAPES` on and off.