fix: bind guarded writer to supplied env

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## Unreleased
+
+- Fix the FCAME-1 guarded writer so `createKnowledgeGuardedWriter({ env })`
+  authenticates guarded HTTP requests with the API endpoint and credential from
+  the supplied env, rather than allowing ambient profile, override, or disk
+  credential tiers to outrank that caller-supplied transport env.
+
 ## 0.2.96
 
 - Align the public declaration surface with the runtime export contract by

bin/knowledge-mcp.js

@@ -16197,6 +16197,10 @@ function clientTransportEnvKeys2(name) {
     apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
   };
 }
+function credentialOverrideEnvKey2(name) {
+  return `HASNA_${envToken2(name)}_API_KEY_OVERRIDE`;
+}
+var CREDENTIAL_PROFILE_ENV_KEY2 = "HASNA_PROFILE";
 var MAX_CREDENTIAL_FILE_BYTES2 = 64 * 1024;
 var INSPECT_CUSTOM2 = Symbol.for("nodejs.util.inspect.custom");
 var DEPRECATION_REGISTRY2 = Symbol.for("hasna:contracts:credentialDeprecationNotices");
@@ -16566,10 +16570,19 @@ function resolveKnowledgeCloudStore(env = process.env) {
   const client = resolveKnowledgeCloudClient(env);
   return client ? wrap(client) : null;
 }
-function resolveKnowledgeCloudClient(env) {
+function guardedTransportEnv(env) {
+  const guardedEnv = { ...env };
+  delete guardedEnv.HOME;
+  delete guardedEnv.USERPROFILE;
+  delete guardedEnv[CREDENTIAL_PROFILE_ENV_KEY2];
+  delete guardedEnv[credentialOverrideEnvKey2(KNOWLEDGE_APP_SLUG)];
+  return guardedEnv;
+}
+function resolveKnowledgeCloudClient(env, options = {}) {
   if (resolveKnowledgeModeSelection(env).mode !== "postgres")
     return null;
-  const resolved = resolveStorageClient(KNOWLEDGE_APP_SLUG, pinnedTransportEnv(env, "postgres"), transportOverrides(env));
+  const transportEnv = options.guarded ? guardedTransportEnv(env) : env;
+  const resolved = resolveStorageClient(KNOWLEDGE_APP_SLUG, pinnedTransportEnv(transportEnv, "postgres"), transportOverrides(transportEnv));
   if (resolved.transport !== "http")
     return null;
   return resolved.client;

dist/index.js

@@ -15978,6 +15978,10 @@ function clientTransportEnvKeys2(name) {
     apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
   };
 }
+function credentialOverrideEnvKey2(name) {
+  return `HASNA_${envToken2(name)}_API_KEY_OVERRIDE`;
+}
+var CREDENTIAL_PROFILE_ENV_KEY2 = "HASNA_PROFILE";
 var MAX_CREDENTIAL_FILE_BYTES2 = 64 * 1024;
 var INSPECT_CUSTOM2 = Symbol.for("nodejs.util.inspect.custom");
 var DEPRECATION_REGISTRY2 = Symbol.for("hasna:contracts:credentialDeprecationNotices");
@@ -16654,12 +16658,21 @@ function resolveKnowledgeCloudStore(env = process.env) {
   return client ? wrap(client) : null;
 }
 function resolveKnowledgeGuardedTransport(env = process.env) {
-  return resolveKnowledgeCloudClient(env)?.transport ?? null;
+  return resolveKnowledgeCloudClient(env, { guarded: true })?.transport ?? null;
+}
+function guardedTransportEnv(env) {
+  const guardedEnv = { ...env };
+  delete guardedEnv.HOME;
+  delete guardedEnv.USERPROFILE;
+  delete guardedEnv[CREDENTIAL_PROFILE_ENV_KEY2];
+  delete guardedEnv[credentialOverrideEnvKey2(KNOWLEDGE_APP_SLUG)];
+  return guardedEnv;
 }
-function resolveKnowledgeCloudClient(env) {
+function resolveKnowledgeCloudClient(env, options = {}) {
   if (resolveKnowledgeModeSelection(env).mode !== "postgres")
     return null;
-  const resolved = resolveStorageClient(KNOWLEDGE_APP_SLUG, pinnedTransportEnv(env, "postgres"), transportOverrides(env));
+  const transportEnv = options.guarded ? guardedTransportEnv(env) : env;
+  const resolved = resolveStorageClient(KNOWLEDGE_APP_SLUG, pinnedTransportEnv(transportEnv, "postgres"), transportOverrides(transportEnv));
   if (resolved.transport !== "http")
     return null;
   return resolved.client;

dist/storage.js

@@ -1108,6 +1108,10 @@ function clientTransportEnvKeys2(name) {
     apiKeyKeys: [`HASNA_${envSegment}_API_KEY`, `${envSegment}_API_KEY`]
   };
 }
+function credentialOverrideEnvKey2(name) {
+  return `HASNA_${envToken2(name)}_API_KEY_OVERRIDE`;
+}
+var CREDENTIAL_PROFILE_ENV_KEY2 = "HASNA_PROFILE";
 var MAX_CREDENTIAL_FILE_BYTES2 = 64 * 1024;
 var INSPECT_CUSTOM2 = Symbol.for("nodejs.util.inspect.custom");
 var DEPRECATION_REGISTRY2 = Symbol.for("hasna:contracts:credentialDeprecationNotices");
@@ -1784,12 +1788,21 @@ function resolveKnowledgeCloudStore(env = process.env) {
   return client ? wrap(client) : null;
 }
 function resolveKnowledgeGuardedTransport(env = process.env) {
-  return resolveKnowledgeCloudClient(env)?.transport ?? null;
+  return resolveKnowledgeCloudClient(env, { guarded: true })?.transport ?? null;
+}
+function guardedTransportEnv(env) {
+  const guardedEnv = { ...env };
+  delete guardedEnv.HOME;
+  delete guardedEnv.USERPROFILE;
+  delete guardedEnv[CREDENTIAL_PROFILE_ENV_KEY2];
+  delete guardedEnv[credentialOverrideEnvKey2(KNOWLEDGE_APP_SLUG)];
+  return guardedEnv;
 }
-function resolveKnowledgeCloudClient(env) {
+function resolveKnowledgeCloudClient(env, options = {}) {
   if (resolveKnowledgeModeSelection(env).mode !== "postgres")
     return null;
-  const resolved = resolveStorageClient(KNOWLEDGE_APP_SLUG, pinnedTransportEnv(env, "postgres"), transportOverrides(env));
+  const transportEnv = options.guarded ? guardedTransportEnv(env) : env;
+  const resolved = resolveStorageClient(KNOWLEDGE_APP_SLUG, pinnedTransportEnv(transportEnv, "postgres"), transportOverrides(transportEnv));
   if (resolved.transport !== "http")
     return null;
   return resolved.client;

src/cloud-store.ts

@@ -27,6 +27,10 @@ import {
   resolveStorageClient,
   type HasnaStorageClient,
 } from '@hasna/contracts/client/storage';
+import {
+  CREDENTIAL_PROFILE_ENV_KEY,
+  credentialOverrideEnvKey,
+} from '@hasna/contracts/client';
 import type { KnowledgeItem, KnowledgeItemVersion, KnowledgeItemVersionList } from './store';
 import {
   KNOWLEDGE_APP_SLUG,
@@ -293,15 +297,28 @@ export function resolveKnowledgeCloudStore(env: NodeJS.ProcessEnv = process.env)
 export function resolveKnowledgeGuardedTransport(
   env: NodeJS.ProcessEnv = process.env,
 ): HasnaStorageClient['transport'] | null {
-  return resolveKnowledgeCloudClient(env)?.transport ?? null;
+  return resolveKnowledgeCloudClient(env, { guarded: true })?.transport ?? null;
+}
+
+function guardedTransportEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  const guardedEnv = { ...env };
+  // FCAME-1 producers are handed an explicit transport env for one authority.
+  // Do not let broader process credential tiers (profile, override, or HOME
+  // disk lookup) outrank that supplied env and authenticate as another tenant.
+  delete guardedEnv.HOME;
+  delete guardedEnv.USERPROFILE;
+  delete guardedEnv[CREDENTIAL_PROFILE_ENV_KEY];
+  delete guardedEnv[credentialOverrideEnvKey(KNOWLEDGE_APP_SLUG)];
+  return guardedEnv;
 }
 
-function resolveKnowledgeCloudClient(env: NodeJS.ProcessEnv): HasnaStorageClient | null {
+function resolveKnowledgeCloudClient(env: NodeJS.ProcessEnv, options: { guarded?: boolean } = {}): HasnaStorageClient | null {
   if (resolveKnowledgeModeSelection(env).mode !== 'postgres') return null;
+  const transportEnv = options.guarded ? guardedTransportEnv(env) : env;
   const resolved = resolveStorageClient(
     KNOWLEDGE_APP_SLUG,
-    pinnedTransportEnv(env, 'postgres'),
-    transportOverrides(env),
+    pinnedTransportEnv(transportEnv, 'postgres'),
+    transportOverrides(transportEnv),
   );
   if (resolved.transport !== 'http') return null;
   return resolved.client;

tests/guarded-writer.test.ts

@@ -1,9 +1,13 @@
 import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
 import { ApiKeyStore, mintApiKey, verifyApiKey } from '@hasna/contracts/auth';
 import type { PGlite } from '@electric-sql/pglite';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import * as publicApi from '../src/index';
 import {
   DEFAULT_KNOWLEDGE_GUARDED_LIMITS,
+  KNOWLEDGE_GUARDED_WRITE_CONTRACT,
   KnowledgeGuardedManifestConflictError,
   KnowledgeGuardedManifestStepRefusedError,
   KnowledgeGuardedOperationConflictError,
@@ -42,6 +46,8 @@ const BINDING: KnowledgeGuardedBinding = {
   scope: 'global',
   parent_id: 'global:global',
 };
+const SUPPLIED_SENTINEL_KEY = 'fake-supplied-guarded-writer-env-key';
+const AMBIENT_SENTINEL_KEY = 'fake-ambient-guarded-writer-env-key';
 
 let db: PGlite;
 let server: { port: number; stop: (closeActive?: boolean) => void };
@@ -124,6 +130,74 @@ function writer(binding: KnowledgeGuardedBinding = BINDING, requireManifest = fa
   });
 }
 
+test('REGRESSION: guarded writer uses the supplied env endpoint and credential, not ambient credentials', async () => {
+  const originalFetch = globalThis.fetch;
+  const savedAmbient = {
+    mode: process.env.HASNA_KNOWLEDGE_STORAGE_MODE,
+    url: process.env.HASNA_KNOWLEDGE_API_URL,
+    key: process.env.HASNA_KNOWLEDGE_API_KEY,
+  };
+  const home = mkdtempSync(join(tmpdir(), 'knowledge-guarded-writer-env-'));
+  const credentialDir = join(home, '.hasna', 'cloud');
+  mkdirSync(credentialDir, { recursive: true });
+  await Bun.write(
+    join(credentialDir, 'knowledge.env'),
+    `HASNA_KNOWLEDGE_API_KEY=${AMBIENT_SENTINEL_KEY}\n`,
+  );
+
+  const captured: Array<{ url: string; xApiKey: string | null; authorization: string | null }> = [];
+  globalThis.fetch = (async (input, init) => {
+    const headers = new Headers(init?.headers);
+    captured.push({
+      url: String(input),
+      xApiKey: headers.get('x-api-key'),
+      authorization: headers.get('authorization'),
+    });
+    return new Response(JSON.stringify({
+      contract: KNOWLEDGE_GUARDED_WRITE_CONTRACT,
+      exact: true,
+      bounded: true,
+      manifest: { manifest_id: 'manifest-env-precedence' },
+    }), {
+      status: 200,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as typeof fetch;
+
+  try {
+    process.env.HASNA_KNOWLEDGE_STORAGE_MODE = 'postgres';
+    process.env.HASNA_KNOWLEDGE_API_URL = 'http://127.0.0.1:65530/ambient';
+    process.env.HASNA_KNOWLEDGE_API_KEY = AMBIENT_SENTINEL_KEY;
+
+    const suppliedEnv = {
+      ...process.env,
+      HOME: home,
+      HASNA_KNOWLEDGE_STORAGE_MODE: 'postgres',
+      HASNA_KNOWLEDGE_API_URL: 'http://127.0.0.1:65531/supplied',
+      HASNA_KNOWLEDGE_API_KEY: SUPPLIED_SENTINEL_KEY,
+      KNOWLEDGE_API_KEY: SUPPLIED_SENTINEL_KEY,
+    } as NodeJS.ProcessEnv;
+
+    const guarded = createKnowledgeGuardedWriter({ binding: BINDING, env: suppliedEnv });
+    await guarded.reconcileManifest('manifest-env-precedence');
+
+    expect(captured).toHaveLength(1);
+    expect(captured[0].url).toStartWith('http://127.0.0.1:65531/supplied/v1/guarded-manifests/');
+    expect(captured[0].xApiKey).toBe(SUPPLIED_SENTINEL_KEY);
+    expect(captured[0].authorization).toBe(`Bearer ${SUPPLIED_SENTINEL_KEY}`);
+    expect(captured[0].xApiKey).not.toBe(AMBIENT_SENTINEL_KEY);
+  } finally {
+    globalThis.fetch = originalFetch;
+    rmSync(home, { recursive: true, force: true });
+    if (savedAmbient.mode === undefined) delete process.env.HASNA_KNOWLEDGE_STORAGE_MODE;
+    else process.env.HASNA_KNOWLEDGE_STORAGE_MODE = savedAmbient.mode;
+    if (savedAmbient.url === undefined) delete process.env.HASNA_KNOWLEDGE_API_URL;
+    else process.env.HASNA_KNOWLEDGE_API_URL = savedAmbient.url;
+    if (savedAmbient.key === undefined) delete process.env.HASNA_KNOWLEDGE_API_KEY;
+    else process.env.HASNA_KNOWLEDGE_API_KEY = savedAmbient.key;
+  }
+});
+
 function deterministicManifestId(
   operationId: string,
   binding: KnowledgeGuardedBinding = BINDING,