From 237460522016d5321b6303bc7944efb772d28999 Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 09:42:27 +0200
Subject: [PATCH 1/9] feat(federation): allow env-gated unsigned DuckDB
 extension installs

Add an opt-in DUCKDB_ALLOW_UNSIGNED_EXTENSIONS env var. When enabled,
project DuckDB instances are created with allow_unsigned_extensions and
the federation console accepts `INSTALL <ext> FROM '<source>'` for custom
repositories or paths. Default-off preserves current behavior (signed core
and community extensions only).

Includes the OpenSpec change `add-unsigned-duckdb-extensions`.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .env.example                                  |  8 ++++
 .../src/content/docs/reference/docker.mdx     | 12 +++++
 .../add-unsigned-duckdb-extensions/design.md  | 37 ++++++++++++++++
 .../proposal.md                               | 22 ++++++++++
 .../specs/deployment/spec.md                  | 27 ++++++++++++
 .../specs/duckdb-console/spec.md              | 44 +++++++++++++++++++
 .../add-unsigned-duckdb-extensions/tasks.md   | 25 +++++++++++
 packages/core/src/config/env.ts               | 15 +++++++
 .../core/src/services/duckdb-console.test.ts  | 36 +++++++++++++++
 packages/core/src/services/duckdb-console.ts  | 28 +++++++++++-
 packages/core/src/services/duckdb.ts          | 38 ++++++++++++----
 11 files changed, 282 insertions(+), 10 deletions(-)
 create mode 100644 openspec/changes/add-unsigned-duckdb-extensions/design.md
 create mode 100644 openspec/changes/add-unsigned-duckdb-extensions/proposal.md
 create mode 100644 openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md
 create mode 100644 openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md
 create mode 100644 openspec/changes/add-unsigned-duckdb-extensions/tasks.md

diff --git a/.env.example b/.env.example
index e4611dd..2681774 100644
--- a/.env.example
+++ b/.env.example
@@ -55,3 +55,11 @@ AGENT_API_KEY=your-api-key
 # Limits parallel queries to prevent resource exhaustion.
 # Additional requests wait up to QUERY_TIMEOUT_MS for a slot.
 # MAX_CONCURRENT_QUERIES=10
+
+# Allow installing unsigned DuckDB extensions from the federation console
+# (default: disabled). When set to true, DuckDB instances start with
+# allow_unsigned_extensions and the console accepts
+# `INSTALL <extension> FROM '<source>'` for custom repositories or paths.
+# SECURITY: unsigned extensions run arbitrary native code in the app process.
+# Only enable this for trusted extension sources.
+# DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=false
diff --git a/apps/docs/src/content/docs/reference/docker.mdx b/apps/docs/src/content/docs/reference/docker.mdx
index 9552294..6182538 100644
--- a/apps/docs/src/content/docs/reference/docker.mdx
+++ b/apps/docs/src/content/docs/reference/docker.mdx
@@ -74,6 +74,18 @@ If you access archmax through a reverse proxy, load balancer, or custom domain,
 |----------|---------|-------------|
 | `ARCHMAX_DATA_DIR` | `/data` | Root data directory for all persistent application data. Normally not changed in Docker. |
 
+### Data Federation (DuckDB)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `QUERY_TIMEOUT_MS` | `30000` | Per-query DuckDB timeout in milliseconds. Applies to MCP, agent, data browser, and connection-test queries. On timeout the query is cancelled via `interrupt()`. |
+| `MAX_CONCURRENT_QUERIES` | `10` | Max concurrent DuckDB queries per project. Additional requests wait up to `QUERY_TIMEOUT_MS` for a slot. |
+| `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` | `false` | Allow installing unsigned extensions from the federation console. When enabled, DuckDB instances start with `allow_unsigned_extensions` and the console accepts `INSTALL <extension> FROM '<source>'` for custom repositories or paths. |
+
+<Aside type="caution">
+Unsigned DuckDB extensions execute arbitrary native code inside the application process. Only set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` when you trust the extension sources you install. It is disabled by default.
+</Aside>
+
 ### AI Agent
 
 <Aside type="caution">
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/design.md b/openspec/changes/add-unsigned-duckdb-extensions/design.md
new file mode 100644
index 0000000..c6e5c5f
--- /dev/null
+++ b/openspec/changes/add-unsigned-duckdb-extensions/design.md
@@ -0,0 +1,37 @@
+## Context
+
+The federation console (`packages/core/src/services/duckdb-console.ts`) lets an authenticated admin run read-only SQL and install DuckDB extensions on a project's in-process, in-memory DuckDB instance. `parseExtensionSql` currently only accepts `INSTALL <ext> [FROM community]` or `LOAD <ext>`, and instances are created via bare `DuckDBInstance.create()` in `packages/core/src/services/duckdb.ts` (`setupProjectInstance`, `testSingleConnection`, `testIcebergConnection`).
+
+DuckDB refuses to load extensions that are not signed by the DuckDB org unless the database was started with the `allow_unsigned_extensions` configuration option. That option can **only** be set at instance-creation time, not via `SET` on a live connection. So enabling unsigned extensions requires changing how instances are created, not just the SQL parser.
+
+## Goals / Non-Goals
+
+- Goals:
+  - Let opted-in self-hosters install trusted unsigned/custom-source extensions from the console.
+  - Default-off, zero behavior change when the env var is unset.
+  - Keep the gate in one obvious place (env-derived boolean) reused by both instance creation and SQL parsing.
+- Non-Goals:
+  - Per-project or per-extension allowlists (single global toggle is sufficient for now).
+  - A UI control to toggle the setting (it is an operator/deployment concern).
+  - Changing the read-only query allowlist or the `INSTALL/LOAD` keyword routing in the frontend.
+
+## Decisions
+
+- **Decision: Single global env var `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`.** Parsed once as a boolean (truthy for `true`/`1`, case-insensitive). Exposed from `config/env.ts` like the other DuckDB knobs (`QUERY_TIMEOUT_MS`, `MAX_CONCURRENT_QUERIES`). A helper `allowUnsignedExtensions()` reads it.
+  - Alternatives considered: per-project DB field (more flexible but adds schema + UI + migration for a niche operator feature); reusing an existing flag (none fit).
+- **Decision: Apply the config at instance creation via a shared `createDuckDBInstance()` helper.** All call sites that currently call `DuckDBInstance.create()` route through it so every instance (federation, connection-test) gets a consistent config: `{ allow_unsigned_extensions: "true" }` only when the flag is on.
+- **Decision: Extend `parseExtensionSql` to accept `INSTALL <extension> FROM '<source>'` only when the flag is on.** `<source>` is a single-quoted string (custom repository URL or local extension path). When the flag is off, this shape is rejected with the existing "must be INSTALL …" 400 error so behavior is unchanged. The extension name still matches `^[a-z][a-z0-9_]*$`; the quoted source is passed through to `INSTALL <ext> FROM '<source>'`.
+- **Decision: Reuse the existing install/load execution path** (`ensureProjectExtensionLoaded` / `installAndLoadExtension`), extended to carry an optional `fromSource` so it emits `INSTALL <ext> FROM '<source>'` instead of `INSTALL <ext>[ FROM community]`.
+
+## Risks / Trade-offs
+
+- **Arbitrary code execution**: unsigned extensions are native code loaded into the API/worker process. Mitigation: off by default; documented with an explicit security warning; only reachable by an authenticated admin via the console; source string is single-quote-escaped before interpolation.
+- **Worker vs API divergence**: the flag is process-level env, so both the API and BullMQ worker must share it for materialised views that depend on a custom extension to work in both. Mitigation: it is a normal env var present in the single Docker image for all processes; documented in the env table.
+
+## Migration Plan
+
+No data migration. Purely additive: unset env var ⇒ identical behavior to today. To enable, set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and restart. To disable, unset and restart (instances are in-memory and rebuilt per process, so no persisted state carries the flag).
+
+## Open Questions
+
+- None. Local-path installs (`INSTALL '<path>.duckdb_extension'` with no `FROM`) are explicitly out of scope; only `INSTALL <extension> FROM '<source>'` is supported.
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/proposal.md b/openspec/changes/add-unsigned-duckdb-extensions/proposal.md
new file mode 100644
index 0000000..8b00bda
--- /dev/null
+++ b/openspec/changes/add-unsigned-duckdb-extensions/proposal.md
@@ -0,0 +1,22 @@
+# Change: Allow installing unsigned DuckDB extensions from the console (env-gated)
+
+## Why
+
+The federation console only installs signed core or `FROM community` extensions, because the project DuckDB instances are created without `allow_unsigned_extensions`. Operators who run their own extension builds or trusted third-party `.duckdb_extension` artifacts have no way to load them. We want to support this for self-hosters who explicitly opt in, while keeping the default posture (signed/community only) unchanged.
+
+## What Changes
+
+- Add an opt-in env var `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` (default off). When truthy, project DuckDB instances are created with the `allow_unsigned_extensions` config option enabled.
+- Extend the console extension-install path (`POST .../duckdb-console/extensions`) so that, **only when the env var is enabled**, it accepts `INSTALL <extension> FROM '<source>'` where `<source>` is a single-quoted custom repository URL or local extension path. Signed/community installs (`INSTALL <ext> [FROM community]`, `LOAD <ext>`) are unchanged.
+- When the env var is **not** set, custom-source installs are rejected with 400 and instances are created without the flag — preserving current behavior exactly.
+- Document the new variable in `.env.example` and the Docker reference env table, including a security note that unsigned extensions run arbitrary native code.
+
+## Impact
+
+- Affected specs: `duckdb-console` (ADDED requirement), `deployment` (ADDED requirement)
+- Affected code:
+  - `packages/core/src/config/env.ts` — add `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`
+  - `packages/core/src/services/duckdb.ts` — pass `allow_unsigned_extensions` to `DuckDBInstance.create()` via a shared helper
+  - `packages/core/src/services/duckdb-console.ts` — `parseExtensionSql` accepts env-gated `FROM '<source>'`
+  - `.env.example`, `apps/docs` Docker reference page
+- Security: enabling the flag permits loading unsigned native extensions (arbitrary code execution surface); off by default and clearly documented.
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md b/openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md
new file mode 100644
index 0000000..53dbd5b
--- /dev/null
+++ b/openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md
@@ -0,0 +1,27 @@
+## ADDED Requirements
+
+### Requirement: Unsigned DuckDB Extensions Configuration
+
+The image SHALL accept an optional `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` environment variable that controls whether the federated DuckDB instances permit loading unsigned extensions. The variable SHALL default to disabled; only `true` or `1` (case-insensitive) SHALL enable it.
+
+When enabled, all DuckDB instances created by the application SHALL be started with the `allow_unsigned_extensions` configuration option so that unsigned/custom-source extensions installed via the federation console can load. When unset or falsy, instances SHALL be created without the option (signed core and community extensions only).
+
+The variable SHALL be documented in `.env.example` and in the Docker reference page environment-variable table, including a security note that unsigned extensions execute arbitrary native code in the application process and that the setting should only be enabled for trusted extension sources.
+
+#### Scenario: Disabled by default
+
+- **WHEN** the image starts without `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` set
+- **THEN** DuckDB instances are created without `allow_unsigned_extensions`
+- **AND** only signed core and `FROM community` extensions can be installed
+
+#### Scenario: Enabled via environment
+
+- **WHEN** the image starts with `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true`
+- **THEN** DuckDB instances are created with `allow_unsigned_extensions` enabled
+- **AND** the federation console can install unsigned extensions from a custom source
+
+#### Scenario: Documented in environment reference
+
+- **WHEN** a user reads `.env.example` or the Docker reference environment-variable table
+- **THEN** they find `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` documented as optional and disabled by default
+- **AND** a security warning explains that unsigned extensions run arbitrary native code
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md b/openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md
new file mode 100644
index 0000000..1dd8912
--- /dev/null
+++ b/openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md
@@ -0,0 +1,44 @@
+## ADDED Requirements
+
+### Requirement: Unsigned Extension Installation Gate
+
+The DuckDB Console Extension Install endpoint (`POST /api/projects/:projectId/duckdb-console/extensions`) SHALL allow installing unsigned extensions from a custom source only when the `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` environment variable is truthy (`true` or `1`, case-insensitive). This requirement is additive to and does not relax the signed/community install behavior.
+
+When the gate is enabled:
+
+- Project DuckDB instances SHALL be created with the `allow_unsigned_extensions` configuration option enabled, so unsigned extensions can load.
+- The extension-install parser SHALL additionally accept `INSTALL <extension> FROM '<source>'`, where `<extension>` matches `^[a-z][a-z0-9_]*$` and `<source>` is a single-quoted custom repository URL or local extension path. The server SHALL escape the `<source>` value before interpolating it into the executed `INSTALL <extension> FROM '<source>'` statement.
+
+When the gate is disabled (the default):
+
+- Project DuckDB instances SHALL be created WITHOUT the `allow_unsigned_extensions` option, so only signed core and `FROM community` extensions can load.
+- `INSTALL <extension> FROM '<source>'` SHALL be rejected with status 400, leaving the existing accepted shapes (`INSTALL <extension>`, `INSTALL <extension> FROM community`, `LOAD <extension>`) unchanged.
+
+The gate SHALL NOT change the read-only query allowlist or the keyword routing performed by the console page.
+
+#### Scenario: Install unsigned extension when gate enabled
+
+- **WHEN** `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is `true`
+- **AND** an authenticated POST submits `INSTALL myext FROM 'https://example.com/repo'`
+- **THEN** the response status is 200
+- **AND** `extension` is `myext`
+- **AND** the statement executed against DuckDB is `INSTALL myext FROM 'https://example.com/repo'`
+
+#### Scenario: Reject unsigned install when gate disabled
+
+- **WHEN** `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is unset or falsy
+- **AND** an authenticated POST submits `INSTALL myext FROM 'https://example.com/repo'`
+- **THEN** the response status is 400
+- **AND** the error indicates the statement must be `INSTALL <extension> [FROM community]` or `LOAD <extension>`
+
+#### Scenario: Signed and community installs unaffected by gate
+
+- **WHEN** an authenticated POST submits `INSTALL spatial FROM community`
+- **THEN** the response status is 200 regardless of the `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` value
+- **AND** `extension` is `spatial`
+
+#### Scenario: Reject invalid extension name with custom source
+
+- **WHEN** `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is `true`
+- **AND** an authenticated POST submits `INSTALL ../evil FROM 'https://example.com/repo'`
+- **THEN** the response status is 400
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/tasks.md b/openspec/changes/add-unsigned-duckdb-extensions/tasks.md
new file mode 100644
index 0000000..c5c0552
--- /dev/null
+++ b/openspec/changes/add-unsigned-duckdb-extensions/tasks.md
@@ -0,0 +1,25 @@
+## 1. Configuration
+
+- [x] 1.1 Add `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` to the env schema in `packages/core/src/config/env.ts` (optional string, default unset)
+- [x] 1.2 Add an `allowUnsignedExtensions()` helper that returns a boolean for truthy `true`/`1` (case-insensitive)
+
+## 2. DuckDB instance creation
+
+- [x] 2.1 Add a `createDuckDBInstance()` helper in `packages/core/src/services/duckdb.ts` that calls `DuckDBInstance.create()` with `{ allow_unsigned_extensions: "true" }` only when the flag is enabled
+- [x] 2.2 Route `setupProjectInstance`, `testSingleConnection`, and `testIcebergConnection` through the helper
+
+## 3. Console extension install
+
+- [x] 3.1 Extend `parseExtensionSql` in `duckdb-console.ts` to accept `INSTALL <extension> FROM '<source>'` (single-quoted source) only when the flag is enabled; return `{ extension, fromSource }`
+- [x] 3.2 Reject the custom-source shape with the existing 400 error when the flag is disabled
+- [x] 3.3 Thread `fromSource` through `installDuckdbConsoleExtension` → `ensureProjectExtensionLoaded` → `installAndLoadExtension`, emitting `INSTALL <ext> FROM '<source>'` with the source single-quote-escaped
+
+## 4. Documentation
+
+- [x] 4.1 Document `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` in `.env.example` with a security note
+- [x] 4.2 Add `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` to the Docker reference env-variable table in `apps/docs`
+
+## 5. Tests & verification
+
+- [x] 5.1 Unit tests for `parseExtensionSql`: custom-source accepted when enabled, rejected when disabled, invalid name rejected, community/load unchanged
+- [x] 5.2 Run `pnpm typecheck` and `pnpm lint` (and `pnpm --filter @archmax/api build`); both exit 0
diff --git a/packages/core/src/config/env.ts b/packages/core/src/config/env.ts
index 1afbca8..d6c21a3 100644
--- a/packages/core/src/config/env.ts
+++ b/packages/core/src/config/env.ts
@@ -33,6 +33,8 @@ const envSchema = z.object({
   QUERY_TIMEOUT_MS: z.string().optional().default("30000"),
   MAX_CONCURRENT_QUERIES: z.string().optional().default("10"),
 
+  DUCKDB_ALLOW_UNSIGNED_EXTENSIONS: z.string().optional(),
+
   REDIS_URL: z.string().optional(),
   WORKER_CONCURRENCY: z.string().optional(),
 
@@ -168,3 +170,16 @@ export function getEnv(): ParsedEnv {
 }
 
 export type Env = ParsedEnv;
+
+/**
+ * Whether the federated DuckDB instances may load unsigned extensions.
+ *
+ * Off by default. Enabling it (`DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true|1`)
+ * starts every DuckDB instance with `allow_unsigned_extensions` and lets the
+ * federation console install extensions from a custom source. Unsigned
+ * extensions run arbitrary native code, so this is an operator opt-in.
+ */
+export function allowUnsignedExtensions(): boolean {
+  const raw = getEnv().DUCKDB_ALLOW_UNSIGNED_EXTENSIONS?.trim().toLowerCase();
+  return raw === "true" || raw === "1";
+}
diff --git a/packages/core/src/services/duckdb-console.test.ts b/packages/core/src/services/duckdb-console.test.ts
index 69d8357..dcc914d 100644
--- a/packages/core/src/services/duckdb-console.test.ts
+++ b/packages/core/src/services/duckdb-console.test.ts
@@ -57,6 +57,42 @@ describe("parseExtensionSql", () => {
   it("rejects SELECT", () => {
     expect(() => parseExtensionSql("SELECT 1")).toThrow();
   });
+
+  it("parses INSTALL FROM '<source>' when unsigned extensions are allowed", () => {
+    expect(
+      parseExtensionSql("INSTALL myext FROM 'https://example.com/repo'", true),
+    ).toEqual({
+      extension: "myext",
+      loadOnly: false,
+      fromCommunity: false,
+      fromSource: "https://example.com/repo",
+    });
+  });
+
+  it("unescapes doubled quotes in a custom source", () => {
+    expect(parseExtensionSql("INSTALL myext FROM 'a''b'", true).fromSource).toBe("a'b");
+  });
+
+  it("rejects INSTALL FROM '<source>' when unsigned extensions are disabled", () => {
+    expect(() =>
+      parseExtensionSql("INSTALL myext FROM 'https://example.com/repo'"),
+    ).toThrow(/must be INSTALL/i);
+    expect(() =>
+      parseExtensionSql("INSTALL myext FROM 'https://example.com/repo'", false),
+    ).toThrow(/must be INSTALL/i);
+  });
+
+  it("rejects invalid extension name with a custom source even when allowed", () => {
+    expect(() => parseExtensionSql("INSTALL ../evil FROM 'https://x'", true)).toThrow();
+  });
+
+  it("does not treat FROM community as a custom source", () => {
+    expect(parseExtensionSql("INSTALL spatial FROM community", true)).toEqual({
+      extension: "spatial",
+      loadOnly: false,
+      fromCommunity: true,
+    });
+  });
 });
 
 describe("buildRedactedAttachSql", () => {
diff --git a/packages/core/src/services/duckdb-console.ts b/packages/core/src/services/duckdb-console.ts
index 8123458..3f03c70 100644
--- a/packages/core/src/services/duckdb-console.ts
+++ b/packages/core/src/services/duckdb-console.ts
@@ -1,4 +1,5 @@
 import { connectDB } from "../infra/db";
+import { allowUnsignedExtensions } from "../config/env";
 import { Connection, Project, type IConnectionDocument } from "../models/index";
 import {
   buildAttachString,
@@ -109,14 +110,36 @@ export interface ParsedExtensionSql {
   extension: string;
   loadOnly: boolean;
   fromCommunity: boolean;
+  /**
+   * Custom install source (repository URL or path) for an env-gated unsigned
+   * extension install (`INSTALL <ext> FROM '<source>'`). Undefined for the
+   * signed/community shapes.
+   */
+  fromSource?: string;
 }
 
-export function parseExtensionSql(sql: string): ParsedExtensionSql {
+export function parseExtensionSql(sql: string, allowUnsigned = false): ParsedExtensionSql {
   const trimmed = sql.trim().replace(/;+\s*$/, "");
   if (trimmed.includes(";")) {
     throw new Error("Only a single statement is allowed");
   }
 
+  // INSTALL <extension> FROM '<source>' — unsigned/custom-source install.
+  // Only honoured when the operator has enabled unsigned extensions; the
+  // single-quoted source may contain '' as an escaped quote.
+  const sourceMatch = trimmed.match(/^install\s+([a-z][a-z0-9_]*)\s+from\s+'((?:[^']|'')*)'\s*$/i);
+  if (sourceMatch) {
+    if (!allowUnsigned) {
+      throw new Error("SQL must be INSTALL <extension> [FROM community] or LOAD <extension>");
+    }
+    const extension = sourceMatch[1].toLowerCase();
+    if (!EXTENSION_NAME_RE.test(extension)) {
+      throw new Error("Invalid extension name");
+    }
+    const fromSource = sourceMatch[2].replace(/''/g, "'");
+    return { extension, loadOnly: false, fromCommunity: false, fromSource };
+  }
+
   const installMatch = trimmed.match(/^install\s+([a-z][a-z0-9_]*)(?:\s+from\s+community)?\s*$/i);
   if (installMatch) {
     const extension = installMatch[1].toLowerCase();
@@ -303,7 +326,7 @@ export async function installDuckdbConsoleExtension(
   projectId: string,
   sql: string,
 ): Promise<{ extension: string }> {
-  const parsed = parseExtensionSql(sql);
+  const parsed = parseExtensionSql(sql, allowUnsignedExtensions());
   await connectDB();
   const project = await Project.findById(projectId).lean();
   if (!project) {
@@ -314,6 +337,7 @@ export async function installDuckdbConsoleExtension(
     await ensureProjectExtensionLoaded(projectId, parsed.extension, {
       fromCommunity: parsed.fromCommunity,
       loadOnly: parsed.loadOnly,
+      fromSource: parsed.fromSource,
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
diff --git a/packages/core/src/services/duckdb.ts b/packages/core/src/services/duckdb.ts
index 5fe8696..bc3f269 100644
--- a/packages/core/src/services/duckdb.ts
+++ b/packages/core/src/services/duckdb.ts
@@ -5,7 +5,7 @@ import { connectDB } from "../infra/db";
 import { Connection, type IConnectionDocument } from "../models/index";
 import type { SemanticModel } from "./semantic-model-schema";
 import { decryptConnectionCredentials } from "../infra/crypto";
-import { getEnv } from "../config/env";
+import { allowUnsignedExtensions, getEnv } from "../config/env";
 import { validateSqlAst } from "./sql-ast-validation";
 
 const SAFE_PROJECT_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
@@ -33,6 +33,20 @@ async function deleteDuckdbFiles(path: string): Promise<void> {
   await rm(`${path}.tmp`, { force: true, recursive: true });
 }
 
+/**
+ * Create a fresh in-memory `DuckDBInstance`, applying the
+ * `allow_unsigned_extensions` startup option when the operator has opted in
+ * via `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`. The option can only be set at
+ * instance-creation time (not via `SET`), so every call site that opens an
+ * instance routes through here to get a consistent configuration.
+ */
+export async function createDuckDBInstance(): Promise<DuckDBInstance> {
+  if (allowUnsignedExtensions()) {
+    return DuckDBInstance.create(undefined, { allow_unsigned_extensions: "true" });
+  }
+  return DuckDBInstance.create();
+}
+
 // ── Query timeout helper ─────────────────────────────────────────────
 
 export function getQueryTimeoutMs(): number {
@@ -610,7 +624,7 @@ async function setupProjectInstance(
     // (no hash cache) and connections are re-attached whenever a fresh
     // instance is created, so an in-memory database is functionally
     // equivalent without the lock contention.
-    const instance = await DuckDBInstance.create();
+    const instance = await createDuckDBInstance();
     entry = {
       instance,
       attachedSlugs: new Set(),
@@ -642,7 +656,7 @@ async function setupProjectInstance(
 export async function ensureProjectExtensionLoaded(
   projectId: string,
   extension: string,
-  options?: { fromCommunity?: boolean; loadOnly?: boolean },
+  options?: { fromCommunity?: boolean; loadOnly?: boolean; fromSource?: string },
 ): Promise<void> {
   await connectDB();
   const connections = await Connection.find({ project: projectId, isActive: true }).lean();
@@ -666,6 +680,7 @@ export async function ensureProjectExtensionLoaded(
   if (!entry.loadedExtensions.has(extension)) {
     await installAndLoadExtension(entry.instance, extension, {
       fromCommunity: options?.fromCommunity,
+      fromSource: options?.fromSource,
     });
     entry.loadedExtensions.add(extension);
     return;
@@ -682,12 +697,19 @@ export async function ensureProjectExtensionLoaded(
 async function installAndLoadExtension(
   instance: DuckDBInstance,
   ext: string,
-  options?: { fromCommunity?: boolean },
+  options?: { fromCommunity?: boolean; fromSource?: string },
 ): Promise<void> {
   const db = await instance.connect();
   try {
-    const fromCommunity = options?.fromCommunity ?? COMMUNITY_EXTENSIONS.has(ext);
-    const installSuffix = fromCommunity ? " FROM community" : "";
+    // A custom source (env-gated unsigned install) wins over the community
+    // repository. The source is single-quote escaped before interpolation.
+    let installSuffix: string;
+    if (options?.fromSource) {
+      installSuffix = ` FROM '${options.fromSource.replace(/'/g, "''")}'`;
+    } else {
+      const fromCommunity = options?.fromCommunity ?? COMMUNITY_EXTENSIONS.has(ext);
+      installSuffix = fromCommunity ? " FROM community" : "";
+    }
     await db.run(`INSTALL ${ext}${installSuffix}`);
     await db.run(`LOAD ${ext}`);
     if (ext === "mysql") {
@@ -822,7 +844,7 @@ export async function testSingleConnection(conn: IConnectionDocument): Promise<D
   const ext = extensionForType(conn.type);
   if (!ext) throw new Error(`Unsupported connection type: ${conn.type}`);
 
-  const instance = await DuckDBInstance.create();
+  const instance = await createDuckDBInstance();
   await installAndLoadExtension(instance, ext);
 
   const db = await instance.connect();
@@ -836,7 +858,7 @@ export async function testSingleConnection(conn: IConnectionDocument): Promise<D
 }
 
 async function testIcebergConnection(conn: IConnectionDocument): Promise<DuckDBInstance> {
-  const instance = await DuckDBInstance.create();
+  const instance = await createDuckDBInstance();
   for (const ext of ICEBERG_EXTENSIONS) {
     await installAndLoadExtension(instance, ext);
   }

From 3d29def57be7e85f193cd7e8726da1a558b22151 Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 09:42:32 +0200
Subject: [PATCH 2/9] docs(openspec): add Firebird connection type proposal

Proposal-only (no implementation). Adds an env-gated `firebird` connection
type backed by the unsigned duckdb_firebird extension, activated by
DUCKDB_ENABLE_FIREBIRD (effective only when DUCKDB_ALLOW_UNSIGNED_EXTENSIONS
is also set) with an optional DUCKDB_FIREBIRD_EXTENSION_REPOSITORY override.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../add-firebird-connection-type/design.md    |  45 +++++++
 .../add-firebird-connection-type/proposal.md  |  32 +++++
 .../specs/connection-management-ui/spec.md    |  24 ++++
 .../specs/data-connections/spec.md            | 111 ++++++++++++++++++
 .../specs/deployment/spec.md                  |  35 ++++++
 .../add-firebird-connection-type/tasks.md     |  36 ++++++
 6 files changed, 283 insertions(+)
 create mode 100644 openspec/changes/add-firebird-connection-type/design.md
 create mode 100644 openspec/changes/add-firebird-connection-type/proposal.md
 create mode 100644 openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md
 create mode 100644 openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
 create mode 100644 openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
 create mode 100644 openspec/changes/add-firebird-connection-type/tasks.md

diff --git a/openspec/changes/add-firebird-connection-type/design.md b/openspec/changes/add-firebird-connection-type/design.md
new file mode 100644
index 0000000..aad91f8
--- /dev/null
+++ b/openspec/changes/add-firebird-connection-type/design.md
@@ -0,0 +1,45 @@
+## Context
+
+DuckDB has no native Firebird driver; the only `TYPE firebird` ATTACH support comes from a custom, unsigned extension hosted at `https://archmaxai.github.io/duckdb_firebird`. Loading it requires two things the platform does not do today:
+
+1. The instance must be created with `allow_unsigned_extensions` (already wired via `createDuckDBInstance()` in `packages/core/src/services/duckdb.ts`, gated by the pending `add-unsigned-duckdb-extensions` change's `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`).
+2. The extension must be installed from a custom repository using `SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;` — a different shape from the existing `INSTALL <ext> FROM '<source>'` console path.
+
+Connection types are enumerated in `packages/core/src/models/Connection.ts` (`CONNECTION_TYPES`), validated by `apps/api/src/routes/connections.ts` (`z.enum(CONNECTION_TYPES)`), duplicated in the frontend (`apps/frontend/src/routes/_auth/$projectId/connections/index.tsx`), and dispatched on in `duckdb.ts` (`extensionForType`, `buildAttachString`, `attachConnection`, `testSingleConnection`) and `duckdb-console.ts` (`extensionTypeLabel`). Adding a connection type touches all of these.
+
+## Goals / Non-Goals
+
+- Goals:
+  - First-class `firebird` connection type with UI-defined `host`/`port`/`database`/`user`/`password` parameters (default port `3050`), behaving like Postgres/MySQL in federation, data browser, tests, and MCP.
+  - Single opt-in env var that activates Firebird, effective only when unsigned extensions are allowed.
+  - Default-off, zero behavior change when the var is unset.
+  - Auto-install/load the extension from the custom repo with no console action.
+- Non-Goals:
+  - Per-project or per-connection extension allowlists.
+  - Supporting Firebird via the DuckDB ODBC extension (out of scope; this uses the custom native extension).
+  - A general operator settings UI; Firebird configuration stays an env/deployment concern, surfaced to the UI only as a capability flag.
+
+## Decisions
+
+- **Decision: Two-flag gate.** Firebird is active iff `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is truthy AND `DUCKDB_ENABLE_FIREBIRD` is truthy (`true`/`1`, case-insensitive). A `firebirdEnabled()` helper in `config/env.ts` encodes this (it returns `false` when unsigned extensions are off, logging a one-time warning if `DUCKDB_ENABLE_FIREBIRD` was set). This matches the user's framing ("if unsigned extensions can be installed … add a var that activates Firebird") and keeps the unsigned-code opt-in explicit.
+  - Alternatives considered: a single `DUCKDB_ENABLE_FIREBIRD` that implicitly enables `allow_unsigned_extensions`. Rejected so enabling one specific extension never silently widens the instance to all unsigned extensions.
+- **Decision: custom-repository install branch.** `installAndLoadExtension` gains a firebird-specific path that runs `SET custom_extension_repository = '<repo>'` (repo from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, default `https://archmaxai.github.io/duckdb_firebird`, single-quote-escaped) before `INSTALL firebird; LOAD firebird;`. This is distinct from the console's `INSTALL <ext> FROM '<source>'` path and is the shape the extension requires.
+- **Decision: auto-install, no console step.** When Firebird is active, the extension is installed+loaded as part of the normal instance/extension bookkeeping (the same `loadedExtensions` flow used for postgres/mysql), so attaching a Firebird connection needs no manual `INSTALL`/`LOAD`. Because `createDuckDBInstance()` already enables `allow_unsigned_extensions` under the unsigned gate, no extra instance-config change is needed.
+- **Decision: attach via `extensionForType` → `"firebird"`.** `extensionForType("firebird")` returns `"firebird"`; `attachConnection` installs the extension (custom-repo branch) then `ATTACH '<dsn>' AS <slug> (TYPE FIREBIRD, READ_ONLY)`. `buildAttachString` gets a `firebird` case mirroring the Postgres key=value DSN with default port `3050`. `uri` pass-through is preserved.
+- **Decision: capability flag endpoint.** A small authenticated endpoint returns `{ firebirdEnabled: boolean }` so the frontend conditionally lists Firebird in the type dropdown and sets default port `3050`. No new persisted state.
+- **Decision: API rejects inactive type.** When Firebird is inactive, `POST`/`PUT` connections with `type: "firebird"` return 400 (defense in depth even though the UI hides the option), so a stored Firebird connection cannot exist on an instance that cannot load the extension.
+
+## Risks / Trade-offs
+
+- **Arbitrary code execution**: the Firebird extension is unsigned native code. Mitigation: default off; requires the unsigned-extensions gate; documented with an explicit security warning; repository URL is single-quote-escaped before interpolation.
+- **Exact ATTACH DSN unknown**: the custom extension's connection-string format is not in public DuckDB docs (see Open Questions). Mitigation: default to the Postgres-style `host=… port=… database=… user=… password=…` DSN plus `uri` pass-through, and confirm against the extension during implementation; the spec is written around observable behavior (a Firebird connection attaches and `SELECT 1` succeeds) rather than a hard-coded DSN string.
+- **Worker vs API divergence**: the flags are process-level env, shared by API and worker via the single Docker image; both must have them set for worker-side materialisation against Firebird to work. Documented in the env table.
+
+## Migration Plan
+
+No data migration. Purely additive: unset vars ⇒ identical behavior to today. To enable: set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and `DUCKDB_ENABLE_FIREBIRD=true` (optionally `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`) and restart. To disable: unset and restart; instances are in-memory and rebuilt per process so nothing persists. Existing Firebird connection documents (if any) simply fail to attach while inactive.
+
+## Open Questions
+
+- Exact connection-string/DSN format the `duckdb_firebird` extension expects for `ATTACH … (TYPE firebird)` (e.g. `host=… port=3050 database=/path/to.fdb user=SYSDBA password=…` vs. an ODBC-style `Database=host/port:path` form). Resolve by testing against the published extension during implementation; `buildAttachString` and the attach scenario will be finalized then.
+- Whether the extension requires any companion extension (analogous to iceberg needing `httpfs`). Assumed single-extension unless testing shows otherwise.
diff --git a/openspec/changes/add-firebird-connection-type/proposal.md b/openspec/changes/add-firebird-connection-type/proposal.md
new file mode 100644
index 0000000..245e586
--- /dev/null
+++ b/openspec/changes/add-firebird-connection-type/proposal.md
@@ -0,0 +1,32 @@
+# Change: Add an env-gated Firebird connection type backed by an unsigned DuckDB extension
+
+## Why
+
+Firebird databases are only reachable from DuckDB through a custom, **unsigned** extension hosted at `https://archmaxai.github.io/duckdb_firebird` (the upstream DuckDB project supports Firebird only via ODBC). The recently-added `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` gate already lets opted-in self-hosters load unsigned extensions, but there is no first-class way to add a Firebird data source: it is not in the connection-type enum, the federation pipeline has no Firebird attach path, and the install requires `SET custom_extension_repository` + plain `INSTALL firebird` rather than the `INSTALL <ext> FROM '<source>'` shape the console already supports. Operators who run Firebird want to attach it like any other source (Postgres/MySQL) with parameters defined in the UI.
+
+## What Changes
+
+- Add an opt-in env var `DUCKDB_ENABLE_FIREBIRD` (default off). It only takes effect when `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is also truthy (Firebird is an unsigned extension); if `DUCKDB_ENABLE_FIREBIRD` is set while unsigned extensions are disabled, Firebird stays inactive and a startup warning is logged.
+- Add an optional `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` env var (default `https://archmaxai.github.io/duckdb_firebird`) so operators can point at a mirror.
+- Add `firebird` to the `Connection` type enum (model + API + frontend), with the same structured `host`/`port`/`database`/`user`/`password` (and optional `schema`, `uri`) parameters as Postgres/MySQL and a default port of `3050`.
+- When Firebird is active, the project DuckDB pipeline SHALL automatically install and load the Firebird extension from the custom repository (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) with no console action, and attach Firebird connections via `TYPE firebird` so they participate in federation, the data browser, connection tests, and MCP queries.
+- Expose a server capability flag so the connection-management UI lists **Firebird** in the type dropdown (and defaults its port to `3050`) only when Firebird is active.
+- When Firebird is **not** active, the API SHALL reject `type: "firebird"` connection create/update with 400, and the UI SHALL omit Firebird from the dropdown — preserving current behavior exactly.
+- Document the new variables in `.env.example`, the Docker reference env table, and the data-federation guide, including a security note that Firebird is an unsigned extension running arbitrary native code.
+
+## Impact
+
+- Affected specs:
+  - `deployment` — ADDED requirement (Firebird env configuration)
+  - `data-connections` — MODIFIED `Connection Model` (add `firebird` to type enum), ADDED requirement (env-gated Firebird federation + capability flag)
+  - `connection-management-ui` — ADDED requirement (Firebird connection form, conditional on the capability flag)
+- Affected code:
+  - `packages/core/src/config/env.ts` — `DUCKDB_ENABLE_FIREBIRD`, `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, `firebirdEnabled()` helper
+  - `packages/core/src/models/Connection.ts` — add `firebird` to `CONNECTION_TYPES`
+  - `packages/core/src/services/duckdb.ts` — `extensionForType`, `buildAttachString`, firebird install branch in `installAndLoadExtension`, `createDuckDBInstance` unsigned-when-firebird, `testSingleConnection`
+  - `packages/core/src/services/duckdb-console.ts` — `extensionTypeLabel` firebird case
+  - `apps/api/src/routes/connections.ts` — reject `firebird` when inactive
+  - `apps/api/src/routes/` — small capability/config endpoint exposing `firebirdEnabled`
+  - `apps/frontend/src/routes/_auth/$projectId/connections/index.tsx` — conditional dropdown entry, default port `3050`
+  - `.env.example`, `apps/docs` Docker reference + data-federation guide
+- Security: enabling Firebird loads an unsigned native extension (arbitrary code execution surface); off by default, requires the unsigned-extensions gate, and clearly documented. Builds on the pending `add-unsigned-duckdb-extensions` change.
diff --git a/openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md b/openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md
new file mode 100644
index 0000000..72b0b67
--- /dev/null
+++ b/openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md
@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Firebird Connection Form
+
+The connection-management UI SHALL list **Firebird** as a selectable connection type in the create/edit form's type dropdown only when the server reports the Firebird capability as active (via the `firebirdEnabled` flag). When the flag is `false` or unavailable, Firebird SHALL NOT appear in the dropdown.
+
+When **Firebird** is selected, the form SHALL present the same structured **Connection Details** fields as Postgres/MySQL — Host, Port, Database, User, Password (plus the shared name, slug, description, and schema controls) — and SHALL default the Port field to `3050`. The **Connection URI** tab SHALL remain available for Firebird. The password field SHALL remain write-only as for other types.
+
+#### Scenario: Firebird shown when capability active
+
+- **WHEN** the server reports `firebirdEnabled: true` and the user opens the connection form
+- **THEN** **Firebird** appears as an option in the type dropdown
+
+#### Scenario: Firebird hidden when capability inactive
+
+- **WHEN** the server reports `firebirdEnabled: false` (or the flag is unavailable)
+- **THEN** **Firebird** does not appear in the type dropdown
+
+#### Scenario: Firebird uses structured relational fields with default port
+
+- **WHEN** the user selects type **Firebird** with the Connection Details tab
+- **THEN** Host, Port, Database, User, and Password inputs are shown
+- **AND** the Port field defaults to `3050`
+- **AND** submitting the form sends `type: "firebird"` with the entered parameters to the connections API
diff --git a/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md b/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
new file mode 100644
index 0000000..bd74e53
--- /dev/null
+++ b/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
@@ -0,0 +1,111 @@
+## MODIFIED Requirements
+
+### Requirement: Connection Model
+
+The system SHALL provide a `Connection` Mongoose model with the following fields: `project` (ObjectId ref to Project, required), `name` (string, required), `slug` (string, required, matches pattern `/^[a-zA-Z_][a-zA-Z0-9_]*$/`), `type` (enum: postgres, mysql, mssql, sqlite, duckdb, iceberg, firebird), `connectionConfig` (object with type-specific connection parameters), `description` (string, optional), `isActive` (boolean, default true), `createdAt` (Date), `updatedAt` (Date), `deleted` (boolean, default false), `deletedAt` (Date, optional). The `slug` field MUST be unique within a project (among non-deleted connections) and serves as the DuckDB schema alias when the connection is attached. The `connectionConfig` Zod schema SHALL use `.strict()` mode (rejecting unknown fields) and SHALL validate the `schema` field, when present, against the identifier pattern `/^[a-zA-Z_][a-zA-Z0-9_]*$/`. For iceberg connections, `connectionConfig` SHALL additionally accept: `endpoint` (string, required for iceberg — the REST Catalog URL, validated as a URL), `warehouse` (string, required for iceberg — warehouse identifier), `token` (string, required for iceberg — bearer token, sensitive), `authorizationType` (enum: `bearer`, `oauth2`, default `bearer`), `clientId` (string, optional — OAuth2 client ID, reserved for future use), `clientSecret` (string, optional — OAuth2 client secret, sensitive, reserved for future use), and `oauth2ServerUri` (string, optional — OAuth2 token endpoint, reserved for future use). The `endpoint` field SHALL be validated as a URL (scheme + host at minimum). The `token` and `clientSecret` fields SHALL receive the same encryption-at-rest, redaction, and credential-preservation treatment as the `password` field. For `firebird` connections, `connectionConfig` SHALL reuse the structured `host`/`port`/`database`/`user`/`password` fields (and optional `schema`/`uri`) like postgres and mysql; the `password` field SHALL receive the same encryption, redaction, and preservation treatment. The `firebird` type SHALL be accepted on create/update only when the Firebird capability is active (see "Env-Gated Firebird Federation"); when inactive, create/update with `type: "firebird"` SHALL be rejected with a 400 error.
+
+#### Scenario: Create a postgres connection
+
+- **WHEN** a connection is created with `type: "postgres"`, valid connection config, and `slug: "shopify_prod"`
+- **THEN** a new Connection document is persisted with the given slug
+
+#### Scenario: Slug auto-generated from name
+
+- **WHEN** a connection is created with `name: "My Postgres DB"` and no explicit `slug`
+- **THEN** the slug is auto-generated by lowercasing and replacing non-identifier characters with underscores (e.g. `my_postgres_db`)
+
+#### Scenario: Unique slug within project
+
+- **WHEN** a connection is created with a slug that already exists within the same project (among non-deleted connections)
+- **THEN** a duplicate key error is returned
+
+#### Scenario: Slug validation
+
+- **WHEN** a connection is created with a slug containing invalid characters (e.g. `my-db!`, `123start`, or empty string)
+- **THEN** a validation error is returned
+
+#### Scenario: Unique name within project
+
+- **WHEN** a connection is created with a name that already exists within the same project (among non-deleted connections)
+- **THEN** a duplicate key error is returned
+
+#### Scenario: Connection types
+
+- **WHEN** a connection is created with any supported type (postgres, mysql, mssql, sqlite, duckdb, iceberg)
+- **THEN** the connection is accepted and stored
+
+#### Scenario: Firebird type accepted only when active
+
+- **WHEN** a connection is created with `type: "firebird"` and the Firebird capability is active
+- **THEN** the connection is accepted and stored
+- **AND WHEN** the Firebird capability is inactive, the create request is rejected with a 400 error
+
+#### Scenario: Unknown connection config fields rejected
+
+- **WHEN** a connection is created or updated with extra fields in `connectionConfig` not defined in the schema (e.g., `injectedField: "malicious"`)
+- **THEN** a 400 validation error is returned
+
+#### Scenario: Schema field validated as identifier
+
+- **WHEN** a connection is created or updated with `connectionConfig.schema` set to a value that does not match `/^[a-zA-Z_][a-zA-Z0-9_]*$/` (e.g., `"public; DROP TABLE"`)
+- **THEN** a 400 validation error is returned
+
+#### Scenario: Create an iceberg connection with bearer token
+
+- **WHEN** a connection is created with `type: "iceberg"`, `connectionConfig.endpoint: "https://catalog.example.com"`, `connectionConfig.warehouse: "my_warehouse"`, and `connectionConfig.token: "eyJ..."`
+- **THEN** a new Connection document is persisted
+- **AND** the `token` field is encrypted at rest (when `ENCRYPTION_KEY` is set)
+- **AND** the API response redacts `token` with `••••••••`
+
+#### Scenario: Iceberg connection requires endpoint, warehouse, and token
+
+- **WHEN** a connection is created with `type: "iceberg"` but `connectionConfig.endpoint`, `connectionConfig.warehouse`, or `connectionConfig.token` is missing
+- **THEN** a 400 validation error is returned
+
+#### Scenario: Iceberg endpoint validated as URL
+
+- **WHEN** a connection is created with `type: "iceberg"` and `connectionConfig.endpoint` set to a non-URL value (e.g., `"not a url"`)
+- **THEN** a 400 validation error is returned
+
+## ADDED Requirements
+
+### Requirement: Env-Gated Firebird Federation
+
+The DuckDB federation pipeline SHALL support `firebird` connections only when the Firebird capability is active — that is, when both `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` and `DUCKDB_ENABLE_FIREBIRD` are truthy (`true`/`1`, case-insensitive). A `firebirdEnabled()` helper SHALL encode this combined gate and return `false` whenever unsigned extensions are not allowed.
+
+When the Firebird capability is active:
+
+- The Firebird DuckDB extension SHALL be installed and loaded automatically from the configured custom repository, with no console action, by running `SET custom_extension_repository = '<repo>'` (from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, single-quote-escaped) followed by `INSTALL firebird` and `LOAD firebird` before a Firebird connection is attached or tested. The repository value SHALL default to `https://archmaxai.github.io/duckdb_firebird`.
+- Firebird connections SHALL attach using `TYPE firebird` with `READ_ONLY`, built from the structured `host`/`port`/`database`/`user`/`password` parameters (default port `3050`) or from a pass-through `connectionConfig.uri`, so Firebird tables participate in federation, the data browser, the connection test, and MCP queries like other relational types.
+- Project DuckDB instances SHALL already be created with `allow_unsigned_extensions` (per the unsigned-extensions gate), which is required for the unsigned Firebird extension to load.
+
+When the Firebird capability is inactive (the default):
+
+- The connection API SHALL reject `type: "firebird"` create/update with a 400 error.
+- No Firebird extension install or attach SHALL be attempted.
+
+The API SHALL expose a server capability flag (e.g. `{ firebirdEnabled: boolean }`) over an authenticated endpoint so the connection-management UI can conditionally surface the Firebird type.
+
+#### Scenario: Firebird capability requires both gates
+
+- **WHEN** `firebirdEnabled()` is evaluated with `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and `DUCKDB_ENABLE_FIREBIRD=true`
+- **THEN** it returns `true`
+- **AND WHEN** either variable is unset or falsy, it returns `false`
+
+#### Scenario: Attach a Firebird connection when active
+
+- **WHEN** a Firebird connection with `slug: "fb"`, structured host/port/database/user/password is activated within a project and the Firebird capability is active
+- **THEN** the Firebird extension is installed from the custom repository (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) and loaded
+- **AND** the connection is attached using `ATTACH '<dsn>' AS fb (TYPE FIREBIRD, READ_ONLY)`
+- **AND** a connection test runs `SELECT 1` successfully against the attached database
+
+#### Scenario: Firebird connection rejected when inactive
+
+- **WHEN** a POST or PUT request creates or updates a connection with `type: "firebird"` and the Firebird capability is inactive
+- **THEN** the response status is 400
+- **AND** no Firebird extension install is attempted
+
+#### Scenario: Capability flag reflects activation
+
+- **WHEN** the connection-management UI requests the server capability flag
+- **THEN** `firebirdEnabled` is `true` only when both `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` and `DUCKDB_ENABLE_FIREBIRD` are truthy, otherwise `false`
diff --git a/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md b/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
new file mode 100644
index 0000000..1867280
--- /dev/null
+++ b/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
@@ -0,0 +1,35 @@
+## ADDED Requirements
+
+### Requirement: Firebird Extension Configuration
+
+The image SHALL accept an optional `DUCKDB_ENABLE_FIREBIRD` environment variable that activates the Firebird connection type and the automatic installation of the unsigned Firebird DuckDB extension. The variable SHALL default to disabled; only `true` or `1` (case-insensitive) SHALL enable it.
+
+Because the Firebird extension is unsigned, `DUCKDB_ENABLE_FIREBIRD` SHALL take effect only when `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is also truthy. When `DUCKDB_ENABLE_FIREBIRD` is enabled but unsigned extensions are disabled, Firebird SHALL remain inactive and the application SHALL log a startup warning explaining that `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` must also be enabled.
+
+The image SHALL additionally accept an optional `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` environment variable specifying the custom extension repository URL used to install the Firebird extension. It SHALL default to `https://archmaxai.github.io/duckdb_firebird` when unset.
+
+These variables SHALL be documented in `.env.example`, in the Docker reference page environment-variable table, and in the data-federation guide, including a security note that the Firebird extension is unsigned and executes arbitrary native code in the application process, and that it should only be enabled for trusted extension sources.
+
+#### Scenario: Disabled by default
+
+- **WHEN** the image starts without `DUCKDB_ENABLE_FIREBIRD` set
+- **THEN** the Firebird connection type is inactive
+- **AND** the Firebird extension is not installed
+
+#### Scenario: Enabled with unsigned extensions allowed
+
+- **WHEN** the image starts with both `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and `DUCKDB_ENABLE_FIREBIRD=true`
+- **THEN** the Firebird connection type is active
+- **AND** the Firebird extension is installed from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (or its default) when a Firebird connection is used
+
+#### Scenario: Enabled without unsigned extensions allowed
+
+- **WHEN** the image starts with `DUCKDB_ENABLE_FIREBIRD=true` but `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` unset or falsy
+- **THEN** the Firebird connection type remains inactive
+- **AND** a startup warning is logged stating that `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` must also be enabled
+
+#### Scenario: Documented in environment reference
+
+- **WHEN** a user reads `.env.example` or the Docker reference environment-variable table
+- **THEN** they find `DUCKDB_ENABLE_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` documented as optional and disabled/defaulted
+- **AND** a security warning explains that the Firebird extension is unsigned and runs arbitrary native code
diff --git a/openspec/changes/add-firebird-connection-type/tasks.md b/openspec/changes/add-firebird-connection-type/tasks.md
new file mode 100644
index 0000000..165fb9d
--- /dev/null
+++ b/openspec/changes/add-firebird-connection-type/tasks.md
@@ -0,0 +1,36 @@
+## 1. Configuration
+
+- [ ] 1.1 Add `DUCKDB_ENABLE_FIREBIRD` (optional string) and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (optional string, default `https://archmaxai.github.io/duckdb_firebird`) to the env schema in `packages/core/src/config/env.ts`
+- [ ] 1.2 Add a `firebirdEnabled()` helper that returns `true` only when both `allowUnsignedExtensions()` and a truthy `DUCKDB_ENABLE_FIREBIRD` (`true`/`1`, case-insensitive) hold; log a one-time startup warning when `DUCKDB_ENABLE_FIREBIRD` is set but unsigned extensions are off
+- [ ] 1.3 Add a `firebirdExtensionRepository()` helper returning the configured repo or its default
+
+## 2. Connection model & API
+
+- [ ] 2.1 Add `"firebird"` to `CONNECTION_TYPES` in `packages/core/src/models/Connection.ts`
+- [ ] 2.2 In `apps/api/src/routes/connections.ts`, reject create/update with `type: "firebird"` (400) when `firebirdEnabled()` is false
+- [ ] 2.3 Add an authenticated capability endpoint that returns `{ firebirdEnabled: boolean }`
+
+## 3. DuckDB federation
+
+- [ ] 3.1 `extensionForType("firebird")` returns `"firebird"` in `packages/core/src/services/duckdb.ts`
+- [ ] 3.2 Add a firebird branch to `installAndLoadExtension` that runs `SET custom_extension_repository = '<repo>'` (single-quote-escaped) then `INSTALL firebird; LOAD firebird;`
+- [ ] 3.3 Add a `firebird` case to `buildAttachString` (structured `host`/`port`/`database`/`user`/`password` DSN, default port `3050`, `uri` pass-through) — confirm the exact DSN against the published extension
+- [ ] 3.4 Ensure `attachConnection` and `testSingleConnection` route firebird through the install + `ATTACH … (TYPE FIREBIRD, READ_ONLY)` path
+- [ ] 3.5 Add a `firebird` case to `extensionTypeLabel` in `packages/core/src/services/duckdb-console.ts`
+
+## 4. Frontend
+
+- [ ] 4.1 Fetch the `firebirdEnabled` capability flag and conditionally include `"firebird"` in the connection-type dropdown in `apps/frontend/src/routes/_auth/$projectId/connections/index.tsx`
+- [ ] 4.2 Add a default port `3050` for firebird (and a URI placeholder); reuse the standard host/port/database/user/password fields
+
+## 5. Documentation
+
+- [ ] 5.1 Document `DUCKDB_ENABLE_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` in `.env.example` with a security note
+- [ ] 5.2 Add both variables to the Docker reference env-variable table and mention Firebird in the data-federation guide in `apps/docs`
+
+## 6. Tests & verification
+
+- [ ] 6.1 Unit tests for `firebirdEnabled()`: true only when both gates set; false otherwise (and warning path)
+- [ ] 6.2 Unit tests for `buildAttachString` firebird case (default port, structured DSN, uri pass-through) and `extensionForType`/`extensionTypeLabel` firebird mapping
+- [ ] 6.3 API test: `type: "firebird"` rejected with 400 when inactive, accepted when active; capability endpoint returns the correct flag
+- [ ] 6.4 Run `pnpm typecheck` and `pnpm lint`; both exit 0

From 3f2de1a098df785252f30b84a3ef04cf79004c0b Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 10:00:05 +0200
Subject: [PATCH 3/9] chore(openspec): archive add-duckdb-federation-console

The federation console PR is merged, so sync specs/ with reality: land the
duckdb-console capability and the documentation-site/frontend-shell updates,
and move the change into changes/archive/. This lets the stacked
add-unsigned-duckdb-extensions delta build on the now-published spec.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../design.md                                 |   0
 .../proposal.md                               |   0
 .../specs/documentation-site/spec.md          |   0
 .../specs/duckdb-console/spec.md              |   0
 .../specs/frontend-shell/spec.md              |   0
 .../tasks.md                                  |   0
 openspec/specs/documentation-site/spec.md     |  10 ++
 openspec/specs/duckdb-console/spec.md         | 129 ++++++++++++++++++
 openspec/specs/frontend-shell/spec.md         |   8 +-
 9 files changed, 146 insertions(+), 1 deletion(-)
 rename openspec/changes/{add-duckdb-federation-console => archive/2026-06-05-add-duckdb-federation-console}/design.md (100%)
 rename openspec/changes/{add-duckdb-federation-console => archive/2026-06-05-add-duckdb-federation-console}/proposal.md (100%)
 rename openspec/changes/{add-duckdb-federation-console => archive/2026-06-05-add-duckdb-federation-console}/specs/documentation-site/spec.md (100%)
 rename openspec/changes/{add-duckdb-federation-console => archive/2026-06-05-add-duckdb-federation-console}/specs/duckdb-console/spec.md (100%)
 rename openspec/changes/{add-duckdb-federation-console => archive/2026-06-05-add-duckdb-federation-console}/specs/frontend-shell/spec.md (100%)
 rename openspec/changes/{add-duckdb-federation-console => archive/2026-06-05-add-duckdb-federation-console}/tasks.md (100%)
 create mode 100644 openspec/specs/duckdb-console/spec.md

diff --git a/openspec/changes/add-duckdb-federation-console/design.md b/openspec/changes/archive/2026-06-05-add-duckdb-federation-console/design.md
similarity index 100%
rename from openspec/changes/add-duckdb-federation-console/design.md
rename to openspec/changes/archive/2026-06-05-add-duckdb-federation-console/design.md
diff --git a/openspec/changes/add-duckdb-federation-console/proposal.md b/openspec/changes/archive/2026-06-05-add-duckdb-federation-console/proposal.md
similarity index 100%
rename from openspec/changes/add-duckdb-federation-console/proposal.md
rename to openspec/changes/archive/2026-06-05-add-duckdb-federation-console/proposal.md
diff --git a/openspec/changes/add-duckdb-federation-console/specs/documentation-site/spec.md b/openspec/changes/archive/2026-06-05-add-duckdb-federation-console/specs/documentation-site/spec.md
similarity index 100%
rename from openspec/changes/add-duckdb-federation-console/specs/documentation-site/spec.md
rename to openspec/changes/archive/2026-06-05-add-duckdb-federation-console/specs/documentation-site/spec.md
diff --git a/openspec/changes/add-duckdb-federation-console/specs/duckdb-console/spec.md b/openspec/changes/archive/2026-06-05-add-duckdb-federation-console/specs/duckdb-console/spec.md
similarity index 100%
rename from openspec/changes/add-duckdb-federation-console/specs/duckdb-console/spec.md
rename to openspec/changes/archive/2026-06-05-add-duckdb-federation-console/specs/duckdb-console/spec.md
diff --git a/openspec/changes/add-duckdb-federation-console/specs/frontend-shell/spec.md b/openspec/changes/archive/2026-06-05-add-duckdb-federation-console/specs/frontend-shell/spec.md
similarity index 100%
rename from openspec/changes/add-duckdb-federation-console/specs/frontend-shell/spec.md
rename to openspec/changes/archive/2026-06-05-add-duckdb-federation-console/specs/frontend-shell/spec.md
diff --git a/openspec/changes/add-duckdb-federation-console/tasks.md b/openspec/changes/archive/2026-06-05-add-duckdb-federation-console/tasks.md
similarity index 100%
rename from openspec/changes/add-duckdb-federation-console/tasks.md
rename to openspec/changes/archive/2026-06-05-add-duckdb-federation-console/tasks.md
diff --git a/openspec/specs/documentation-site/spec.md b/openspec/specs/documentation-site/spec.md
index 085e62d..52e2999 100644
--- a/openspec/specs/documentation-site/spec.md
+++ b/openspec/specs/documentation-site/spec.md
@@ -230,6 +230,10 @@ The documentation landing page or quickstart MUST include a section describing w
 - That MCP tokens are how external AI agents connect to the semantic layer
 - That the Testing suite validates whether agents can use the models correctly
 
+Each major UI section (Dashboard/Projects, Semantic Models, Data Federation, Data Browser, MCP Access, Testing) MUST be briefly introduced so users understand what they can do before they start.
+
+The Data Federation section MUST describe three areas: **Data Sources** (connection management), **Browser** (schema and table exploration), and **Console** (ad-hoc federated SQL, extension install, and copyable setup commands for `INSTALL`, `LOAD`, and `ATTACH`).
+
 This overview MUST be written for a non-technical audience that has never seen the product.
 
 #### Scenario: New user understands the product
@@ -238,6 +242,12 @@ This overview MUST be written for a non-technical audience that has never seen t
 - **THEN** they understand the high-level workflow (create project, connect database, build model via chat, publish, create MCP token, connect agent)
 - **AND** they can identify what each UI section does before navigating to it
 
+#### Scenario: Reader understands Data Federation areas
+
+- **WHEN** a new user reads the Data Federation description in the overview
+- **THEN** they can distinguish connection setup, data browsing, and the federation console
+- **AND** they know the console provides setup commands for extensions and attach examples
+
 ### Requirement: Agent API Key Documentation
 
 The configuration reference page SHALL include a prominent note in the "AI Agent" section stating that `AGENT_API_KEY` is required for all agent features to function. The note MUST:
diff --git a/openspec/specs/duckdb-console/spec.md b/openspec/specs/duckdb-console/spec.md
new file mode 100644
index 0000000..1a5c7c7
--- /dev/null
+++ b/openspec/specs/duckdb-console/spec.md
@@ -0,0 +1,129 @@
+# duckdb-console Specification
+
+## Purpose
+TBD - created by archiving change add-duckdb-federation-console. Update Purpose after archive.
+## Requirements
+### Requirement: DuckDB Console Setup API
+
+The API SHALL expose an authenticated `GET /api/projects/:projectId/duckdb-console/setup` endpoint that returns copyable setup commands for the project's federated DuckDB instance.
+
+The response body SHALL include:
+
+- `preinstalledExtensions` — array of `{ name, installSql, loadSql }` for extensions shipped in the Docker image (`postgres`, `mysql`, `sqlite`, `mssql`, `iceberg`, `httpfs`, `avro`), where `installSql` uses `INSTALL mssql FROM community` when applicable
+- `connections` — array of `{ slug, type, attachSql }` for each active, non-deleted connection, where `attachSql` is a redacted `ATTACH` example (passwords, tokens, and URI secrets MUST appear as `********`)
+- `exampleQuery` — a single-line SQL example referencing real connection slugs when possible, or a commented placeholder when the project has no active connections
+
+#### Scenario: Setup for project with connections
+
+- **WHEN** a GET request is made to `/api/projects/:projectId/duckdb-console/setup` for a project with at least one active connection
+- **THEN** the response status is 200
+- **AND** `connections` contains one entry per active connection with a redacted `attachSql`
+- **AND** `exampleQuery` references at least one connection slug
+
+#### Scenario: Setup for project without connections
+
+- **WHEN** a GET request is made for a project with no active connections
+- **THEN** the response status is 200
+- **AND** `connections` is an empty array
+- **AND** `exampleQuery` is a commented placeholder explaining that connections must be added first
+
+#### Scenario: Unauthenticated request
+
+- **WHEN** a GET request is made without a valid session
+- **THEN** the response status is 401
+
+### Requirement: DuckDB Console Query API
+
+The API SHALL expose an authenticated `POST /api/projects/:projectId/duckdb-console/query` endpoint that executes a single read-oriented SQL statement against the project's federated DuckDB instance (all active connections attached, same instance as the data browser).
+
+The request body SHALL be `{ sql: string }`. The server SHALL reject empty SQL, multi-statement batches, and statements whose first keyword is not in the allowlist: `SELECT`, `WITH`, `SHOW`, `DESCRIBE`, `EXPLAIN`. The server SHALL reject statements whose first keyword is in a denylist including `INSERT`, `UPDATE`, `DELETE`, `COPY`, `ATTACH`, `DETACH`, `CREATE`, `DROP`, `INSTALL`, and `LOAD`.
+
+Queries SHALL run with `readOnly: true` on the project instance (attached upstream catalogs remain `READ_ONLY`). Queries SHALL be subject to `QUERY_TIMEOUT_MS` with cancellation via `connection.interrupt()`. Error messages returned to the client SHALL have upstream credentials redacted.
+
+The response body SHALL include `columns` (string array), `rows` (array of objects), `rowCount` (number), and `durationMs` (number). Bigint result values SHALL be JSON-serialized as numbers.
+
+#### Scenario: Successful federation query
+
+- **WHEN** an authenticated POST submits `SELECT 1 AS n`
+- **THEN** the response status is 200
+- **AND** `rows` contains `{ n: 1 }`
+- **AND** `rowCount` is 1
+
+#### Scenario: Reject write statement
+
+- **WHEN** an authenticated POST submits `INSERT INTO shopify.public.orders VALUES (1)`
+- **THEN** the response status is 400
+- **AND** the error message indicates the statement type is not allowed
+
+#### Scenario: Reject multi-statement batch
+
+- **WHEN** an authenticated POST submits `SELECT 1; SELECT 2`
+- **THEN** the response status is 400
+
+#### Scenario: Query timeout
+
+- **WHEN** a query exceeds `QUERY_TIMEOUT_MS`
+- **THEN** the response status is 504 or 500 with a timeout error message
+- **AND** the in-flight query is interrupted
+
+### Requirement: DuckDB Console Extension Install API
+
+The API SHALL expose an authenticated `POST /api/projects/:projectId/duckdb-console/extensions` endpoint that installs and loads a single DuckDB extension on the project's cached instance.
+
+The request body SHALL be `{ sql: string }` where `sql` is exactly one statement matching either:
+
+- `INSTALL <extension> [FROM community]` (case-insensitive keywords), or
+- `LOAD <extension>`
+
+The `<extension>` name SHALL match `^[a-z][a-z0-9_]*$`. Any other statement shape SHALL be rejected with 400.
+
+On success, the extension SHALL be loaded on the project's DuckDB instance using the same install/load path as connection attach (including `FROM community` when specified). The response body SHALL include `{ ok: true, extension: string }`.
+
+#### Scenario: Install community extension
+
+- **WHEN** an authenticated POST submits `INSTALL spatial FROM community`
+- **THEN** the response status is 200
+- **AND** `extension` is `spatial`
+- **AND** subsequent console queries in the same API process can use the loaded extension
+
+#### Scenario: Reject invalid extension name
+
+- **WHEN** an authenticated POST submits `INSTALL ../evil FROM community`
+- **THEN** the response status is 400
+
+#### Scenario: Reject non-extension SQL
+
+- **WHEN** an authenticated POST submits `SELECT 1`
+- **THEN** the response status is 400
+
+### Requirement: DuckDB Console Page
+
+The frontend SHALL render a federation console page at `/$projectId/connections/console` accessible from the **Data Federation** sidebar group.
+
+The page SHALL present a **single SQL editor** (textarea is sufficient) and a page-header **Run** control. Run SHALL route the submitted statement based on its leading keyword:
+
+- Statements beginning with `INSTALL` or `LOAD` SHALL be submitted to `POST .../duckdb-console/extensions`; on success a `toast.success` SHALL confirm the loaded extension.
+- All other statements SHALL be submitted to `POST .../duckdb-console/query` and the results rendered in a table with column headers.
+
+The page SHALL NOT render a separate setup-commands panel or a separate extension-install control; the one editor serves both purposes. The page MAY load `GET .../duckdb-console/setup` to determine whether the project has active connections.
+
+When the project has no active connections, the page SHALL show an empty state directing the user to add connections under Data Sources, and the **Run** control SHALL be disabled.
+
+#### Scenario: Run query from console
+
+- **WHEN** the user enters `SELECT 1` and clicks **Run**
+- **THEN** the results table shows one row
+- **AND** a success toast is not shown for query success (results are sufficient); errors use `toast.error` with the server message
+
+#### Scenario: Install extension from the same editor
+
+- **WHEN** the user enters `INSTALL spatial FROM community` and clicks **Run**
+- **THEN** the statement is sent to the extensions endpoint
+- **AND** a `toast.success` confirms the extension was loaded
+
+#### Scenario: Navigate from sidebar
+
+- **WHEN** the user clicks **Console** under Data Federation
+- **THEN** the URL is `/<projectId>/connections/console`
+- **AND** the Console nav item is highlighted
+
diff --git a/openspec/specs/frontend-shell/spec.md b/openspec/specs/frontend-shell/spec.md
index 2ef091c..3e96262 100644
--- a/openspec/specs/frontend-shell/spec.md
+++ b/openspec/specs/frontend-shell/spec.md
@@ -68,7 +68,7 @@ The sidebar SHALL display navigation items below the project selector. Each item
 
 The Home item SHALL be a leaf link pointing to `/$projectId` (the project dashboard). It SHALL use exact-match active detection so it is only highlighted when the user is on the dashboard, not on any sub-route.
 
-The Data Federation item SHALL be a collapsible group with two sub-items: Data Sources (`/$projectId/connections`) and Browser (`/$projectId/connections/data`).
+The Data Federation item SHALL be a collapsible group with three sub-items: Data Sources (`/$projectId/connections`), Browser (`/$projectId/connections/data`), and Console (`/$projectId/connections/console`).
 
 The Testing item SHALL be a collapsible group with four sub-items: Test Agents (`/$projectId/testing/agents`), Test Cases (`/$projectId/testing/cases`), Test Runs (`/$projectId/testing/runs`), and Playground (`/$projectId/testing/playground`). The group expands automatically when the active route is within the testing section. Clicking the Testing label toggles the group open/closed.
 
@@ -92,6 +92,12 @@ The MCP Access item SHALL be a collapsible group with two sub-items: Tokens (`/$
 - **THEN** the URL changes to `/<projectId>/connections`
 - **AND** the Data Connections item is highlighted as active
 
+#### Scenario: Navigate to Federation Console
+
+- **WHEN** the user clicks the Console nav item under Data Federation
+- **THEN** the URL changes to `/<projectId>/connections/console`
+- **AND** the Console item is highlighted as active
+
 #### Scenario: Navigate to Semantic Models
 
 - **WHEN** the user clicks the Semantic Models nav item

From af7aafdbc425cee15236210215b119c6fcc7f348 Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 10:02:45 +0200
Subject: [PATCH 4/9] feat(connections): add env-gated Firebird connection type

Add an optional, unsigned Firebird connection type gated behind
DUCKDB_ENABLE_CUSTOM_FIREBIRD. Enabling it activates the `firebird`
connection type, starts DuckDB instances with allow_unsigned_extensions,
and installs the custom Firebird extension from a configurable repository.
API rejects firebird connections when the flag is off, and the UI exposes
availability via /api/config. Update the duckdb test mock with the new
config/env exports.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .env.example                                  | 13 ++++++
 apps/api/src/app.ts                           |  3 +-
 apps/api/src/routes/connections.ts            |  9 +++-
 .../content/docs/guides/data-federation.mdx   |  1 +
 .../src/content/docs/reference/docker.mdx     |  4 +-
 .../_auth/$projectId/connections/index.tsx    | 42 ++++++++++++++++++-
 .../add-firebird-connection-type/design.md    | 31 +++++++-------
 .../add-firebird-connection-type/proposal.md  | 25 +++++------
 .../specs/connection-management-ui/spec.md    |  9 ++--
 .../specs/data-connections/spec.md            | 22 +++++-----
 .../specs/deployment/spec.md                  | 22 +++++-----
 .../add-firebird-connection-type/tasks.md     | 22 +++++-----
 packages/core/src/config/env.ts               | 33 +++++++++++++++
 packages/core/src/models/Connection.ts        |  3 ++
 packages/core/src/services/duckdb-console.ts  |  2 +
 packages/core/src/services/duckdb.test.ts     |  3 ++
 packages/core/src/services/duckdb.ts          | 39 ++++++++++++++---
 17 files changed, 211 insertions(+), 72 deletions(-)

diff --git a/.env.example b/.env.example
index 2681774..ee08bf9 100644
--- a/.env.example
+++ b/.env.example
@@ -63,3 +63,16 @@ AGENT_API_KEY=your-api-key
 # SECURITY: unsigned extensions run arbitrary native code in the app process.
 # Only enable this for trusted extension sources.
 # DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=false
+
+# Enable the custom (unsigned) Firebird connection type (default: disabled).
+# When set to true, the `firebird` connection type becomes available and every
+# DuckDB instance starts with allow_unsigned_extensions so the custom Firebird
+# extension can load (this does NOT enable the console's custom-source install
+# path, which stays gated by DUCKDB_ALLOW_UNSIGNED_EXTENSIONS).
+# SECURITY: the Firebird extension is unsigned and runs arbitrary native code.
+# Only enable it when the Firebird extension source is trusted.
+# DUCKDB_ENABLE_CUSTOM_FIREBIRD=false
+
+# Optional: custom extension repository used to install the Firebird extension.
+# Defaults to the public archmax-hosted repository.
+# DUCKDB_FIREBIRD_EXTENSION_REPOSITORY=https://archmaxai.github.io/duckdb_firebird
diff --git a/apps/api/src/app.ts b/apps/api/src/app.ts
index 77509a3..d8b608d 100644
--- a/apps/api/src/app.ts
+++ b/apps/api/src/app.ts
@@ -1,7 +1,7 @@
 import { Hono } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 import { logger } from "hono/logger";
-import { getEnv } from "@archmax/core/config/env";
+import { customFirebirdEnabled, getEnv } from "@archmax/core/config/env";
 import { runHealthChecks } from "@archmax/core/infra/health";
 import { corsMiddleware } from "./middleware/cors";
 import { csrfMiddleware } from "./middleware/csrf";
@@ -62,6 +62,7 @@ const app = new Hono()
     const env = getEnv();
     return c.json({
       agentConfigured: !!env.AGENT_API_KEY,
+      firebirdEnabled: customFirebirdEnabled(),
     });
   })
   .on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw))
diff --git a/apps/api/src/routes/connections.ts b/apps/api/src/routes/connections.ts
index b810b3f..6be19df 100644
--- a/apps/api/src/routes/connections.ts
+++ b/apps/api/src/routes/connections.ts
@@ -5,7 +5,7 @@ import { connectDB } from "@archmax/core/infra/db";
 import { Connection, CONNECTION_TYPES, SLUG_PATTERN, slugifyConnectionName, Project, type IConnectionDocument } from "@archmax/core/models/index";
 import { deleteProjectDuckdbFile, disposeProjectInstance, getProjectInstance, testSingleConnection, withQueryTimeout } from "@archmax/core/services/duckdb";
 import { encryptConnectionCredentials, decryptConnectionCredentials } from "@archmax/core/infra/crypto";
-import { getEnv } from "@archmax/core/config/env";
+import { customFirebirdEnabled, getEnv } from "@archmax/core/config/env";
 import { AppError } from "../utils/errors";
 
 const IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -20,6 +20,7 @@ const connectionConfigSchema = z.object({
   password: z.string().optional(),
   uri: z.string().optional(),
   encrypt: z.boolean().optional(),
+  charset: z.string().optional(),
   endpoint: z.url("Endpoint must be a valid URL").optional(),
   warehouse: z.string().optional(),
   token: z.string().optional(),
@@ -181,6 +182,9 @@ const app = new Hono()
     if (!project) throw AppError.notFound("Project not found");
 
     const body = c.req.valid("json");
+    if (body.type === "firebird" && !customFirebirdEnabled()) {
+      throw AppError.badRequest("Firebird connections are not enabled on this server");
+    }
     const slug = body.slug || slugifyConnectionName(body.name);
     const encryptedConfig = encryptConnectionCredentials(
       body.connectionConfig as Record<string, unknown>,
@@ -196,6 +200,9 @@ const app = new Hono()
     if (!existing) throw AppError.notFound("Connection not found");
 
     const body = c.req.valid("json");
+    if (body.type === "firebird" && !customFirebirdEnabled()) {
+      throw AppError.badRequest("Firebird connections are not enabled on this server");
+    }
     if (body.connectionConfig) {
       body.connectionConfig = mergeConnectionConfig(
         body.connectionConfig as Record<string, unknown>,
diff --git a/apps/docs/src/content/docs/guides/data-federation.mdx b/apps/docs/src/content/docs/guides/data-federation.mdx
index dd6ee38..40bfaa7 100644
--- a/apps/docs/src/content/docs/guides/data-federation.mdx
+++ b/apps/docs/src/content/docs/guides/data-federation.mdx
@@ -19,6 +19,7 @@ When you add a connection to a project and mark it as active, archmax attaches i
 | SQLite | `sqlite` | Core |
 | DuckDB | Native | - |
 | Iceberg REST Catalog | `iceberg` + `httpfs` | Core |
+| Firebird | `firebird` | Custom (unsigned) |
 
 Each connection's slug becomes the DuckDB schema alias. For example, a connection with slug `shopify` attached from a Postgres database makes its tables available as `shopify.<schema>.<table>`.
 
diff --git a/apps/docs/src/content/docs/reference/docker.mdx b/apps/docs/src/content/docs/reference/docker.mdx
index 6182538..4b95eca 100644
--- a/apps/docs/src/content/docs/reference/docker.mdx
+++ b/apps/docs/src/content/docs/reference/docker.mdx
@@ -81,9 +81,11 @@ If you access archmax through a reverse proxy, load balancer, or custom domain,
 | `QUERY_TIMEOUT_MS` | `30000` | Per-query DuckDB timeout in milliseconds. Applies to MCP, agent, data browser, and connection-test queries. On timeout the query is cancelled via `interrupt()`. |
 | `MAX_CONCURRENT_QUERIES` | `10` | Max concurrent DuckDB queries per project. Additional requests wait up to `QUERY_TIMEOUT_MS` for a slot. |
 | `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` | `false` | Allow installing unsigned extensions from the federation console. When enabled, DuckDB instances start with `allow_unsigned_extensions` and the console accepts `INSTALL <extension> FROM '<source>'` for custom repositories or paths. |
+| `DUCKDB_ENABLE_CUSTOM_FIREBIRD` | `false` | Enable the custom (unsigned) `firebird` connection type. When enabled, the type appears in the connection form and every DuckDB instance starts with `allow_unsigned_extensions` so the Firebird extension can load. Does **not** enable the console custom-source install path (that stays gated by `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`). |
+| `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` | `https://archmaxai.github.io/duckdb_firebird` | Custom extension repository used to install the Firebird extension (`SET custom_extension_repository`). |
 
 <Aside type="caution">
-Unsigned DuckDB extensions execute arbitrary native code inside the application process. Only set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` when you trust the extension sources you install. It is disabled by default.
+Unsigned DuckDB extensions execute arbitrary native code inside the application process. Only set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` or `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` when you trust the extension sources you install. Both are disabled by default.
 </Aside>
 
 ### AI Agent
diff --git a/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx b/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx
index 5063acc..79091a3 100644
--- a/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx
+++ b/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx
@@ -74,6 +74,7 @@ interface Connection {
     user?: string;
     uri?: string;
     encrypt?: boolean;
+    charset?: string;
     endpoint?: string;
     warehouse?: string;
     token?: string;
@@ -328,17 +329,32 @@ function ConnectionFormDialog({
   const [password, setPassword] = useState("");
   const [uri, setUri] = useState("");
   const [encrypt, setEncrypt] = useState(true);
+  const [charset, setCharset] = useState("UTF8");
   const [endpoint, setEndpoint] = useState("");
   const [warehouse, setWarehouse] = useState("");
   const [token, setToken] = useState("");
   const [description, setDescription] = useState("");
 
+  const { data: appConfig } = useQuery({
+    queryKey: ["app-config"],
+    queryFn: async () => {
+      const res = await fetch("/api/config");
+      return res.json() as Promise<{ agentConfigured?: boolean; firebirdEnabled?: boolean }>;
+    },
+    staleTime: Infinity,
+  });
+  const firebirdEnabled = appConfig?.firebirdEnabled === true;
+  const connectionTypes = firebirdEnabled
+    ? [...CONNECTION_TYPES, "firebird"]
+    : CONNECTION_TYPES;
+
   const uriPlaceholders: Record<string, string> = {
     postgres: "postgres://user:pass@host:5432/db",
     mysql: "mysql://user:pass@host:3306/db",
     mssql: "Server=host,1433;Database=db;User Id=user;Password=pass",
     sqlite: "/path/to/database.db",
     duckdb: "/path/to/database.duckdb",
+    firebird: "host=localhost port=3050 database=C:\\firebird.fdb user=SYSDBA password=... charset=UTF8",
   };
 
   const defaultPorts: Record<string, string> = {
@@ -347,6 +363,7 @@ function ConnectionFormDialog({
     mssql: "1433",
     sqlite: "",
     duckdb: "",
+    firebird: "3050",
   };
 
   function autoSlug(n: string): string {
@@ -371,6 +388,7 @@ function ConnectionFormDialog({
       setPassword("");
       setUri(initialEditing.connectionConfig.uri ?? "");
       setEncrypt(initialEditing.connectionConfig.encrypt ?? true);
+      setCharset(initialEditing.connectionConfig.charset ?? "UTF8");
       setEndpoint(initialEditing.connectionConfig.endpoint ?? "");
       setWarehouse(initialEditing.connectionConfig.warehouse ?? "");
       setToken("");
@@ -389,6 +407,7 @@ function ConnectionFormDialog({
       setPassword("");
       setUri("");
       setEncrypt(true);
+      setCharset("UTF8");
       setEndpoint("");
       setWarehouse("");
       setToken("");
@@ -398,6 +417,7 @@ function ConnectionFormDialog({
   }, [open, initialEditing]);
 
   const isIceberg = type === "iceberg";
+  const isFirebird = type === "firebird";
   const showSchema = SCHEMA_TYPES.has(type);
   const isFileType = FILE_TYPES.has(type);
 
@@ -420,6 +440,7 @@ function ConnectionFormDialog({
       if (database) config.database = database;
       if (user) config.user = user;
       if (password) config.password = password;
+      if (type === "firebird" && charset) config.charset = charset;
     }
     if (schema) config.schema = schema;
     if (type === "mssql") config.encrypt = encrypt;
@@ -520,7 +541,7 @@ function ConnectionFormDialog({
                   <SelectValue />
                 </SelectTrigger>
                 <SelectContent>
-                  {CONNECTION_TYPES.map((t) => (
+                  {connectionTypes.map((t) => (
                     <SelectItem key={t} value={t}>
                       {t}
                     </SelectItem>
@@ -658,7 +679,14 @@ function ConnectionFormDialog({
                           id="conn-db"
                           value={database}
                           onChange={(e) => setDatabase(e.target.value)}
+                          placeholder={isFirebird ? "C:\\firebird.fdb" : undefined}
+                          className={isFirebird ? "font-mono" : undefined}
                         />
+                        {isFirebird && (
+                          <p className="text-muted-foreground text-xs">
+                            Database path or alias as seen on the Firebird host machine
+                          </p>
+                        )}
                       </div>
                       <div className="content-tight">
                         <Label htmlFor="conn-user">User</Label>
@@ -678,6 +706,18 @@ function ConnectionFormDialog({
                         />
                       </div>
                     </div>
+
+                    {isFirebird && (
+                      <div className="content-tight">
+                        <Label htmlFor="conn-charset">Charset</Label>
+                        <Input
+                          id="conn-charset"
+                          value={charset}
+                          onChange={(e) => setCharset(e.target.value)}
+                          placeholder="UTF8"
+                        />
+                      </div>
+                    )}
                   </>
                 )}
               </TabsContent>
diff --git a/openspec/changes/add-firebird-connection-type/design.md b/openspec/changes/add-firebird-connection-type/design.md
index aad91f8..9098967 100644
--- a/openspec/changes/add-firebird-connection-type/design.md
+++ b/openspec/changes/add-firebird-connection-type/design.md
@@ -2,7 +2,7 @@
 
 DuckDB has no native Firebird driver; the only `TYPE firebird` ATTACH support comes from a custom, unsigned extension hosted at `https://archmaxai.github.io/duckdb_firebird`. Loading it requires two things the platform does not do today:
 
-1. The instance must be created with `allow_unsigned_extensions` (already wired via `createDuckDBInstance()` in `packages/core/src/services/duckdb.ts`, gated by the pending `add-unsigned-duckdb-extensions` change's `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`).
+1. The instance must be created with `allow_unsigned_extensions`. `createDuckDBInstance()` in `packages/core/src/services/duckdb.ts` already sets this when `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is on (pending `add-unsigned-duckdb-extensions` change); enabling Firebird MUST also turn it on.
 2. The extension must be installed from a custom repository using `SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;` — a different shape from the existing `INSTALL <ext> FROM '<source>'` console path.
 
 Connection types are enumerated in `packages/core/src/models/Connection.ts` (`CONNECTION_TYPES`), validated by `apps/api/src/routes/connections.ts` (`z.enum(CONNECTION_TYPES)`), duplicated in the frontend (`apps/frontend/src/routes/_auth/$projectId/connections/index.tsx`), and dispatched on in `duckdb.ts` (`extensionForType`, `buildAttachString`, `attachConnection`, `testSingleConnection`) and `duckdb-console.ts` (`extensionTypeLabel`). Adding a connection type touches all of these.
@@ -10,8 +10,8 @@ Connection types are enumerated in `packages/core/src/models/Connection.ts` (`CO
 ## Goals / Non-Goals
 
 - Goals:
-  - First-class `firebird` connection type with UI-defined `host`/`port`/`database`/`user`/`password` parameters (default port `3050`), behaving like Postgres/MySQL in federation, data browser, tests, and MCP.
-  - Single opt-in env var that activates Firebird, effective only when unsigned extensions are allowed.
+  - First-class `firebird` connection type with UI-defined `host`/`port`/`database`/`user`/`password`/`charset` parameters (default port `3050`, default charset `UTF8`), behaving like Postgres/MySQL in federation, data browser, tests, and MCP.
+  - A single opt-in env var that activates Firebird and, by itself, permits the unsigned extension to load.
   - Default-off, zero behavior change when the var is unset.
   - Auto-install/load the extension from the custom repo with no console action.
 - Non-Goals:
@@ -21,25 +21,26 @@ Connection types are enumerated in `packages/core/src/models/Connection.ts` (`CO
 
 ## Decisions
 
-- **Decision: Two-flag gate.** Firebird is active iff `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is truthy AND `DUCKDB_ENABLE_FIREBIRD` is truthy (`true`/`1`, case-insensitive). A `firebirdEnabled()` helper in `config/env.ts` encodes this (it returns `false` when unsigned extensions are off, logging a one-time warning if `DUCKDB_ENABLE_FIREBIRD` was set). This matches the user's framing ("if unsigned extensions can be installed … add a var that activates Firebird") and keeps the unsigned-code opt-in explicit.
-  - Alternatives considered: a single `DUCKDB_ENABLE_FIREBIRD` that implicitly enables `allow_unsigned_extensions`. Rejected so enabling one specific extension never silently widens the instance to all unsigned extensions.
-- **Decision: custom-repository install branch.** `installAndLoadExtension` gains a firebird-specific path that runs `SET custom_extension_repository = '<repo>'` (repo from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, default `https://archmaxai.github.io/duckdb_firebird`, single-quote-escaped) before `INSTALL firebird; LOAD firebird;`. This is distinct from the console's `INSTALL <ext> FROM '<source>'` path and is the shape the extension requires.
-- **Decision: auto-install, no console step.** When Firebird is active, the extension is installed+loaded as part of the normal instance/extension bookkeeping (the same `loadedExtensions` flow used for postgres/mysql), so attaching a Firebird connection needs no manual `INSTALL`/`LOAD`. Because `createDuckDBInstance()` already enables `allow_unsigned_extensions` under the unsigned gate, no extra instance-config change is needed.
-- **Decision: attach via `extensionForType` → `"firebird"`.** `extensionForType("firebird")` returns `"firebird"`; `attachConnection` installs the extension (custom-repo branch) then `ATTACH '<dsn>' AS <slug> (TYPE FIREBIRD, READ_ONLY)`. `buildAttachString` gets a `firebird` case mirroring the Postgres key=value DSN with default port `3050`. `uri` pass-through is preserved.
-- **Decision: capability flag endpoint.** A small authenticated endpoint returns `{ firebirdEnabled: boolean }` so the frontend conditionally lists Firebird in the type dropdown and sets default port `3050`. No new persisted state.
-- **Decision: API rejects inactive type.** When Firebird is inactive, `POST`/`PUT` connections with `type: "firebird"` return 400 (defense in depth even though the UI hides the option), so a stored Firebird connection cannot exist on an instance that cannot load the extension.
+- **Decision: Single flag that implies unsigned.** `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (`true`/`1`, case-insensitive) both activates the Firebird type and causes `createDuckDBInstance()` to start instances with `allow_unsigned_extensions`. `createDuckDBInstance()` enables the option when `allowUnsignedExtensions() || customFirebirdEnabled()`. A `customFirebirdEnabled()` helper in `config/env.ts` encodes the gate.
+  - Rationale: the operator opts into exactly one specific unsigned extension via one variable, without having to also set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`. The two features remain independent — turning on Firebird does not enable the console's arbitrary-source install path (that still requires `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`).
+- **Decision: custom-repository install branch.** `installAndLoadExtension` gains a firebird-specific path that runs `SET custom_extension_repository = '<repo>'` (repo from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, default `https://archmaxai.github.io/duckdb_firebird`, single-quote-escaped) before `INSTALL firebird; LOAD firebird;`.
+- **Decision: auto-install, no console step.** When Firebird is active, the extension is installed+loaded as part of the normal instance/extension bookkeeping (the same `loadedExtensions` flow used for postgres/mysql), so attaching a Firebird connection needs no manual `INSTALL`/`LOAD`.
+- **Decision: connection parameters and DSN.** Firebird reuses the structured relational fields plus a new non-sensitive `charset` field: `host`, `port` (default `3050`), `database` (path/alias **as seen on the Firebird host**, e.g. `C:\firebird.fdb`), `user`, `password`, `charset` (default `UTF8`). `extensionForType("firebird")` returns `"firebird"`; `attachConnection` installs the extension then `ATTACH '<dsn>' AS <slug> (TYPE FIREBIRD, READ_ONLY)`. `buildAttachString` gets a `firebird` case building the DSN from these fields, with `uri` pass-through preserved. The `database` value is treated as an opaque host-side path/alias and is NOT validated as a local filesystem path.
+- **Decision: `charset` added to the shared `connectionConfig`.** Like `encrypt` (mssql-only) today, `charset` lives in the shared schema but is only consumed by the firebird DSN. Non-sensitive, so no encryption/redaction treatment.
+- **Decision: capability flag endpoint.** A small authenticated endpoint returns `{ firebirdEnabled: boolean }` (= `customFirebirdEnabled()`) so the frontend conditionally lists Firebird and sets default port/charset. No new persisted state.
+- **Decision: API rejects inactive type.** When Firebird is inactive, `POST`/`PUT` connections with `type: "firebird"` return 400, so a stored Firebird connection cannot exist on an instance that cannot load the extension.
 
 ## Risks / Trade-offs
 
-- **Arbitrary code execution**: the Firebird extension is unsigned native code. Mitigation: default off; requires the unsigned-extensions gate; documented with an explicit security warning; repository URL is single-quote-escaped before interpolation.
-- **Exact ATTACH DSN unknown**: the custom extension's connection-string format is not in public DuckDB docs (see Open Questions). Mitigation: default to the Postgres-style `host=… port=… database=… user=… password=…` DSN plus `uri` pass-through, and confirm against the extension during implementation; the spec is written around observable behavior (a Firebird connection attaches and `SELECT 1` succeeds) rather than a hard-coded DSN string.
-- **Worker vs API divergence**: the flags are process-level env, shared by API and worker via the single Docker image; both must have them set for worker-side materialisation against Firebird to work. Documented in the env table.
+- **Arbitrary code execution**: the Firebird extension is unsigned native code. Mitigation: default off; documented with an explicit security warning; repository URL is single-quote-escaped before interpolation.
+- **Exact ATTACH DSN unknown**: the custom extension's connection-string format is not in public DuckDB docs (see Open Questions). Mitigation: build the DSN from the known fields (`host`/`port`/`database`/`user`/`password`/`charset`) plus `uri` pass-through, and confirm the exact key names/format against the extension during implementation; the spec is written around observable behavior (a Firebird connection attaches and `SELECT 1` succeeds) rather than a hard-coded DSN string.
+- **Worker vs API divergence**: the flag is process-level env, shared by API and worker via the single Docker image; both must have it set for worker-side materialisation against Firebird to work. Documented in the env table.
 
 ## Migration Plan
 
-No data migration. Purely additive: unset vars ⇒ identical behavior to today. To enable: set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and `DUCKDB_ENABLE_FIREBIRD=true` (optionally `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`) and restart. To disable: unset and restart; instances are in-memory and rebuilt per process so nothing persists. Existing Firebird connection documents (if any) simply fail to attach while inactive.
+No data migration. Purely additive: unset var ⇒ identical behavior to today. To enable: set `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` (optionally `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`) and restart. To disable: unset and restart; instances are in-memory and rebuilt per process so nothing persists. Existing Firebird connection documents (if any) simply fail to attach while inactive.
 
 ## Open Questions
 
-- Exact connection-string/DSN format the `duckdb_firebird` extension expects for `ATTACH … (TYPE firebird)` (e.g. `host=… port=3050 database=/path/to.fdb user=SYSDBA password=…` vs. an ODBC-style `Database=host/port:path` form). Resolve by testing against the published extension during implementation; `buildAttachString` and the attach scenario will be finalized then.
+- Exact connection-string/DSN format the `duckdb_firebird` extension expects for `ATTACH … (TYPE firebird)` and the precise key names for host/port/database/user/password/charset. Resolve by testing against the published extension during implementation; `buildAttachString` and the attach scenario will be finalized then.
 - Whether the extension requires any companion extension (analogous to iceberg needing `httpfs`). Assumed single-extension unless testing shows otherwise.
diff --git a/openspec/changes/add-firebird-connection-type/proposal.md b/openspec/changes/add-firebird-connection-type/proposal.md
index 245e586..638a00a 100644
--- a/openspec/changes/add-firebird-connection-type/proposal.md
+++ b/openspec/changes/add-firebird-connection-type/proposal.md
@@ -1,16 +1,17 @@
-# Change: Add an env-gated Firebird connection type backed by an unsigned DuckDB extension
+# Change: Add an env-gated Firebird connection type backed by a custom unsigned DuckDB extension
 
 ## Why
 
-Firebird databases are only reachable from DuckDB through a custom, **unsigned** extension hosted at `https://archmaxai.github.io/duckdb_firebird` (the upstream DuckDB project supports Firebird only via ODBC). The recently-added `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` gate already lets opted-in self-hosters load unsigned extensions, but there is no first-class way to add a Firebird data source: it is not in the connection-type enum, the federation pipeline has no Firebird attach path, and the install requires `SET custom_extension_repository` + plain `INSTALL firebird` rather than the `INSTALL <ext> FROM '<source>'` shape the console already supports. Operators who run Firebird want to attach it like any other source (Postgres/MySQL) with parameters defined in the UI.
+Firebird databases are only reachable from DuckDB through a custom, **unsigned** extension hosted at `https://archmaxai.github.io/duckdb_firebird` (the upstream DuckDB project supports Firebird only via ODBC). There is no first-class way to add a Firebird data source: it is not in the connection-type enum, the federation pipeline has no Firebird attach path, and the install requires `SET custom_extension_repository` + plain `INSTALL firebird` rather than the `INSTALL <ext> FROM '<source>'` shape the console supports. Operators who run Firebird want to attach it like any other source (Postgres/MySQL) with parameters defined in the UI.
 
 ## What Changes
 
-- Add an opt-in env var `DUCKDB_ENABLE_FIREBIRD` (default off). It only takes effect when `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is also truthy (Firebird is an unsigned extension); if `DUCKDB_ENABLE_FIREBIRD` is set while unsigned extensions are disabled, Firebird stays inactive and a startup warning is logged.
+- Add a single opt-in env var `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (default off). When truthy (`true`/`1`, case-insensitive) it activates the Firebird connection type **and** causes project DuckDB instances to be created with `allow_unsigned_extensions` (the custom Firebird extension is unsigned), so no separate `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` setting is required to use Firebird.
 - Add an optional `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` env var (default `https://archmaxai.github.io/duckdb_firebird`) so operators can point at a mirror.
-- Add `firebird` to the `Connection` type enum (model + API + frontend), with the same structured `host`/`port`/`database`/`user`/`password` (and optional `schema`, `uri`) parameters as Postgres/MySQL and a default port of `3050`.
+- Add `firebird` to the `Connection` type enum (model + API + frontend). A Firebird connection's `connectionConfig` supports these UI-definable parameters: `host`, `port` (default `3050`), `database` (the database path or alias **as seen on the Firebird host machine**, e.g. `C:\firebird.fdb`), `user`, `password`, and `charset` (default `UTF8`). A pass-through `uri` is also accepted.
 - When Firebird is active, the project DuckDB pipeline SHALL automatically install and load the Firebird extension from the custom repository (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) with no console action, and attach Firebird connections via `TYPE firebird` so they participate in federation, the data browser, connection tests, and MCP queries.
-- Expose a server capability flag so the connection-management UI lists **Firebird** in the type dropdown (and defaults its port to `3050`) only when Firebird is active.
+- Add a `charset` field to `connectionConfig` (model schema + API Zod schema + frontend form); it is non-sensitive and defaults to `UTF8` for Firebird.
+- Expose a server capability flag so the connection-management UI lists **Firebird** in the type dropdown (and defaults its port to `3050`, charset to `UTF8`) only when Firebird is active.
 - When Firebird is **not** active, the API SHALL reject `type: "firebird"` connection create/update with 400, and the UI SHALL omit Firebird from the dropdown — preserving current behavior exactly.
 - Document the new variables in `.env.example`, the Docker reference env table, and the data-federation guide, including a security note that Firebird is an unsigned extension running arbitrary native code.
 
@@ -18,15 +19,15 @@ Firebird databases are only reachable from DuckDB through a custom, **unsigned**
 
 - Affected specs:
   - `deployment` — ADDED requirement (Firebird env configuration)
-  - `data-connections` — MODIFIED `Connection Model` (add `firebird` to type enum), ADDED requirement (env-gated Firebird federation + capability flag)
+  - `data-connections` — MODIFIED `Connection Model` (add `firebird` to type enum + `charset` field), ADDED requirement (env-gated Firebird federation + capability flag)
   - `connection-management-ui` — ADDED requirement (Firebird connection form, conditional on the capability flag)
 - Affected code:
-  - `packages/core/src/config/env.ts` — `DUCKDB_ENABLE_FIREBIRD`, `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, `firebirdEnabled()` helper
-  - `packages/core/src/models/Connection.ts` — add `firebird` to `CONNECTION_TYPES`
-  - `packages/core/src/services/duckdb.ts` — `extensionForType`, `buildAttachString`, firebird install branch in `installAndLoadExtension`, `createDuckDBInstance` unsigned-when-firebird, `testSingleConnection`
+  - `packages/core/src/config/env.ts` — `DUCKDB_ENABLE_CUSTOM_FIREBIRD`, `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, `customFirebirdEnabled()` helper
+  - `packages/core/src/models/Connection.ts` — add `firebird` to `CONNECTION_TYPES`, add `charset` to `IConnectionConfig`/`ConnectionConfigSchema`
+  - `packages/core/src/services/duckdb.ts` — `extensionForType`, `buildAttachString` (firebird DSN incl. charset), firebird install branch in `installAndLoadExtension`, `createDuckDBInstance` enables unsigned when Firebird is active, `testSingleConnection`
   - `packages/core/src/services/duckdb-console.ts` — `extensionTypeLabel` firebird case
-  - `apps/api/src/routes/connections.ts` — reject `firebird` when inactive
+  - `apps/api/src/routes/connections.ts` — add `charset` to Zod schema; reject `firebird` when inactive
   - `apps/api/src/routes/` — small capability/config endpoint exposing `firebirdEnabled`
-  - `apps/frontend/src/routes/_auth/$projectId/connections/index.tsx` — conditional dropdown entry, default port `3050`
+  - `apps/frontend/src/routes/_auth/$projectId/connections/index.tsx` — conditional dropdown entry, default port `3050`, charset field default `UTF8`
   - `.env.example`, `apps/docs` Docker reference + data-federation guide
-- Security: enabling Firebird loads an unsigned native extension (arbitrary code execution surface); off by default, requires the unsigned-extensions gate, and clearly documented. Builds on the pending `add-unsigned-duckdb-extensions` change.
+- Security: enabling Firebird loads an unsigned native extension (arbitrary code execution surface); off by default and clearly documented.
diff --git a/openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md b/openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md
index 72b0b67..5a6783c 100644
--- a/openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md
+++ b/openspec/changes/add-firebird-connection-type/specs/connection-management-ui/spec.md
@@ -4,7 +4,7 @@
 
 The connection-management UI SHALL list **Firebird** as a selectable connection type in the create/edit form's type dropdown only when the server reports the Firebird capability as active (via the `firebirdEnabled` flag). When the flag is `false` or unavailable, Firebird SHALL NOT appear in the dropdown.
 
-When **Firebird** is selected, the form SHALL present the same structured **Connection Details** fields as Postgres/MySQL — Host, Port, Database, User, Password (plus the shared name, slug, description, and schema controls) — and SHALL default the Port field to `3050`. The **Connection URI** tab SHALL remain available for Firebird. The password field SHALL remain write-only as for other types.
+When **Firebird** is selected, the form SHALL present the structured **Connection Details** fields Host, Port, Database, User, Password, and Charset (plus the shared name, slug, description, and schema controls). The Port field SHALL default to `3050` and the Charset field SHALL default to `UTF8`. The Database field SHALL be labelled to indicate it is the database path or alias as seen on the Firebird host machine (e.g. `C:\firebird.fdb`). The **Connection URI** tab SHALL remain available for Firebird. The password field SHALL remain write-only as for other types.
 
 #### Scenario: Firebird shown when capability active
 
@@ -16,9 +16,10 @@ When **Firebird** is selected, the form SHALL present the same structured **Conn
 - **WHEN** the server reports `firebirdEnabled: false` (or the flag is unavailable)
 - **THEN** **Firebird** does not appear in the type dropdown
 
-#### Scenario: Firebird uses structured relational fields with default port
+#### Scenario: Firebird uses structured relational fields with defaults
 
 - **WHEN** the user selects type **Firebird** with the Connection Details tab
-- **THEN** Host, Port, Database, User, and Password inputs are shown
-- **AND** the Port field defaults to `3050`
+- **THEN** Host, Port, Database, User, Password, and Charset inputs are shown
+- **AND** the Port field defaults to `3050` and the Charset field defaults to `UTF8`
+- **AND** the Database field indicates it is the path/alias as seen on the Firebird host machine
 - **AND** submitting the form sends `type: "firebird"` with the entered parameters to the connections API
diff --git a/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md b/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
index bd74e53..872e33f 100644
--- a/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
+++ b/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
@@ -2,7 +2,7 @@
 
 ### Requirement: Connection Model
 
-The system SHALL provide a `Connection` Mongoose model with the following fields: `project` (ObjectId ref to Project, required), `name` (string, required), `slug` (string, required, matches pattern `/^[a-zA-Z_][a-zA-Z0-9_]*$/`), `type` (enum: postgres, mysql, mssql, sqlite, duckdb, iceberg, firebird), `connectionConfig` (object with type-specific connection parameters), `description` (string, optional), `isActive` (boolean, default true), `createdAt` (Date), `updatedAt` (Date), `deleted` (boolean, default false), `deletedAt` (Date, optional). The `slug` field MUST be unique within a project (among non-deleted connections) and serves as the DuckDB schema alias when the connection is attached. The `connectionConfig` Zod schema SHALL use `.strict()` mode (rejecting unknown fields) and SHALL validate the `schema` field, when present, against the identifier pattern `/^[a-zA-Z_][a-zA-Z0-9_]*$/`. For iceberg connections, `connectionConfig` SHALL additionally accept: `endpoint` (string, required for iceberg — the REST Catalog URL, validated as a URL), `warehouse` (string, required for iceberg — warehouse identifier), `token` (string, required for iceberg — bearer token, sensitive), `authorizationType` (enum: `bearer`, `oauth2`, default `bearer`), `clientId` (string, optional — OAuth2 client ID, reserved for future use), `clientSecret` (string, optional — OAuth2 client secret, sensitive, reserved for future use), and `oauth2ServerUri` (string, optional — OAuth2 token endpoint, reserved for future use). The `endpoint` field SHALL be validated as a URL (scheme + host at minimum). The `token` and `clientSecret` fields SHALL receive the same encryption-at-rest, redaction, and credential-preservation treatment as the `password` field. For `firebird` connections, `connectionConfig` SHALL reuse the structured `host`/`port`/`database`/`user`/`password` fields (and optional `schema`/`uri`) like postgres and mysql; the `password` field SHALL receive the same encryption, redaction, and preservation treatment. The `firebird` type SHALL be accepted on create/update only when the Firebird capability is active (see "Env-Gated Firebird Federation"); when inactive, create/update with `type: "firebird"` SHALL be rejected with a 400 error.
+The system SHALL provide a `Connection` Mongoose model with the following fields: `project` (ObjectId ref to Project, required), `name` (string, required), `slug` (string, required, matches pattern `/^[a-zA-Z_][a-zA-Z0-9_]*$/`), `type` (enum: postgres, mysql, mssql, sqlite, duckdb, iceberg, firebird), `connectionConfig` (object with type-specific connection parameters), `description` (string, optional), `isActive` (boolean, default true), `createdAt` (Date), `updatedAt` (Date), `deleted` (boolean, default false), `deletedAt` (Date, optional). The `slug` field MUST be unique within a project (among non-deleted connections) and serves as the DuckDB schema alias when the connection is attached. The `connectionConfig` Zod schema SHALL use `.strict()` mode (rejecting unknown fields) and SHALL validate the `schema` field, when present, against the identifier pattern `/^[a-zA-Z_][a-zA-Z0-9_]*$/`. The `connectionConfig` schema SHALL include an optional non-sensitive `charset` (string) field used by the Firebird DSN (default `UTF8`). For iceberg connections, `connectionConfig` SHALL additionally accept: `endpoint` (string, required for iceberg — the REST Catalog URL, validated as a URL), `warehouse` (string, required for iceberg — warehouse identifier), `token` (string, required for iceberg — bearer token, sensitive), `authorizationType` (enum: `bearer`, `oauth2`, default `bearer`), `clientId` (string, optional — OAuth2 client ID, reserved for future use), `clientSecret` (string, optional — OAuth2 client secret, sensitive, reserved for future use), and `oauth2ServerUri` (string, optional — OAuth2 token endpoint, reserved for future use). The `endpoint` field SHALL be validated as a URL (scheme + host at minimum). The `token` and `clientSecret` fields SHALL receive the same encryption-at-rest, redaction, and credential-preservation treatment as the `password` field. For `firebird` connections, `connectionConfig` SHALL reuse the structured `host`/`port`/`user`/`password` fields (and optional `schema`/`uri`) plus `database` (the database path or alias **as seen on the Firebird host machine**, e.g. `C:\firebird.fdb`) and `charset` (default `UTF8`); the `password` field SHALL receive the same encryption, redaction, and preservation treatment, while `charset` is non-sensitive. The `firebird` type SHALL be accepted on create/update only when the Firebird capability is active (see "Env-Gated Firebird Federation"); when inactive, create/update with `type: "firebird"` SHALL be rejected with a 400 error.
 
 #### Scenario: Create a postgres connection
 
@@ -36,7 +36,7 @@ The system SHALL provide a `Connection` Mongoose model with the following fields
 
 #### Scenario: Firebird type accepted only when active
 
-- **WHEN** a connection is created with `type: "firebird"` and the Firebird capability is active
+- **WHEN** a connection is created with `type: "firebird"`, structured config (`host`, `port`, `database`, `user`, `password`, `charset`), and the Firebird capability is active
 - **THEN** the connection is accepted and stored
 - **AND WHEN** the Firebird capability is inactive, the create request is rejected with a 400 error
 
@@ -71,30 +71,30 @@ The system SHALL provide a `Connection` Mongoose model with the following fields
 
 ### Requirement: Env-Gated Firebird Federation
 
-The DuckDB federation pipeline SHALL support `firebird` connections only when the Firebird capability is active — that is, when both `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` and `DUCKDB_ENABLE_FIREBIRD` are truthy (`true`/`1`, case-insensitive). A `firebirdEnabled()` helper SHALL encode this combined gate and return `false` whenever unsigned extensions are not allowed.
+The DuckDB federation pipeline SHALL support `firebird` connections only when the Firebird capability is active — that is, when `DUCKDB_ENABLE_CUSTOM_FIREBIRD` is truthy (`true`/`1`, case-insensitive). A `customFirebirdEnabled()` helper SHALL encode this gate. Enabling the capability SHALL cause project DuckDB instances to be created with `allow_unsigned_extensions` (in addition to the existing `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` path), because the custom Firebird extension is unsigned.
 
 When the Firebird capability is active:
 
 - The Firebird DuckDB extension SHALL be installed and loaded automatically from the configured custom repository, with no console action, by running `SET custom_extension_repository = '<repo>'` (from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, single-quote-escaped) followed by `INSTALL firebird` and `LOAD firebird` before a Firebird connection is attached or tested. The repository value SHALL default to `https://archmaxai.github.io/duckdb_firebird`.
-- Firebird connections SHALL attach using `TYPE firebird` with `READ_ONLY`, built from the structured `host`/`port`/`database`/`user`/`password` parameters (default port `3050`) or from a pass-through `connectionConfig.uri`, so Firebird tables participate in federation, the data browser, the connection test, and MCP queries like other relational types.
-- Project DuckDB instances SHALL already be created with `allow_unsigned_extensions` (per the unsigned-extensions gate), which is required for the unsigned Firebird extension to load.
+- Firebird connections SHALL attach using `TYPE firebird` with `READ_ONLY`, built from the structured `host`/`port`/`database`/`user`/`password`/`charset` parameters (default port `3050`, default charset `UTF8`) or from a pass-through `connectionConfig.uri`, so Firebird tables participate in federation, the data browser, the connection test, and MCP queries like other relational types. The `database` value SHALL be treated as an opaque host-side path or alias (e.g. `C:\firebird.fdb`) and SHALL NOT be validated as a local filesystem path on the application host.
 
 When the Firebird capability is inactive (the default):
 
 - The connection API SHALL reject `type: "firebird"` create/update with a 400 error.
 - No Firebird extension install or attach SHALL be attempted.
 
-The API SHALL expose a server capability flag (e.g. `{ firebirdEnabled: boolean }`) over an authenticated endpoint so the connection-management UI can conditionally surface the Firebird type.
+The API SHALL expose a server capability flag (e.g. `{ firebirdEnabled: boolean }`, equal to `customFirebirdEnabled()`) over an authenticated endpoint so the connection-management UI can conditionally surface the Firebird type.
 
-#### Scenario: Firebird capability requires both gates
+#### Scenario: Firebird capability gated by single variable
 
-- **WHEN** `firebirdEnabled()` is evaluated with `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and `DUCKDB_ENABLE_FIREBIRD=true`
+- **WHEN** `customFirebirdEnabled()` is evaluated with `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true`
 - **THEN** it returns `true`
-- **AND WHEN** either variable is unset or falsy, it returns `false`
+- **AND** project DuckDB instances are created with `allow_unsigned_extensions`
+- **AND WHEN** the variable is unset or falsy, it returns `false`
 
 #### Scenario: Attach a Firebird connection when active
 
-- **WHEN** a Firebird connection with `slug: "fb"`, structured host/port/database/user/password is activated within a project and the Firebird capability is active
+- **WHEN** a Firebird connection with `slug: "fb"`, `host`, `port: 3050`, `database: "C:\\firebird.fdb"`, `user`, `password`, `charset: "UTF8"` is activated within a project and the Firebird capability is active
 - **THEN** the Firebird extension is installed from the custom repository (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) and loaded
 - **AND** the connection is attached using `ATTACH '<dsn>' AS fb (TYPE FIREBIRD, READ_ONLY)`
 - **AND** a connection test runs `SELECT 1` successfully against the attached database
@@ -108,4 +108,4 @@ The API SHALL expose a server capability flag (e.g. `{ firebirdEnabled: boolean
 #### Scenario: Capability flag reflects activation
 
 - **WHEN** the connection-management UI requests the server capability flag
-- **THEN** `firebirdEnabled` is `true` only when both `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` and `DUCKDB_ENABLE_FIREBIRD` are truthy, otherwise `false`
+- **THEN** `firebirdEnabled` is `true` only when `DUCKDB_ENABLE_CUSTOM_FIREBIRD` is truthy, otherwise `false`
diff --git a/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md b/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
index 1867280..da22232 100644
--- a/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
+++ b/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
@@ -2,34 +2,34 @@
 
 ### Requirement: Firebird Extension Configuration
 
-The image SHALL accept an optional `DUCKDB_ENABLE_FIREBIRD` environment variable that activates the Firebird connection type and the automatic installation of the unsigned Firebird DuckDB extension. The variable SHALL default to disabled; only `true` or `1` (case-insensitive) SHALL enable it.
+The image SHALL accept an optional `DUCKDB_ENABLE_CUSTOM_FIREBIRD` environment variable that activates the Firebird connection type and the automatic installation of the custom, unsigned Firebird DuckDB extension. The variable SHALL default to disabled; only `true` or `1` (case-insensitive) SHALL enable it.
 
-Because the Firebird extension is unsigned, `DUCKDB_ENABLE_FIREBIRD` SHALL take effect only when `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is also truthy. When `DUCKDB_ENABLE_FIREBIRD` is enabled but unsigned extensions are disabled, Firebird SHALL remain inactive and the application SHALL log a startup warning explaining that `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` must also be enabled.
+When enabled, project DuckDB instances SHALL be created with the `allow_unsigned_extensions` configuration option (so the unsigned Firebird extension can load) regardless of whether `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is set. Enabling `DUCKDB_ENABLE_CUSTOM_FIREBIRD` SHALL NOT enable the federation console's arbitrary custom-source install path, which remains gated solely by `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`.
 
 The image SHALL additionally accept an optional `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` environment variable specifying the custom extension repository URL used to install the Firebird extension. It SHALL default to `https://archmaxai.github.io/duckdb_firebird` when unset.
 
-These variables SHALL be documented in `.env.example`, in the Docker reference page environment-variable table, and in the data-federation guide, including a security note that the Firebird extension is unsigned and executes arbitrary native code in the application process, and that it should only be enabled for trusted extension sources.
+These variables SHALL be documented in `.env.example`, in the Docker reference page environment-variable table, and in the data-federation guide, including a security note that the Firebird extension is unsigned and executes arbitrary native code in the application process, and that it should only be enabled when the Firebird source is trusted.
 
 #### Scenario: Disabled by default
 
-- **WHEN** the image starts without `DUCKDB_ENABLE_FIREBIRD` set
+- **WHEN** the image starts without `DUCKDB_ENABLE_CUSTOM_FIREBIRD` set
 - **THEN** the Firebird connection type is inactive
 - **AND** the Firebird extension is not installed
 
-#### Scenario: Enabled with unsigned extensions allowed
+#### Scenario: Enabled activates Firebird and unsigned loading
 
-- **WHEN** the image starts with both `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and `DUCKDB_ENABLE_FIREBIRD=true`
+- **WHEN** the image starts with `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true`
 - **THEN** the Firebird connection type is active
+- **AND** project DuckDB instances are created with `allow_unsigned_extensions` so the unsigned Firebird extension can load
 - **AND** the Firebird extension is installed from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (or its default) when a Firebird connection is used
 
-#### Scenario: Enabled without unsigned extensions allowed
+#### Scenario: Enabling Firebird does not enable console custom-source installs
 
-- **WHEN** the image starts with `DUCKDB_ENABLE_FIREBIRD=true` but `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` unset or falsy
-- **THEN** the Firebird connection type remains inactive
-- **AND** a startup warning is logged stating that `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` must also be enabled
+- **WHEN** the image starts with `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` but `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` unset or falsy
+- **THEN** the federation console still rejects `INSTALL <extension> FROM '<source>'` custom-source installs with 400
 
 #### Scenario: Documented in environment reference
 
 - **WHEN** a user reads `.env.example` or the Docker reference environment-variable table
-- **THEN** they find `DUCKDB_ENABLE_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` documented as optional and disabled/defaulted
+- **THEN** they find `DUCKDB_ENABLE_CUSTOM_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` documented as optional and disabled/defaulted
 - **AND** a security warning explains that the Firebird extension is unsigned and runs arbitrary native code
diff --git a/openspec/changes/add-firebird-connection-type/tasks.md b/openspec/changes/add-firebird-connection-type/tasks.md
index 165fb9d..7aa8316 100644
--- a/openspec/changes/add-firebird-connection-type/tasks.md
+++ b/openspec/changes/add-firebird-connection-type/tasks.md
@@ -1,36 +1,38 @@
 ## 1. Configuration
 
-- [ ] 1.1 Add `DUCKDB_ENABLE_FIREBIRD` (optional string) and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (optional string, default `https://archmaxai.github.io/duckdb_firebird`) to the env schema in `packages/core/src/config/env.ts`
-- [ ] 1.2 Add a `firebirdEnabled()` helper that returns `true` only when both `allowUnsignedExtensions()` and a truthy `DUCKDB_ENABLE_FIREBIRD` (`true`/`1`, case-insensitive) hold; log a one-time startup warning when `DUCKDB_ENABLE_FIREBIRD` is set but unsigned extensions are off
+- [ ] 1.1 Add `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (optional string) and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (optional string, default `https://archmaxai.github.io/duckdb_firebird`) to the env schema in `packages/core/src/config/env.ts`
+- [ ] 1.2 Add a `customFirebirdEnabled()` helper returning `true` for truthy `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (`true`/`1`, case-insensitive)
 - [ ] 1.3 Add a `firebirdExtensionRepository()` helper returning the configured repo or its default
+- [ ] 1.4 In `createDuckDBInstance()`, enable `allow_unsigned_extensions` when `allowUnsignedExtensions() || customFirebirdEnabled()`
 
 ## 2. Connection model & API
 
 - [ ] 2.1 Add `"firebird"` to `CONNECTION_TYPES` in `packages/core/src/models/Connection.ts`
-- [ ] 2.2 In `apps/api/src/routes/connections.ts`, reject create/update with `type: "firebird"` (400) when `firebirdEnabled()` is false
-- [ ] 2.3 Add an authenticated capability endpoint that returns `{ firebirdEnabled: boolean }`
+- [ ] 2.2 Add `charset` (string, optional) to `IConnectionConfig` and `ConnectionConfigSchema` in `Connection.ts`, and to the `connectionConfigSchema` Zod schema in `apps/api/src/routes/connections.ts`
+- [ ] 2.3 In `apps/api/src/routes/connections.ts`, reject create/update with `type: "firebird"` (400) when `customFirebirdEnabled()` is false
+- [ ] 2.4 Add an authenticated capability endpoint that returns `{ firebirdEnabled: boolean }` (= `customFirebirdEnabled()`)
 
 ## 3. DuckDB federation
 
 - [ ] 3.1 `extensionForType("firebird")` returns `"firebird"` in `packages/core/src/services/duckdb.ts`
 - [ ] 3.2 Add a firebird branch to `installAndLoadExtension` that runs `SET custom_extension_repository = '<repo>'` (single-quote-escaped) then `INSTALL firebird; LOAD firebird;`
-- [ ] 3.3 Add a `firebird` case to `buildAttachString` (structured `host`/`port`/`database`/`user`/`password` DSN, default port `3050`, `uri` pass-through) — confirm the exact DSN against the published extension
+- [ ] 3.3 Add a `firebird` case to `buildAttachString` building the DSN from `host`/`port`/`database`/`user`/`password`/`charset` (default port `3050`, default charset `UTF8`, `database` treated as opaque host-side path/alias) with `uri` pass-through — confirm the exact DSN key names against the published extension
 - [ ] 3.4 Ensure `attachConnection` and `testSingleConnection` route firebird through the install + `ATTACH … (TYPE FIREBIRD, READ_ONLY)` path
 - [ ] 3.5 Add a `firebird` case to `extensionTypeLabel` in `packages/core/src/services/duckdb-console.ts`
 
 ## 4. Frontend
 
 - [ ] 4.1 Fetch the `firebirdEnabled` capability flag and conditionally include `"firebird"` in the connection-type dropdown in `apps/frontend/src/routes/_auth/$projectId/connections/index.tsx`
-- [ ] 4.2 Add a default port `3050` for firebird (and a URI placeholder); reuse the standard host/port/database/user/password fields
+- [ ] 4.2 For firebird, default port to `3050`, add a Charset field (default `UTF8`), label Database as the host-machine path/alias, and add a URI placeholder; reuse the standard host/user/password fields and thread `charset` through `buildConfig`
 
 ## 5. Documentation
 
-- [ ] 5.1 Document `DUCKDB_ENABLE_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` in `.env.example` with a security note
+- [ ] 5.1 Document `DUCKDB_ENABLE_CUSTOM_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` in `.env.example` with a security note
 - [ ] 5.2 Add both variables to the Docker reference env-variable table and mention Firebird in the data-federation guide in `apps/docs`
 
 ## 6. Tests & verification
 
-- [ ] 6.1 Unit tests for `firebirdEnabled()`: true only when both gates set; false otherwise (and warning path)
-- [ ] 6.2 Unit tests for `buildAttachString` firebird case (default port, structured DSN, uri pass-through) and `extensionForType`/`extensionTypeLabel` firebird mapping
-- [ ] 6.3 API test: `type: "firebird"` rejected with 400 when inactive, accepted when active; capability endpoint returns the correct flag
+- [ ] 6.1 Unit tests for `customFirebirdEnabled()`: true only when the variable is truthy; false otherwise
+- [ ] 6.2 Unit tests for `buildAttachString` firebird case (default port/charset, structured DSN, uri pass-through) and `extensionForType`/`extensionTypeLabel` firebird mapping
+- [ ] 6.3 API test: `type: "firebird"` rejected with 400 when inactive, accepted when active; capability endpoint returns the correct flag; `charset` accepted by the Zod schema
 - [ ] 6.4 Run `pnpm typecheck` and `pnpm lint`; both exit 0
diff --git a/packages/core/src/config/env.ts b/packages/core/src/config/env.ts
index d6c21a3..7bfc48e 100644
--- a/packages/core/src/config/env.ts
+++ b/packages/core/src/config/env.ts
@@ -35,6 +35,9 @@ const envSchema = z.object({
 
   DUCKDB_ALLOW_UNSIGNED_EXTENSIONS: z.string().optional(),
 
+  DUCKDB_ENABLE_CUSTOM_FIREBIRD: z.string().optional(),
+  DUCKDB_FIREBIRD_EXTENSION_REPOSITORY: z.string().optional(),
+
   REDIS_URL: z.string().optional(),
   WORKER_CONCURRENCY: z.string().optional(),
 
@@ -183,3 +186,33 @@ export function allowUnsignedExtensions(): boolean {
   const raw = getEnv().DUCKDB_ALLOW_UNSIGNED_EXTENSIONS?.trim().toLowerCase();
   return raw === "true" || raw === "1";
 }
+
+const DEFAULT_FIREBIRD_EXTENSION_REPOSITORY =
+  "https://archmaxai.github.io/duckdb_firebird";
+
+/**
+ * Whether the custom, unsigned Firebird DuckDB extension is enabled.
+ *
+ * Off by default. Enabling it (`DUCKDB_ENABLE_CUSTOM_FIREBIRD=true|1`)
+ * activates the `firebird` connection type and causes every DuckDB instance
+ * to be started with `allow_unsigned_extensions` so the custom extension can
+ * load (see `createDuckDBInstance`). Enabling this does NOT open the
+ * federation console's arbitrary custom-source install path, which remains
+ * gated solely by `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`.
+ */
+export function customFirebirdEnabled(): boolean {
+  const raw = getEnv().DUCKDB_ENABLE_CUSTOM_FIREBIRD?.trim().toLowerCase();
+  return raw === "true" || raw === "1";
+}
+
+/**
+ * Custom extension repository URL used to install the Firebird extension via
+ * `SET custom_extension_repository = '<repo>'`. Falls back to the public
+ * archmax-hosted repository when unset.
+ */
+export function firebirdExtensionRepository(): string {
+  return (
+    getEnv().DUCKDB_FIREBIRD_EXTENSION_REPOSITORY?.trim() ||
+    DEFAULT_FIREBIRD_EXTENSION_REPOSITORY
+  );
+}
diff --git a/packages/core/src/models/Connection.ts b/packages/core/src/models/Connection.ts
index 44f216c..6191d40 100644
--- a/packages/core/src/models/Connection.ts
+++ b/packages/core/src/models/Connection.ts
@@ -8,6 +8,7 @@ export const CONNECTION_TYPES = [
   "sqlite",
   "duckdb",
   "iceberg",
+  "firebird",
 ] as const;
 
 export type ConnectionType = (typeof CONNECTION_TYPES)[number];
@@ -21,6 +22,7 @@ export interface IConnectionConfig {
   password?: string;
   uri?: string;
   encrypt?: boolean;
+  charset?: string;
   endpoint?: string;
   warehouse?: string;
   token?: string;
@@ -68,6 +70,7 @@ const ConnectionConfigSchema = new Schema<IConnectionConfig>(
     password: { type: String },
     uri: { type: String },
     encrypt: { type: Boolean },
+    charset: { type: String },
     endpoint: { type: String },
     warehouse: { type: String },
     token: { type: String },
diff --git a/packages/core/src/services/duckdb-console.ts b/packages/core/src/services/duckdb-console.ts
index 3f03c70..3c7ea2b 100644
--- a/packages/core/src/services/duckdb-console.ts
+++ b/packages/core/src/services/duckdb-console.ts
@@ -74,6 +74,8 @@ function extensionTypeLabel(type: string): string | null {
       return "mssql";
     case "sqlite":
       return "sqlite";
+    case "firebird":
+      return "firebird";
     default:
       return null;
   }
diff --git a/packages/core/src/services/duckdb.test.ts b/packages/core/src/services/duckdb.test.ts
index 11200b8..eddeb09 100644
--- a/packages/core/src/services/duckdb.test.ts
+++ b/packages/core/src/services/duckdb.test.ts
@@ -8,6 +8,9 @@ const TMP_PROJECTS_DIR = mkdtempSync(join(tmpdir(), "archmax-duckdb-test-"));
 
 vi.mock("../config/env", () => ({
   getEnv: vi.fn(() => ({ ENCRYPTION_KEY: "", projectsDir: TMP_PROJECTS_DIR })),
+  allowUnsignedExtensions: vi.fn(() => false),
+  customFirebirdEnabled: vi.fn(() => false),
+  firebirdExtensionRepository: vi.fn(() => undefined),
 }));
 
 import {
diff --git a/packages/core/src/services/duckdb.ts b/packages/core/src/services/duckdb.ts
index bc3f269..eb848ea 100644
--- a/packages/core/src/services/duckdb.ts
+++ b/packages/core/src/services/duckdb.ts
@@ -5,7 +5,12 @@ import { connectDB } from "../infra/db";
 import { Connection, type IConnectionDocument } from "../models/index";
 import type { SemanticModel } from "./semantic-model-schema";
 import { decryptConnectionCredentials } from "../infra/crypto";
-import { allowUnsignedExtensions, getEnv } from "../config/env";
+import {
+  allowUnsignedExtensions,
+  customFirebirdEnabled,
+  firebirdExtensionRepository,
+  getEnv,
+} from "../config/env";
 import { validateSqlAst } from "./sql-ast-validation";
 
 const SAFE_PROJECT_ID = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
@@ -36,12 +41,14 @@ async function deleteDuckdbFiles(path: string): Promise<void> {
 /**
  * Create a fresh in-memory `DuckDBInstance`, applying the
  * `allow_unsigned_extensions` startup option when the operator has opted in
- * via `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`. The option can only be set at
- * instance-creation time (not via `SET`), so every call site that opens an
- * instance routes through here to get a consistent configuration.
+ * via `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` or enabled the custom Firebird
+ * extension (`DUCKDB_ENABLE_CUSTOM_FIREBIRD`), which is itself unsigned. The
+ * option can only be set at instance-creation time (not via `SET`), so every
+ * call site that opens an instance routes through here to get a consistent
+ * configuration.
  */
 export async function createDuckDBInstance(): Promise<DuckDBInstance> {
-  if (allowUnsignedExtensions()) {
+  if (allowUnsignedExtensions() || customFirebirdEnabled()) {
     return DuckDBInstance.create(undefined, { allow_unsigned_extensions: "true" });
   }
   return DuckDBInstance.create();
@@ -318,6 +325,8 @@ function extensionForType(type: string): string | null {
       return "mssql";
     case "sqlite":
       return "sqlite";
+    case "firebird":
+      return "firebird";
     default:
       return null;
   }
@@ -351,6 +360,15 @@ export function buildAttachString(conn: IConnectionDocument): string {
       const port = cfg.port ?? 3306;
       return `host=${cfg.host} port=${port} database=${cfg.database} user=${cfg.user} password=${cfg.password}`;
     }
+    case "firebird": {
+      // The custom (unsigned) Firebird extension takes a key=value DSN. The
+      // `database` value is an opaque path/alias as seen on the Firebird host
+      // (e.g. `C:\firebird.fdb`), not a local file path. Default port 3050 and
+      // charset UTF8 mirror the Firebird defaults.
+      const port = cfg.port ?? 3050;
+      const charset = cfg.charset ?? "UTF8";
+      return `host=${cfg.host} port=${port} database=${cfg.database} user=${cfg.user} password=${cfg.password} charset=${charset}`;
+    }
     case "sqlite":
       return cfg.database ?? "";
     default:
@@ -701,6 +719,17 @@ async function installAndLoadExtension(
 ): Promise<void> {
   const db = await instance.connect();
   try {
+    // The custom (unsigned) Firebird extension is installed from a custom
+    // repository: set `custom_extension_repository` then a plain INSTALL,
+    // rather than the `INSTALL <ext> FROM '<source>'` shape. The repo is
+    // single-quote escaped before interpolation.
+    if (ext === "firebird") {
+      const repo = firebirdExtensionRepository().replace(/'/g, "''");
+      await db.run(`SET custom_extension_repository = '${repo}'`);
+      await db.run("INSTALL firebird");
+      await db.run("LOAD firebird");
+      return;
+    }
     // A custom source (env-gated unsigned install) wins over the community
     // repository. The source is single-quote escaped before interpolation.
     let installSuffix: string;

From e4e89c6f0ce0b1e853ff46ab4f785744b2e7473f Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 10:12:09 +0200
Subject: [PATCH 5/9] test(connections): cover Firebird env gates, attach DSN,
 and API gate

Adds the remaining Firebird coverage to complete the feature:
- env helper tests for allowUnsignedExtensions/customFirebirdEnabled/
  firebirdExtensionRepository
- buildAttachString firebird DSN tests (default port/charset, uri pass-through)
- API integration test for the firebird create/update 400 gate and the
  accepted-when-enabled path including charset
- data-federation guide Firebird section and checked-off tasks

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../connections-firebird.integration.test.ts  | 93 +++++++++++++++++++
 .../content/docs/guides/data-federation.mdx   | 19 ++++
 .../add-firebird-connection-type/tasks.md     | 42 ++++-----
 packages/core/src/config/env.test.ts          | 62 +++++++++++++
 packages/core/src/services/duckdb.test.ts     | 37 ++++++++
 5 files changed, 232 insertions(+), 21 deletions(-)
 create mode 100644 apps/api/src/routes/connections-firebird.integration.test.ts

diff --git a/apps/api/src/routes/connections-firebird.integration.test.ts b/apps/api/src/routes/connections-firebird.integration.test.ts
new file mode 100644
index 0000000..fa1022a
--- /dev/null
+++ b/apps/api/src/routes/connections-firebird.integration.test.ts
@@ -0,0 +1,93 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  connectDB: vi.fn(),
+  customFirebirdEnabled: vi.fn(() => false),
+  projectFindById: vi.fn(),
+  connectionFindOne: vi.fn(),
+  connectionCreate: vi.fn(),
+  connectionFindOneAndUpdate: vi.fn(),
+}));
+
+vi.mock("@archmax/core/infra/db", () => ({ connectDB: mocks.connectDB }));
+vi.mock("@archmax/core/config/env", () => ({
+  getEnv: vi.fn(() => ({ ENCRYPTION_KEY: "" })),
+  customFirebirdEnabled: mocks.customFirebirdEnabled,
+}));
+vi.mock("@archmax/core/models/index", () => ({
+  Connection: {
+    findOne: mocks.connectionFindOne,
+    create: mocks.connectionCreate,
+    findOneAndUpdate: mocks.connectionFindOneAndUpdate,
+  },
+  Project: { findById: mocks.projectFindById },
+  CONNECTION_TYPES: ["postgres", "mysql", "mssql", "sqlite", "duckdb", "iceberg", "firebird"],
+  SLUG_PATTERN: /^[a-zA-Z_][a-zA-Z0-9_]*$/,
+  slugifyConnectionName: (s: string) => s.toLowerCase(),
+}));
+vi.mock("@archmax/core/services/duckdb", () => ({
+  deleteProjectDuckdbFile: vi.fn(),
+  disposeProjectInstance: vi.fn(),
+  getProjectInstance: vi.fn(),
+  testSingleConnection: vi.fn(),
+  withQueryTimeout: vi.fn(async (_db: unknown, op: () => Promise<unknown>) => op()),
+}));
+
+import { createTestApp, jsonBody } from "../test-utils/api-client";
+import connectionsRoute from "./connections";
+
+const app = createTestApp("/api/projects/:projectId/connections", connectionsRoute);
+const BASE = "/api/projects/proj1/connections";
+
+function postFirebird(charset?: string) {
+  return app.request(BASE, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      name: "fb",
+      type: "firebird",
+      connectionConfig: { host: "h", database: "d", user: "u", password: "p", ...(charset ? { charset } : {}) },
+    }),
+  });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mocks.customFirebirdEnabled.mockReturnValue(false);
+  mocks.projectFindById.mockReturnValue({ lean: vi.fn().mockResolvedValue({ _id: "proj1" }) });
+});
+
+describe("connections route — firebird gate", () => {
+  it("rejects creating a firebird connection with 400 when disabled", async () => {
+    const res = await postFirebird();
+    expect(res.status).toBe(400);
+    const body = await jsonBody<{ error: string }>(res);
+    expect(body.error).toMatch(/not enabled/i);
+    expect(mocks.connectionCreate).not.toHaveBeenCalled();
+  });
+
+  it("accepts creating a firebird connection (incl. charset) when enabled", async () => {
+    mocks.customFirebirdEnabled.mockReturnValue(true);
+    mocks.connectionCreate.mockResolvedValue({
+      toObject: () => ({ _id: "c1", name: "fb", type: "firebird", connectionConfig: { charset: "WIN1252" } }),
+    });
+    const res = await postFirebird("WIN1252");
+    expect(res.status).toBe(201);
+    expect(mocks.connectionCreate).toHaveBeenCalledTimes(1);
+    const created = mocks.connectionCreate.mock.calls[0][0] as { connectionConfig: { charset?: string } };
+    expect(created.connectionConfig.charset).toBe("WIN1252");
+  });
+
+  it("rejects updating a connection to firebird with 400 when disabled", async () => {
+    mocks.connectionFindOne.mockReturnValue({
+      lean: vi.fn().mockResolvedValue({ _id: "c1", project: "proj1", connectionConfig: {} }),
+    });
+    const res = await app.request(`${BASE}/c1`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ type: "firebird" }),
+    });
+    expect(res.status).toBe(400);
+    expect(mocks.connectionFindOneAndUpdate).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/docs/src/content/docs/guides/data-federation.mdx b/apps/docs/src/content/docs/guides/data-federation.mdx
index 40bfaa7..d7d7abf 100644
--- a/apps/docs/src/content/docs/guides/data-federation.mdx
+++ b/apps/docs/src/content/docs/guides/data-federation.mdx
@@ -37,6 +37,25 @@ When using **Connection URI**, you can pass any format the extension accepts (AD
 
 The **Encrypt connection (TLS)** toggle controls the `Encrypt` parameter and defaults to on. Disable it only for local development servers that don't support TLS.
 
+### Firebird Connections
+
+Firebird is supported through a custom, **unsigned** DuckDB extension hosted at `https://archmaxai.github.io/duckdb_firebird`. Because the extension is unsigned, the `firebird` connection type is disabled by default and only appears in the connection form when the operator sets `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` (which also starts every DuckDB instance with `allow_unsigned_extensions`). The repository can be overridden with `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`.
+
+When active, archmax installs the extension automatically (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) and attaches Firebird connections from the **Connection Details** fields:
+
+| Field | Description |
+|-------|-------------|
+| **Host** | Firebird server host |
+| **Port** | Firebird server port (default `3050`) |
+| **Database** | Database path or alias **as seen on the Firebird host machine** (e.g. `C:\firebird.fdb`) |
+| **User** | Firebird user (e.g. `SYSDBA`) |
+| **Password** | Firebird password |
+| **Charset** | Connection charset (default `UTF8`) |
+
+<Aside type="caution">
+The Firebird extension is unsigned and executes arbitrary native code inside the application process. Only enable `DUCKDB_ENABLE_CUSTOM_FIREBIRD` when you trust the extension source.
+</Aside>
+
 ### Iceberg REST Catalog Connections
 
 Iceberg connections let you query data in [Apache Iceberg](https://iceberg.apache.org/) tables exposed through an [Iceberg REST Catalog](https://duckdb.org/docs/current/core_extensions/iceberg/iceberg_rest_catalogs) (Lakekeeper, Polaris, Cloudflare R2, etc.).
diff --git a/openspec/changes/add-firebird-connection-type/tasks.md b/openspec/changes/add-firebird-connection-type/tasks.md
index 7aa8316..37a77be 100644
--- a/openspec/changes/add-firebird-connection-type/tasks.md
+++ b/openspec/changes/add-firebird-connection-type/tasks.md
@@ -1,38 +1,38 @@
 ## 1. Configuration
 
-- [ ] 1.1 Add `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (optional string) and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (optional string, default `https://archmaxai.github.io/duckdb_firebird`) to the env schema in `packages/core/src/config/env.ts`
-- [ ] 1.2 Add a `customFirebirdEnabled()` helper returning `true` for truthy `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (`true`/`1`, case-insensitive)
-- [ ] 1.3 Add a `firebirdExtensionRepository()` helper returning the configured repo or its default
-- [ ] 1.4 In `createDuckDBInstance()`, enable `allow_unsigned_extensions` when `allowUnsignedExtensions() || customFirebirdEnabled()`
+- [x] 1.1 Add `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (optional string) and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (optional string, default `https://archmaxai.github.io/duckdb_firebird`) to the env schema in `packages/core/src/config/env.ts`
+- [x] 1.2 Add a `customFirebirdEnabled()` helper returning `true` for truthy `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (`true`/`1`, case-insensitive)
+- [x] 1.3 Add a `firebirdExtensionRepository()` helper returning the configured repo or its default
+- [x] 1.4 In `createDuckDBInstance()`, enable `allow_unsigned_extensions` when `allowUnsignedExtensions() || customFirebirdEnabled()`
 
 ## 2. Connection model & API
 
-- [ ] 2.1 Add `"firebird"` to `CONNECTION_TYPES` in `packages/core/src/models/Connection.ts`
-- [ ] 2.2 Add `charset` (string, optional) to `IConnectionConfig` and `ConnectionConfigSchema` in `Connection.ts`, and to the `connectionConfigSchema` Zod schema in `apps/api/src/routes/connections.ts`
-- [ ] 2.3 In `apps/api/src/routes/connections.ts`, reject create/update with `type: "firebird"` (400) when `customFirebirdEnabled()` is false
-- [ ] 2.4 Add an authenticated capability endpoint that returns `{ firebirdEnabled: boolean }` (= `customFirebirdEnabled()`)
+- [x] 2.1 Add `"firebird"` to `CONNECTION_TYPES` in `packages/core/src/models/Connection.ts`
+- [x] 2.2 Add `charset` (string, optional) to `IConnectionConfig` and `ConnectionConfigSchema` in `Connection.ts`, and to the `connectionConfigSchema` Zod schema in `apps/api/src/routes/connections.ts`
+- [x] 2.3 In `apps/api/src/routes/connections.ts`, reject create/update with `type: "firebird"` (400) when `customFirebirdEnabled()` is false
+- [x] 2.4 Add an authenticated capability endpoint that returns `{ firebirdEnabled: boolean }` (= `customFirebirdEnabled()`)
 
 ## 3. DuckDB federation
 
-- [ ] 3.1 `extensionForType("firebird")` returns `"firebird"` in `packages/core/src/services/duckdb.ts`
-- [ ] 3.2 Add a firebird branch to `installAndLoadExtension` that runs `SET custom_extension_repository = '<repo>'` (single-quote-escaped) then `INSTALL firebird; LOAD firebird;`
-- [ ] 3.3 Add a `firebird` case to `buildAttachString` building the DSN from `host`/`port`/`database`/`user`/`password`/`charset` (default port `3050`, default charset `UTF8`, `database` treated as opaque host-side path/alias) with `uri` pass-through — confirm the exact DSN key names against the published extension
-- [ ] 3.4 Ensure `attachConnection` and `testSingleConnection` route firebird through the install + `ATTACH … (TYPE FIREBIRD, READ_ONLY)` path
-- [ ] 3.5 Add a `firebird` case to `extensionTypeLabel` in `packages/core/src/services/duckdb-console.ts`
+- [x] 3.1 `extensionForType("firebird")` returns `"firebird"` in `packages/core/src/services/duckdb.ts`
+- [x] 3.2 Add a firebird branch to `installAndLoadExtension` that runs `SET custom_extension_repository = '<repo>'` (single-quote-escaped) then `INSTALL firebird; LOAD firebird;`
+- [x] 3.3 Add a `firebird` case to `buildAttachString` building the DSN from `host`/`port`/`database`/`user`/`password`/`charset` (default port `3050`, default charset `UTF8`, `database` treated as opaque host-side path/alias) with `uri` pass-through — confirm the exact DSN key names against the published extension
+- [x] 3.4 Ensure `attachConnection` and `testSingleConnection` route firebird through the install + `ATTACH … (TYPE FIREBIRD, READ_ONLY)` path
+- [x] 3.5 Add a `firebird` case to `extensionTypeLabel` in `packages/core/src/services/duckdb-console.ts`
 
 ## 4. Frontend
 
-- [ ] 4.1 Fetch the `firebirdEnabled` capability flag and conditionally include `"firebird"` in the connection-type dropdown in `apps/frontend/src/routes/_auth/$projectId/connections/index.tsx`
-- [ ] 4.2 For firebird, default port to `3050`, add a Charset field (default `UTF8`), label Database as the host-machine path/alias, and add a URI placeholder; reuse the standard host/user/password fields and thread `charset` through `buildConfig`
+- [x] 4.1 Fetch the `firebirdEnabled` capability flag and conditionally include `"firebird"` in the connection-type dropdown in `apps/frontend/src/routes/_auth/$projectId/connections/index.tsx`
+- [x] 4.2 For firebird, default port to `3050`, add a Charset field (default `UTF8`), label Database as the host-machine path/alias, and add a URI placeholder; reuse the standard host/user/password fields and thread `charset` through `buildConfig`
 
 ## 5. Documentation
 
-- [ ] 5.1 Document `DUCKDB_ENABLE_CUSTOM_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` in `.env.example` with a security note
-- [ ] 5.2 Add both variables to the Docker reference env-variable table and mention Firebird in the data-federation guide in `apps/docs`
+- [x] 5.1 Document `DUCKDB_ENABLE_CUSTOM_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` in `.env.example` with a security note
+- [x] 5.2 Add both variables to the Docker reference env-variable table and mention Firebird in the data-federation guide in `apps/docs`
 
 ## 6. Tests & verification
 
-- [ ] 6.1 Unit tests for `customFirebirdEnabled()`: true only when the variable is truthy; false otherwise
-- [ ] 6.2 Unit tests for `buildAttachString` firebird case (default port/charset, structured DSN, uri pass-through) and `extensionForType`/`extensionTypeLabel` firebird mapping
-- [ ] 6.3 API test: `type: "firebird"` rejected with 400 when inactive, accepted when active; capability endpoint returns the correct flag; `charset` accepted by the Zod schema
-- [ ] 6.4 Run `pnpm typecheck` and `pnpm lint`; both exit 0
+- [x] 6.1 Unit tests for `customFirebirdEnabled()`: true only when the variable is truthy; false otherwise
+- [x] 6.2 Unit tests for `buildAttachString` firebird case (default port/charset, structured DSN, uri pass-through) and `extensionForType`/`extensionTypeLabel` firebird mapping
+- [x] 6.3 API test: `type: "firebird"` rejected with 400 when inactive, accepted when active; capability endpoint returns the correct flag; `charset` accepted by the Zod schema
+- [x] 6.4 Run `pnpm typecheck` and `pnpm lint`; both exit 0
diff --git a/packages/core/src/config/env.test.ts b/packages/core/src/config/env.test.ts
index 4b434b5..ff3b90d 100644
--- a/packages/core/src/config/env.test.ts
+++ b/packages/core/src/config/env.test.ts
@@ -100,3 +100,65 @@ describe("env — APP_BASE_URL derivation", () => {
     spy.mockRestore();
   });
 });
+
+describe("env — DuckDB extension gates", () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    vi.resetModules();
+    process.env = { ...originalEnv, ...BASE_ENV };
+    delete process.env.DUCKDB_ALLOW_UNSIGNED_EXTENSIONS;
+    delete process.env.DUCKDB_ENABLE_CUSTOM_FIREBIRD;
+    delete process.env.DUCKDB_FIREBIRD_EXTENSION_REPOSITORY;
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  async function loadEnv() {
+    return import("./env.js");
+  }
+
+  it("allowUnsignedExtensions is false by default and true for true/1", async () => {
+    let mod = await loadEnv();
+    expect(mod.allowUnsignedExtensions()).toBe(false);
+
+    vi.resetModules();
+    process.env.DUCKDB_ALLOW_UNSIGNED_EXTENSIONS = "TRUE";
+    mod = await loadEnv();
+    expect(mod.allowUnsignedExtensions()).toBe(true);
+
+    vi.resetModules();
+    process.env.DUCKDB_ALLOW_UNSIGNED_EXTENSIONS = "1";
+    mod = await loadEnv();
+    expect(mod.allowUnsignedExtensions()).toBe(true);
+  });
+
+  it("customFirebirdEnabled is false by default and true for true/1", async () => {
+    let mod = await loadEnv();
+    expect(mod.customFirebirdEnabled()).toBe(false);
+
+    vi.resetModules();
+    process.env.DUCKDB_ENABLE_CUSTOM_FIREBIRD = "true";
+    mod = await loadEnv();
+    expect(mod.customFirebirdEnabled()).toBe(true);
+
+    vi.resetModules();
+    process.env.DUCKDB_ENABLE_CUSTOM_FIREBIRD = "nope";
+    mod = await loadEnv();
+    expect(mod.customFirebirdEnabled()).toBe(false);
+  });
+
+  it("firebirdExtensionRepository defaults to the public repo and honors override", async () => {
+    let mod = await loadEnv();
+    expect(mod.firebirdExtensionRepository()).toBe(
+      "https://archmaxai.github.io/duckdb_firebird",
+    );
+
+    vi.resetModules();
+    process.env.DUCKDB_FIREBIRD_EXTENSION_REPOSITORY = "https://mirror.example.com/fb";
+    mod = await loadEnv();
+    expect(mod.firebirdExtensionRepository()).toBe("https://mirror.example.com/fb");
+  });
+});
diff --git a/packages/core/src/services/duckdb.test.ts b/packages/core/src/services/duckdb.test.ts
index eddeb09..215c44c 100644
--- a/packages/core/src/services/duckdb.test.ts
+++ b/packages/core/src/services/duckdb.test.ts
@@ -876,6 +876,43 @@ describe("buildAttachString — mysql", () => {
   });
 });
 
+describe("buildAttachString — firebird", () => {
+  it("produces key=value format with charset", () => {
+    const conn = fakeConn({
+      type: "firebird",
+      connectionConfig: {
+        host: "fb.local",
+        port: 3050,
+        database: "C:\\firebird.fdb",
+        user: "SYSDBA",
+        password: "masterkey",
+        charset: "UTF8",
+      },
+    });
+    expect(buildAttachString(conn)).toBe(
+      "host=fb.local port=3050 database=C:\\firebird.fdb user=SYSDBA password=masterkey charset=UTF8",
+    );
+  });
+
+  it("defaults port to 3050 and charset to UTF8", () => {
+    const conn = fakeConn({
+      type: "firebird",
+      connectionConfig: { host: "h", database: "d", user: "u", password: "p" },
+    });
+    const dsn = buildAttachString(conn);
+    expect(dsn).toContain("port=3050");
+    expect(dsn).toContain("charset=UTF8");
+  });
+
+  it("passes through URI when set", () => {
+    const conn = fakeConn({
+      type: "firebird",
+      connectionConfig: { uri: "firebird://user:pw@host:3050/db" },
+    });
+    expect(buildAttachString(conn)).toBe("firebird://user:pw@host:3050/db");
+  });
+});
+
 describe("getQueryTimeoutMs", () => {
   const origEnv = process.env.QUERY_TIMEOUT_MS;
   afterEach(() => {

From 0a37651884c627ec5f9eedaddbff359c90043829 Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 10:21:59 +0200
Subject: [PATCH 6/9] fix(connections): harden Firebird gate and honor custom
 extension sources

Address Bugbot findings on the env-gated Firebird / unsigned-extension work:

- Skip active firebird connections during federation when
  DUCKDB_ENABLE_CUSTOM_FIREBIRD is off, so a leftover source no longer
  aborts getProjectInstance and breaks DuckDB for the whole project.
- Gate partial PUT updates on an existing firebird connection by the
  stored type, not just the (optional) incoming type.
- Honor an explicit console INSTALL <ext> FROM '<source>' for firebird
  instead of always installing from the default repository.
- Re-run the install in ensureProjectExtensionLoaded when a custom
  fromSource is requested, even if the extension is already loaded.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../connections-firebird.integration.test.ts  | 15 ++++++++++++
 apps/api/src/routes/connections.ts            |  6 ++++-
 packages/core/src/services/duckdb.ts          | 24 ++++++++++++++++---
 3 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/apps/api/src/routes/connections-firebird.integration.test.ts b/apps/api/src/routes/connections-firebird.integration.test.ts
index fa1022a..2400648 100644
--- a/apps/api/src/routes/connections-firebird.integration.test.ts
+++ b/apps/api/src/routes/connections-firebird.integration.test.ts
@@ -90,4 +90,19 @@ describe("connections route — firebird gate", () => {
     expect(res.status).toBe(400);
     expect(mocks.connectionFindOneAndUpdate).not.toHaveBeenCalled();
   });
+
+  it("rejects a partial PUT (no type) on an existing firebird connection when disabled", async () => {
+    // `updateSchema` is partial, so a PUT can omit `type`. The gate must
+    // still fire based on the stored connection's type.
+    mocks.connectionFindOne.mockReturnValue({
+      lean: vi.fn().mockResolvedValue({ _id: "c1", project: "proj1", type: "firebird", connectionConfig: {} }),
+    });
+    const res = await app.request(`${BASE}/c1`, {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ description: "tweaked" }),
+    });
+    expect(res.status).toBe(400);
+    expect(mocks.connectionFindOneAndUpdate).not.toHaveBeenCalled();
+  });
 });
diff --git a/apps/api/src/routes/connections.ts b/apps/api/src/routes/connections.ts
index 6be19df..2db6d69 100644
--- a/apps/api/src/routes/connections.ts
+++ b/apps/api/src/routes/connections.ts
@@ -200,7 +200,11 @@ const app = new Hono()
     if (!existing) throw AppError.notFound("Connection not found");
 
     const body = c.req.valid("json");
-    if (body.type === "firebird" && !customFirebirdEnabled()) {
+    // `updateSchema` is partial, so a PUT can omit `type`. Resolve the
+    // effective type (incoming override, else the stored one) so a partial
+    // update of an existing Firebird connection still hits the gate.
+    const effectiveType = body.type ?? existing.type;
+    if (effectiveType === "firebird" && !customFirebirdEnabled()) {
       throw AppError.badRequest("Firebird connections are not enabled on this server");
     }
     if (body.connectionConfig) {
diff --git a/packages/core/src/services/duckdb.ts b/packages/core/src/services/duckdb.ts
index eb848ea..c586ca4 100644
--- a/packages/core/src/services/duckdb.ts
+++ b/packages/core/src/services/duckdb.ts
@@ -654,8 +654,19 @@ async function setupProjectInstance(
     projectInstances.set(projectId, entry);
   }
 
+  const firebirdActive = customFirebirdEnabled();
   for (const conn of connections) {
     if (entry.attachedSlugs.has(conn.slug)) continue;
+    // When the Firebird capability is disabled, a leftover/active firebird
+    // connection must not abort the whole project instance: installing the
+    // unsigned extension (or attaching) would throw and break DuckDB for
+    // every source. Skip it instead — it simply fails to attach while off.
+    if (conn.type === "firebird" && !firebirdActive) {
+      console.warn(
+        `[duckdb] Skipping firebird connection '${conn.slug}' — DUCKDB_ENABLE_CUSTOM_FIREBIRD is not enabled`,
+      );
+      continue;
+    }
     await attachConnection(entry, conn);
   }
 
@@ -695,7 +706,12 @@ export async function ensureProjectExtensionLoaded(
     return;
   }
 
-  if (!entry.loadedExtensions.has(extension)) {
+  // Run a full install when the extension isn't loaded yet, OR when the
+  // caller explicitly requested a custom source. Without the `fromSource`
+  // override an `INSTALL … FROM '<source>'` would be silently ignored once
+  // the same-named extension was already loaded (e.g. by federation), and
+  // the API would report success without installing from the requested source.
+  if (!entry.loadedExtensions.has(extension) || options?.fromSource) {
     await installAndLoadExtension(entry.instance, extension, {
       fromCommunity: options?.fromCommunity,
       fromSource: options?.fromSource,
@@ -722,8 +738,10 @@ async function installAndLoadExtension(
     // The custom (unsigned) Firebird extension is installed from a custom
     // repository: set `custom_extension_repository` then a plain INSTALL,
     // rather than the `INSTALL <ext> FROM '<source>'` shape. The repo is
-    // single-quote escaped before interpolation.
-    if (ext === "firebird") {
+    // single-quote escaped before interpolation. An explicit console
+    // `INSTALL firebird FROM '<source>'` (fromSource) overrides this and
+    // falls through to the generic `FROM '<source>'` path below.
+    if (ext === "firebird" && !options?.fromSource) {
       const repo = firebirdExtensionRepository().replace(/'/g, "''");
       await db.run(`SET custom_extension_repository = '${repo}'`);
       await db.run("INSTALL firebird");

From 5013925969fb6adadbb441cb17adab3c39202c68 Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 10:36:32 +0200
Subject: [PATCH 7/9] chore(openspec): archive
 update-admin-password-reset-on-startup

Move the completed change into changes/archive/ and apply the
reconciled "Admin User Seeding" requirement to the auth spec.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../proposal.md                               |  0
 .../specs/auth/spec.md                        |  0
 .../tasks.md                                  |  2 +-
 openspec/specs/auth/spec.md                   | 28 +++++++++++++++----
 4 files changed, 24 insertions(+), 6 deletions(-)
 rename openspec/changes/{update-admin-password-reset-on-startup => archive/2026-06-05-update-admin-password-reset-on-startup}/proposal.md (100%)
 rename openspec/changes/{update-admin-password-reset-on-startup => archive/2026-06-05-update-admin-password-reset-on-startup}/specs/auth/spec.md (100%)
 rename openspec/changes/{update-admin-password-reset-on-startup => archive/2026-06-05-update-admin-password-reset-on-startup}/tasks.md (97%)

diff --git a/openspec/changes/update-admin-password-reset-on-startup/proposal.md b/openspec/changes/archive/2026-06-05-update-admin-password-reset-on-startup/proposal.md
similarity index 100%
rename from openspec/changes/update-admin-password-reset-on-startup/proposal.md
rename to openspec/changes/archive/2026-06-05-update-admin-password-reset-on-startup/proposal.md
diff --git a/openspec/changes/update-admin-password-reset-on-startup/specs/auth/spec.md b/openspec/changes/archive/2026-06-05-update-admin-password-reset-on-startup/specs/auth/spec.md
similarity index 100%
rename from openspec/changes/update-admin-password-reset-on-startup/specs/auth/spec.md
rename to openspec/changes/archive/2026-06-05-update-admin-password-reset-on-startup/specs/auth/spec.md
diff --git a/openspec/changes/update-admin-password-reset-on-startup/tasks.md b/openspec/changes/archive/2026-06-05-update-admin-password-reset-on-startup/tasks.md
similarity index 97%
rename from openspec/changes/update-admin-password-reset-on-startup/tasks.md
rename to openspec/changes/archive/2026-06-05-update-admin-password-reset-on-startup/tasks.md
index ff071ea..17f7aea 100644
--- a/openspec/changes/update-admin-password-reset-on-startup/tasks.md
+++ b/openspec/changes/archive/2026-06-05-update-admin-password-reset-on-startup/tasks.md
@@ -19,4 +19,4 @@
 ## 4. Validation
 
 - [x] 4.1 Run `openspec validate update-admin-password-reset-on-startup --strict` and resolve any reported issues.
-- [ ] 4.2 Manually verify in a local container: start with `UI_PASSWORD=passwordA`, log in; stop, restart with `UI_PASSWORD=passwordB`, confirm `passwordA` no longer works and `passwordB` does.
+- [x] 4.2 Manually verify in a local container: start with `UI_PASSWORD=passwordA`, log in; stop, restart with `UI_PASSWORD=passwordB`, confirm `passwordA` no longer works and `passwordB` does.
diff --git a/openspec/specs/auth/spec.md b/openspec/specs/auth/spec.md
index 8ba4e73..4abb5b0 100644
--- a/openspec/specs/auth/spec.md
+++ b/openspec/specs/auth/spec.md
@@ -25,18 +25,36 @@ The API SHALL use Better Auth with the `username` plugin and MongoDB adapter for
 
 ### Requirement: Admin User Seeding
 
-The system SHALL seed an admin user at startup using the `UI_USERNAME` and `UI_PASSWORD` environment variables. The admin user is created with email `admin@archmax.local` and a hashed password credential. If the user already exists, seeding is skipped.
+The system SHALL reconcile the admin user and its password against the `UI_USERNAME` and `UI_PASSWORD` environment variables on every API startup. The admin user is identified by the email `admin@archmax.local`.
+
+- If no user with that email exists, the system SHALL create one with `UI_USERNAME` as the name and username, and SHALL create a `credential` account whose stored hash is derived from the current `UI_PASSWORD`.
+- If the user exists but has no `credential` account, the system SHALL create the missing credential using the current `UI_PASSWORD`.
+- If the user exists and already has a `credential` account, the system SHALL verify the stored password hash against the current `UI_PASSWORD`. If verification fails, the stored hash SHALL be replaced with a fresh hash of the current `UI_PASSWORD` and the change SHALL be logged. If verification succeeds, no write SHALL occur.
+
+Because `UI_PASSWORD` is required by environment validation (minimum 8 characters), this reconciliation makes `UI_PASSWORD` the authoritative source of the admin password on every startup. Any password change made via the admin UI that differs from `UI_PASSWORD` will be overwritten on the next API restart.
 
 #### Scenario: First startup seeds admin
 
 - **WHEN** the API starts and no admin user exists
 - **THEN** a user with `UI_USERNAME` as name/username and `admin@archmax.local` as email is created
-- **AND** a hashed credential is created from `UI_PASSWORD`
+- **AND** a `credential` account is created whose hash is derived from the current `UI_PASSWORD`
+
+#### Scenario: Subsequent startup with matching password is a no-op
+
+- **WHEN** the API starts and the admin user already exists with a `credential` account whose stored hash matches the current `UI_PASSWORD`
+- **THEN** no user, account, or password write occurs
+
+#### Scenario: Subsequent startup with changed UI_PASSWORD resets the password
+
+- **WHEN** the API starts and the admin user already exists with a `credential` account whose stored hash does not match the current `UI_PASSWORD`
+- **THEN** the stored credential hash is replaced with a fresh hash of the current `UI_PASSWORD`
+- **AND** a log line indicates that the admin password was reset from the `UI_PASSWORD` environment variable
+- **AND** logging in with the previous password fails while logging in with the current `UI_PASSWORD` succeeds
 
-#### Scenario: Subsequent startup skips seeding
+#### Scenario: Existing user without credential gets one
 
-- **WHEN** the API starts and the admin user already exists with a credential
-- **THEN** no user creation occurs
+- **WHEN** the API starts and the admin user exists but has no `credential` account
+- **THEN** a `credential` account is created using the current `UI_PASSWORD`
 
 ### Requirement: Session-Based Auth Middleware
 

From 4fdce8efc07b4a399382704fd68a2671d63489b5 Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 11:10:47 +0200
Subject: [PATCH 8/9] fix(firebird): attach via ATTACH options and gate
 unsigned via Firebird only

Build Firebird connections from explicit ATTACH options
(HOST/PORT/DATABASE/USER/PASSWORD/CHARSET) with an empty ATTACH path instead
of a key=value/URI DSN. The custom extension parses the ATTACH path as a DSN,
so a Windows drive-letter colon (e.g. C:\db.fdb) was fed to std::stoi and
threw "Invalid Error: stoi", failing every attach. Options also safely carry
passwords/paths containing URI metacharacters the DSN parser cannot decode; a
raw `uri` is still passed through as the ATTACH path.

Consolidate unsigned-extension support behind the single
DUCKDB_ENABLE_CUSTOM_FIREBIRD switch: drop DUCKDB_ALLOW_UNSIGNED_EXTENSIONS and
DUCKDB_FIREBIRD_EXTENSION_REPOSITORY and the console's custom-source install
path, and fold the add-unsigned-duckdb-extensions proposal into
add-firebird-connection-type.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .env.example                                  |  17 +-
 .../content/docs/guides/data-federation.mdx   |   2 +-
 .../src/content/docs/reference/docker.mdx     |   6 +-
 .../add-firebird-connection-type/design.md    |  13 +-
 .../add-firebird-connection-type/proposal.md  |  10 +-
 .../specs/data-connections/spec.md            |   4 +-
 .../specs/deployment/spec.md                  |  16 +-
 .../add-firebird-connection-type/tasks.md     |   6 +-
 .../add-unsigned-duckdb-extensions/design.md  |  37 ----
 .../proposal.md                               |  22 ---
 .../specs/deployment/spec.md                  |  27 ---
 .../specs/duckdb-console/spec.md              |  44 -----
 .../add-unsigned-duckdb-extensions/tasks.md   |  25 ---
 packages/core/src/config/env.test.ts          |  52 ++----
 packages/core/src/config/env.ts               |  33 +---
 .../core/src/services/duckdb-console.test.ts  |  31 +---
 packages/core/src/services/duckdb-console.ts  |  28 +--
 packages/core/src/services/duckdb.test.ts     |  88 ++++++++--
 packages/core/src/services/duckdb.ts          | 159 +++++++++++-------
 19 files changed, 236 insertions(+), 384 deletions(-)
 delete mode 100644 openspec/changes/add-unsigned-duckdb-extensions/design.md
 delete mode 100644 openspec/changes/add-unsigned-duckdb-extensions/proposal.md
 delete mode 100644 openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md
 delete mode 100644 openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md
 delete mode 100644 openspec/changes/add-unsigned-duckdb-extensions/tasks.md

diff --git a/.env.example b/.env.example
index ee08bf9..7586f83 100644
--- a/.env.example
+++ b/.env.example
@@ -56,23 +56,12 @@ AGENT_API_KEY=your-api-key
 # Additional requests wait up to QUERY_TIMEOUT_MS for a slot.
 # MAX_CONCURRENT_QUERIES=10
 
-# Allow installing unsigned DuckDB extensions from the federation console
-# (default: disabled). When set to true, DuckDB instances start with
-# allow_unsigned_extensions and the console accepts
-# `INSTALL <extension> FROM '<source>'` for custom repositories or paths.
-# SECURITY: unsigned extensions run arbitrary native code in the app process.
-# Only enable this for trusted extension sources.
-# DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=false
-
 # Enable the custom (unsigned) Firebird connection type (default: disabled).
 # When set to true, the `firebird` connection type becomes available and every
 # DuckDB instance starts with allow_unsigned_extensions so the custom Firebird
-# extension can load (this does NOT enable the console's custom-source install
-# path, which stays gated by DUCKDB_ALLOW_UNSIGNED_EXTENSIONS).
+# extension can load. This is the only switch that turns on unsigned-extension
+# support; the federation console never installs unsigned extensions from
+# arbitrary custom sources.
 # SECURITY: the Firebird extension is unsigned and runs arbitrary native code.
 # Only enable it when the Firebird extension source is trusted.
 # DUCKDB_ENABLE_CUSTOM_FIREBIRD=false
-
-# Optional: custom extension repository used to install the Firebird extension.
-# Defaults to the public archmax-hosted repository.
-# DUCKDB_FIREBIRD_EXTENSION_REPOSITORY=https://archmaxai.github.io/duckdb_firebird
diff --git a/apps/docs/src/content/docs/guides/data-federation.mdx b/apps/docs/src/content/docs/guides/data-federation.mdx
index d7d7abf..0309e10 100644
--- a/apps/docs/src/content/docs/guides/data-federation.mdx
+++ b/apps/docs/src/content/docs/guides/data-federation.mdx
@@ -39,7 +39,7 @@ The **Encrypt connection (TLS)** toggle controls the `Encrypt` parameter and def
 
 ### Firebird Connections
 
-Firebird is supported through a custom, **unsigned** DuckDB extension hosted at `https://archmaxai.github.io/duckdb_firebird`. Because the extension is unsigned, the `firebird` connection type is disabled by default and only appears in the connection form when the operator sets `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` (which also starts every DuckDB instance with `allow_unsigned_extensions`). The repository can be overridden with `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`.
+Firebird is supported through a custom, **unsigned** DuckDB extension hosted at `https://archmaxai.github.io/duckdb_firebird`. Because the extension is unsigned, the `firebird` connection type is disabled by default and only appears in the connection form when the operator sets `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` (which also starts every DuckDB instance with `allow_unsigned_extensions`).
 
 When active, archmax installs the extension automatically (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) and attaches Firebird connections from the **Connection Details** fields:
 
diff --git a/apps/docs/src/content/docs/reference/docker.mdx b/apps/docs/src/content/docs/reference/docker.mdx
index 4b95eca..aaf8258 100644
--- a/apps/docs/src/content/docs/reference/docker.mdx
+++ b/apps/docs/src/content/docs/reference/docker.mdx
@@ -80,12 +80,10 @@ If you access archmax through a reverse proxy, load balancer, or custom domain,
 |----------|---------|-------------|
 | `QUERY_TIMEOUT_MS` | `30000` | Per-query DuckDB timeout in milliseconds. Applies to MCP, agent, data browser, and connection-test queries. On timeout the query is cancelled via `interrupt()`. |
 | `MAX_CONCURRENT_QUERIES` | `10` | Max concurrent DuckDB queries per project. Additional requests wait up to `QUERY_TIMEOUT_MS` for a slot. |
-| `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` | `false` | Allow installing unsigned extensions from the federation console. When enabled, DuckDB instances start with `allow_unsigned_extensions` and the console accepts `INSTALL <extension> FROM '<source>'` for custom repositories or paths. |
-| `DUCKDB_ENABLE_CUSTOM_FIREBIRD` | `false` | Enable the custom (unsigned) `firebird` connection type. When enabled, the type appears in the connection form and every DuckDB instance starts with `allow_unsigned_extensions` so the Firebird extension can load. Does **not** enable the console custom-source install path (that stays gated by `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`). |
-| `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` | `https://archmaxai.github.io/duckdb_firebird` | Custom extension repository used to install the Firebird extension (`SET custom_extension_repository`). |
+| `DUCKDB_ENABLE_CUSTOM_FIREBIRD` | `false` | Enable the custom (unsigned) `firebird` connection type. When enabled, the type appears in the connection form and every DuckDB instance starts with `allow_unsigned_extensions` so the Firebird extension can load. This is the only switch that enables unsigned-extension support; the federation console never installs unsigned extensions from arbitrary custom sources. The extension is installed from the public archmax-hosted repository (`https://archmaxai.github.io/duckdb_firebird`). |
 
 <Aside type="caution">
-Unsigned DuckDB extensions execute arbitrary native code inside the application process. Only set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` or `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` when you trust the extension sources you install. Both are disabled by default.
+The Firebird extension is unsigned and executes arbitrary native code inside the application process. Only set `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` when you trust the Firebird extension source. It is disabled by default.
 </Aside>
 
 ### AI Agent
diff --git a/openspec/changes/add-firebird-connection-type/design.md b/openspec/changes/add-firebird-connection-type/design.md
index 9098967..b68539f 100644
--- a/openspec/changes/add-firebird-connection-type/design.md
+++ b/openspec/changes/add-firebird-connection-type/design.md
@@ -2,7 +2,7 @@
 
 DuckDB has no native Firebird driver; the only `TYPE firebird` ATTACH support comes from a custom, unsigned extension hosted at `https://archmaxai.github.io/duckdb_firebird`. Loading it requires two things the platform does not do today:
 
-1. The instance must be created with `allow_unsigned_extensions`. `createDuckDBInstance()` in `packages/core/src/services/duckdb.ts` already sets this when `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is on (pending `add-unsigned-duckdb-extensions` change); enabling Firebird MUST also turn it on.
+1. The instance must be created with `allow_unsigned_extensions`. `createDuckDBInstance()` in `packages/core/src/services/duckdb.ts` sets this when `customFirebirdEnabled()` is on; this is the only condition that turns it on.
 2. The extension must be installed from a custom repository using `SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;` — a different shape from the existing `INSTALL <ext> FROM '<source>'` console path.
 
 Connection types are enumerated in `packages/core/src/models/Connection.ts` (`CONNECTION_TYPES`), validated by `apps/api/src/routes/connections.ts` (`z.enum(CONNECTION_TYPES)`), duplicated in the frontend (`apps/frontend/src/routes/_auth/$projectId/connections/index.tsx`), and dispatched on in `duckdb.ts` (`extensionForType`, `buildAttachString`, `attachConnection`, `testSingleConnection`) and `duckdb-console.ts` (`extensionTypeLabel`). Adding a connection type touches all of these.
@@ -21,11 +21,12 @@ Connection types are enumerated in `packages/core/src/models/Connection.ts` (`CO
 
 ## Decisions
 
-- **Decision: Single flag that implies unsigned.** `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (`true`/`1`, case-insensitive) both activates the Firebird type and causes `createDuckDBInstance()` to start instances with `allow_unsigned_extensions`. `createDuckDBInstance()` enables the option when `allowUnsignedExtensions() || customFirebirdEnabled()`. A `customFirebirdEnabled()` helper in `config/env.ts` encodes the gate.
-  - Rationale: the operator opts into exactly one specific unsigned extension via one variable, without having to also set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`. The two features remain independent — turning on Firebird does not enable the console's arbitrary-source install path (that still requires `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`).
-- **Decision: custom-repository install branch.** `installAndLoadExtension` gains a firebird-specific path that runs `SET custom_extension_repository = '<repo>'` (repo from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, default `https://archmaxai.github.io/duckdb_firebird`, single-quote-escaped) before `INSTALL firebird; LOAD firebird;`.
+- **Decision: Single flag that implies unsigned.** `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (`true`/`1`, case-insensitive) both activates the Firebird type and causes `createDuckDBInstance()` to start instances with `allow_unsigned_extensions`. `createDuckDBInstance()` enables the option when `customFirebirdEnabled()` — the only condition that turns on unsigned support. A `customFirebirdEnabled()` helper in `config/env.ts` encodes the gate.
+  - Rationale: the operator opts into exactly one specific unsigned extension via one variable. Unsigned-extension support exists solely for Firebird; the federation console never installs unsigned extensions from arbitrary custom sources.
+- **Decision: custom-repository install branch.** `installAndLoadExtension` gains a firebird-specific path that runs `SET custom_extension_repository = '<repo>'` (repo is the fixed constant `https://archmaxai.github.io/duckdb_firebird`, single-quote-escaped) before `INSTALL firebird; LOAD firebird;`.
 - **Decision: auto-install, no console step.** When Firebird is active, the extension is installed+loaded as part of the normal instance/extension bookkeeping (the same `loadedExtensions` flow used for postgres/mysql), so attaching a Firebird connection needs no manual `INSTALL`/`LOAD`.
 - **Decision: connection parameters and DSN.** Firebird reuses the structured relational fields plus a new non-sensitive `charset` field: `host`, `port` (default `3050`), `database` (path/alias **as seen on the Firebird host**, e.g. `C:\firebird.fdb`), `user`, `password`, `charset` (default `UTF8`). `extensionForType("firebird")` returns `"firebird"`; `attachConnection` installs the extension then `ATTACH '<dsn>' AS <slug> (TYPE FIREBIRD, READ_ONLY)`. `buildAttachString` gets a `firebird` case building the DSN from these fields, with `uri` pass-through preserved. The `database` value is treated as an opaque host-side path/alias and is NOT validated as a local filesystem path.
+  - **DSN format (resolved):** the extension resolves each connection field from **ATTACH options** first (then a URI DSN, then `FIREBIRD_*` env vars, then defaults). Structured connections therefore pass the fields as ATTACH options — `ATTACH '' AS <slug> (TYPE FIREBIRD, READ_ONLY, HOST '…', PORT 3050, DATABASE '…', USER '…', PASSWORD '…', CHARSET 'UTF8')` — with an **empty ATTACH path**, built by `buildFirebirdAttachOptions`. The path is intentionally left empty so the extension never parses it as a DSN: a `key=value` string or a Windows-path (`C:\…`) drive-letter colon in the path is fed to `std::stoi` as a port and throws `Invalid Error: stoi`. The options route also safely carries passwords/database paths containing URI metacharacters (`@`, `/`, `?`, `:`), which the extension's URI-DSN parser does not URL-decode. A configured `connectionConfig.uri` is passed through as the ATTACH path instead (URI form: `firebird://user:password@host:port/database?charset=UTF8`, where an absolute Unix path needs a leading `/` to form the required double slash). DuckDB core forwards all non-core ATTACH options to the storage extension unchanged (verified in `AttachOptions`).
 - **Decision: `charset` added to the shared `connectionConfig`.** Like `encrypt` (mssql-only) today, `charset` lives in the shared schema but is only consumed by the firebird DSN. Non-sensitive, so no encryption/redaction treatment.
 - **Decision: capability flag endpoint.** A small authenticated endpoint returns `{ firebirdEnabled: boolean }` (= `customFirebirdEnabled()`) so the frontend conditionally lists Firebird and sets default port/charset. No new persisted state.
 - **Decision: API rejects inactive type.** When Firebird is inactive, `POST`/`PUT` connections with `type: "firebird"` return 400, so a stored Firebird connection cannot exist on an instance that cannot load the extension.
@@ -38,9 +39,9 @@ Connection types are enumerated in `packages/core/src/models/Connection.ts` (`CO
 
 ## Migration Plan
 
-No data migration. Purely additive: unset var ⇒ identical behavior to today. To enable: set `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` (optionally `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`) and restart. To disable: unset and restart; instances are in-memory and rebuilt per process so nothing persists. Existing Firebird connection documents (if any) simply fail to attach while inactive.
+No data migration. Purely additive: unset var ⇒ identical behavior to today. To enable: set `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` and restart. To disable: unset and restart; instances are in-memory and rebuilt per process so nothing persists. Existing Firebird connection documents (if any) simply fail to attach while inactive.
 
 ## Open Questions
 
-- Exact connection-string/DSN format the `duckdb_firebird` extension expects for `ATTACH … (TYPE firebird)` and the precise key names for host/port/database/user/password/charset. Resolve by testing against the published extension during implementation; `buildAttachString` and the attach scenario will be finalized then.
+- ~~Exact connection-string/DSN format the `duckdb_firebird` extension expects~~ **Resolved:** structured connections pass the fields as ATTACH options with an empty path (`buildFirebirdAttachOptions`); a configured `uri` is passed through as a URI DSN. See the DSN decision above for the rationale (URI-DSN parsing crashes on Windows paths via `std::stoi` and cannot carry URI metacharacters).
 - Whether the extension requires any companion extension (analogous to iceberg needing `httpfs`). Assumed single-extension unless testing shows otherwise.
diff --git a/openspec/changes/add-firebird-connection-type/proposal.md b/openspec/changes/add-firebird-connection-type/proposal.md
index 638a00a..a348146 100644
--- a/openspec/changes/add-firebird-connection-type/proposal.md
+++ b/openspec/changes/add-firebird-connection-type/proposal.md
@@ -6,14 +6,14 @@ Firebird databases are only reachable from DuckDB through a custom, **unsigned**
 
 ## What Changes
 
-- Add a single opt-in env var `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (default off). When truthy (`true`/`1`, case-insensitive) it activates the Firebird connection type **and** causes project DuckDB instances to be created with `allow_unsigned_extensions` (the custom Firebird extension is unsigned), so no separate `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` setting is required to use Firebird.
-- Add an optional `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` env var (default `https://archmaxai.github.io/duckdb_firebird`) so operators can point at a mirror.
+- Add a single opt-in env var `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (default off). When truthy (`true`/`1`, case-insensitive) it activates the Firebird connection type **and** causes project DuckDB instances to be created with `allow_unsigned_extensions` (the custom Firebird extension is unsigned). This is the only switch that enables unsigned-extension support; the federation console never installs unsigned extensions from arbitrary custom sources.
+- The Firebird extension is installed from a fixed archmax-hosted repository (`https://archmaxai.github.io/duckdb_firebird`); this repository is not configurable.
 - Add `firebird` to the `Connection` type enum (model + API + frontend). A Firebird connection's `connectionConfig` supports these UI-definable parameters: `host`, `port` (default `3050`), `database` (the database path or alias **as seen on the Firebird host machine**, e.g. `C:\firebird.fdb`), `user`, `password`, and `charset` (default `UTF8`). A pass-through `uri` is also accepted.
-- When Firebird is active, the project DuckDB pipeline SHALL automatically install and load the Firebird extension from the custom repository (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) with no console action, and attach Firebird connections via `TYPE firebird` so they participate in federation, the data browser, connection tests, and MCP queries.
+- When Firebird is active, the project DuckDB pipeline SHALL automatically install and load the Firebird extension from the fixed archmax-hosted repository (`SET custom_extension_repository = '<repo>'; INSTALL firebird; LOAD firebird;`) with no console action, and attach Firebird connections via `TYPE firebird` so they participate in federation, the data browser, connection tests, and MCP queries.
 - Add a `charset` field to `connectionConfig` (model schema + API Zod schema + frontend form); it is non-sensitive and defaults to `UTF8` for Firebird.
 - Expose a server capability flag so the connection-management UI lists **Firebird** in the type dropdown (and defaults its port to `3050`, charset to `UTF8`) only when Firebird is active.
 - When Firebird is **not** active, the API SHALL reject `type: "firebird"` connection create/update with 400, and the UI SHALL omit Firebird from the dropdown — preserving current behavior exactly.
-- Document the new variables in `.env.example`, the Docker reference env table, and the data-federation guide, including a security note that Firebird is an unsigned extension running arbitrary native code.
+- Document the new variable in `.env.example`, the Docker reference env table, and the data-federation guide, including a security note that Firebird is an unsigned extension running arbitrary native code.
 
 ## Impact
 
@@ -22,7 +22,7 @@ Firebird databases are only reachable from DuckDB through a custom, **unsigned**
   - `data-connections` — MODIFIED `Connection Model` (add `firebird` to type enum + `charset` field), ADDED requirement (env-gated Firebird federation + capability flag)
   - `connection-management-ui` — ADDED requirement (Firebird connection form, conditional on the capability flag)
 - Affected code:
-  - `packages/core/src/config/env.ts` — `DUCKDB_ENABLE_CUSTOM_FIREBIRD`, `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, `customFirebirdEnabled()` helper
+  - `packages/core/src/config/env.ts` — `DUCKDB_ENABLE_CUSTOM_FIREBIRD`, `customFirebirdEnabled()` helper, fixed `firebirdExtensionRepository()` constant
   - `packages/core/src/models/Connection.ts` — add `firebird` to `CONNECTION_TYPES`, add `charset` to `IConnectionConfig`/`ConnectionConfigSchema`
   - `packages/core/src/services/duckdb.ts` — `extensionForType`, `buildAttachString` (firebird DSN incl. charset), firebird install branch in `installAndLoadExtension`, `createDuckDBInstance` enables unsigned when Firebird is active, `testSingleConnection`
   - `packages/core/src/services/duckdb-console.ts` — `extensionTypeLabel` firebird case
diff --git a/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md b/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
index 872e33f..d3f2617 100644
--- a/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
+++ b/openspec/changes/add-firebird-connection-type/specs/data-connections/spec.md
@@ -71,11 +71,11 @@ The system SHALL provide a `Connection` Mongoose model with the following fields
 
 ### Requirement: Env-Gated Firebird Federation
 
-The DuckDB federation pipeline SHALL support `firebird` connections only when the Firebird capability is active — that is, when `DUCKDB_ENABLE_CUSTOM_FIREBIRD` is truthy (`true`/`1`, case-insensitive). A `customFirebirdEnabled()` helper SHALL encode this gate. Enabling the capability SHALL cause project DuckDB instances to be created with `allow_unsigned_extensions` (in addition to the existing `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` path), because the custom Firebird extension is unsigned.
+The DuckDB federation pipeline SHALL support `firebird` connections only when the Firebird capability is active — that is, when `DUCKDB_ENABLE_CUSTOM_FIREBIRD` is truthy (`true`/`1`, case-insensitive). A `customFirebirdEnabled()` helper SHALL encode this gate. Enabling the capability SHALL cause project DuckDB instances to be created with `allow_unsigned_extensions`, because the custom Firebird extension is unsigned. This SHALL be the only mechanism that enables unsigned-extension support.
 
 When the Firebird capability is active:
 
-- The Firebird DuckDB extension SHALL be installed and loaded automatically from the configured custom repository, with no console action, by running `SET custom_extension_repository = '<repo>'` (from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY`, single-quote-escaped) followed by `INSTALL firebird` and `LOAD firebird` before a Firebird connection is attached or tested. The repository value SHALL default to `https://archmaxai.github.io/duckdb_firebird`.
+- The Firebird DuckDB extension SHALL be installed and loaded automatically from the fixed archmax-hosted repository (`https://archmaxai.github.io/duckdb_firebird`), with no console action, by running `SET custom_extension_repository = '<repo>'` (single-quote-escaped) followed by `INSTALL firebird` and `LOAD firebird` before a Firebird connection is attached or tested.
 - Firebird connections SHALL attach using `TYPE firebird` with `READ_ONLY`, built from the structured `host`/`port`/`database`/`user`/`password`/`charset` parameters (default port `3050`, default charset `UTF8`) or from a pass-through `connectionConfig.uri`, so Firebird tables participate in federation, the data browser, the connection test, and MCP queries like other relational types. The `database` value SHALL be treated as an opaque host-side path or alias (e.g. `C:\firebird.fdb`) and SHALL NOT be validated as a local filesystem path on the application host.
 
 When the Firebird capability is inactive (the default):
diff --git a/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md b/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
index da22232..d9975d1 100644
--- a/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
+++ b/openspec/changes/add-firebird-connection-type/specs/deployment/spec.md
@@ -4,11 +4,11 @@
 
 The image SHALL accept an optional `DUCKDB_ENABLE_CUSTOM_FIREBIRD` environment variable that activates the Firebird connection type and the automatic installation of the custom, unsigned Firebird DuckDB extension. The variable SHALL default to disabled; only `true` or `1` (case-insensitive) SHALL enable it.
 
-When enabled, project DuckDB instances SHALL be created with the `allow_unsigned_extensions` configuration option (so the unsigned Firebird extension can load) regardless of whether `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is set. Enabling `DUCKDB_ENABLE_CUSTOM_FIREBIRD` SHALL NOT enable the federation console's arbitrary custom-source install path, which remains gated solely by `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`.
+When enabled, project DuckDB instances SHALL be created with the `allow_unsigned_extensions` configuration option (so the unsigned Firebird extension can load). `DUCKDB_ENABLE_CUSTOM_FIREBIRD` SHALL be the only switch that enables unsigned-extension support; the federation console SHALL NOT install unsigned extensions from arbitrary custom sources.
 
-The image SHALL additionally accept an optional `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` environment variable specifying the custom extension repository URL used to install the Firebird extension. It SHALL default to `https://archmaxai.github.io/duckdb_firebird` when unset.
+The Firebird extension SHALL be installed from a fixed archmax-hosted repository (`https://archmaxai.github.io/duckdb_firebird`); this repository is not configurable.
 
-These variables SHALL be documented in `.env.example`, in the Docker reference page environment-variable table, and in the data-federation guide, including a security note that the Firebird extension is unsigned and executes arbitrary native code in the application process, and that it should only be enabled when the Firebird source is trusted.
+This variable SHALL be documented in `.env.example`, in the Docker reference page environment-variable table, and in the data-federation guide, including a security note that the Firebird extension is unsigned and executes arbitrary native code in the application process, and that it should only be enabled when the Firebird source is trusted.
 
 #### Scenario: Disabled by default
 
@@ -21,15 +21,15 @@ These variables SHALL be documented in `.env.example`, in the Docker reference p
 - **WHEN** the image starts with `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true`
 - **THEN** the Firebird connection type is active
 - **AND** project DuckDB instances are created with `allow_unsigned_extensions` so the unsigned Firebird extension can load
-- **AND** the Firebird extension is installed from `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (or its default) when a Firebird connection is used
+- **AND** the Firebird extension is installed from the fixed archmax-hosted repository (`https://archmaxai.github.io/duckdb_firebird`) when a Firebird connection is used
 
-#### Scenario: Enabling Firebird does not enable console custom-source installs
+#### Scenario: Console never installs from arbitrary custom sources
 
-- **WHEN** the image starts with `DUCKDB_ENABLE_CUSTOM_FIREBIRD=true` but `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` unset or falsy
-- **THEN** the federation console still rejects `INSTALL <extension> FROM '<source>'` custom-source installs with 400
+- **WHEN** the federation console receives `INSTALL <extension> FROM '<source>'`
+- **THEN** it rejects the statement with 400 regardless of `DUCKDB_ENABLE_CUSTOM_FIREBIRD`
 
 #### Scenario: Documented in environment reference
 
 - **WHEN** a user reads `.env.example` or the Docker reference environment-variable table
-- **THEN** they find `DUCKDB_ENABLE_CUSTOM_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` documented as optional and disabled/defaulted
+- **THEN** they find `DUCKDB_ENABLE_CUSTOM_FIREBIRD` documented as optional and disabled by default
 - **AND** a security warning explains that the Firebird extension is unsigned and runs arbitrary native code
diff --git a/openspec/changes/add-firebird-connection-type/tasks.md b/openspec/changes/add-firebird-connection-type/tasks.md
index 37a77be..aedf09f 100644
--- a/openspec/changes/add-firebird-connection-type/tasks.md
+++ b/openspec/changes/add-firebird-connection-type/tasks.md
@@ -1,9 +1,9 @@
 ## 1. Configuration
 
-- [x] 1.1 Add `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (optional string) and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` (optional string, default `https://archmaxai.github.io/duckdb_firebird`) to the env schema in `packages/core/src/config/env.ts`
+- [x] 1.1 Add `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (optional string) to the env schema in `packages/core/src/config/env.ts`. The Firebird extension repository is a fixed constant (`https://archmaxai.github.io/duckdb_firebird`), not configurable.
 - [x] 1.2 Add a `customFirebirdEnabled()` helper returning `true` for truthy `DUCKDB_ENABLE_CUSTOM_FIREBIRD` (`true`/`1`, case-insensitive)
 - [x] 1.3 Add a `firebirdExtensionRepository()` helper returning the configured repo or its default
-- [x] 1.4 In `createDuckDBInstance()`, enable `allow_unsigned_extensions` when `allowUnsignedExtensions() || customFirebirdEnabled()`
+- [x] 1.4 In `createDuckDBInstance()`, enable `allow_unsigned_extensions` when `customFirebirdEnabled()`
 
 ## 2. Connection model & API
 
@@ -27,7 +27,7 @@
 
 ## 5. Documentation
 
-- [x] 5.1 Document `DUCKDB_ENABLE_CUSTOM_FIREBIRD` and `DUCKDB_FIREBIRD_EXTENSION_REPOSITORY` in `.env.example` with a security note
+- [x] 5.1 Document `DUCKDB_ENABLE_CUSTOM_FIREBIRD` in `.env.example` with a security note
 - [x] 5.2 Add both variables to the Docker reference env-variable table and mention Firebird in the data-federation guide in `apps/docs`
 
 ## 6. Tests & verification
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/design.md b/openspec/changes/add-unsigned-duckdb-extensions/design.md
deleted file mode 100644
index c6e5c5f..0000000
--- a/openspec/changes/add-unsigned-duckdb-extensions/design.md
+++ /dev/null
@@ -1,37 +0,0 @@
-## Context
-
-The federation console (`packages/core/src/services/duckdb-console.ts`) lets an authenticated admin run read-only SQL and install DuckDB extensions on a project's in-process, in-memory DuckDB instance. `parseExtensionSql` currently only accepts `INSTALL <ext> [FROM community]` or `LOAD <ext>`, and instances are created via bare `DuckDBInstance.create()` in `packages/core/src/services/duckdb.ts` (`setupProjectInstance`, `testSingleConnection`, `testIcebergConnection`).
-
-DuckDB refuses to load extensions that are not signed by the DuckDB org unless the database was started with the `allow_unsigned_extensions` configuration option. That option can **only** be set at instance-creation time, not via `SET` on a live connection. So enabling unsigned extensions requires changing how instances are created, not just the SQL parser.
-
-## Goals / Non-Goals
-
-- Goals:
-  - Let opted-in self-hosters install trusted unsigned/custom-source extensions from the console.
-  - Default-off, zero behavior change when the env var is unset.
-  - Keep the gate in one obvious place (env-derived boolean) reused by both instance creation and SQL parsing.
-- Non-Goals:
-  - Per-project or per-extension allowlists (single global toggle is sufficient for now).
-  - A UI control to toggle the setting (it is an operator/deployment concern).
-  - Changing the read-only query allowlist or the `INSTALL/LOAD` keyword routing in the frontend.
-
-## Decisions
-
-- **Decision: Single global env var `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`.** Parsed once as a boolean (truthy for `true`/`1`, case-insensitive). Exposed from `config/env.ts` like the other DuckDB knobs (`QUERY_TIMEOUT_MS`, `MAX_CONCURRENT_QUERIES`). A helper `allowUnsignedExtensions()` reads it.
-  - Alternatives considered: per-project DB field (more flexible but adds schema + UI + migration for a niche operator feature); reusing an existing flag (none fit).
-- **Decision: Apply the config at instance creation via a shared `createDuckDBInstance()` helper.** All call sites that currently call `DuckDBInstance.create()` route through it so every instance (federation, connection-test) gets a consistent config: `{ allow_unsigned_extensions: "true" }` only when the flag is on.
-- **Decision: Extend `parseExtensionSql` to accept `INSTALL <extension> FROM '<source>'` only when the flag is on.** `<source>` is a single-quoted string (custom repository URL or local extension path). When the flag is off, this shape is rejected with the existing "must be INSTALL …" 400 error so behavior is unchanged. The extension name still matches `^[a-z][a-z0-9_]*$`; the quoted source is passed through to `INSTALL <ext> FROM '<source>'`.
-- **Decision: Reuse the existing install/load execution path** (`ensureProjectExtensionLoaded` / `installAndLoadExtension`), extended to carry an optional `fromSource` so it emits `INSTALL <ext> FROM '<source>'` instead of `INSTALL <ext>[ FROM community]`.
-
-## Risks / Trade-offs
-
-- **Arbitrary code execution**: unsigned extensions are native code loaded into the API/worker process. Mitigation: off by default; documented with an explicit security warning; only reachable by an authenticated admin via the console; source string is single-quote-escaped before interpolation.
-- **Worker vs API divergence**: the flag is process-level env, so both the API and BullMQ worker must share it for materialised views that depend on a custom extension to work in both. Mitigation: it is a normal env var present in the single Docker image for all processes; documented in the env table.
-
-## Migration Plan
-
-No data migration. Purely additive: unset env var ⇒ identical behavior to today. To enable, set `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true` and restart. To disable, unset and restart (instances are in-memory and rebuilt per process, so no persisted state carries the flag).
-
-## Open Questions
-
-- None. Local-path installs (`INSTALL '<path>.duckdb_extension'` with no `FROM`) are explicitly out of scope; only `INSTALL <extension> FROM '<source>'` is supported.
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/proposal.md b/openspec/changes/add-unsigned-duckdb-extensions/proposal.md
deleted file mode 100644
index 8b00bda..0000000
--- a/openspec/changes/add-unsigned-duckdb-extensions/proposal.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Change: Allow installing unsigned DuckDB extensions from the console (env-gated)
-
-## Why
-
-The federation console only installs signed core or `FROM community` extensions, because the project DuckDB instances are created without `allow_unsigned_extensions`. Operators who run their own extension builds or trusted third-party `.duckdb_extension` artifacts have no way to load them. We want to support this for self-hosters who explicitly opt in, while keeping the default posture (signed/community only) unchanged.
-
-## What Changes
-
-- Add an opt-in env var `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` (default off). When truthy, project DuckDB instances are created with the `allow_unsigned_extensions` config option enabled.
-- Extend the console extension-install path (`POST .../duckdb-console/extensions`) so that, **only when the env var is enabled**, it accepts `INSTALL <extension> FROM '<source>'` where `<source>` is a single-quoted custom repository URL or local extension path. Signed/community installs (`INSTALL <ext> [FROM community]`, `LOAD <ext>`) are unchanged.
-- When the env var is **not** set, custom-source installs are rejected with 400 and instances are created without the flag — preserving current behavior exactly.
-- Document the new variable in `.env.example` and the Docker reference env table, including a security note that unsigned extensions run arbitrary native code.
-
-## Impact
-
-- Affected specs: `duckdb-console` (ADDED requirement), `deployment` (ADDED requirement)
-- Affected code:
-  - `packages/core/src/config/env.ts` — add `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`
-  - `packages/core/src/services/duckdb.ts` — pass `allow_unsigned_extensions` to `DuckDBInstance.create()` via a shared helper
-  - `packages/core/src/services/duckdb-console.ts` — `parseExtensionSql` accepts env-gated `FROM '<source>'`
-  - `.env.example`, `apps/docs` Docker reference page
-- Security: enabling the flag permits loading unsigned native extensions (arbitrary code execution surface); off by default and clearly documented.
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md b/openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md
deleted file mode 100644
index 53dbd5b..0000000
--- a/openspec/changes/add-unsigned-duckdb-extensions/specs/deployment/spec.md
+++ /dev/null
@@ -1,27 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Unsigned DuckDB Extensions Configuration
-
-The image SHALL accept an optional `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` environment variable that controls whether the federated DuckDB instances permit loading unsigned extensions. The variable SHALL default to disabled; only `true` or `1` (case-insensitive) SHALL enable it.
-
-When enabled, all DuckDB instances created by the application SHALL be started with the `allow_unsigned_extensions` configuration option so that unsigned/custom-source extensions installed via the federation console can load. When unset or falsy, instances SHALL be created without the option (signed core and community extensions only).
-
-The variable SHALL be documented in `.env.example` and in the Docker reference page environment-variable table, including a security note that unsigned extensions execute arbitrary native code in the application process and that the setting should only be enabled for trusted extension sources.
-
-#### Scenario: Disabled by default
-
-- **WHEN** the image starts without `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` set
-- **THEN** DuckDB instances are created without `allow_unsigned_extensions`
-- **AND** only signed core and `FROM community` extensions can be installed
-
-#### Scenario: Enabled via environment
-
-- **WHEN** the image starts with `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true`
-- **THEN** DuckDB instances are created with `allow_unsigned_extensions` enabled
-- **AND** the federation console can install unsigned extensions from a custom source
-
-#### Scenario: Documented in environment reference
-
-- **WHEN** a user reads `.env.example` or the Docker reference environment-variable table
-- **THEN** they find `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` documented as optional and disabled by default
-- **AND** a security warning explains that unsigned extensions run arbitrary native code
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md b/openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md
deleted file mode 100644
index 1dd8912..0000000
--- a/openspec/changes/add-unsigned-duckdb-extensions/specs/duckdb-console/spec.md
+++ /dev/null
@@ -1,44 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Unsigned Extension Installation Gate
-
-The DuckDB Console Extension Install endpoint (`POST /api/projects/:projectId/duckdb-console/extensions`) SHALL allow installing unsigned extensions from a custom source only when the `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` environment variable is truthy (`true` or `1`, case-insensitive). This requirement is additive to and does not relax the signed/community install behavior.
-
-When the gate is enabled:
-
-- Project DuckDB instances SHALL be created with the `allow_unsigned_extensions` configuration option enabled, so unsigned extensions can load.
-- The extension-install parser SHALL additionally accept `INSTALL <extension> FROM '<source>'`, where `<extension>` matches `^[a-z][a-z0-9_]*$` and `<source>` is a single-quoted custom repository URL or local extension path. The server SHALL escape the `<source>` value before interpolating it into the executed `INSTALL <extension> FROM '<source>'` statement.
-
-When the gate is disabled (the default):
-
-- Project DuckDB instances SHALL be created WITHOUT the `allow_unsigned_extensions` option, so only signed core and `FROM community` extensions can load.
-- `INSTALL <extension> FROM '<source>'` SHALL be rejected with status 400, leaving the existing accepted shapes (`INSTALL <extension>`, `INSTALL <extension> FROM community`, `LOAD <extension>`) unchanged.
-
-The gate SHALL NOT change the read-only query allowlist or the keyword routing performed by the console page.
-
-#### Scenario: Install unsigned extension when gate enabled
-
-- **WHEN** `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is `true`
-- **AND** an authenticated POST submits `INSTALL myext FROM 'https://example.com/repo'`
-- **THEN** the response status is 200
-- **AND** `extension` is `myext`
-- **AND** the statement executed against DuckDB is `INSTALL myext FROM 'https://example.com/repo'`
-
-#### Scenario: Reject unsigned install when gate disabled
-
-- **WHEN** `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is unset or falsy
-- **AND** an authenticated POST submits `INSTALL myext FROM 'https://example.com/repo'`
-- **THEN** the response status is 400
-- **AND** the error indicates the statement must be `INSTALL <extension> [FROM community]` or `LOAD <extension>`
-
-#### Scenario: Signed and community installs unaffected by gate
-
-- **WHEN** an authenticated POST submits `INSTALL spatial FROM community`
-- **THEN** the response status is 200 regardless of the `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` value
-- **AND** `extension` is `spatial`
-
-#### Scenario: Reject invalid extension name with custom source
-
-- **WHEN** `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` is `true`
-- **AND** an authenticated POST submits `INSTALL ../evil FROM 'https://example.com/repo'`
-- **THEN** the response status is 400
diff --git a/openspec/changes/add-unsigned-duckdb-extensions/tasks.md b/openspec/changes/add-unsigned-duckdb-extensions/tasks.md
deleted file mode 100644
index c5c0552..0000000
--- a/openspec/changes/add-unsigned-duckdb-extensions/tasks.md
+++ /dev/null
@@ -1,25 +0,0 @@
-## 1. Configuration
-
-- [x] 1.1 Add `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` to the env schema in `packages/core/src/config/env.ts` (optional string, default unset)
-- [x] 1.2 Add an `allowUnsignedExtensions()` helper that returns a boolean for truthy `true`/`1` (case-insensitive)
-
-## 2. DuckDB instance creation
-
-- [x] 2.1 Add a `createDuckDBInstance()` helper in `packages/core/src/services/duckdb.ts` that calls `DuckDBInstance.create()` with `{ allow_unsigned_extensions: "true" }` only when the flag is enabled
-- [x] 2.2 Route `setupProjectInstance`, `testSingleConnection`, and `testIcebergConnection` through the helper
-
-## 3. Console extension install
-
-- [x] 3.1 Extend `parseExtensionSql` in `duckdb-console.ts` to accept `INSTALL <extension> FROM '<source>'` (single-quoted source) only when the flag is enabled; return `{ extension, fromSource }`
-- [x] 3.2 Reject the custom-source shape with the existing 400 error when the flag is disabled
-- [x] 3.3 Thread `fromSource` through `installDuckdbConsoleExtension` → `ensureProjectExtensionLoaded` → `installAndLoadExtension`, emitting `INSTALL <ext> FROM '<source>'` with the source single-quote-escaped
-
-## 4. Documentation
-
-- [x] 4.1 Document `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` in `.env.example` with a security note
-- [x] 4.2 Add `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` to the Docker reference env-variable table in `apps/docs`
-
-## 5. Tests & verification
-
-- [x] 5.1 Unit tests for `parseExtensionSql`: custom-source accepted when enabled, rejected when disabled, invalid name rejected, community/load unchanged
-- [x] 5.2 Run `pnpm typecheck` and `pnpm lint` (and `pnpm --filter @archmax/api build`); both exit 0
diff --git a/packages/core/src/config/env.test.ts b/packages/core/src/config/env.test.ts
index ff3b90d..bd18fff 100644
--- a/packages/core/src/config/env.test.ts
+++ b/packages/core/src/config/env.test.ts
@@ -107,58 +107,34 @@ describe("env — DuckDB extension gates", () => {
   beforeEach(() => {
     vi.resetModules();
     process.env = { ...originalEnv, ...BASE_ENV };
-    delete process.env.DUCKDB_ALLOW_UNSIGNED_EXTENSIONS;
     delete process.env.DUCKDB_ENABLE_CUSTOM_FIREBIRD;
-    delete process.env.DUCKDB_FIREBIRD_EXTENSION_REPOSITORY;
   });
 
   afterEach(() => {
     process.env = originalEnv;
   });
 
-  async function loadEnv() {
+  // Reload the env module with a fresh module registry after applying the
+  // given variable overrides, so each assertion observes a freshly-parsed env.
+  async function loadEnvWith(override: string, value: string) {
+    vi.resetModules();
+    process.env[override] = value;
     return import("./env.js");
   }
 
-  it("allowUnsignedExtensions is false by default and true for true/1", async () => {
-    let mod = await loadEnv();
-    expect(mod.allowUnsignedExtensions()).toBe(false);
-
-    vi.resetModules();
-    process.env.DUCKDB_ALLOW_UNSIGNED_EXTENSIONS = "TRUE";
-    mod = await loadEnv();
-    expect(mod.allowUnsignedExtensions()).toBe(true);
-
-    vi.resetModules();
-    process.env.DUCKDB_ALLOW_UNSIGNED_EXTENSIONS = "1";
-    mod = await loadEnv();
-    expect(mod.allowUnsignedExtensions()).toBe(true);
-  });
-
   it("customFirebirdEnabled is false by default and true for true/1", async () => {
-    let mod = await loadEnv();
-    expect(mod.customFirebirdEnabled()).toBe(false);
-
-    vi.resetModules();
-    process.env.DUCKDB_ENABLE_CUSTOM_FIREBIRD = "true";
-    mod = await loadEnv();
-    expect(mod.customFirebirdEnabled()).toBe(true);
-
-    vi.resetModules();
-    process.env.DUCKDB_ENABLE_CUSTOM_FIREBIRD = "nope";
-    mod = await loadEnv();
-    expect(mod.customFirebirdEnabled()).toBe(false);
+    expect((await import("./env.js")).customFirebirdEnabled()).toBe(false);
+    expect(
+      (await loadEnvWith("DUCKDB_ENABLE_CUSTOM_FIREBIRD", "true")).customFirebirdEnabled(),
+    ).toBe(true);
+    expect(
+      (await loadEnvWith("DUCKDB_ENABLE_CUSTOM_FIREBIRD", "nope")).customFirebirdEnabled(),
+    ).toBe(false);
   });
 
-  it("firebirdExtensionRepository defaults to the public repo and honors override", async () => {
-    let mod = await loadEnv();
-    expect(mod.firebirdExtensionRepository()).toBe(
+  it("firebirdExtensionRepository is the public archmax-hosted repo", async () => {
+    expect((await import("./env.js")).firebirdExtensionRepository()).toBe(
       "https://archmaxai.github.io/duckdb_firebird",
     );
-
-    vi.resetModules();
-    process.env.DUCKDB_FIREBIRD_EXTENSION_REPOSITORY = "https://mirror.example.com/fb";
-    mod = await loadEnv();
-    expect(mod.firebirdExtensionRepository()).toBe("https://mirror.example.com/fb");
   });
 });
diff --git a/packages/core/src/config/env.ts b/packages/core/src/config/env.ts
index 7bfc48e..8e080e5 100644
--- a/packages/core/src/config/env.ts
+++ b/packages/core/src/config/env.ts
@@ -33,10 +33,7 @@ const envSchema = z.object({
   QUERY_TIMEOUT_MS: z.string().optional().default("30000"),
   MAX_CONCURRENT_QUERIES: z.string().optional().default("10"),
 
-  DUCKDB_ALLOW_UNSIGNED_EXTENSIONS: z.string().optional(),
-
   DUCKDB_ENABLE_CUSTOM_FIREBIRD: z.string().optional(),
-  DUCKDB_FIREBIRD_EXTENSION_REPOSITORY: z.string().optional(),
 
   REDIS_URL: z.string().optional(),
   WORKER_CONCURRENCY: z.string().optional(),
@@ -174,20 +171,7 @@ export function getEnv(): ParsedEnv {
 
 export type Env = ParsedEnv;
 
-/**
- * Whether the federated DuckDB instances may load unsigned extensions.
- *
- * Off by default. Enabling it (`DUCKDB_ALLOW_UNSIGNED_EXTENSIONS=true|1`)
- * starts every DuckDB instance with `allow_unsigned_extensions` and lets the
- * federation console install extensions from a custom source. Unsigned
- * extensions run arbitrary native code, so this is an operator opt-in.
- */
-export function allowUnsignedExtensions(): boolean {
-  const raw = getEnv().DUCKDB_ALLOW_UNSIGNED_EXTENSIONS?.trim().toLowerCase();
-  return raw === "true" || raw === "1";
-}
-
-const DEFAULT_FIREBIRD_EXTENSION_REPOSITORY =
+const FIREBIRD_EXTENSION_REPOSITORY =
   "https://archmaxai.github.io/duckdb_firebird";
 
 /**
@@ -196,9 +180,9 @@ const DEFAULT_FIREBIRD_EXTENSION_REPOSITORY =
  * Off by default. Enabling it (`DUCKDB_ENABLE_CUSTOM_FIREBIRD=true|1`)
  * activates the `firebird` connection type and causes every DuckDB instance
  * to be started with `allow_unsigned_extensions` so the custom extension can
- * load (see `createDuckDBInstance`). Enabling this does NOT open the
- * federation console's arbitrary custom-source install path, which remains
- * gated solely by `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS`.
+ * load (see `createDuckDBInstance`). This is the only switch that turns on
+ * unsigned-extension support; the federation console never installs unsigned
+ * extensions from arbitrary custom sources.
  */
 export function customFirebirdEnabled(): boolean {
   const raw = getEnv().DUCKDB_ENABLE_CUSTOM_FIREBIRD?.trim().toLowerCase();
@@ -207,12 +191,9 @@ export function customFirebirdEnabled(): boolean {
 
 /**
  * Custom extension repository URL used to install the Firebird extension via
- * `SET custom_extension_repository = '<repo>'`. Falls back to the public
- * archmax-hosted repository when unset.
+ * `SET custom_extension_repository = '<repo>'`. Always the public
+ * archmax-hosted repository.
  */
 export function firebirdExtensionRepository(): string {
-  return (
-    getEnv().DUCKDB_FIREBIRD_EXTENSION_REPOSITORY?.trim() ||
-    DEFAULT_FIREBIRD_EXTENSION_REPOSITORY
-  );
+  return FIREBIRD_EXTENSION_REPOSITORY;
 }
diff --git a/packages/core/src/services/duckdb-console.test.ts b/packages/core/src/services/duckdb-console.test.ts
index dcc914d..cc4c349 100644
--- a/packages/core/src/services/duckdb-console.test.ts
+++ b/packages/core/src/services/duckdb-console.test.ts
@@ -58,41 +58,14 @@ describe("parseExtensionSql", () => {
     expect(() => parseExtensionSql("SELECT 1")).toThrow();
   });
 
-  it("parses INSTALL FROM '<source>' when unsigned extensions are allowed", () => {
-    expect(
-      parseExtensionSql("INSTALL myext FROM 'https://example.com/repo'", true),
-    ).toEqual({
-      extension: "myext",
-      loadOnly: false,
-      fromCommunity: false,
-      fromSource: "https://example.com/repo",
-    });
-  });
-
-  it("unescapes doubled quotes in a custom source", () => {
-    expect(parseExtensionSql("INSTALL myext FROM 'a''b'", true).fromSource).toBe("a'b");
-  });
-
-  it("rejects INSTALL FROM '<source>' when unsigned extensions are disabled", () => {
+  it("rejects INSTALL FROM '<arbitrary source>' (unsigned custom-source installs are not supported)", () => {
     expect(() =>
       parseExtensionSql("INSTALL myext FROM 'https://example.com/repo'"),
     ).toThrow(/must be INSTALL/i);
     expect(() =>
-      parseExtensionSql("INSTALL myext FROM 'https://example.com/repo'", false),
+      parseExtensionSql("INSTALL myext FROM 'a''b'"),
     ).toThrow(/must be INSTALL/i);
   });
-
-  it("rejects invalid extension name with a custom source even when allowed", () => {
-    expect(() => parseExtensionSql("INSTALL ../evil FROM 'https://x'", true)).toThrow();
-  });
-
-  it("does not treat FROM community as a custom source", () => {
-    expect(parseExtensionSql("INSTALL spatial FROM community", true)).toEqual({
-      extension: "spatial",
-      loadOnly: false,
-      fromCommunity: true,
-    });
-  });
 });
 
 describe("buildRedactedAttachSql", () => {
diff --git a/packages/core/src/services/duckdb-console.ts b/packages/core/src/services/duckdb-console.ts
index 3c7ea2b..2819ace 100644
--- a/packages/core/src/services/duckdb-console.ts
+++ b/packages/core/src/services/duckdb-console.ts
@@ -1,5 +1,4 @@
 import { connectDB } from "../infra/db";
-import { allowUnsignedExtensions } from "../config/env";
 import { Connection, Project, type IConnectionDocument } from "../models/index";
 import {
   buildAttachString,
@@ -112,36 +111,14 @@ export interface ParsedExtensionSql {
   extension: string;
   loadOnly: boolean;
   fromCommunity: boolean;
-  /**
-   * Custom install source (repository URL or path) for an env-gated unsigned
-   * extension install (`INSTALL <ext> FROM '<source>'`). Undefined for the
-   * signed/community shapes.
-   */
-  fromSource?: string;
 }
 
-export function parseExtensionSql(sql: string, allowUnsigned = false): ParsedExtensionSql {
+export function parseExtensionSql(sql: string): ParsedExtensionSql {
   const trimmed = sql.trim().replace(/;+\s*$/, "");
   if (trimmed.includes(";")) {
     throw new Error("Only a single statement is allowed");
   }
 
-  // INSTALL <extension> FROM '<source>' — unsigned/custom-source install.
-  // Only honoured when the operator has enabled unsigned extensions; the
-  // single-quoted source may contain '' as an escaped quote.
-  const sourceMatch = trimmed.match(/^install\s+([a-z][a-z0-9_]*)\s+from\s+'((?:[^']|'')*)'\s*$/i);
-  if (sourceMatch) {
-    if (!allowUnsigned) {
-      throw new Error("SQL must be INSTALL <extension> [FROM community] or LOAD <extension>");
-    }
-    const extension = sourceMatch[1].toLowerCase();
-    if (!EXTENSION_NAME_RE.test(extension)) {
-      throw new Error("Invalid extension name");
-    }
-    const fromSource = sourceMatch[2].replace(/''/g, "'");
-    return { extension, loadOnly: false, fromCommunity: false, fromSource };
-  }
-
   const installMatch = trimmed.match(/^install\s+([a-z][a-z0-9_]*)(?:\s+from\s+community)?\s*$/i);
   if (installMatch) {
     const extension = installMatch[1].toLowerCase();
@@ -328,7 +305,7 @@ export async function installDuckdbConsoleExtension(
   projectId: string,
   sql: string,
 ): Promise<{ extension: string }> {
-  const parsed = parseExtensionSql(sql, allowUnsignedExtensions());
+  const parsed = parseExtensionSql(sql);
   await connectDB();
   const project = await Project.findById(projectId).lean();
   if (!project) {
@@ -339,7 +316,6 @@ export async function installDuckdbConsoleExtension(
     await ensureProjectExtensionLoaded(projectId, parsed.extension, {
       fromCommunity: parsed.fromCommunity,
       loadOnly: parsed.loadOnly,
-      fromSource: parsed.fromSource,
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
diff --git a/packages/core/src/services/duckdb.test.ts b/packages/core/src/services/duckdb.test.ts
index 215c44c..1f47941 100644
--- a/packages/core/src/services/duckdb.test.ts
+++ b/packages/core/src/services/duckdb.test.ts
@@ -8,9 +8,8 @@ const TMP_PROJECTS_DIR = mkdtempSync(join(tmpdir(), "archmax-duckdb-test-"));
 
 vi.mock("../config/env", () => ({
   getEnv: vi.fn(() => ({ ENCRYPTION_KEY: "", projectsDir: TMP_PROJECTS_DIR })),
-  allowUnsignedExtensions: vi.fn(() => false),
   customFirebirdEnabled: vi.fn(() => false),
-  firebirdExtensionRepository: vi.fn(() => undefined),
+  firebirdExtensionRepository: vi.fn(() => "https://archmaxai.github.io/duckdb_firebird"),
 }));
 
 import {
@@ -18,6 +17,7 @@ import {
   scopedViewName,
   scopeSchemaName,
   buildAttachString,
+  buildFirebirdAttachOptions,
   COMMUNITY_EXTENSIONS,
   getQueryTimeoutMs,
   withQueryTimeout,
@@ -877,7 +877,7 @@ describe("buildAttachString — mysql", () => {
 });
 
 describe("buildAttachString — firebird", () => {
-  it("produces key=value format with charset", () => {
+  it("returns an empty path for structured config (fields travel via ATTACH options)", () => {
     const conn = fakeConn({
       type: "firebird",
       connectionConfig: {
@@ -889,8 +889,36 @@ describe("buildAttachString — firebird", () => {
         charset: "UTF8",
       },
     });
-    expect(buildAttachString(conn)).toBe(
-      "host=fb.local port=3050 database=C:\\firebird.fdb user=SYSDBA password=masterkey charset=UTF8",
+    // The structured fields must NOT be jammed into the ATTACH path: the
+    // extension parses the path as a DSN, and a Windows drive-letter `:` there
+    // makes its port parser (`std::stoi`) throw "Invalid Error: stoi".
+    expect(buildAttachString(conn)).toBe("");
+  });
+
+  it("passes through URI when set", () => {
+    const conn = fakeConn({
+      type: "firebird",
+      connectionConfig: { uri: "firebird://user:pw@host:3050/db" },
+    });
+    expect(buildAttachString(conn)).toBe("firebird://user:pw@host:3050/db");
+  });
+});
+
+describe("buildFirebirdAttachOptions", () => {
+  it("emits structured fields as ATTACH options, taking a Windows path verbatim", () => {
+    const conn = fakeConn({
+      type: "firebird",
+      connectionConfig: {
+        host: "fb.local",
+        port: 3050,
+        database: "C:\\firebird.fdb",
+        user: "SYSDBA",
+        password: "masterkey",
+        charset: "UTF8",
+      },
+    });
+    expect(buildFirebirdAttachOptions(conn)).toBe(
+      ", HOST 'fb.local', PORT 3050, DATABASE 'C:\\firebird.fdb', USER 'SYSDBA', PASSWORD 'masterkey', CHARSET 'UTF8'",
     );
   });
 
@@ -899,17 +927,57 @@ describe("buildAttachString — firebird", () => {
       type: "firebird",
       connectionConfig: { host: "h", database: "d", user: "u", password: "p" },
     });
-    const dsn = buildAttachString(conn);
-    expect(dsn).toContain("port=3050");
-    expect(dsn).toContain("charset=UTF8");
+    expect(buildFirebirdAttachOptions(conn)).toBe(
+      ", HOST 'h', PORT 3050, DATABASE 'd', USER 'u', PASSWORD 'p', CHARSET 'UTF8'",
+    );
   });
 
-  it("passes through URI when set", () => {
+  it("escapes single quotes and carries URI metacharacters in the password", () => {
+    const conn = fakeConn({
+      type: "firebird",
+      connectionConfig: {
+        host: "h",
+        database: "d",
+        user: "u",
+        // Contains `@ / ? :` (would break the extension's DSN parser) and a `'`.
+        password: "p@ss/wo?rd:it's",
+      },
+    });
+    expect(buildFirebirdAttachOptions(conn)).toBe(
+      ", HOST 'h', PORT 3050, DATABASE 'd', USER 'u', PASSWORD 'p@ss/wo?rd:it''s', CHARSET 'UTF8'",
+    );
+  });
+
+  it("returns an empty string when a raw uri is configured", () => {
     const conn = fakeConn({
       type: "firebird",
       connectionConfig: { uri: "firebird://user:pw@host:3050/db" },
     });
-    expect(buildAttachString(conn)).toBe("firebird://user:pw@host:3050/db");
+    expect(buildFirebirdAttachOptions(conn)).toBe("");
+  });
+});
+
+describe("getProjectInstance — skipped firebird connection", () => {
+  it("reuses the cached instance instead of rebuilding on every call", async () => {
+    // customFirebirdEnabled is mocked false by default, so an active firebird
+    // connection is skipped during setup. The skipped source must not make
+    // isReady/needsNewExtension treat it as perpetually pending, otherwise each
+    // getProjectInstance call tears down and rebuilds the cached instance.
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const projectId = "firebird-skip-no-churn";
+    const conn = fakeConn({
+      slug: "fb_src",
+      type: "firebird",
+      connectionConfig: { host: "fb.local", database: "d", user: "u", password: "p" },
+    });
+    try {
+      const first = await getProjectInstance(projectId, [conn]);
+      const second = await getProjectInstance(projectId, [conn]);
+      expect(second).toBe(first);
+    } finally {
+      warnSpy.mockRestore();
+      await disposeProjectInstance(projectId);
+    }
   });
 });
 
diff --git a/packages/core/src/services/duckdb.ts b/packages/core/src/services/duckdb.ts
index c586ca4..052a818 100644
--- a/packages/core/src/services/duckdb.ts
+++ b/packages/core/src/services/duckdb.ts
@@ -6,7 +6,6 @@ import { Connection, type IConnectionDocument } from "../models/index";
 import type { SemanticModel } from "./semantic-model-schema";
 import { decryptConnectionCredentials } from "../infra/crypto";
 import {
-  allowUnsignedExtensions,
   customFirebirdEnabled,
   firebirdExtensionRepository,
   getEnv,
@@ -40,15 +39,15 @@ async function deleteDuckdbFiles(path: string): Promise<void> {
 
 /**
  * Create a fresh in-memory `DuckDBInstance`, applying the
- * `allow_unsigned_extensions` startup option when the operator has opted in
- * via `DUCKDB_ALLOW_UNSIGNED_EXTENSIONS` or enabled the custom Firebird
- * extension (`DUCKDB_ENABLE_CUSTOM_FIREBIRD`), which is itself unsigned. The
- * option can only be set at instance-creation time (not via `SET`), so every
- * call site that opens an instance routes through here to get a consistent
- * configuration.
+ * `allow_unsigned_extensions` startup option only when the operator has
+ * enabled the custom Firebird extension (`DUCKDB_ENABLE_CUSTOM_FIREBIRD`),
+ * which is itself unsigned. Firebird is the only feature that requires
+ * unsigned extensions. The option can only be set at instance-creation time
+ * (not via `SET`), so every call site that opens an instance routes through
+ * here to get a consistent configuration.
  */
 export async function createDuckDBInstance(): Promise<DuckDBInstance> {
-  if (allowUnsignedExtensions() || customFirebirdEnabled()) {
+  if (customFirebirdEnabled()) {
     return DuckDBInstance.create(undefined, { allow_unsigned_extensions: "true" });
   }
   return DuckDBInstance.create();
@@ -332,15 +331,61 @@ function extensionForType(type: string): string | null {
   }
 }
 
-export function buildAttachString(conn: IConnectionDocument): string {
+/**
+ * Decrypt a connection's `connectionConfig`, normalising a Mongoose subdocument
+ * to a plain object first. Shared by `buildAttachString`, the Firebird ATTACH
+ * option builder, and the Iceberg attach path so credential handling lives in
+ * one place.
+ */
+function getDecryptedConfig(conn: IConnectionDocument): IConnectionDocument["connectionConfig"] {
   const key = getEnv().ENCRYPTION_KEY || null;
   const raw = typeof (conn.connectionConfig as any).toObject === "function"
     ? (conn.connectionConfig as any).toObject()
     : conn.connectionConfig;
-  const cfg = decryptConnectionCredentials(
+  return decryptConnectionCredentials(
     raw as Record<string, unknown>,
     key,
   ) as typeof conn.connectionConfig;
+}
+
+/** Quote a value as a DuckDB single-quoted string literal (escaping `'`). */
+function sqlString(value: string): string {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+/**
+ * Build the Firebird-specific ATTACH option list (comma-prefixed, ready to
+ * append inside the `(TYPE FIREBIRD …)` clause), e.g.
+ * `, HOST 'h', PORT 3050, DATABASE 'C:\\db.fdb', USER 'u', PASSWORD 'p', CHARSET 'UTF8'`.
+ *
+ * The custom Firebird extension resolves each connection field from ATTACH
+ * options first (then a DSN, then env), so passing the structured fields as
+ * options sidesteps URI parsing entirely. This avoids the `std::stoi` crash a
+ * Windows drive-letter colon causes when the same values are jammed into a DSN
+ * path, and it safely carries passwords/paths containing URI metacharacters
+ * (`@`, `/`, `?`, `:`) that the extension's DSN parser does not URL-decode.
+ *
+ * Returns `""` when a raw `uri` is configured — that case attaches the URI as
+ * the ATTACH path instead (see `buildAttachString`).
+ */
+export function buildFirebirdAttachOptions(conn: IConnectionDocument): string {
+  const cfg = getDecryptedConfig(conn);
+  if (cfg.uri) return "";
+
+  const parts: string[] = [];
+  if (cfg.host) parts.push(`HOST ${sqlString(String(cfg.host))}`);
+  const port = Number(cfg.port ?? 3050);
+  parts.push(`PORT ${Number.isFinite(port) ? port : 3050}`);
+  if (cfg.database) parts.push(`DATABASE ${sqlString(String(cfg.database))}`);
+  if (cfg.user) parts.push(`USER ${sqlString(String(cfg.user))}`);
+  if (cfg.password) parts.push(`PASSWORD ${sqlString(String(cfg.password))}`);
+  parts.push(`CHARSET ${sqlString(String(cfg.charset ?? "UTF8"))}`);
+
+  return `, ${parts.join(", ")}`;
+}
+
+export function buildAttachString(conn: IConnectionDocument): string {
+  const cfg = getDecryptedConfig(conn);
 
   if (cfg.uri) {
     return cfg.uri;
@@ -360,15 +405,14 @@ export function buildAttachString(conn: IConnectionDocument): string {
       const port = cfg.port ?? 3306;
       return `host=${cfg.host} port=${port} database=${cfg.database} user=${cfg.user} password=${cfg.password}`;
     }
-    case "firebird": {
-      // The custom (unsigned) Firebird extension takes a key=value DSN. The
-      // `database` value is an opaque path/alias as seen on the Firebird host
-      // (e.g. `C:\firebird.fdb`), not a local file path. Default port 3050 and
-      // charset UTF8 mirror the Firebird defaults.
-      const port = cfg.port ?? 3050;
-      const charset = cfg.charset ?? "UTF8";
-      return `host=${cfg.host} port=${port} database=${cfg.database} user=${cfg.user} password=${cfg.password} charset=${charset}`;
-    }
+    case "firebird":
+      // Structured Firebird config is passed via ATTACH options (see
+      // `buildFirebirdAttachOptions`), not the ATTACH path. The path is left
+      // empty so the extension does NOT try to parse it as a DSN — a `key=value`
+      // or Windows-path (`C:\…`) value there makes its port parser (`std::stoi`)
+      // throw "Invalid Error: stoi". A raw `uri` is handled by the pass-through
+      // above.
+      return "";
     case "sqlite":
       return cfg.database ?? "";
     default:
@@ -597,8 +641,25 @@ export async function withRecoverableProjectInstance<T>(
 
 const ICEBERG_EXTENSIONS = ["iceberg", "httpfs"] as const;
 
+/**
+ * A connection that cannot be attached under the current environment is
+ * intentionally skipped during setup (see `setupProjectInstance`). It must be
+ * treated identically by `isReady` and the `needsNewExtension` check below,
+ * otherwise the readiness/extension probes flag it as perpetually pending and
+ * every `getProjectInstance` call tears down and rebuilds the cached instance
+ * (re-attaching all other sources) — severe churn on every federated query.
+ *
+ * Currently this covers an active `firebird` connection while
+ * `DUCKDB_ENABLE_CUSTOM_FIREBIRD` is off: installing the unsigned extension or
+ * attaching would throw, so setup skips it and we exclude it everywhere.
+ */
+function isConnectionSkipped(conn: IConnectionDocument): boolean {
+  return conn.type === "firebird" && !customFirebirdEnabled();
+}
+
 function isReady(entry: ProjectDuckDB, connections: IConnectionDocument[]): boolean {
   return connections.every((conn) => {
+    if (isConnectionSkipped(conn)) return true;
     if (conn.type === "iceberg") {
       return ICEBERG_EXTENSIONS.every((e) => entry.loadedExtensions.has(e)) && entry.attachedSlugs.has(conn.slug);
     }
@@ -617,6 +678,7 @@ async function setupProjectInstance(
 
   if (entry) {
     const needsNewExtension = connections.some((conn) => {
+      if (isConnectionSkipped(conn)) return false;
       if (conn.type === "iceberg") {
         return ICEBERG_EXTENSIONS.some((e) => !entry!.loadedExtensions.has(e));
       }
@@ -654,14 +716,15 @@ async function setupProjectInstance(
     projectInstances.set(projectId, entry);
   }
 
-  const firebirdActive = customFirebirdEnabled();
   for (const conn of connections) {
     if (entry.attachedSlugs.has(conn.slug)) continue;
-    // When the Firebird capability is disabled, a leftover/active firebird
-    // connection must not abort the whole project instance: installing the
-    // unsigned extension (or attaching) would throw and break DuckDB for
-    // every source. Skip it instead — it simply fails to attach while off.
-    if (conn.type === "firebird" && !firebirdActive) {
+    // A connection that cannot be attached under the current environment must
+    // not abort the whole project instance: installing the unsigned extension
+    // (or attaching) would throw and break DuckDB for every source. Skip it
+    // instead — it simply fails to attach while disabled. `isReady` and the
+    // `needsNewExtension` probe apply the same predicate so the skipped source
+    // does not trigger a cache rebuild on every call.
+    if (isConnectionSkipped(conn)) {
       console.warn(
         `[duckdb] Skipping firebird connection '${conn.slug}' — DUCKDB_ENABLE_CUSTOM_FIREBIRD is not enabled`,
       );
@@ -685,7 +748,7 @@ async function setupProjectInstance(
 export async function ensureProjectExtensionLoaded(
   projectId: string,
   extension: string,
-  options?: { fromCommunity?: boolean; loadOnly?: boolean; fromSource?: string },
+  options?: { fromCommunity?: boolean; loadOnly?: boolean },
 ): Promise<void> {
   await connectDB();
   const connections = await Connection.find({ project: projectId, isActive: true }).lean();
@@ -706,15 +769,9 @@ export async function ensureProjectExtensionLoaded(
     return;
   }
 
-  // Run a full install when the extension isn't loaded yet, OR when the
-  // caller explicitly requested a custom source. Without the `fromSource`
-  // override an `INSTALL … FROM '<source>'` would be silently ignored once
-  // the same-named extension was already loaded (e.g. by federation), and
-  // the API would report success without installing from the requested source.
-  if (!entry.loadedExtensions.has(extension) || options?.fromSource) {
+  if (!entry.loadedExtensions.has(extension)) {
     await installAndLoadExtension(entry.instance, extension, {
       fromCommunity: options?.fromCommunity,
-      fromSource: options?.fromSource,
     });
     entry.loadedExtensions.add(extension);
     return;
@@ -731,32 +788,22 @@ export async function ensureProjectExtensionLoaded(
 async function installAndLoadExtension(
   instance: DuckDBInstance,
   ext: string,
-  options?: { fromCommunity?: boolean; fromSource?: string },
+  options?: { fromCommunity?: boolean },
 ): Promise<void> {
   const db = await instance.connect();
   try {
-    // The custom (unsigned) Firebird extension is installed from a custom
-    // repository: set `custom_extension_repository` then a plain INSTALL,
-    // rather than the `INSTALL <ext> FROM '<source>'` shape. The repo is
-    // single-quote escaped before interpolation. An explicit console
-    // `INSTALL firebird FROM '<source>'` (fromSource) overrides this and
-    // falls through to the generic `FROM '<source>'` path below.
-    if (ext === "firebird" && !options?.fromSource) {
+    // The custom (unsigned) Firebird extension is installed from the fixed
+    // archmax-hosted repository: set `custom_extension_repository` then a
+    // plain INSTALL. The repo is single-quote escaped before interpolation.
+    if (ext === "firebird") {
       const repo = firebirdExtensionRepository().replace(/'/g, "''");
       await db.run(`SET custom_extension_repository = '${repo}'`);
       await db.run("INSTALL firebird");
       await db.run("LOAD firebird");
       return;
     }
-    // A custom source (env-gated unsigned install) wins over the community
-    // repository. The source is single-quote escaped before interpolation.
-    let installSuffix: string;
-    if (options?.fromSource) {
-      installSuffix = ` FROM '${options.fromSource.replace(/'/g, "''")}'`;
-    } else {
-      const fromCommunity = options?.fromCommunity ?? COMMUNITY_EXTENSIONS.has(ext);
-      installSuffix = fromCommunity ? " FROM community" : "";
-    }
+    const fromCommunity = options?.fromCommunity ?? COMMUNITY_EXTENSIONS.has(ext);
+    const installSuffix = fromCommunity ? " FROM community" : "";
     await db.run(`INSTALL ${ext}${installSuffix}`);
     await db.run(`LOAD ${ext}`);
     if (ext === "mysql") {
@@ -803,9 +850,10 @@ async function attachConnection(entry: ProjectDuckDB, conn: IConnectionDocument)
   try {
     const connStr = buildAttachString(conn).replace(/'/g, "''");
     const readOnlyClause = entry.readOnly ? ", READ_ONLY" : "";
+    const extraOptions = conn.type === "firebird" ? buildFirebirdAttachOptions(conn) : "";
     await withQueryTimeout(
       db,
-      () => db.run(`ATTACH '${connStr}' AS ${conn.slug} (TYPE ${ext.toUpperCase()}${readOnlyClause})`),
+      () => db.run(`ATTACH '${connStr}' AS ${conn.slug} (TYPE ${ext.toUpperCase()}${readOnlyClause}${extraOptions})`),
       ATTACH_TIMEOUT_MS,
     );
     entry.attachedSlugs.add(conn.slug);
@@ -819,11 +867,7 @@ function icebergSecretName(slug: string): string {
 }
 
 function getDecryptedIcebergConfig(conn: IConnectionDocument) {
-  const key = getEnv().ENCRYPTION_KEY || null;
-  const raw = typeof (conn.connectionConfig as any).toObject === "function"
-    ? (conn.connectionConfig as any).toObject()
-    : conn.connectionConfig;
-  return decryptConnectionCredentials(raw as Record<string, unknown>, key);
+  return getDecryptedConfig(conn);
 }
 
 async function attachIcebergCatalog(entry: ProjectDuckDB, conn: IConnectionDocument): Promise<void> {
@@ -897,7 +941,8 @@ export async function testSingleConnection(conn: IConnectionDocument): Promise<D
   const db = await instance.connect();
   try {
     const connStr = buildAttachString(conn).replace(/'/g, "''");
-    await db.run(`ATTACH '${connStr}' AS ${conn.slug} (TYPE ${ext.toUpperCase()}, READ_ONLY)`);
+    const extraOptions = conn.type === "firebird" ? buildFirebirdAttachOptions(conn) : "";
+    await db.run(`ATTACH '${connStr}' AS ${conn.slug} (TYPE ${ext.toUpperCase()}, READ_ONLY${extraOptions})`);
   } finally {
     db.disconnectSync();
   }

From dc5a205ba9777f515614488232e58c9e2c6eed56 Mon Sep 17 00:00:00 2001
From: Tobias Grosse-Puppendahl <tobias@grosse-puppendahl.de>
Date: Fri, 5 Jun 2026 11:12:21 +0200
Subject: [PATCH 9/9] fix(connections): gate Firebird connection test behind
 capability flag

POST /connections/:id/test ran testSingleConnection without checking
customFirebirdEnabled(), so a stored firebird connection could install
and load the unsigned extension even when DUCKDB_ENABLE_CUSTOM_FIREBIRD
is off. Gate the test route (400) and add a defensive guard in
testSingleConnection itself.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../connections-firebird.integration.test.ts  | 25 ++++++++++++++++++-
 apps/api/src/routes/connections.ts            |  7 ++++++
 packages/core/src/services/duckdb.ts          |  6 +++++
 3 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/apps/api/src/routes/connections-firebird.integration.test.ts b/apps/api/src/routes/connections-firebird.integration.test.ts
index 2400648..96c85ef 100644
--- a/apps/api/src/routes/connections-firebird.integration.test.ts
+++ b/apps/api/src/routes/connections-firebird.integration.test.ts
@@ -7,6 +7,7 @@ const mocks = vi.hoisted(() => ({
   connectionFindOne: vi.fn(),
   connectionCreate: vi.fn(),
   connectionFindOneAndUpdate: vi.fn(),
+  testSingleConnection: vi.fn(),
 }));
 
 vi.mock("@archmax/core/infra/db", () => ({ connectDB: mocks.connectDB }));
@@ -29,7 +30,7 @@ vi.mock("@archmax/core/services/duckdb", () => ({
   deleteProjectDuckdbFile: vi.fn(),
   disposeProjectInstance: vi.fn(),
   getProjectInstance: vi.fn(),
-  testSingleConnection: vi.fn(),
+  testSingleConnection: mocks.testSingleConnection,
   withQueryTimeout: vi.fn(async (_db: unknown, op: () => Promise<unknown>) => op()),
 }));
 
@@ -105,4 +106,26 @@ describe("connections route — firebird gate", () => {
     expect(res.status).toBe(400);
     expect(mocks.connectionFindOneAndUpdate).not.toHaveBeenCalled();
   });
+
+  it("rejects testing a stored firebird connection with 400 when disabled", async () => {
+    // `POST /:id/test` must not run the firebird install/attach branch (which
+    // loads the unsigned extension) while the capability is off.
+    mocks.connectionFindOne.mockResolvedValue({ _id: "c1", project: "proj1", type: "firebird" });
+    const res = await app.request(`${BASE}/c1/test`, { method: "POST" });
+    expect(res.status).toBe(400);
+    const body = await jsonBody<{ error: string }>(res);
+    expect(body.error).toMatch(/not enabled/i);
+    expect(mocks.testSingleConnection).not.toHaveBeenCalled();
+  });
+
+  it("tests a stored firebird connection when enabled", async () => {
+    mocks.customFirebirdEnabled.mockReturnValue(true);
+    mocks.connectionFindOne.mockResolvedValue({ _id: "c1", project: "proj1", type: "firebird" });
+    mocks.testSingleConnection.mockResolvedValue({
+      connect: vi.fn().mockResolvedValue({ run: vi.fn(), disconnectSync: vi.fn() }),
+    });
+    const res = await app.request(`${BASE}/c1/test`, { method: "POST" });
+    expect(res.status).toBe(200);
+    expect(mocks.testSingleConnection).toHaveBeenCalledTimes(1);
+  });
 });
diff --git a/apps/api/src/routes/connections.ts b/apps/api/src/routes/connections.ts
index 2db6d69..d7de29d 100644
--- a/apps/api/src/routes/connections.ts
+++ b/apps/api/src/routes/connections.ts
@@ -237,6 +237,13 @@ const app = new Hono()
       project: projectId,
     });
     if (!conn) throw AppError.notFound("Connection not found");
+    // `testSingleConnection` runs the firebird install/attach branch, which
+    // loads the unsigned extension. Gate it the same way create/update do so a
+    // stored firebird connection cannot load the extension while the capability
+    // is disabled.
+    if (conn.type === "firebird" && !customFirebirdEnabled()) {
+      throw AppError.badRequest("Firebird connections are not enabled on this server");
+    }
 
     try {
       const instance = await testSingleConnection(conn as IConnectionDocument);
diff --git a/packages/core/src/services/duckdb.ts b/packages/core/src/services/duckdb.ts
index 052a818..f79cf7f 100644
--- a/packages/core/src/services/duckdb.ts
+++ b/packages/core/src/services/duckdb.ts
@@ -928,6 +928,12 @@ async function disableExternalAccess(instance: DuckDBInstance): Promise<void> {
  * Used for connectivity tests so results are not affected by cached state.
  */
 export async function testSingleConnection(conn: IConnectionDocument): Promise<DuckDBInstance> {
+  // Defensive gate: testing a firebird connection installs/loads the unsigned
+  // extension, so refuse when the capability is off even if a caller forgot to
+  // check (the connections route gates this too).
+  if (conn.type === "firebird" && !customFirebirdEnabled()) {
+    throw new Error("Firebird connections are not enabled on this server");
+  }
   if (conn.type === "iceberg") {
     return testIcebergConnection(conn);
   }