Skip to content

Commit ae02599

Browse files
authored
Merge pull request #1 from sqliteai/fix/correctness-and-hardening-0.2.0
fix: correctness and hardening fixes, release 0.2.0
2 parents f91aa32 + 02f9229 commit ae02599

12 files changed

Lines changed: 3174 additions & 310 deletions

File tree

‎.github/workflows/flutter-package.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ jobs:
1515

1616
steps:
1717

18-
- uses: actions/checkout@v4.2.2
18+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
1919

2020
- name: download release assets
2121
run: |
@@ -40,7 +40,7 @@ jobs:
4040
env:
4141
GH_TOKEN: ${{ github.token }}
4242

43-
- uses: dart-lang/setup-dart@v1.7.1
43+
- uses: dart-lang/setup-dart@e51d8e571e22473a2ddebf0ef8a2123f0ab2c02c # v1.7.1
4444

4545
- name: assemble and publish flutter package
4646
run: |

‎.github/workflows/main.yml‎

Lines changed: 87 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,15 @@ on:
1414
- '**'
1515
workflow_dispatch:
1616

17+
# Least privilege by default; the release job widens it for itself. Previously
18+
# `contents: write` applied to all 16 build jobs, which run third-party actions.
1719
permissions:
18-
contents: write
19-
id-token: write
20+
contents: read
2021

2122
jobs:
2223
build:
24+
permissions:
25+
contents: read
2326
if: ${{ !contains(github.event.head_commit.message, '[auto-update]') }}
2427
runs-on: ${{ matrix.os }}
2528
container: ${{ matrix.container && matrix.container || '' }}
@@ -89,6 +92,7 @@ jobs:
8992
name: android
9093
make: PLATFORM=android ARCH=x86_64
9194
sqlite-amalgamation-zip: https://sqlite.org/2025/sqlite-amalgamation-3490100.zip
95+
sqlite-amalgamation-sha256: 6cebd1d8403fc58c30e93939b246f3e6e58d0765a5cd50546f16c00fd805d2c3
9296

9397
# iOS device
9498
- os: macos-15
@@ -120,13 +124,13 @@ jobs:
120124
if: contains(matrix.name, 'linux-musl') && matrix.arch == 'x86_64'
121125
run: apk update && apk add --no-cache git gcc make sqlite musl-dev linux-headers bash
122126

123-
- uses: actions/checkout@v4.2.2
127+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
124128
with:
125129
submodules: recursive
126130

127131
- name: android setup java
128132
if: matrix.name == 'android-aar'
129-
uses: actions/setup-java@v4
133+
uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4.9.1
130134
with:
131135
distribution: 'temurin'
132136
java-version: '17'
@@ -153,38 +157,61 @@ jobs:
153157
- name: build sqlite-agent
154158
run: ${{ matrix.name == 'linux-musl' && matrix.arch == 'arm64' && 'docker exec alpine' || '' }} make extension ${{ matrix.make && matrix.make || ''}}
155159

160+
# Signing runs only on main, which is the only ref that can release
161+
# (see the `release` job). Without the ref check these steps ran on every
162+
# branch push, so anyone able to push a branch could edit this workflow
163+
# and read the Apple signing secrets.
164+
# Secrets go through `env` rather than being interpolated into the script
165+
# body: an inline secrets expression is expanded into the shell text,
166+
# where a value containing a command substitution or a backtick would be
167+
# executed, and passing passwords as argv makes them visible to other
168+
# processes on the runner.
156169
- name: create keychain for codesign
157-
if: matrix.os == 'macos-15'
170+
if: matrix.os == 'macos-15' && github.ref == 'refs/heads/main'
171+
env:
172+
APPLE_CERTIFICATE: ${{ secrets.APPLE_CERTIFICATE }}
173+
KEYCHAIN_PASSWORD: ${{ secrets.KEYCHAIN_PASSWORD }}
174+
CERTIFICATE_PASSWORD: ${{ secrets.CERTIFICATE_PASSWORD }}
158175
run: |
159-
echo "${{ secrets.APPLE_CERTIFICATE }}" | base64 --decode > certificate.p12
160-
security create-keychain -p "${{ secrets.KEYCHAIN_PASSWORD }}" build.keychain
176+
printf '%s' "$APPLE_CERTIFICATE" | base64 --decode > certificate.p12
177+
security create-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
161178
security default-keychain -s build.keychain
162-
security unlock-keychain -p "${{ secrets.KEYCHAIN_PASSWORD }}" build.keychain
163-
security import certificate.p12 -k build.keychain -P "${{ secrets.CERTIFICATE_PASSWORD }}" -T /usr/bin/codesign
164-
security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "${{ secrets.KEYCHAIN_PASSWORD }}" build.keychain
179+
security unlock-keychain -p "$KEYCHAIN_PASSWORD" build.keychain
180+
security import certificate.p12 -k build.keychain -P "$CERTIFICATE_PASSWORD" -T /usr/bin/codesign
181+
security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" build.keychain
165182
166183
- name: codesign and notarize dylib
167-
if: matrix.os == 'macos-15' && matrix.name != 'apple-xcframework'
184+
if: matrix.os == 'macos-15' && matrix.name != 'apple-xcframework' && github.ref == 'refs/heads/main'
185+
env:
186+
APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
187+
APPLE_ID: ${{ secrets.APPLE_ID }}
188+
APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
168189
run: |
169-
codesign --sign "${{ secrets.APPLE_TEAM_ID }}" --timestamp --options runtime dist/agent.dylib
190+
codesign --sign "$APPLE_TEAM_ID" --timestamp --options runtime dist/agent.dylib
170191
ditto -c -k dist/agent.dylib dist/agent.zip
171-
xcrun notarytool submit dist/agent.zip --apple-id "${{ secrets.APPLE_ID }}" --password "${{ secrets.APPLE_PASSWORD }}" --team-id "${{ secrets.APPLE_TEAM_ID }}" --wait
192+
xcrun notarytool submit dist/agent.zip --apple-id "$APPLE_ID" --password "$APPLE_PASSWORD" --team-id "$APPLE_TEAM_ID" --wait
172193
rm dist/agent.zip
173194
174195
- name: codesign and notarize xcframework
175-
if: matrix.name == 'apple-xcframework'
196+
if: matrix.name == 'apple-xcframework' && github.ref == 'refs/heads/main'
197+
env:
198+
APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
199+
APPLE_ID: ${{ secrets.APPLE_ID }}
200+
APPLE_PASSWORD: ${{ secrets.APPLE_PASSWORD }}
176201
run: |
177-
find dist/agent.xcframework -name "*.framework" -exec echo "Signing: {}" \; -exec codesign --sign "${{ secrets.APPLE_TEAM_ID }}" --timestamp --options runtime {} \;
178-
codesign --sign "${{ secrets.APPLE_TEAM_ID }}" --timestamp --options runtime dist/agent.xcframework
202+
find dist/agent.xcframework -name "*.framework" -exec echo "Signing: {}" \; -exec codesign --sign "$APPLE_TEAM_ID" --timestamp --options runtime {} \;
203+
codesign --sign "$APPLE_TEAM_ID" --timestamp --options runtime dist/agent.xcframework
179204
ditto -c -k --keepParent dist/agent.xcframework dist/agent.xcframework.zip
180-
xcrun notarytool submit dist/agent.xcframework.zip --apple-id "${{ secrets.APPLE_ID }}" --password "${{ secrets.APPLE_PASSWORD }}" --team-id "${{ secrets.APPLE_TEAM_ID }}" --wait
205+
xcrun notarytool submit dist/agent.xcframework.zip --apple-id "$APPLE_ID" --password "$APPLE_PASSWORD" --team-id "$APPLE_TEAM_ID" --wait
181206
rm -rf dist/agent.xcframework
182207
208+
# always(), so a failure in the steps above cannot leave the decoded
209+
# certificate on disk or the keychain unlocked.
183210
- name: cleanup keychain for codesign
184-
if: matrix.os == 'macos-15'
211+
if: always() && matrix.os == 'macos-15' && github.ref == 'refs/heads/main'
185212
run: |
186-
rm certificate.p12
187-
security delete-keychain build.keychain
213+
rm -f certificate.p12
214+
security delete-keychain build.keychain || true
188215
189216
- name: android setup test environment
190217
if: matrix.name == 'android' && matrix.arch != 'arm64-v8a' && matrix.arch != 'armeabi-v7a'
@@ -197,7 +224,11 @@ jobs:
197224
echo "::endgroup::"
198225
199226
echo "::group::download and build sqlite3 without SQLITE_OMIT_LOAD_EXTENSION"
200-
curl -O ${{ matrix.sqlite-amalgamation-zip }}
227+
# The archive is compiled and then executed, so its integrity is
228+
# pinned rather than trusted to the transport alone. Update both the
229+
# URL and this hash together when moving to a new amalgamation.
230+
curl --fail --location --show-error --silent -O ${{ matrix.sqlite-amalgamation-zip }}
231+
echo "${{ matrix.sqlite-amalgamation-sha256 }} $(basename ${{ matrix.sqlite-amalgamation-zip }})" | sha256sum -c -
201232
unzip sqlite-amalgamation-*.zip
202233
export ${{ matrix.make }}
203234
$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/${{ matrix.arch }}-linux-android26-clang sqlite-amalgamation-*/shell.c sqlite-amalgamation-*/sqlite3.c -o sqlite3 -ldl
@@ -216,7 +247,7 @@ jobs:
216247
217248
- name: android test sqlite-agent
218249
if: matrix.name == 'android' && matrix.arch != 'arm64-v8a' && matrix.arch != 'armeabi-v7a'
219-
uses: reactivecircus/android-emulator-runner@v2.34.0
250+
uses: reactivecircus/android-emulator-runner@1dcd0090116d15e7c562f8db72807de5e036a4ed # v2.34.0
220251
with:
221252
api-level: 26
222253
arch: ${{ matrix.arch }}
@@ -230,7 +261,7 @@ jobs:
230261
if: contains(matrix.name, 'linux') || matrix.name == 'windows' || ( matrix.name == 'macos' && matrix.arch != 'x86_64' )
231262
run: ${{ matrix.name == 'linux-musl' && matrix.arch == 'arm64' && 'docker exec alpine' || '' }} make test ${{ matrix.make && matrix.make || ''}}
232263

233-
- uses: actions/upload-artifact@v4.6.2
264+
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
234265
if: always()
235266
with:
236267
name: agent-${{ matrix.name }}${{ matrix.arch && format('-{0}', matrix.arch) || '' }}
@@ -243,14 +274,20 @@ jobs:
243274
needs: build
244275
if: github.ref == 'refs/heads/main'
245276

277+
# contents: write to push the Package.swift checksum commit;
278+
# id-token: write for npm publish --provenance.
279+
permissions:
280+
contents: write
281+
id-token: write
282+
246283
env:
247284
GH_TOKEN: ${{ github.token }}
248285

249286
steps:
250287

251-
- uses: actions/checkout@v4.2.2
288+
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
252289

253-
- uses: actions/download-artifact@v4.2.1
290+
- uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4.2.1
254291
with:
255292
path: artifacts
256293

@@ -280,8 +317,9 @@ jobs:
280317
run: |
281318
VERSION=$(make version)
282319
if [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
283-
LATEST_RELEASE=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" https://api.github.com/repos/${{ github.repository }}/releases/latest)
284-
LATEST=$(echo "$LATEST_RELEASE" | jq -r '.name')
320+
# gh reads the token from GH_TOKEN in the job env, so it never
321+
# appears on a command line other processes can read.
322+
LATEST=$(gh api "repos/$GITHUB_REPOSITORY/releases/latest" --jq '.name' 2>/dev/null || echo "")
285323
286324
if [[ "$VERSION" != "$LATEST" || "$GITHUB_EVENT_NAME" == "workflow_dispatch" ]]; then
287325
echo "version=$VERSION" >> $GITHUB_OUTPUT
@@ -293,17 +331,26 @@ jobs:
293331
echo "❌ SQLITE_AGENT_VERSION not found in sqlite-agent.h"
294332
exit 1
295333
296-
- uses: actions/setup-java@v4
334+
- uses: actions/setup-java@cf277c60eb25467037889841efdb72551f06f6c3 # v4.9.1
297335
if: steps.tag.outputs.version != ''
298336
with:
299337
distribution: 'temurin'
300338
java-version: '17'
301339

340+
# The signing key and Sonatype credentials arrive as ORG_GRADLE_PROJECT_*
341+
# env vars, which Gradle exposes as the same project properties that
342+
# build.gradle reads. Passing them as -P put them in the process's argv,
343+
# where any other process on the runner could read them.
302344
- name: release android aar to maven central
303345
if: steps.tag.outputs.version != ''
304-
run: cd packages/android && ./gradlew publishAggregationToCentralPortal -PSIGNING_KEY="${{ secrets.SIGNING_KEY }}" -PSIGNING_PASSWORD="${{ secrets.SIGNING_PASSWORD }}" -PSONATYPE_USERNAME="${{ secrets.MAVEN_CENTRAL_USERNAME }}" -PSONATYPE_PASSWORD="${{ secrets.MAVEN_CENTRAL_TOKEN }}" -PVERSION="${{ steps.tag.outputs.version }}" -PAAR_PATH="../../artifacts/agent-android-aar/agent.aar"
305-
306-
- uses: actions/setup-node@v4
346+
env:
347+
ORG_GRADLE_PROJECT_SIGNING_KEY: ${{ secrets.SIGNING_KEY }}
348+
ORG_GRADLE_PROJECT_SIGNING_PASSWORD: ${{ secrets.SIGNING_PASSWORD }}
349+
ORG_GRADLE_PROJECT_SONATYPE_USERNAME: ${{ secrets.MAVEN_CENTRAL_USERNAME }}
350+
ORG_GRADLE_PROJECT_SONATYPE_PASSWORD: ${{ secrets.MAVEN_CENTRAL_TOKEN }}
351+
run: cd packages/android && ./gradlew publishAggregationToCentralPortal -PVERSION="${{ steps.tag.outputs.version }}" -PAAR_PATH="../../artifacts/agent-android-aar/agent.aar"
352+
353+
- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
307354
if: steps.tag.outputs.version != ''
308355
with:
309356
node-version: '24'
@@ -330,7 +377,14 @@ jobs:
330377
echo "✓ Generated platform packages"
331378
ls -la platform-packages/
332379
333-
# Build main package
380+
# Build main package.
381+
# `npm install` rather than `npm ci`: the optionalDependencies are
382+
# this project's own platform packages at the version being released,
383+
# which by definition are not on the registry yet and so cannot be in
384+
# the lock file. With package-lock.json committed, npm install still
385+
# installs the locked toolchain versions — that is what pins the
386+
# build — and only the optional platform packages are left to fail,
387+
# which is expected here.
334388
echo "Building main package..."
335389
npm install
336390
npm run build
@@ -378,7 +432,7 @@ jobs:
378432
git push origin main || true
379433
fi
380434
381-
- uses: softprops/action-gh-release@v2.2.1
435+
- uses: softprops/action-gh-release@c95fe1489396fe8a9eb87c0abf8aa5b2ef267fda # v2.2.1
382436
if: steps.tag.outputs.version != ''
383437
with:
384438
token: ${{ secrets.RELEASE_PAT }}

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,9 @@ jniLibs/
2828

2929
# Node.js
3030
node_modules/
31-
package-lock.json
31+
# package-lock.json IS tracked on purpose: it pins the build toolchain
32+
# (tsup/esbuild/typescript) that produces the published bundle, so a
33+
# compromised transitive dependency cannot slip into a release unnoticed.
3234
*.tsbuildinfo
3335
coverage/
3436
*.log

‎API.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,55 @@ SELECT agent_run(
114114

115115
---
116116

117+
## Security model
118+
119+
`agent_run()` hands control of what happens next to a language model, so it is
120+
worth being explicit about what is trusted and what is not.
121+
122+
**What is trusted:** the SQL you issue yourself — the goal, the target table and
123+
any custom system prompt — and the MCP server you chose in `mcp_connect()`.
124+
125+
**What is not trusted:** everything that comes back from that server. Tool
126+
names, descriptions and input schemas, and above all tool *results*, which may
127+
contain whatever the tool fetched: a web page, a file, an API response. All of
128+
it is quoted into the model's prompt.
129+
130+
Two controls apply:
131+
132+
- **Untrusted text is fenced.** Each `agent_run()` call mints a random
133+
delimiter and wraps every block of server-supplied text in it, instructing the
134+
model to treat the contents as data. Because the delimiter is unpredictable,
135+
injected text cannot close the fence and escape into the instruction region.
136+
- **Tools are restricted to those advertised.** A tool the model asks for is
137+
invoked only if it appeared in `mcp_list_tools_respond`. Text telling the
138+
model to "call tool X" cannot reach a tool the server never offered.
139+
140+
**What these controls do not do.** They do not protect you from a malicious MCP
141+
server: a server you connect to can advertise any tool it likes, and the agent
142+
will use it. Choosing which server to connect to is your trust decision. They
143+
also do not make the model's judgement reliable — a sufficiently persuasive
144+
injected instruction may still get the agent to call an advertised tool with
145+
arguments you would not have chosen. Treat an agent connected to an untrusted
146+
server, or to tools that read untrusted content, as semi-trusted: give the MCP
147+
server the narrowest credentials that still do the job, and prefer read-only
148+
tools where the server supports it.
149+
150+
**`agent_run()` is marked `SQLITE_DIRECTONLY`.** It can only be called from SQL
151+
your application issues directly — never from a VIEW, TRIGGER, CHECK
152+
constraint, generated column or index expression. This matters because the
153+
function makes network calls and writes rows: without the restriction, merely
154+
querying a table in a database file somebody else prepared could trigger those
155+
side effects on your behalf. If you need the result in a view, materialise it
156+
into a table first.
157+
158+
Finally, `max_iterations` bounds how many LLM and tool round trips a single call
159+
can make. It is your cost and runtime ceiling, so set it deliberately. Values
160+
below 1 or above 100 are rejected; the hard cap keeps one SQL statement from
161+
spending an unbounded amount of time and money against the LLM and the MCP
162+
server.
163+
164+
---
165+
117166
## Error Handling
118167

119168
**Common Errors:**
@@ -127,6 +176,17 @@ SELECT agent_run('Find apartments', 5);
127176
SELECT agent_run('Find apartments', 'nonexistent', 5);
128177
-- Error: Table does not exist or has no columns
129178

179+
-- max_iterations must be between 1 and 100
180+
SELECT agent_run('Find apartments', 'listings', 0);
181+
-- Error: max_iterations must be >= 1
182+
SELECT agent_run('Find apartments', 'listings', 500);
183+
-- Error: max_iterations must be <= 100
184+
185+
-- Called from a VIEW or TRIGGER rather than directly
186+
CREATE VIEW v AS SELECT agent_run('Find apartments', 5);
187+
SELECT * FROM v;
188+
-- Error: unsafe use of agent_run()
189+
130190
-- LLM not loaded (table mode)
131191
SELECT agent_run('Find apartments', 'listings', 5);
132192
-- Error: Failed to create LLM chat context

0 commit comments

Comments
 (0)