@objectstack/service-datasource 9.11.0 → 10.2.0

package/src/__tests__/admin-routes.test.ts

@@ -42,6 +42,64 @@ describe('registerDatasourceAdminRoutes (real HonoHttpServer)', () => {
     expect(listDatasources).toHaveBeenCalledOnce();
   });
 
+  it('GET /api/v1/datasources/drivers returns the driver catalog with configSchema', async () => {
+    const app = mount({}); // no service dependency — static catalog
+    const res = await app.fetch(json('/api/v1/datasources/drivers'));
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { drivers: Array<{ id: string; label: string; configSchema: any }> };
+    expect(Array.isArray(body.drivers)).toBe(true);
+    const sqlite = body.drivers.find((d) => d.id === 'sqlite');
+    expect(sqlite).toBeTruthy();
+    expect(sqlite!.label).toBe('SQLite');
+    expect(sqlite!.configSchema?.properties?.filename?.type).toBe('string');
+  });
+
+  it('GET /api/v1/datasources/:name/remote-tables lists remote tables', async () => {
+    const listRemoteTables = vi.fn().mockResolvedValue([{ name: 'customers', columnCount: 4 }]);
+    const app = mount({ listRemoteTables });
+    const res = await app.fetch(json('/api/v1/datasources/demo_ext/remote-tables'));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ tables: [{ name: 'customers', columnCount: 4 }] });
+    expect(listRemoteTables).toHaveBeenCalledWith('demo_ext');
+  });
+
+  it('POST /api/v1/datasources/:name/object-draft generates a draft (400 without table)', async () => {
+    const generateObjectDraft = vi.fn().mockResolvedValue({ name: 'customers', definition: { fields: { id: {} } } });
+    const app = mount({ generateObjectDraft });
+
+    const missing = await app.fetch(json('/api/v1/datasources/demo_ext/object-draft', { method: 'POST', body: JSON.stringify({}) }));
+    expect(missing.status).toBe(400);
+
+    const ok = await app.fetch(json('/api/v1/datasources/demo_ext/object-draft', { method: 'POST', body: JSON.stringify({ table: 'customers' }) }));
+    expect(ok.status).toBe(200);
+    expect((await ok.json()).draft.name).toBe('customers');
+    expect(generateObjectDraft).toHaveBeenCalledWith('demo_ext', 'customers', {});
+  });
+
+  it('GET /api/v1/datasources/:name returns the credential-stripped detail (404 when unknown)', async () => {
+    const getDatasource = vi.fn(async (name: string) =>
+      name === 'demo_ext'
+        ? { name: 'demo_ext', driver: 'sqlite', schemaMode: 'managed', config: { filename: '/tmp/x.db' }, active: true, origin: 'runtime', hasSecret: false }
+        : undefined,
+    );
+    const app = mount({ getDatasource });
+    const ok = await app.fetch(json('/api/v1/datasources/demo_ext'));
+    expect(ok.status).toBe(200);
+    expect((await ok.json()).datasource.config.filename).toBe('/tmp/x.db');
+    const missing = await app.fetch(json('/api/v1/datasources/nope'));
+    expect(missing.status).toBe(404);
+    expect(getDatasource).toHaveBeenCalledWith('demo_ext');
+  });
+
+  it('POST /api/v1/datasources/:name/test probes a saved datasource by name', async () => {
+    const testConnection = vi.fn().mockResolvedValue({ ok: true, latencyMs: 7, tableCount: 2 });
+    const app = mount({ testConnection });
+    const res = await app.fetch(json('/api/v1/datasources/demo_ext/test', { method: 'POST', body: '{}' }));
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, latencyMs: 7, tableCount: 2 });
+    expect(testConnection).toHaveBeenCalledWith('demo_ext');
+  });
+
   it('POST /api/v1/datasources/test splits the inline secret out of the draft', async () => {
     const testConnection = vi.fn().mockResolvedValue({ ok: true });
     const app = mount({ testConnection });

package/src/__tests__/datasource-admin-plugin.test.ts

@@ -229,3 +229,62 @@ describe('DatasourceAdminServicePlugin: persistence + bound count', () => {
     await expect(service.removeDatasource('reporting')).rejects.toThrow(/1 object\(s\)/);
   });
 });
+
+describe('DatasourceAdminServicePlugin: runtime datasource durability', () => {
+  /** In-memory `sys_metadata` engine shared across two boots (a "restart"). */
+  function fakeSysMetadataEngine() {
+    const rows: Array<Record<string, unknown>> = [];
+    return {
+      rows,
+      registerDriver() {},
+      registerDatasourceDef() {},
+      getDriverByName() { return undefined; },
+      findOne: async (_o: string, q: { where?: Record<string, unknown> }) => {
+        const w = q.where ?? {};
+        return rows.find((r) => Object.entries(w).every(([k, v]) => r[k] === v));
+      },
+      find: async (_o: string, q: { where?: Record<string, unknown> }) => {
+        const w = q.where ?? {};
+        return rows.filter((r) => Object.entries(w).every(([k, v]) => r[k] === v));
+      },
+      insert: async (_o: string, row: Record<string, unknown>) => { rows.push({ ...row }); },
+      update: async (_o: string, row: Record<string, unknown>, opts: { where: Record<string, unknown> }) => {
+        const i = rows.findIndex((r) => r.id === opts.where.id);
+        if (i >= 0) rows[i] = { ...rows[i], ...row };
+      },
+      delete: async (_o: string, opts: { where: Record<string, unknown> }) => {
+        const i = rows.findIndex((r) => r.id === opts.where.id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+    };
+  }
+
+  it('persists a UI-created datasource to sys_metadata and restores it after a restart', async () => {
+    const data = fakeSysMetadataEngine();
+
+    // Boot #1: create a runtime sqlite datasource (no secret needed).
+    const b1 = await boot({ services: { data } });
+    await b1.service.createDatasource({ name: 'demo_ext', driver: 'sqlite', config: { filename: '/tmp/x.db' } });
+    // It is durably written to sys_metadata (not just the in-memory registry).
+    expect(data.rows.filter((r) => r.type === 'datasource' && r.name === 'demo_ext')).toHaveLength(1);
+
+    // Boot #2 = "restart": fresh in-memory registry, SAME sys_metadata engine.
+    const b2 = await boot({ services: { data } });
+    // Before restore, the fresh registry is empty.
+    expect(await b2.service.listDatasources()).toHaveLength(0);
+    // start() restores runtime rows from sys_metadata into the registry.
+    await b2.plugin.start(b2.ctx);
+    const after = await b2.service.listDatasources();
+    expect(after.map((d) => d.name)).toContain('demo_ext');
+    expect(after.find((d) => d.name === 'demo_ext')?.origin).toBe('runtime');
+  });
+
+  it('removes the durable sys_metadata row when a datasource is deleted', async () => {
+    const data = fakeSysMetadataEngine();
+    const b = await boot({ services: { data } });
+    await b.service.createDatasource({ name: 'gone', driver: 'sqlite', config: { filename: '/tmp/y.db' } });
+    expect(data.rows.some((r) => r.name === 'gone')).toBe(true);
+    await b.service.removeDatasource('gone');
+    expect(data.rows.some((r) => r.name === 'gone')).toBe(false);
+  });
+});

package/src/__tests__/datasource-admin-service.test.ts

@@ -286,3 +286,33 @@ describe('removeDatasource', () => {
     await expect(service.removeDatasource('nope')).rejects.toThrow(/not found/i);
   });
 });
+
+describe('getDatasource', () => {
+  it('returns config + hasSecret with the credentialsRef stripped', async () => {
+    const { service } = makeHarness({
+      seed: [
+        {
+          name: 'pg',
+          driver: 'postgres',
+          origin: 'runtime',
+          config: { host: 'db', port: 5432, database: 'app' },
+          external: { credentialsRef: 'sys_secret://datasource/pg#1' },
+        },
+      ],
+    });
+    const ds = await service.getDatasource('pg');
+    expect(ds).toMatchObject({ name: 'pg', driver: 'postgres', origin: 'runtime', hasSecret: true });
+    expect(ds!.config).toEqual({ host: 'db', port: 5432, database: 'app' });
+    // The opaque credential handle must never be returned.
+    expect(JSON.stringify(ds)).not.toContain('sys_secret');
+    expect(JSON.stringify(ds)).not.toContain('credentialsRef');
+  });
+
+  it('reports hasSecret:false and returns undefined for unknown names', async () => {
+    const { service } = makeHarness({
+      seed: [{ name: 'lite', driver: 'sqlite', origin: 'runtime', config: { filename: '/tmp/a.db' } }],
+    });
+    expect((await service.getDatasource('lite'))!.hasSecret).toBe(false);
+    expect(await service.getDatasource('missing')).toBeUndefined();
+  });
+});

package/src/__tests__/datasource-connection-service.test.ts

@@ -0,0 +1,294 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi } from 'vitest';
+import {
+  DatasourceConnectionService,
+  isDatasourceAddressed,
+  type ConnectableDatasource,
+  type ConnectionEngineLike,
+} from '../datasource-connection-service.js';
+import type { IDatasourceDriverFactory } from '../contracts/datasource-driver-factory.js';
+import type { DatasourceConnectPolicy } from '../contracts/connect-policy.js';
+
+/** A fake engine recording driver registration + schema syncs. */
+function fakeEngine() {
+  const drivers = new Map<string, { name?: string }>();
+  const defs: Array<{ name: string; schemaMode?: string }> = [];
+  const synced: string[] = [];
+  const engine: ConnectionEngineLike & { drivers: typeof drivers; defs: typeof defs; synced: string[] } = {
+    drivers,
+    defs,
+    synced,
+    registerDriver: (driver: any) => {
+      if (drivers.has(driver.name)) return; // mirror engine's skip-if-present
+      drivers.set(driver.name, driver);
+    },
+    registerDatasourceDef: (def) => {
+      defs.push(def);
+    },
+    getDriverByName: (name) => drivers.get(name),
+    syncObjectSchema: async (name) => {
+      synced.push(name);
+    },
+  };
+  return engine;
+}
+
+/** A fake factory that builds a trivial connectable handle. */
+function fakeFactory(opts: { supports?: (id: string) => boolean; connectThrows?: boolean } = {}): IDatasourceDriverFactory {
+  return {
+    supports: opts.supports ?? (() => true),
+    create: vi.fn(async () => {
+      const driver: any = { name: 'com.fake.driver' };
+      return {
+        driver,
+        connect: opts.connectThrows
+          ? async () => {
+              throw new Error('connection refused');
+            }
+          : async () => {
+              driver.connected = true;
+            },
+      };
+    }),
+  };
+}
+
+function svc(over: {
+  factory?: IDatasourceDriverFactory | undefined;
+  engine?: ConnectionEngineLike | undefined;
+  policy?: DatasourceConnectPolicy;
+  secrets?: { resolve?: (ref: string) => Promise<string | undefined> };
+} = {}) {
+  const engine = over.engine === undefined ? fakeEngine() : over.engine;
+  const factory = over.factory === undefined ? fakeFactory() : over.factory;
+  const service = new DatasourceConnectionService({
+    factory: () => factory ?? undefined,
+    engine: () => engine ?? undefined,
+    policy: over.policy,
+    secrets: over.secrets,
+  });
+  return { service, engine: engine as ReturnType<typeof fakeEngine> | undefined, factory };
+}
+
+const externalDs: ConnectableDatasource = {
+  name: 'warehouse',
+  driver: 'sqlite',
+  schemaMode: 'external',
+  config: { filename: '/tmp/w.db' },
+  external: { allowWrites: false, validation: { onMismatch: 'warn' } },
+};
+
+describe('isDatasourceAddressed (ADR-0062 D2 gate)', () => {
+  it('connects external datasources (a)', () => {
+    expect(isDatasourceAddressed({ name: 'x', schemaMode: 'external' }, { objects: [] })).toBe(true);
+    expect(isDatasourceAddressed({ name: 'x', schemaMode: 'validate-only' }, { objects: [] })).toBe(true);
+  });
+
+  it('connects when an object explicitly binds via object.datasource (b)', () => {
+    expect(
+      isDatasourceAddressed({ name: 'reporting', schemaMode: 'managed' }, { objects: [{ name: 'o', datasource: 'reporting' }] }),
+    ).toBe(true);
+  });
+
+  it('connects when autoConnect:true (c)', () => {
+    expect(isDatasourceAddressed({ name: 'x', schemaMode: 'managed', autoConnect: true }, { objects: [] })).toBe(true);
+  });
+
+  it('does NOT connect a managed datasource that is only mapped / unrouted (app-crm byte-for-byte unchanged)', () => {
+    // app-crm: crm_primary is managed + referenced by datasourceMapping only,
+    // crm_analytics is managed + unrouted. Neither has an object binding.
+    expect(isDatasourceAddressed({ name: 'crm_primary', schemaMode: 'managed' }, { objects: [] })).toBe(false);
+    expect(isDatasourceAddressed({ name: 'crm_analytics', schemaMode: 'managed' }, { objects: [] })).toBe(false);
+    // An object bound to a DIFFERENT datasource must not flip the gate.
+    expect(
+      isDatasourceAddressed({ name: 'crm_primary', schemaMode: 'managed' }, { objects: [{ name: 'acct', datasource: 'default' }] }),
+    ).toBe(false);
+  });
+});
+
+describe('DatasourceConnectionService.connect', () => {
+  it('builds, connects, stamps the datasource name, and registers the driver + def', async () => {
+    const { service, engine, factory } = svc();
+    const result = await service.connect(externalDs, { objects: ['ext_customer'] });
+    expect(result.status).toBe('connected');
+    expect(factory.create).toHaveBeenCalledOnce();
+    // Driver registered under the DATASOURCE name (engine routes by driver.name).
+    expect(engine!.drivers.has('warehouse')).toBe(true);
+    expect(engine!.drivers.get('warehouse')!.name).toBe('warehouse');
+    // Datasource definition recorded for the write gate.
+    expect(engine!.defs).toEqual([{ name: 'warehouse', schemaMode: 'external', external: externalDs.external }]);
+    // Bound external objects got read metadata synced (DDL-free).
+    expect(engine!.synced).toEqual(['ext_customer']);
+  });
+
+  it('is idempotent — an already-registered driver is skipped (onEnable escape hatch)', async () => {
+    const { service, engine, factory } = svc();
+    engine!.drivers.set('warehouse', { name: 'warehouse' }); // pretend onEnable registered it
+    const result = await service.connect(externalDs, { objects: ['ext_customer'] });
+    expect(result.status).toBe('already-registered');
+    expect(factory.create).not.toHaveBeenCalled();
+    expect(engine!.synced).toEqual([]); // no double sync
+  });
+
+  it('resolves external.credentialsRef via the secret resolver before building', async () => {
+    const resolve = vi.fn(async () => 's3cr3t');
+    const create = vi.fn(async () => ({ driver: { name: 'd' }, connect: async () => {} }));
+    const factory: IDatasourceDriverFactory = { supports: () => true, create };
+    const { service } = svc({ factory, secrets: { resolve } });
+    await service.connect({ ...externalDs, external: { ...externalDs.external, credentialsRef: 'secret:wh/pw' } });
+    expect(resolve).toHaveBeenCalledWith('secret:wh/pw');
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ secret: 's3cr3t' }));
+  });
+
+  it('respects a deny policy — left unconnected, metadata-only', async () => {
+    const policy: DatasourceConnectPolicy = { canConnect: () => ({ allow: false, reason: 'egress blocked' }) };
+    const { service, engine, factory } = svc({ policy });
+    const result = await service.connect(externalDs);
+    expect(result.status).toBe('skipped-policy');
+    expect(result.reason).toBe('egress blocked');
+    expect(factory.create).not.toHaveBeenCalled();
+    expect(engine!.drivers.size).toBe(0);
+  });
+
+  it('treats a throwing policy as a denial (fail-closed)', async () => {
+    const policy: DatasourceConnectPolicy = {
+      canConnect: () => {
+        throw new Error('policy backend down');
+      },
+    };
+    const { service, engine } = svc({ policy });
+    const result = await service.connect(externalDs);
+    expect(result.status).toBe('skipped-policy');
+    expect(engine!.drivers.size).toBe(0);
+  });
+
+  it('degrades (no throw) when there is no factory / engine', async () => {
+    const noFactory = new DatasourceConnectionService({ factory: () => undefined, engine: () => fakeEngine() });
+    expect((await noFactory.connect(externalDs)).status).toBe('skipped-no-infra');
+    const noEngine = new DatasourceConnectionService({ factory: () => fakeFactory(), engine: () => undefined });
+    expect((await noEngine.connect(externalDs)).status).toBe('skipped-no-infra');
+  });
+
+  describe('D5 connect-failure policy', () => {
+    const failExternal: ConnectableDatasource = {
+      ...externalDs,
+      external: { allowWrites: false, validation: { onMismatch: 'fail' } },
+    };
+
+    it('fail-fast: a declared-auto external + onMismatch:fail re-throws (bricks boot)', async () => {
+      const { service } = svc({ factory: fakeFactory({ connectThrows: true }) });
+      await expect(
+        service.connect(failExternal, { context: { trigger: 'declared-auto' } }),
+      ).rejects.toThrow(/fail-fast/);
+    });
+
+    it('degrade: the SAME datasource connected via runtime-admin never bricks the server', async () => {
+      const { service } = svc({ factory: fakeFactory({ connectThrows: true }) });
+      const result = await service.connect(failExternal, { context: { trigger: 'runtime-admin' } });
+      expect(result.status).toBe('failed-degraded');
+    });
+
+    it('degrade: external + onMismatch:warn degrades even at boot', async () => {
+      const { service } = svc({ factory: fakeFactory({ connectThrows: true }) });
+      const result = await service.connect(externalDs, { context: { trigger: 'declared-auto' } });
+      expect(result.status).toBe('failed-degraded');
+    });
+  });
+});
+
+describe('D3 credential resolution — fail-closed', () => {
+  const credExternal: ConnectableDatasource = {
+    name: 'warehouse',
+    driver: 'sqlite',
+    schemaMode: 'external',
+    config: {},
+    external: { allowWrites: false, credentialsRef: 'sys_secret:abc', validation: { onMismatch: 'warn' } },
+  };
+
+  it('fails closed when a credentialsRef is declared but NO secret store is configured', async () => {
+    const factory = fakeFactory();
+    const { service, engine } = svc({ factory }); // no `secrets`
+    const result = await service.connect(credExternal, { context: { trigger: 'runtime-admin' } });
+    expect(result.status).toBe('failed-credentials');
+    expect(result.reason).toMatch(/no secret store/);
+    expect(factory.create).not.toHaveBeenCalled(); // never built without the secret
+    expect(engine!.drivers.size).toBe(0);
+  });
+
+  it('fails closed when the credentialsRef cannot be resolved/decrypted (undefined)', async () => {
+    const factory = fakeFactory();
+    const { service } = svc({ factory, secrets: { resolve: async () => undefined } });
+    const result = await service.connect(credExternal, { context: { trigger: 'runtime-admin' } });
+    expect(result.status).toBe('failed-credentials');
+    expect(result.reason).toMatch(/could not be resolved or decrypted/);
+    expect(factory.create).not.toHaveBeenCalled();
+  });
+
+  it('fails closed when the resolver throws', async () => {
+    const factory = fakeFactory();
+    const { service } = svc({
+      factory,
+      secrets: {
+        resolve: async () => {
+          throw new Error('kms unreachable');
+        },
+      },
+    });
+    const result = await service.connect(credExternal, { context: { trigger: 'runtime-admin' } });
+    expect(result.status).toBe('failed-credentials');
+    expect(factory.create).not.toHaveBeenCalled();
+  });
+
+  it('fail-fast: a declared-auto external + onMismatch:fail with an unresolvable credential re-throws', async () => {
+    const failCred: ConnectableDatasource = {
+      ...credExternal,
+      external: { allowWrites: false, credentialsRef: 'sys_secret:abc', validation: { onMismatch: 'fail' } },
+    };
+    const { service } = svc({ secrets: { resolve: async () => undefined } });
+    await expect(service.connect(failCred, { context: { trigger: 'declared-auto' } })).rejects.toThrow(/fail-fast/);
+  });
+
+  it('connects when the credential resolves to a secret', async () => {
+    const create = vi.fn(async () => ({ driver: { name: 'd' }, connect: async () => {} }));
+    const factory: IDatasourceDriverFactory = { supports: () => true, create };
+    const { service } = svc({ factory, secrets: { resolve: async () => 's3cr3t' } });
+    const result = await service.connect(credExternal);
+    expect(result.status).toBe('connected');
+    expect(create).toHaveBeenCalledWith(expect.objectContaining({ secret: 's3cr3t' }));
+  });
+});
+
+describe('DatasourceConnectionService.connectDeclared', () => {
+  it('connects only the gated datasources and syncs each one’s bound objects', async () => {
+    const { service, engine, factory } = svc();
+    const datasources: ConnectableDatasource[] = [
+      externalDs, // external → connect
+      { name: 'crm_primary', driver: 'sqlite', schemaMode: 'managed', config: { filename: ':memory:' } }, // managed+unrouted → skip
+      { name: 'reporting', driver: 'sqlite', schemaMode: 'managed', config: {} }, // managed but object-bound → connect
+    ];
+    const objects = [
+      { name: 'ext_customer', datasource: 'warehouse' },
+      { name: 'report_row', datasource: 'reporting' },
+      { name: 'account', datasource: 'default' }, // routes to default → no effect
+    ];
+    const results = await service.connectDeclared({ datasources, objects });
+    const byName = Object.fromEntries(results.map((r) => [r.name, r.status]));
+    expect(byName).toEqual({ warehouse: 'connected', reporting: 'connected' });
+    expect(engine!.drivers.has('crm_primary')).toBe(false); // unchanged
+    expect(engine!.drivers.has('warehouse')).toBe(true);
+    expect(engine!.drivers.has('reporting')).toBe(true);
+    expect(engine!.synced.sort()).toEqual(['ext_customer', 'report_row']);
+    expect(factory.create).toHaveBeenCalledTimes(2);
+  });
+
+  it('skips inactive datasources', async () => {
+    const { service, engine } = svc();
+    const results = await service.connectDeclared({
+      datasources: [{ ...externalDs, active: false }],
+      objects: [],
+    });
+    expect(results).toEqual([]);
+    expect(engine!.drivers.size).toBe(0);
+  });
+});

package/src/admin-routes.ts

@@ -2,6 +2,7 @@
 
 import type { PluginContext } from '@objectstack/core';
 import type { IHttpServer } from '@objectstack/spec/contracts';
+import { DRIVER_CATALOG } from './driver-catalog.js';
 
 /**
  * Datasource lifecycle REST routes (ADR-0015 Addendum §3.5).
@@ -36,6 +37,14 @@ export function registerDatasourceAdminRoutes(
     }
   };
 
+  const externalService = (): any => {
+    try {
+      return ctx.getService<any>('external-datasource');
+    } catch {
+      return undefined;
+    }
+  };
+
   const unavailable = (res: any) =>
     res.status(503).json({ error: 'datasource_admin_unavailable' });
 
@@ -63,6 +72,72 @@ export function registerDatasourceAdminRoutes(
     res.json({ datasources });
   });
 
+  // Catalog of connection drivers + their JSON-Schema config (drives the
+  // Studio connection form). Static metadata — no service dependency, so it
+  // is always available even before any datasource-admin service is wired.
+  server.get(`${root}/drivers`, async (_req: any, res: any) => {
+    res.json({ drivers: DRIVER_CATALOG });
+  });
+
+  // Read-only schema introspection for the Studio "sync objects" flow.
+  // `GET /datasources/:name/remote-tables` lists the datasource's remote tables;
+  // `POST /datasources/:name/object-draft` generates an ObjectStack object
+  // definition draft for one table (introspect + type-map, no persistence —
+  // the caller creates the object through the normal metadata channel).
+  server.get(`${root}/:name/remote-tables`, async (req: any, res: any) => {
+    const svc = externalService();
+    if (!svc?.listRemoteTables) return unavailable(res);
+    try {
+      const tables = await svc.listRemoteTables(req.params.name);
+      res.json({ tables });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
+  // Test a *saved* datasource by name with a live round-trip (backs the
+  // `datasource` `test_connection` action). Distinct from `POST /datasources/test`
+  // which probes an unsaved draft carried inline. Registered before the generic
+  // `:name` mutation routes.
+  // Read one datasource's full detail for the edit form (credential stripped;
+  // `config` is non-sensitive, plus a `hasSecret` flag). Registered after the
+  // static `/drivers` route so that literal segment is never captured as a name.
+  server.get(`${root}/:name`, async (req: any, res: any) => {
+    const svc = adminService();
+    if (!svc?.getDatasource) return unavailable(res);
+    try {
+      const datasource = await svc.getDatasource(req.params.name);
+      if (!datasource) return res.status(404).json({ error: 'not_found' });
+      res.json({ datasource });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
+  server.post(`${root}/:name/test`, async (req: any, res: any) => {
+    const svc = externalService();
+    if (!svc?.testConnection) return unavailable(res);
+    try {
+      const result = await svc.testConnection(req.params.name);
+      res.json(result);
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
+  server.post(`${root}/:name/object-draft`, async (req: any, res: any) => {
+    const svc = externalService();
+    if (!svc?.generateObjectDraft) return unavailable(res);
+    const { table, ...opts } = (req.body as Record<string, unknown>) ?? {};
+    if (!table) return badRequest(res, new Error('Body field "table" is required.'));
+    try {
+      const draft = await svc.generateObjectDraft(req.params.name, String(table), opts);
+      res.json({ draft });
+    } catch (err) {
+      badRequest(res, err);
+    }
+  });
+
   // Probe a connection without persisting anything. Registered before the
   // `:name` routes so the literal `test` segment is never captured as a name.
   server.post(`${root}/test`, async (req: any, res: any) => {

package/src/contracts/connect-policy.ts

@@ -0,0 +1,69 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * DatasourceConnectPolicy — host-injectable gate consulted *before*
+ * {@link DatasourceConnectionService} builds and registers a live driver
+ * (ADR-0062 D1/D5, and the epic #2163 "connect-policy seam" note).
+ *
+ * The framework ships a permissive default ({@link allowAllConnectPolicy}) so a
+ * self-hosted single-environment runtime connects external datasources out of
+ * the box (subject to the D2 auto-connect gate, which is applied separately by
+ * {@link DatasourceConnectionService.connectDeclared}). A multi-tenant host
+ * (shared-container cloud) binds a stricter policy that can *fail-close* on the
+ * shared runtime — e.g. checking `sys_environment.plan`, an egress allow-list,
+ * and per-tenant quota — to enforce SSRF / egress isolation.
+ *
+ * This keeps a single connect path for code- and runtime-origin datasources
+ * (D1): the host injects a policy rather than forking a second connect path.
+ * No plan coupling lives in the open framework.
+ */
+
+/** Why a connect is being attempted — lets a policy treat origins differently. */
+export interface DatasourceConnectContext {
+  /** Provenance of the datasource being connected. */
+  origin?: 'code' | 'runtime';
+  /**
+   * What triggered this connect:
+   *  - `declared-auto`  — code-defined datasource auto-connected at boot (D2 gate passed).
+   *  - `runtime-admin`  — UI "Add/Update Datasource" hot pool registration.
+   *  - `rehydrate`      — boot rehydration of a persisted runtime datasource.
+   */
+  trigger?: 'declared-auto' | 'runtime-admin' | 'rehydrate';
+}
+
+/** A policy verdict. `allow:false` leaves the datasource unconnected (metadata-only). */
+export interface DatasourceConnectDecision {
+  allow: boolean;
+  /** Human-readable reason, surfaced in logs when a connect is denied. */
+  reason?: string;
+}
+
+/** The minimal datasource shape a policy inspects (never a secret). */
+export interface DatasourceConnectSubject {
+  name: string;
+  driver: string;
+  schemaMode?: 'managed' | 'external' | 'validate-only';
+  external?: Record<string, unknown>;
+}
+
+/** Host-provided policy gate consulted before opening a connection. */
+export interface DatasourceConnectPolicy {
+  /**
+   * Decide whether `ds` may be connected. Sync or async. Throwing is treated
+   * as a denial (fail-closed) by {@link DatasourceConnectionService}.
+   */
+  canConnect(
+    ds: DatasourceConnectSubject,
+    ctx?: DatasourceConnectContext,
+  ): DatasourceConnectDecision | Promise<DatasourceConnectDecision>;
+}
+
+/**
+ * Open-core default: allow every connect. The D2 auto-connect gate (external /
+ * explicitly-routed / `autoConnect:true`) still applies on top of this for
+ * code-defined datasources, so a managed, unrouted datasource is never
+ * connected even under the permissive policy.
+ */
+export const allowAllConnectPolicy: DatasourceConnectPolicy = {
+  canConnect: () => ({ allow: true }),
+};

package/src/contracts/index.ts

@@ -16,3 +16,14 @@ export type {
   DatasourceDriverHandle,
   IDatasourceDriverFactory,
 } from './datasource-driver-factory.js';
+
+// Host-injectable connect policy (ADR-0062 D5 / epic #2163 seam).
+export {
+  allowAllConnectPolicy,
+} from './connect-policy.js';
+export type {
+  DatasourceConnectPolicy,
+  DatasourceConnectDecision,
+  DatasourceConnectContext,
+  DatasourceConnectSubject,
+} from './connect-policy.js';