Implements phase 2 of docs/design-sql-bound-parameters.md. jetc --lint-sql [--strict] <file|dir>... lists each <sql> whose statement contains a $[...] or #[...] reference instead of a <bind>, with file:line and where each value comes from. Row values ($[.col], $[session.col], $[?N], $[#]) are only reported with --strict. References in <bind>, <if>, <set> and the other attribute-only tags, <comment> and |> <| are skipped. A custom tag defined as <sql><container></sql> (barant.com's <showtable>) is checked at each use. Exit status is 0 for none found, 1 for findings, 2 for an unreadable path. - jetc/JetLint.*: the scanner; jetc.cpp: the option - build scripts and runbindtests.sh: link JetLint.cpp - tests/runlinttests.sh and tests/lintsql/: fixtures and expected output - docs: worklist for the local copies of both sites, design doc status, manual note on the lint Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
Design: bound parameters for <sql>
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
<sql> builds its query by rendering its body as text, then sending the finished
string to MySQL:
// __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:
<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
- A way to pass values to
<sql>that can never change the query's meaning, whatever they contain. - No change to how results are read -
<ifrow>,<whilerow>,$[.column],$[?N],$[#]keep working exactly as today. - Easy, mechanical migration of existing pages; old pages keep running until migrated.
- 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:
<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 unquotedwhere 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 asYYYY-MM-DD/YYYY-MM-DD HH:MM[:SS]; quoted. -
ident- for the things SQL can't parameterise (column inORDER BY, a sort direction, a table name). The value must be inallowor it throws; emitted backtick-quoted (ASC/DESCemitted bare). Example:<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 respectsNO_BACKSLASH_ESCAPES, which plainmysql_real_escape_stringdoesn'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 aSET NAMES/SET CHARACTER SETstatement (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(walkparentwithdynamic_cast<__sql*>; throw"bind must be inside sql"if none), resolvevalue/type/null/allow, validate per type, and callsql->addBind(...). Produces no output. __sql: astd::vector<BoundValue>member andaddBind(). AfterprocessContainer(container), runbindPlaceholders(out)- a small scanner that tracks'...'(with''and\'),"...",`...`,--,#and/* */so?inside them is left alone - thenquery(result).__mysql:escapeString(const MString&)wrapper aroundmysql_real_escape_string_quote; pinutf8mb4at connect.Tag.cpp: addifTagName(in, "bind")next tosql(line ~494).jetcJetParser.cpp: add"bind"to the Jet void-tag list (it has no closing tag);JetCodegen.cpp: emit__bindlike 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:
<!-- 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>: throwcoreutils::Exceptionwith 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:
-
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.As implemented (
jetc/JetLint.cpp):jetc --lint-sql [--strict] <file|dir>...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--strictis given. References in the attributes of<bind>,<if>,<else>,<ifrow>,<while>,<whilerow>,<until>,<for>and<set>are not reported, since those never become statement text; nor is anything inside<comment>or|> <|. A custom tag defined as<sql ...><container></sql>(barant.com's<showtable>) takes its statement from the caller's content, so each use of it is checked like an<sql>. Exit status: 0 nothing found, 1 findings, 2 a path could not be read. Tests:tests/runlinttests.sh. -
Per-site strict mode - an APIServer site setting
"sqlInterpolation": "warn" | "error". Inerrormode<sql>refuses to run if its body substituted any$[...]except$[.column];warnlogs it. Defaultwarnfor existing sites,errorfor new ones. -
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. 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 |
| 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 as0xbf27,--,;, 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_ESCAPESon and off.