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>
226 lines
9.8 KiB
Markdown
226 lines
9.8 KiB
Markdown
# 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.
|