feat(federation): env-gated unsigned DuckDB extensions (+ Firebird proposal)

[tobias-gp]

Summary

• Implemented: Adds an opt-in DUCKDB_ALLOW_UNSIGNED_EXTENSIONS env var (default off). When enabled, project DuckDB instances are created with allow_unsigned_extensions, and the federation console accepts INSTALL <extension> FROM '<source>' for custom repositories/paths. When unset, behavior is identical to today (signed core + FROM community only).
• Proposal only (no code): Includes the OpenSpec change add-firebird-connection-type, which proposes an env-gated firebird connection type built on top of the unsigned-extensions gate. This is design/spec docs for review, not implemented in this PR.

What changed (implemented)

• packages/core/src/config/env.ts — DUCKDB_ALLOW_UNSIGNED_EXTENSIONS + allowUnsignedExtensions() helper.
• packages/core/src/services/duckdb.ts — createDuckDBInstance() applies allow_unsigned_extensions at instance creation (the option can only be set at startup); all three creation sites route through it. fromSource threaded through ensureProjectExtensionLoaded → installAndLoadExtension, emitting INSTALL <ext> FROM '<source>' (single-quote-escaped).
• packages/core/src/services/duckdb-console.ts — parseExtensionSql(sql, allowUnsigned) matches the env-gated FROM '<source>' shape; rejected with the existing 400 message when the flag is off.
• Docs: .env.example and a new "Data Federation (DuckDB)" table in apps/docs/.../reference/docker.mdx, both with a security caution that unsigned extensions run arbitrary native code.
• OpenSpec: add-unsigned-duckdb-extensions (proposal/design/tasks/specs, all tasks checked off).

Test plan

• npx vitest run packages/core/src/services/duckdb-console.test.ts — 16/16 pass (5 new cases for the gated parser)
• pnpm typecheck exits 0
• pnpm lint exits 0
• pnpm --filter @archmax/api build exits 0 (runs as part of typecheck)
• Manual: with DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true, INSTALL <ext> FROM '<repo>' loads from the console; with it unset, the same statement is rejected with 400

Notes

• The add-firebird-connection-type proposal has an open question (exact ATTACH DSN for the custom duckdb_firebird extension) to resolve during its own implementation PR. It is intentionally not implemented here.

Made with Cursor

---

Note

High Risk
Enabling the flag loads unsigned native code and turns on allow_unsigned_extensions for all DuckDB instances; misconfiguration or a compromised extension repo is a serious security concern despite API/console restrictions.

Overview
Adds an opt-in, default-off firebird data source backed by a custom unsigned DuckDB extension, gated by DUCKDB_ENABLE_CUSTOM_FIREBIRD (not a general unsigned-extensions flag).

When enabled, project DuckDB instances are created with allow_unsigned_extensions, the Firebird extension is auto-installed from a fixed archmax-hosted repo (SET custom_extension_repository + INSTALL/LOAD firebird), and connections attach via TYPE FIREBIRD with structured fields passed as ATTACH options (empty path + HOST/PORT/DATABASE/etc.) to avoid Windows-path / URI parsing bugs. When disabled, create/update/test for Firebird return 400, active Firebird connections are skipped during federation (without breaking other sources), and the federation console still rejects INSTALL … FROM '<arbitrary source>'.

API & UI: firebird on the connection model, optional charset in config, /api/config exposes firebirdEnabled, and the connections form shows Firebird only when the flag is on (defaults port 3050, charset UTF8).

Docs & specs: .env.example, Docker reference, data-federation guide, OpenSpec change add-firebird-connection-type, plus integration/unit tests for gates and attach building.

^{Reviewed by Cursor Bugbot for commit dc5a205. Bugbot is set up for automated code reviews on this repo. Configure here.}

[railway-app]

🚅 Deployed to the archmax-pr-67 environment in archmax SemLayer

Service	Status	Web	Updated (UTC)
archmax_standalone_with_volume	✅ Success (View Logs)		Jun 5, 2026 at 9:13 am
archmax_standalone	✅ Success (View Logs)		Jun 5, 2026 at 9:13 am
archmax_external_dbs	✅ Success (View Logs)		Jun 5, 2026 at 9:13 am

[cursor]

Security review complete: I did not find concrete issues in the changed files.

Checked threat surfaces:

• MCP endpoint auth: apps/api/src/mcp/archmax-route.ts authenticates the bearer token and resolves the project before registering/running tools, re-authenticates resumed sessions against the original token/project/slug, and returns JSON-RPC auth errors for invalid credentials. Token scopes flow into registerArchmaxTools and are enforced by the MCP tool handlers.
• Query execution sandboxing: packages/core/src/services/mcp-tools.ts validates SQL with validateSqlAst before acquiring the project DuckDB instance, materializes scoped model VIEWs, hardens the connection/search path, enforces withQueryTimeout, and truncates results at MAX_ROWS. The new unsigned-extension flag in packages/core/src/services/duckdb.ts does not relax the MCP validator, and packages/core/src/services/duckdb-console.ts gates custom-source INSTALL parsing behind allowUnsignedExtensions().
• Admin auth: packages/core/src/config/env.ts still requires BETTER_AUTH_SECRET length >= 32; the API app applies CSRF middleware before session-authenticated routes; Better Auth production cookies remain Secure, HttpOnly, and SameSite=Lax.
• API input validation: changed console POST bodies continue to use Zod validation, extension names remain allowlisted, and the new custom source is single-quote escaped before interpolation into DuckDB SQL.
• Environment secrets: no .env.local or hardcoded secrets were added; docs/examples use placeholders and warn about unsigned native-code risk. Existing DuckDB error paths redact connection secrets before returning/logging.
• Dependency exposure: no dependency manifest changes were included in this PR, so no new dependency exposure was introduced.

  

_{Sent by Cursor Automation: archmax Security Review}

[github-actions]

Docker image ready

docker pull ghcr.io/archmaxai/archmax:pr-67

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit dc5a205. Configure here.}

[cursor]

Custom repo breaks core installs

High Severity

The Firebird install path sets custom_extension_repository on the shared project DuckDB instance and never restores the default. Later INSTALL calls for core extensions (e.g. postgres, iceberg) without an explicit FROM community clause can resolve against the Firebird repo instead of DuckDB’s core catalog, so multi-source projects may fail attach or extension load depending on connection order.

 

^{Reviewed by Cursor Bugbot for commit dc5a205. Configure here.}

[cursor]

Setup SQL omits Firebird options

Medium Severity

buildRedactedAttachSql still builds Firebird setup commands from buildAttachString only, which returns an empty ATTACH path for structured Firebird configs. The runtime attach path appends buildFirebirdAttachOptions (HOST, PORT, DATABASE, etc.), so console setup copy-paste SQL does not match what the server actually runs and will not attach structured Firebird sources.

 

^{Reviewed by Cursor Bugbot for commit dc5a205. Configure here.}