feat(datasource): fail-closed credential resolution at connect (ADR-0062 Phase 2, D3)

A declared external.credentialsRef MUST resolve to a cleartext secret before the
driver is built — an absent secret store or an unresolvable/undecryptable ref now
fails closed (clear message, datasource left unconnected) instead of silently
building a driver without the credential. Follows the same fail-fast (declared
external + onMismatch:fail) vs degrade policy as connect failures. Converges with
the runtime-admin secret path (same SecretBinder threaded through the shared
connection service).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: os-zhuang

.changeset/adr-0062-credentials-fail-closed.md

@@ -0,0 +1,20 @@
+---
+"@objectstack/service-datasource": minor
+---
+
+feat(datasource): fail-closed credential resolution at connect (ADR-0062 Phase 2, D3)
+
+`DatasourceConnectionService` now treats a declared `external.credentialsRef` as
+**fail-closed**: the credential must resolve to a cleartext secret (via the
+host's `SecretBinder` over `ICryptoProvider`) *before* the driver is built. An
+absent secret store, or a ref that cannot be resolved/decrypted (missing
+`sys_secret` row, rotated key, or a throwing resolver), leaves the datasource
+**unconnected with a clear message** — never a silent build-without-secret that
+would connect with no/wrong auth or fail later with a confusing driver error.
+
+The same policy as connect failures applies: a code-defined `external` datasource
+with `validation.onMismatch: 'fail'` auto-connected at boot fails fast (bricks
+boot); runtime-admin create/update + boot rehydration degrade-with-warning. Code-
+and runtime-origin secrets converge on the one connection path (the same
+`SecretBinder` is threaded through the shared service). New `failed-credentials`
+connect status.

packages/runtime/src/datasource-autoconnect.test.ts

@@ -131,6 +131,55 @@ describe('ADR-0062 declared-datasource auto-connect', () => {
   });
 });
 
+describe('ADR-0062 credentials fail-closed (D3)', () => {
+  // An external datasource that declares a credentialsRef the host cannot
+  // resolve (no matching sys_secret row) must FAIL CLOSED — never connect with
+  // a missing credential. With onMismatch:'fail' that bricks boot (fail-fast).
+  function credArtifact() {
+    return {
+      manifest: { id: 'com.test.ds-cred', name: 'DS Cred', version: '1.0.0' },
+      objects: [{ name: 'note', label: 'Note', fields: { title: { type: 'text' } } }],
+      datasources: [
+        {
+          name: 'needs_secret',
+          driver: 'memory',
+          schemaMode: 'external',
+          origin: 'code',
+          config: {},
+          external: {
+            allowWrites: false,
+            credentialsRef: 'sys_secret:does-not-exist',
+            validation: { onMismatch: 'fail', checkOnBoot: false },
+          },
+          active: true,
+        },
+      ],
+    };
+  }
+
+  it('bricks boot with a clear message when a required credential cannot be resolved', async () => {
+    const { ObjectQLPlugin } = await import('@objectstack/objectql');
+    const { InMemoryDriver } = await import('@objectstack/driver-memory');
+    const { DatasourceAdminServicePlugin, createDefaultDatasourceDriverFactory } = await import(
+      '@objectstack/service-datasource'
+    );
+    const runtime = new Runtime({ cluster: false });
+    const kernel = runtime.getKernel();
+    await kernel.use(new DriverPlugin(new InMemoryDriver()));
+    await kernel.use(new ObjectQLPlugin());
+    await kernel.use(new AppPlugin(credArtifact()));
+    await kernel.use(
+      new DatasourceAdminServicePlugin({
+        driverFactory: createDefaultDatasourceDriverFactory(),
+        // A binder whose resolve never finds the secret (rotated key / missing row).
+        secrets: { bind: async () => 'sys_secret:x', resolve: async () => undefined },
+      }),
+    );
+    await expect(kernel.bootstrap()).rejects.toThrow(/needs_secret|credential|fail-fast/i);
+    try { await (kernel as any)?.stop?.(); } catch { /* noop */ }
+  }, BOOT_TIMEOUT);
+});
+
 describe('ADR-0062 connect policy seam', () => {
   it('a deny policy leaves the external datasource unconnected (cloud egress isolation)', async () => {
     const denyExternal: DatasourceConnectPolicy = {

packages/services/service-datasource/src/__tests__/datasource-connection-service.test.ts

@@ -197,6 +197,68 @@ describe('DatasourceConnectionService.connect', () => {
   });
 });
 
+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();

packages/services/service-datasource/src/datasource-connection-service.ts

@@ -106,6 +106,7 @@ export type ConnectStatus =
   | 'skipped-policy'
   | 'skipped-no-infra'
   | 'skipped-unsupported'
+  | 'failed-credentials'
   | 'failed-degraded';
 
 export interface ConnectResult {
@@ -233,9 +234,42 @@ export class DatasourceConnectionService {
       );
     }
 
+    // Credential resolution (ADR-0062 D3) — FAIL-CLOSED, and done *before* the
+    // build try-block so a fail-fast verdict propagates (rather than being
+    // swallowed and re-classified by the catch below). A declared
+    // `external.credentialsRef` MUST resolve to a cleartext secret before we
+    // open a connection: building a driver without it would silently connect
+    // with no/wrong auth (or fail later with a confusing driver error). So an
+    // absent secret store, or an unresolvable/undecryptable ref, leaves the
+    // datasource unconnected with a clear message — never a silent skip.
+    let secret: string | undefined;
+    const credentialsRef = record.external?.credentialsRef;
+    if (credentialsRef) {
+      const resolver = this.cfg.secrets?.resolve;
+      if (!resolver) {
+        return this.handleFailure(
+          record,
+          'failed-credentials',
+          `requires credential '${credentialsRef}' but no secret store (SecretBinder/ICryptoProvider) is configured`,
+          opts.context,
+        );
+      }
+      try {
+        secret = await resolver(credentialsRef);
+      } catch (err) {
+        return this.handleFailure(record, 'failed-credentials', `resolving credential '${credentialsRef}' threw: ${errMsg(err)}`, opts.context);
+      }
+      if (secret == null || secret === '') {
+        return this.handleFailure(
+          record,
+          'failed-credentials',
+          `credential '${credentialsRef}' could not be resolved or decrypted (missing sys_secret row, or the encryption key changed)`,
+          opts.context,
+        );
+      }
+    }
+
     try {
-      const credentialsRef = record.external?.credentialsRef;
-      const secret = credentialsRef ? await this.cfg.secrets?.resolve?.(credentialsRef) : undefined;
       const handle = await factory.create({ ...toSpec(record), ...(secret ? { secret } : {}) });
       if (typeof handle?.connect === 'function') await handle.connect();
 
@@ -285,11 +319,13 @@ export class DatasourceConnectionService {
   }
 
   /**
-   * Apply the D5 connect-failure policy. A code-defined `external` datasource
-   * with `onMismatch:'fail'` auto-connected at boot re-throws (fail-fast,
-   * bricking boot as intended). Runtime-admin create/update + boot rehydration
-   * always degrade-with-warning — a UI action or a replica blip must never
-   * brick the running server (preserves the pre-ADR-0062 admin behavior).
+   * Apply the D5 connect-failure policy (also covers D3 credential failures). A
+   * code-defined `external` datasource with `onMismatch:'fail'` auto-connected at
+   * boot re-throws (fail-fast, bricking boot as intended). Runtime-admin
+   * create/update + boot rehydration always degrade-with-warning — a UI action
+   * or a replica blip must never brick the running server (preserves the
+   * pre-ADR-0062 admin behavior). Either way the datasource is left unconnected
+   * with a clear message — never a silent skip.
    */
   private handleFailure(
     record: ConnectableDatasource,