@orchestraworks/cli 0.5.8 → 0.6.0

package/README.md

@@ -20,7 +20,7 @@ The full guide to every construct, secrets, connections and troubleshooting is [
 ```bash
 npm install -g @orchestraworks/cli         # the CLI, on your path as `orchestra`
 npm install @orchestraworks/cli            # the current release
-npm install @orchestraworks/cli@0.5.8      # this exact release
+npm install @orchestraworks/cli@0.6.0      # this exact release
 ```
 
 Then `import { Factory, Agent, … } from "@orchestraworks/cli"` normally — the package `exports` entry resolves

package/dist/cli/api/approval.js

@@ -6,7 +6,7 @@
 // policy is resolved once per invocation at command-handler entry and handed in — this module reads no
 // environment variable and holds no default, so a gate can never disagree with the banner that described it.
 // An unattended invocation that WOULD prompt is a named refusal, never a silent proceed.
-import { MANAGED_BY_LABEL_KEY } from "../../core/labels.js";
+import { MANAGED_BY_LABEL_KEY, managedByOf } from "../../core/labels.js";
 import { describeSource, preApprovalLevers, } from "../core/approval-policy.js";
 import { isAffirmative, NOTHING_WAS_WRITTEN, readConfirmLine } from "../core/prompts.js";
 /**
@@ -139,8 +139,8 @@ export function readManagedByMarker(body) {
     if (typeof labels !== "object" || labels === null || Array.isArray(labels)) {
         return undefined;
     }
-    const marker = labels[MANAGED_BY_LABEL_KEY];
-    return typeof marker === "string" && marker !== "" ? marker : undefined;
+    const marker = managedByOf(labels);
+    return marker !== "" ? marker : undefined;
 }
 /**
  * It states the CONSEQUENCE — the next `apply` reverts this — because that, not the marker, is what the

package/dist/cli/commands/outpost/local.js

@@ -15,14 +15,13 @@ import { spawnSync } from "node:child_process";
 import { chmodSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { StackUnreachableError, authorityBytes, readCurrentRun, readProbe, readRun, ensureDir, localDir, readRunFacts, removeIfPresent, sameAddress, stackConfigDir, addressKey, } from "../local/launcher.js";
+import { EGRESS_CA_URL, machineValue } from "./machine-names.js";
 /**
  * Where a container fetches this run's certificate authority when nothing names another path. It is the
  * agent account's own home in our runtime image, which the image contract fixes at `/home`; any other
  * image names its own with `--trust-file`.
  */
 export const DEFAULT_TRUST_FILE = "/home/.orchestra/local-authority.pem";
-/** The name the container's own set carries the plain authority endpoint on (`local/launch/bootstrap.go`). */
-const AUTHORITY_URL_NAME = "SFDK_EGRESS_CA_URL";
 export async function requireLocalEnvironment(call) {
     try {
         await trustThisRunsAuthority(call);
@@ -116,7 +115,8 @@ function authorityEndpoint(call, env) {
             // The folder is gone or unreadable, so the exported endpoint below is all there is.
         }
     }
-    const exported = (env[AUTHORITY_URL_NAME] ?? "").trim();
+    // The container's own set carries the plain authority endpoint on this name (`local/launch/bootstrap.go`).
+    const exported = machineValue(env, EGRESS_CA_URL);
     return exported === "" ? undefined : { url: exported, trustFile: DEFAULT_TRUST_FILE };
 }
 /**

package/dist/cli/commands/outpost/machine-names.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A machine name under the spelling a worker reads first and the former one that a worker built before the
+ * rename reads alone. Both are written, and the new one is read first, until the compatibility rules of
+ * the rename end. Each pair is the one `fwp/schema/environment-v1.json` declares.
+ */
+export interface MachineName {
+    readonly name: string;
+    readonly former: string;
+}
+export declare const EGRESS_CA_URL: MachineName;
+export declare const ENROLLMENT_TOKEN: MachineName;
+export declare const TRANSPORT_TRUST_ROOTS: MachineName;
+export declare const TRANSPORT_TRUST_ROOTS_FILE: MachineName;
+/** The trimmed value under the new name, or under the former one where the new one is unset or blank. */
+export declare function machineValue(env: NodeJS.ProcessEnv, machineName: MachineName): string;
+/** The value under both spellings. */
+export declare function bothSpellings(machineName: MachineName, value: string): Record<string, string>;

package/dist/cli/commands/outpost/machine-names.js

@@ -0,0 +1,22 @@
+export const EGRESS_CA_URL = { name: "ORCHESTRA_EGRESS_CA_URL", former: "SFDK_EGRESS_CA_URL" };
+export const ENROLLMENT_TOKEN = {
+    name: "ORCHESTRA_WORKER_ENROLLMENT_TOKEN",
+    former: "SFDK_ENROLLMENT_TOKEN",
+};
+export const TRANSPORT_TRUST_ROOTS = {
+    name: "ORCHESTRA_WORKER_TRANSPORT_TRUST_ROOTS",
+    former: "SFDK_TRANSPORT_TRUST_ROOTS",
+};
+export const TRANSPORT_TRUST_ROOTS_FILE = {
+    name: "ORCHESTRA_WORKER_TRANSPORT_TRUST_ROOTS_FILE",
+    former: "SFDK_TRANSPORT_TRUST_ROOTS_FILE",
+};
+/** The trimmed value under the new name, or under the former one where the new one is unset or blank. */
+export function machineValue(env, machineName) {
+    const value = (env[machineName.name] ?? "").trim();
+    return value !== "" ? value : (env[machineName.former] ?? "").trim();
+}
+/** The value under both spellings. */
+export function bothSpellings(machineName, value) {
+    return { [machineName.name]: value, [machineName.former]: value };
+}

package/dist/cli/commands/outpost/up.js

@@ -25,6 +25,7 @@ import { runWorkerBinary } from "../worker/launcher.js";
 import { bootCheckOfEnrollment, evaluateChecks, latestSession, listEnrollments, parseBudgets, readAgent, readEnrollment, readEnvironment, renderChecks, } from "../local/checks.js";
 import { ensureDir, readRun, runLocal, stackConfigDir, } from "../local/launcher.js";
 import { DEFAULT_TRUST_FILE, composeBootstrap, mintEnrollment, placeAuthority, requireAgentId, requireEnrolledEnvironment, requireHarness, readOutpostRecord, requireLocalEnvironment, resolveRunFolder, writeOutpostRecord, } from "./local.js";
+import { bothSpellings, EGRESS_CA_URL, ENROLLMENT_TOKEN, machineValue, TRANSPORT_TRUST_ROOTS, TRANSPORT_TRUST_ROOTS_FILE, } from "./machine-names.js";
 /**
  * The port every worker's token feed listens on (`worker/shim/feed.go`). One worker runs on a machine and
  * one shim reads from it, so the two agree on a number rather than on a variable; a second outpost here
@@ -262,14 +263,14 @@ function accountNumber(args) {
  * composed from is this container's own, which is where `docker run -e OPENAI_API_KEY` put it.
  */
 async function prepareInContainer(deps, apis, env, agent, harness, trustFile, namedRoot) {
-    const offer = (env.SFDK_ENROLLMENT_TOKEN ?? "").trim();
+    const offer = machineValue(env, ENROLLMENT_TOKEN);
     if (offer === "") {
         throw new Error("this container carries no enrollment offer: run `orchestra outpost token --agent " +
             `${agent.id}\` on the machine serving the stack and export what it prints here.`);
     }
-    const authority = (env.SFDK_EGRESS_CA_URL ?? "").trim();
+    const authority = machineValue(env, EGRESS_CA_URL);
     if (authority === "") {
-        throw new Error("this container's environment names no certificate authority in SFDK_EGRESS_CA_URL, and it verifies " +
+        throw new Error(`this container's environment names no certificate authority in ${EGRESS_CA_URL.name}, and it verifies ` +
             "this run's certificate against one. Export what `orchestra outpost token` printed.");
     }
     await placeAuthority(authority, trustFile, deps.fetchApi);
@@ -278,10 +279,11 @@ async function prepareInContainer(deps, apis, env, agent, harness, trustFile, na
         throw new Error("no enrollment of this run matches the offer this container carries; mint another one.");
     }
     const composed = workerEnvironment(env, {
-        SFDK_TRANSPORT_TRUST_ROOTS_FILE: trustFile,
+        ...bothSpellings(TRANSPORT_TRUST_ROOTS_FILE, trustFile),
         ...emptiedCarriers(harness, env),
     });
-    delete composed.SFDK_TRANSPORT_TRUST_ROOTS;
+    delete composed[TRANSPORT_TRUST_ROOTS.name];
+    delete composed[TRANSPORT_TRUST_ROOTS.former];
     const home = (composed.HOME ?? "").trim();
     const credentials = composeCredentialFiles(agent, harness, env);
     if (credentials.length > 0 && home === "") {

package/dist/cli/commands/worker/enroll.d.ts

@@ -3,8 +3,9 @@ export interface WorkerEnrollOptions {
     root?: string;
 }
 /**
- * There is deliberately no token flag. The worker reads the enrollment token from `SFDK_ENROLLMENT_TOKEN` or
- * the file `SFDK_ENROLLMENT_TOKEN_FILE` names, because a token on a command line is readable by every process
- * listing on the machine for as long as the process runs, and it lands in shell history on the way in.
+ * There is deliberately no token flag. The worker reads the enrollment token from
+ * `ORCHESTRA_WORKER_ENROLLMENT_TOKEN` or the file `ORCHESTRA_WORKER_ENROLLMENT_TOKEN_FILE` names, because a token
+ * on a command line is readable by every process listing on the machine for as long as the process runs, and it
+ * lands in shell history on the way in.
  */
 export declare function workerEnrollCommand(options?: WorkerEnrollOptions, deps?: WorkerCommandDeps): Promise<void>;

package/dist/cli/commands/worker/enroll.js

@@ -1,8 +1,9 @@
 import { handOffToWorker, optionalFlag } from "./launcher.js";
 /**
- * There is deliberately no token flag. The worker reads the enrollment token from `SFDK_ENROLLMENT_TOKEN` or
- * the file `SFDK_ENROLLMENT_TOKEN_FILE` names, because a token on a command line is readable by every process
- * listing on the machine for as long as the process runs, and it lands in shell history on the way in.
+ * There is deliberately no token flag. The worker reads the enrollment token from
+ * `ORCHESTRA_WORKER_ENROLLMENT_TOKEN` or the file `ORCHESTRA_WORKER_ENROLLMENT_TOKEN_FILE` names, because a token
+ * on a command line is readable by every process listing on the machine for as long as the process runs, and it
+ * lands in shell history on the way in.
  */
 export async function workerEnrollCommand(options = {}, deps = {}) {
     await handOffToWorker(["enroll", ...optionalFlag("--root", options.root)], deps);

package/dist/cli/core/auth.d.ts

@@ -18,10 +18,20 @@ export declare const AUTH_ENV: {
     readonly tokenFile: "ORCHESTRA_API_TOKEN_FILE";
     readonly organizationId: "ORCHESTRA_ORGANIZATION_ID";
     /** Presence is the declaration. */
-    readonly edgeInjected: "SFDK_AUTH_EDGE_INJECTED";
+    readonly edgeInjected: "ORCHESTRA_AUTH_EDGE_INJECTED";
     /** Set by the worker on each harness process it starts. */
+    readonly sessionId: "ORCHESTRA_SESSION_ID";
+};
+/**
+ * The spellings a machine set before the rename, read when the name above is absent: a running worker and a
+ * pinned runtime image still set only these.
+ */
+export declare const FORMER_MACHINE_ENV: {
+    readonly edgeInjected: "SFDK_AUTH_EDGE_INJECTED";
     readonly sessionId: "SFDK_SESSION_ID";
 };
+/** Whether this machine declares edge authentication, under either spelling. */
+export declare function edgeInjectedFrom(env: NodeJS.ProcessEnv): boolean;
 /** The base URL the environment names, and which of the two variables named it. */
 export declare function baseUrlFromEnv(env: NodeJS.ProcessEnv): {
     readonly value: string;

package/dist/cli/core/auth.js

@@ -34,10 +34,22 @@ export const AUTH_ENV = {
     tokenFile: "ORCHESTRA_API_TOKEN_FILE",
     organizationId: "ORCHESTRA_ORGANIZATION_ID",
     /** Presence is the declaration. */
-    edgeInjected: "SFDK_AUTH_EDGE_INJECTED",
+    edgeInjected: "ORCHESTRA_AUTH_EDGE_INJECTED",
     /** Set by the worker on each harness process it starts. */
+    sessionId: "ORCHESTRA_SESSION_ID",
+};
+/**
+ * The spellings a machine set before the rename, read when the name above is absent: a running worker and a
+ * pinned runtime image still set only these.
+ */
+export const FORMER_MACHINE_ENV = {
+    edgeInjected: "SFDK_AUTH_EDGE_INJECTED",
     sessionId: "SFDK_SESSION_ID",
 };
+/** Whether this machine declares edge authentication, under either spelling. */
+export function edgeInjectedFrom(env) {
+    return firstPresent(env[AUTH_ENV.edgeInjected], env[FORMER_MACHINE_ENV.edgeInjected]) !== undefined;
+}
 /** The base URL the environment names, and which of the two variables named it. */
 export function baseUrlFromEnv(env) {
     for (const variable of [AUTH_ENV.baseUrl, AUTH_ENV.machineBaseUrl]) {
@@ -53,8 +65,13 @@ export function baseUrlFromEnv(env) {
  * The only reader of the variable: auth resolution and `login` both call it.
  */
 export function sessionIdFrom(env) {
-    const value = env[AUTH_ENV.sessionId]?.trim();
-    return value === undefined || value === "" ? undefined : value;
+    for (const variable of [AUTH_ENV.sessionId, FORMER_MACHINE_ENV.sessionId]) {
+        const value = env[variable]?.trim();
+        if (value !== undefined && value !== "") {
+            return value;
+        }
+    }
+    return undefined;
 }
 /**
  * The chain distinguishes "absent" from "empty", so the fields are copied conditionally: an unconditional
@@ -159,7 +176,7 @@ export async function resolveAuthWithWarnings(env, flags, deps = {}) {
     const tokenFilePath = firstPresent(env[AUTH_ENV.tokenFile]);
     const fileToken = envToken === undefined && tokenFilePath !== undefined ? tokenFromFile(tokenFilePath) : undefined;
     const profileToken = firstPresent(profile?.token);
-    const edgeDeclared = firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined;
+    const edgeDeclared = edgeInjectedFrom(env);
     // Read before the provider split: a person may export it by hand under any provider.
     const sessionId = sessionIdFrom(env);
     const withSessionId = sessionId !== undefined ? { sessionId } : {};

package/dist/cli/core/session-body.d.ts

@@ -1,5 +1,5 @@
 /**
- * The one body rule behind `SFDK_SESSION_ID`: a JSON object body that names no `sessionId` gains the
+ * The one body rule behind `ORCHESTRA_SESSION_ID`: a JSON object body that names no `sessionId` gains the
  * conversation id. Anything else goes out exactly as it came in: no id, a body that is not a string, a
  * content type other than `application/json`, a body that does not parse as a JSON object, and one that
  * already names a `sessionId`, which is how an explicit `--session-id` wins.

package/dist/cli/core/session-body.js

@@ -1,5 +1,5 @@
 /**
- * The one body rule behind `SFDK_SESSION_ID`: a JSON object body that names no `sessionId` gains the
+ * The one body rule behind `ORCHESTRA_SESSION_ID`: a JSON object body that names no `sessionId` gains the
  * conversation id. Anything else goes out exactly as it came in: no id, a body that is not a string, a
  * content type other than `application/json`, a body that does not parse as a JSON object, and one that
  * already names a `sessionId`, which is how an explicit `--session-id` wins.

package/dist/cli/firstRun.js

@@ -7,7 +7,7 @@
 // EVERYTHING THIS FILE PRINTS GOES TO STDERR, including the sign-in it runs. The interview can precede any
 // command, and stdout is that command's result channel — under `--output json` a question printed there
 // would land inside the document a caller is parsing.
-import { AUTH_ENV, authFlagsFrom, firstPresent, } from "./core/auth.js";
+import { AUTH_ENV, authFlagsFrom, edgeInjectedFrom, firstPresent, } from "./core/auth.js";
 import { loginCommand } from "./core/login.js";
 import { defaultIo } from "./core/output.js";
 import { DEFAULT_PROFILE_NAME, loadProfile as loadProfileFromDisk, saveProfile as saveProfileToDisk, } from "./core/profile.js";
@@ -181,7 +181,7 @@ export async function runFirstRunIfNeeded(flags, deps = {}) {
     }
     if (firstPresent(env[AUTH_ENV.token]) !== undefined ||
         firstPresent(env[AUTH_ENV.tokenFile]) !== undefined ||
-        firstPresent(env[AUTH_ENV.edgeInjected]) !== undefined) {
+        edgeInjectedFrom(env)) {
         return;
     }
     const loadProfile = deps.loadProfile ?? loadProfileFromDisk;

package/dist/cli/main.js

@@ -406,9 +406,10 @@ export function buildProgram(handlers = defaultHandlers, pointer = bundledSkillP
         .command("enroll")
         .option("--root <dir>", "directory this worker installed its pinned runtime and harness families into")
         .description("redeem this machine's enrollment token, then serve it")
-        .addHelpText("after", "\nThe enrollment token is read from SFDK_ENROLLMENT_TOKEN, or from the file SFDK_ENROLLMENT_TOKEN_FILE\n" +
-        "names. There is no flag for it: a token on the command line is readable by every process listing on\n" +
-        "the machine, and it lands in shell history on the way in.\n")
+        .addHelpText("after", "\nThe enrollment token is read from ORCHESTRA_WORKER_ENROLLMENT_TOKEN, or from the file\n" +
+        "ORCHESTRA_WORKER_ENROLLMENT_TOKEN_FILE names; the former names SFDK_ENROLLMENT_TOKEN and\n" +
+        "SFDK_ENROLLMENT_TOKEN_FILE still work. There is no flag for it: a token on the command line is readable\n" +
+        "by every process listing on the machine, and it lands in shell history on the way in.\n")
         .action((options) => handlers.workerEnroll(options));
     // The local environment, and the machines it runs. `up` deliberately takes NO auth flags: it starts a
     // stack rather than reaching one, and the address and the token it prints are the stack's own answer. The

package/dist/constructs/environment.d.ts

@@ -93,6 +93,7 @@ export interface RouteModelsViaGatewayOptions {
 export declare class EgressPolicy {
     private readonly defaultAction;
     private readonly rules;
+    private gatewayKey;
     private constructor();
     static denyAll(): EgressPolicy;
     /**
@@ -140,6 +141,8 @@ export declare class EgressPolicy {
      * as well.
      */
     routeModelsViaGateway(opts: RouteModelsViaGatewayOptions): EgressPolicy;
+    /** @internal The variables this policy names a credential in, each set to its reference. */
+    _declaredEnv(): Record<string, string>;
     /**
      * Each entry lands as an ordinary allow rule — the same wire shape, in the same `rules` array, in the same
      * declaration order — so the emitted plan is byte-identical to one where the author typed every rule out by
@@ -270,18 +273,24 @@ export interface EnvironmentProps {
     /** At most four, and never at `/home`. */
     disks?: DiskMount[];
     /**
-     * Set on every machine built from this environment and forwarded into the agent process itself. There is
-     * deliberately no "looks like a secret" detector on them: a checker that caught most API-key shapes would
-     * teach authors that the ones it missed were safe. Names beginning `SFDK_` are platform-owned, written last
-     * and rejected with a 400, except the four `SFDK_WORKER_*` release settings, which reach the worker alone. `HOME` is not a platform
-     * variable at all — the account inside the runtime image decides where the home directory is — so declaring
-     * it points the harness elsewhere, and a home off the mounted volume does not survive a machine recycle.
-     * `ANTHROPIC_BASE_URL` is not reserved; the way to point a harness at the model gateway is the agent's
-     * `modelSettings.enableModelGateway`. Whether two names are the same name is keyed on the TARGET OS, which makes two rejections real on
-     * Windows that cannot happen on POSIX: a case-variant of the reserved prefix is reserved, and two keys
-     * differing only in case are one variable, so the API keeps neither.
+     * Set on every machine built from this environment and forwarded into the agent process. There is no "looks
+     * like a secret" detector: one that caught most key shapes would teach authors the rest were safe. Names
+     * beginning `ORCHESTRA_` or `SFDK_` are platform-owned and refused, except ordinary `ORCHESTRA_FDK_` names and
+     * the `ORCHESTRA_WORKER_*` release settings, which reach the worker alone. `HOME` is the image's to decide;
+     * declaring it moves the harness off the mounted home. Names are compared under the target OS, so on Windows a
+     * case-variant of a reserved prefix is reserved and two keys differing only in case are one variable.
+     *
+     * A Secret or a Connection in place of text sets the reference `orchestra:secret/<id>` or
+     * `orchestra:connection/<id>`, resolved at apply, which a tool sends as its token and the egress edge
+     * replaces with that credential (`GH_TOKEN`, `GITLAB_TOKEN`, `ORCHESTRA_GIT_CREDENTIAL` for git).
+     */
+    env?: Record<string, string | ISecret | IConnection>;
+    /**
+     * The credentials a request from this environment's machines gets when it names none, the first whose hosts
+     * cover the request's host serving. `replace` defaults to true; false leaves a request that carries its own
+     * value in the credential's header as it was sent. Omitted, apply leaves the live list alone; `[]` clears it.
      */
-    env?: Record<string, string>;
+    credentials?: EnvironmentCredential[];
     /** The reference rides the environment; the value is resolved platform-side at each machine create and never
      *  leaves the control plane. */
     imagePullCredential?: ISecret;
@@ -304,6 +313,10 @@ export interface EnvironmentProps {
     /** Fixed at create; undeclared, the environment is created in Shared. */
     team?: ITeam;
 }
+export interface EnvironmentCredential {
+    credential: ISecret | IConnection;
+    replace?: boolean;
+}
 export declare class Environment extends Construct implements IEnvironment {
     /** Accepts a platform id or a slug interchangeably — one rule, stated on `IResource`. */
     readonly environmentId: string;

package/dist/constructs/environment.js

@@ -130,10 +130,30 @@ function normalizePaths(ruleName, paths) {
     }
     return [...paths];
 }
+/**
+ * The variables {@link EgressPolicy.routeModelsViaGateway} sets to the key Secret's reference: claude sends the
+ * first as its key, and the worker writes the second into codex's own auth file.
+ */
+const GATEWAY_KEY_ENV = ["ANTHROPIC_API_KEY", "ORCHESTRA_WORKER_OPENAI_API_KEY"];
+/** The edge reads this prefix where a request's token goes, and adds the credential the rest names. */
+const REFERENCE_PREFIX = "orchestra:";
+/**
+ * A Secret or a Connection as the platform names it, `secret/<id>` or `connection/<id>`, the id a reference
+ * token or the import as written until apply resolves it. Undefined for anything else.
+ */
+function credentialReference(value) {
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    if ("connectionId" in value && typeof value.connectionId === "string")
+        return `connection/${value.connectionId}`;
+    if ("secretId" in value && typeof value.secretId === "string")
+        return `secret/${value.secretId}`;
+    return undefined;
+}
 /**
  * A rule that still names a credential is an authored statement that can no longer apply, so it fails here
- * with the Secret declaration that replaces it: the rule's hosts become the Secret's `hosts`, and the binder's
- * form becomes its `injection`.
+ * with the Secret declaration that replaces it: the binder's form becomes the Secret's `injection`, and the rule's
+ * hosts its `injection.hosts`.
  */
 function refuseRuleCredential(ruleName, options, hosts) {
     const declared = options.credentials !== undefined
@@ -148,7 +168,7 @@ function refuseRuleCredential(ruleName, options, hosts) {
     const remedies = declared.map((entry) => secretRemedy(entry, hosts));
     throw new Error(`egress rule '${ruleName}': a rule carries no credential, so 'credential'/'credentials' is not accepted. ` +
         `A credential declares where and how it is presented on its own resource: ` +
-        `${remedies.length > 0 ? remedies.join("; ") : "give the Secret 'hosts' and an 'injection' recipe"}. ` +
+        `${remedies.length > 0 ? remedies.join("; ") : "give the Secret an 'injection' recipe with its 'hosts'"}. ` +
         `Then keep this rule as a network rule, with no credential.`);
 }
 /** The Secret declaration one binder stands for, with no value: a recipe and host names only. */
@@ -157,7 +177,7 @@ function secretRemedy(entry, hosts) {
         ? entry._credentialBinding()
         : undefined;
     if (binding === undefined)
-        return "give the Secret 'hosts' and an 'injection' recipe";
+        return "give the Secret an 'injection' recipe with its 'hosts'";
     const name = isRefToken(binding.secretId)
         ? `Secret '${parseRefToken(binding.secretId).path.join("/")}'`
         : `secret '${binding.secretId}'`;
@@ -166,7 +186,7 @@ function secretRemedy(entry, hosts) {
         : binding.header !== undefined
             ? JSON.stringify({ headers: [{ name: binding.header, value: binding.valueTemplate }] })
             : "its own injection recipe";
-    return `${name} takes hosts: ${JSON.stringify(hosts)} and injection: ${injection}`;
+    return `${name} takes injection: ${injection}, with hosts: ${JSON.stringify(hosts)} inside it`;
 }
 /**
  * **The builder is mutating, and every chaining method returns `this`, not a copy.** `denyAll()` or
@@ -181,6 +201,7 @@ function secretRemedy(entry, hosts) {
 export class EgressPolicy {
     defaultAction;
     rules = [];
+    gatewayKey;
     constructor(defaultAction) {
         this.defaultAction = defaultAction;
     }
@@ -300,18 +321,27 @@ export class EgressPolicy {
         }
         if (key instanceof Secret) {
             const remedy = `Declare it as new Secret(scope, id, { value: SecretValue.fromGatewayKey(gatewayKey), ` +
-                `hosts: ["${host}"], injection: { headers: [{ name: "Authorization", value: "Bearer \${secret}" }], ` +
-                `removeHeaders: ["x-api-key"] } }).`;
+                `injection: { headers: [{ name: "Authorization", value: "Bearer \${secret}" }], ` +
+                `removeHeaders: ["x-api-key"], hosts: ["${host}"] } }).`;
             if (!key._presentsHeader()) {
                 throw new Error(`routeModelsViaGateway(): key Secret '${key.node.path.join("/")}' has no 'injection' header, so the ` +
                     `gateway key is never presented. ${remedy}`);
             }
             if (!key._hosts().some((pattern) => hostPatternCovers(pattern, host))) {
                 throw new Error(`routeModelsViaGateway(): key Secret '${key.node.path.join("/")}' does not cover '${host}' in its ` +
-                    `'hosts' ${JSON.stringify(key._hosts())}, so model calls would leave with no key. ${remedy}`);
+                    `'injection.hosts' ${JSON.stringify(key._hosts())}, so model calls would leave with no key. ${remedy}`);
             }
         }
-        return this.allow(DEFAULT_MODEL_GATEWAY_RULE_NAME, { hosts: [host], priority: DEFAULT_MODEL_GATEWAY_PRIORITY });
+        this.allow(DEFAULT_MODEL_GATEWAY_RULE_NAME, { hosts: [host], priority: DEFAULT_MODEL_GATEWAY_PRIORITY });
+        this.gatewayKey = key;
+        return this;
+    }
+    /** @internal The variables this policy names a credential in, each set to its reference. */
+    _declaredEnv() {
+        if (this.gatewayKey === undefined)
+            return {};
+        const reference = REFERENCE_PREFIX + credentialReference(this.gatewayKey);
+        return Object.fromEntries(GATEWAY_KEY_ENV.map((name) => [name, reference]));
     }
     /**
      * Each entry lands as an ordinary allow rule — the same wire shape, in the same `rules` array, in the same
@@ -403,6 +433,16 @@ export class Environment extends Construct {
     constructor(scope, id, props) {
         super(scope, id);
         validateExplicitSlug(this, props.slug, "environment");
+        for (const [name, value] of Object.entries(props.env ?? {})) {
+            if (typeof value !== "string" && credentialReference(value) === undefined) {
+                throw new Error(`Environment '${id}': env '${name}' must be text, a Secret or a Connection.`);
+            }
+        }
+        props.credentials?.forEach((entry, index) => {
+            if (credentialReference(entry?.credential) === undefined) {
+                throw new Error(`Environment '${id}': credentials[${index}]: 'credential' must be a Secret or a Connection.`);
+            }
+        });
         const declaredOnStartMachine = props.hooks?.onStartMachine?.script;
         if (props.setup !== undefined && declaredOnStartMachine !== undefined && props.setup !== declaredOnStartMachine) {
             throw new Error(`Environment '${id}' declares both setup and hooks.onStartMachine with different scripts. ` +
@@ -435,6 +475,9 @@ export class Environment extends Construct {
             // Copied so a key added after the construct accepted the literal cannot ride a later synth into a
             // machine's env.
             ...(props.env !== undefined ? { env: { ...props.env } } : {}),
+            ...(props.credentials !== undefined
+                ? { credentials: props.credentials.map((entry) => ({ ...entry })) }
+                : {}),
         };
         this.explicitSlug = props.slug;
         this.displayName = props.name ?? id;
@@ -464,6 +507,19 @@ export class Environment extends Construct {
         const resources = this.props.resources ?? {};
         const cpu = resources.cpu ?? STANDARD_CPU;
         const onStartMachine = this.props.hooks?.onStartMachine ?? (this.props.setup ? { script: this.props.setup } : undefined);
+        // A FRESH object each synth: emitting the stored map by reference would let a caller mutating one returned
+        // plan's `payload.env` change every later synth.
+        const env = {};
+        for (const [name, value] of Object.entries(this.props.env ?? {})) {
+            env[name] = typeof value === "string" ? value : REFERENCE_PREFIX + credentialReference(value);
+        }
+        for (const [name, reference] of Object.entries(this.props.egress._declaredEnv())) {
+            if (env[name] !== undefined && env[name] !== reference) {
+                throw new Error(`Environment '${this.node.id}': env '${name}' is declared by routeModelsViaGateway() as the gateway ` +
+                    `key's reference, ${reference}. Drop it from env.`);
+            }
+            env[name] = reference;
+        }
         // The egress rules, `ingressPolicy.endpoints`, `volumeMounts` and `env` are ALWAYS emitted — empty when
         // unset — so clearing any of them reconciles through the platform's whole-object PATCH replace instead of
         // being masked as omitted. `env` inherits the known map residual: emptying a declared map as the SOLE
@@ -518,9 +574,7 @@ export class Environment extends Construct {
                     }),
                     ...(this.props.disks ?? []).map((disk) => ({ type: "disk", mountPath: disk.mountPath, size: disk.size })),
                 ],
-                // A FRESH object each synth: emitting the stored map by reference would let a caller mutating one
-                // returned plan's `payload.env` change every later synth.
-                env: { ...(this.props.env ?? {}) },
+                env,
                 // Always emitted — a token or an explicit null — so removing the credential reconciles to a cleared
                 // field. An omitted key would be dropped by JSON.stringify and the PATCH would read "unchanged".
                 imagePullSecretId: this.props.imagePullCredential?.secretId ?? null,
@@ -531,6 +585,16 @@ export class Environment extends Construct {
                     ? { computeProviderId: this.props.computeProvider?.computeProviderId ?? null }
                     : {}),
             },
+            // Only when declared, `[]` included: an omitted list must not clear defaults set in the console or by
+            // the platform's own seed.
+            ...(this.props.credentials !== undefined
+                ? {
+                    credentials: this.props.credentials.map((entry) => ({
+                        credential: credentialReference(entry.credential),
+                        replace: entry.replace ?? true,
+                    })),
+                }
+                : {}),
             ...(this.props.team !== undefined ? { teamId: this.props.team.teamId } : {}),
         };
         return { kind: "environment", path: this.node.path.join("/"), slug, managed: true, payload };

package/dist/constructs/secret.d.ts

@@ -3,9 +3,14 @@ import { Construct } from "../core/construct.js";
 import type { PlanResource, ValueFrom } from "../core/plan.js";
 import type { CredentialBindingData, IGatewayKey, ISecret, ITeam } from "./interfaces.js";
 /**
- * The request mutations the broker applies from this secret: `headers` are injected after credential
- * rendering, `removeHeaders` strips client-sent headers before injection. `removeHeaders` is optional here
- * and normalized to `[]` on the wire, so an inject-only recipe round-trips against the server's shape.
+ * The request mutations the broker applies from this secret, and where: `headers` are injected after credential
+ * rendering, `removeHeaders` strips client-sent headers first, and `hosts` names the hosts the recipe applies on.
+ * Both lists are optional here and `[]` on the wire, so an inject-only recipe round-trips against the server's
+ * shape. A secret with no recipe is stored only: the broker presents it on no request.
+ *
+ * For git over HTTPS, store `base64("<user>:<token>")` and present it as `Basic ${secret}`; GitHub's user is
+ * `x-access-token`. Encode it first, `printf 'x-access-token:%s' "$TOKEN" | base64 | tr -d '\n'`, or let
+ * `SecretValue.basicAuth` encode it at apply.
  */
 export interface InjectionRecipeProps {
     readonly headers: {
@@ -13,6 +18,12 @@ export interface InjectionRecipeProps {
         readonly value: string;
     }[];
     readonly removeHeaders?: string[];
+    /**
+     * The hosts this secret is presented on, in egress rule host syntax: an exact host, `*.suffix`, or `*`. A
+     * request to a covered host gets the `headers` at the egress edge; an environment's rules only decide whether
+     * the request may leave. Omitted, the recipe covers no host.
+     */
+    readonly hosts?: string[];
 }
 /**
  * Shared with the egress `inject()` binding factory so a bad recipe fails at synth identically whether it
@@ -84,12 +95,11 @@ export interface SecretProps {
     slug?: string;
     name?: string;
     description?: string;
+    /** How and where the secret is presented. Omitted, the secret is stored only. */
     injection?: InjectionRecipeProps;
     /**
-     * The hosts this secret is presented on, in egress rule host syntax: an exact host, `*.suffix`, or `*`. A
-     * request to a covered host gets the `injection` headers at the egress edge; an environment's rules only
-     * decide whether the request may leave. Omitted, the secret covers no host, and apply sends `[]`, so
-     * removing the prop clears the list.
+     * @deprecated Declare `injection.hosts` instead. Accepted for one release and moved into the recipe; refused
+     * when the recipe declares a different list.
      */
     hosts?: string[];
     /** Fixed at create; undeclared, the secret is created in Shared. */