stageflow 0.35.0 → 0.36.0

package/dist/channels/providers/slack.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { ChannelError } from "../errors.js";
+import { httpCall, parseJson, statusFailure } from "../http.js";
+import { healthOf, receiptFor, zodValidator } from "./kit.js";
+export const SLACK_BASE_URL = "https://slack.com/api";
+export const SLACK_META = {
+    label: "Slack",
+    blurb: "Not connected · post as a bot",
+    icon: "hash",
+    fields: [
+        { key: "botToken", label: "Bot token", hint: "xoxb-… from your Slack app (OAuth & Permissions). Needs chat:write.", target: "secret", input: "password", required: true, placeholder: "xoxb-..." },
+        { key: "teamId", label: "Workspace ID (optional)", hint: "Pins the connection to one workspace, such as T0123ABCD.", target: "config", input: "text", required: false, placeholder: "T0123ABCD" },
+    ],
+    recipient: { label: "Channel id", placeholder: "C0123ABCD (channel, group, DM or user id)", multiple: false, cc: false, template: false },
+    envNames: ["SLACK_BOT_TOKEN"],
+    yamlExample: `connections:
+  - id: ops-slack
+    provider: slack
+    secrets:
+      botToken: env:SLACK_BOT_TOKEN
+`,
+    stageExample: "    to: C0123ABCD",
+};
+const configSchema = z.object({ teamId: z.string().regex(/^T[A-Z0-9]{2,31}$/).optional() }).strict();
+const targetSchema = z.object({ to: z.string().regex(/^[CGDU][A-Z0-9]{2,31}$/) }).strict();
+const validateConfig = zodValidator(configSchema, "config");
+const validateTarget = zodValidator(targetSchema, "target", (data) => ({ channel: data.to }));
+const AUTH_ERRORS = new Set(["invalid_auth", "not_authed", "account_inactive", "token_revoked", "token_expired"]);
+const SCOPE_ERRORS = new Set(["missing_scope", "not_allowed_token_type", "no_permission", "restricted_action", "access_denied"]);
+const RECIPIENT_ERRORS = new Set([
+    "channel_not_found", "user_not_found", "is_archived", "not_in_channel", "cannot_dm_bot", "user_disabled",
+    "restricted_action_read_only_channel", "restricted_action_thread_only_channel", "channel_is_archived",
+]);
+const TRANSIENT_ERRORS = new Set(["internal_error", "fatal_error", "service_unavailable", "request_timeout"]);
+/** Maps a Slack `ok: false` error name. Names are mapped, never echoed. */
+export function slackFailure(name, mode, connectionId) {
+    const detail = { connectionId };
+    if (typeof name !== "string")
+        return new ChannelError(mode === "send" ? "CHANNEL_SEND_OUTCOME_UNKNOWN" : "CHANNEL_CONNECTION_FAILED", mode !== "send", detail);
+    if (AUTH_ERRORS.has(name))
+        return new ChannelError("CHANNEL_AUTH_FAILED", false, detail);
+    if (SCOPE_ERRORS.has(name))
+        return new ChannelError("CHANNEL_UNAUTHORIZED", false, detail);
+    if (RECIPIENT_ERRORS.has(name))
+        return new ChannelError("CHANNEL_RECIPIENT_REJECTED", false, detail);
+    if (name === "ratelimited" || name === "rate_limited")
+        return new ChannelError("CHANNEL_RATE_LIMIT", true, detail);
+    if (TRANSIENT_ERRORS.has(name)) {
+        return mode === "send" ? new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, detail) : new ChannelError("CHANNEL_CONNECTION_FAILED", true, detail);
+    }
+    return new ChannelError("CHANNEL_INVALID_INPUT", false, detail);
+}
+/**
+ * Posts as a Slack bot through `chat.postMessage`. The bot needs `chat:write`; posting to a
+ * public channel it has not joined also needs `chat:write.public`, and a direct message to a
+ * user id needs `im:write`. Receiving is not part of this phase.
+ */
+export function createSlackProvider(options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const base = options.baseUrl ?? SLACK_BASE_URL;
+    const headers = (connection) => ({ authorization: `Bearer ${connection.secrets.botToken}`, accept: "application/json" });
+    return {
+        id: "slack",
+        meta: SLACK_META,
+        operations: ["send"],
+        secrets: { required: ["botToken"] },
+        validateConfig,
+        validateTarget,
+        describe: config => (config.teamId ? { identity: config.teamId } : {}),
+        check: (connection, signal) => healthOf(async () => {
+            const result = await httpCall({
+                fetch: doFetch, url: `${base}/auth.test`, method: "POST", headers: headers(connection),
+                timeoutMs: options.checkTimeoutMs ?? 10000, signal, mode: "check", connectionId: connection.id,
+            });
+            if (result.status < 200 || result.status >= 300)
+                throw statusFailure(result.status, "check", connection.id);
+            const body = parseJson(result.text);
+            if (body?.ok !== true)
+                throw slackFailure(body?.error, "check", connection.id);
+            if (connection.config.teamId !== undefined && body.team_id !== connection.config.teamId) {
+                throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: connection.id, field: "teamId" });
+            }
+        }),
+        async send(connection, target, message, _context) {
+            const text = message.subject ? `*${message.subject}*\n${message.text}` : message.text;
+            const result = await httpCall({
+                fetch: doFetch, url: `${base}/chat.postMessage`, method: "POST", headers: headers(connection),
+                body: { channel: target.channel, text, link_names: false, unfurl_links: false, unfurl_media: false },
+                timeoutMs: options.sendTimeoutMs ?? 30000, mode: "send", connectionId: connection.id,
+            });
+            if (result.status < 200 || result.status >= 300)
+                throw statusFailure(result.status, "send", connection.id);
+            const body = parseJson(result.text);
+            if (body === undefined)
+                throw new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: connection.id });
+            if (body.ok !== true)
+                throw slackFailure(body.error, "send", connection.id);
+            return receiptFor(typeof body.ts === "string" ? body.ts : undefined);
+        },
+    };
+}

package/dist/channels/providers/telegram.d.ts

@@ -0,0 +1,21 @@
+import type { ChannelProvider, ProviderMeta } from "../types.js";
+export type TelegramConfig = {
+    botUsername?: string;
+};
+export type TelegramTarget = {
+    chatId: string | number;
+};
+export declare const TELEGRAM_BASE_URL = "https://api.telegram.org";
+export declare const TELEGRAM_MAX_TEXT = 4096;
+export declare const TELEGRAM_META: ProviderMeta;
+export type TelegramOptions = {
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    sendTimeoutMs?: number;
+    checkTimeoutMs?: number;
+};
+/**
+ * Sends through the Telegram Bot API with a bot token. The recipient must have started the
+ * bot (or the bot must be a member of the group or channel). Receiving is not part of this phase.
+ */
+export declare function createTelegramProvider(options?: TelegramOptions): ChannelProvider<TelegramConfig, TelegramTarget>;

package/dist/channels/providers/telegram.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { ChannelError } from "../errors.js";
+import { httpCall, parseJson, statusFailure } from "../http.js";
+import { healthOf, receiptFor, zodValidator } from "./kit.js";
+export const TELEGRAM_BASE_URL = "https://api.telegram.org";
+export const TELEGRAM_MAX_TEXT = 4096;
+export const TELEGRAM_META = {
+    label: "Telegram",
+    blurb: "Not connected · bot token",
+    icon: "send",
+    fields: [
+        { key: "botToken", label: "Bot token", hint: "From @BotFather. People must start the bot before it can message them.", target: "secret", input: "password", required: true, placeholder: "123456:ABC..." },
+        { key: "botUsername", label: "Bot username (optional)", hint: "Fails the check if the token belongs to another bot.", target: "config", input: "text", required: false, placeholder: "acme_alerts_bot" },
+    ],
+    recipient: { label: "Chat id", placeholder: "123456789 or @channelname", multiple: false, cc: false, template: false },
+    envNames: ["TELEGRAM_BOT_TOKEN"],
+    yamlExample: `connections:
+  - id: alerts-telegram
+    provider: telegram
+    secrets:
+      botToken: env:TELEGRAM_BOT_TOKEN
+`,
+    stageExample: '    to: "123456789"',
+};
+const configSchema = z.object({ botUsername: z.string().regex(/^[A-Za-z][A-Za-z0-9_]{4,31}$/).optional() }).strict();
+const chatId = z.union([
+    z.number().int().refine(Number.isSafeInteger),
+    z.string().regex(/^-?\d{1,20}$/),
+    z.string().regex(/^@[A-Za-z][A-Za-z0-9_]{4,31}$/),
+]);
+const targetSchema = z.object({ to: chatId }).strict();
+const validateConfig = zodValidator(configSchema, "config");
+const validateTarget = zodValidator(targetSchema, "target", (data) => ({ chatId: data.to }));
+/**
+ * Telegram mirrors its error in the HTTP status. A bot cannot message a user who has not
+ * started it or who blocked it (403), and an unknown chat is a 400. The description is only
+ * matched, never echoed.
+ */
+function telegramFailure(status, body, mode, connectionId) {
+    const detail = { connectionId };
+    const description = typeof body?.description === "string" ? body.description.toLowerCase() : "";
+    if (status === 404)
+        return new ChannelError("CHANNEL_AUTH_FAILED", false, detail);
+    if (status === 403 && mode === "send")
+        return new ChannelError("CHANNEL_RECIPIENT_REJECTED", false, detail);
+    if (status === 400 && mode === "send" && /chat not found|user not found|peer_id_invalid|chat_id is empty/.test(description)) {
+        return new ChannelError("CHANNEL_RECIPIENT_REJECTED", false, detail);
+    }
+    return statusFailure(status, mode, connectionId);
+}
+/**
+ * Sends through the Telegram Bot API with a bot token. The recipient must have started the
+ * bot (or the bot must be a member of the group or channel). Receiving is not part of this phase.
+ */
+export function createTelegramProvider(options = {}) {
+    const doFetch = options.fetch ?? fetch;
+    const base = options.baseUrl ?? TELEGRAM_BASE_URL;
+    const url = (connection, method) => `${base}/bot${connection.secrets.botToken}/${method}`;
+    return {
+        id: "telegram",
+        meta: TELEGRAM_META,
+        operations: ["send"],
+        secrets: { required: ["botToken"] },
+        validateConfig,
+        validateTarget,
+        describe: config => (config.botUsername ? { identity: `@${config.botUsername}` } : {}),
+        check: (connection, signal) => healthOf(async () => {
+            const result = await httpCall({
+                fetch: doFetch, url: url(connection, "getMe"), method: "GET", headers: { accept: "application/json" },
+                timeoutMs: options.checkTimeoutMs ?? 10000, signal, mode: "check", connectionId: connection.id,
+            });
+            const body = parseJson(result.text);
+            if (result.status < 200 || result.status >= 300)
+                throw telegramFailure(result.status, body, "check", connection.id);
+            if (body?.ok !== true)
+                throw new ChannelError("CHANNEL_CONNECTION_FAILED", true, { connectionId: connection.id });
+            const pinned = connection.config.botUsername;
+            if (pinned !== undefined && String(body.result?.username).toLowerCase() !== pinned.toLowerCase()) {
+                throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: connection.id, field: "botUsername" });
+            }
+        }),
+        async send(connection, target, message, _context) {
+            const text = message.subject ? `${message.subject}\n\n${message.text}` : message.text;
+            if (text.length > TELEGRAM_MAX_TEXT)
+                throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: connection.id, field: "text" });
+            const result = await httpCall({
+                fetch: doFetch, url: url(connection, "sendMessage"), method: "POST", headers: { accept: "application/json" },
+                body: { chat_id: target.chatId, text, link_preview_options: { is_disabled: true } },
+                timeoutMs: options.sendTimeoutMs ?? 30000, mode: "send", connectionId: connection.id,
+            });
+            const body = parseJson(result.text);
+            if (result.status < 200 || result.status >= 300)
+                throw telegramFailure(result.status, body, "send", connection.id);
+            if (body?.ok !== true)
+                throw new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, { connectionId: connection.id });
+            const id = body.result?.message_id;
+            return receiptFor(typeof id === "number" ? String(id) : undefined);
+        },
+    };
+}

package/dist/channels/providers.d.ts

@@ -0,0 +1,5 @@
+import type { AnyChannelProvider } from "./types.js";
+/** Built-in providers are listed in the initial map as they are implemented. */
+export declare function channelProviders(): AnyChannelProvider[];
+export declare function registerChannelProvider(provider: AnyChannelProvider): void;
+export declare function unregisterChannelProvider(id: string): void;

package/dist/channels/providers.js

@@ -0,0 +1,22 @@
+import { createAgentMailProvider } from "./providers/agentmail.js";
+import { createSlackProvider } from "./providers/slack.js";
+import { createTelegramProvider } from "./providers/telegram.js";
+import { createPhotonImessageProvider } from "./providers/photonImessage.js";
+import { createPhotonWhatsappProvider } from "./providers/photonWhatsapp.js";
+const providers = new Map([
+    ["agentmail", createAgentMailProvider()],
+    ["slack", createSlackProvider()],
+    ["telegram", createTelegramProvider()],
+    ["imessage", createPhotonImessageProvider()],
+    ["whatsapp", createPhotonWhatsappProvider()],
+]);
+/** Built-in providers are listed in the initial map as they are implemented. */
+export function channelProviders() {
+    return [...providers.values()];
+}
+export function registerChannelProvider(provider) {
+    providers.set(provider.id, provider);
+}
+export function unregisterChannelProvider(id) {
+    providers.delete(id);
+}

package/dist/channels/registry.d.ts

@@ -0,0 +1,54 @@
+import { type ConnectionsFile } from "./config.js";
+import { ChannelSecretStore, type SecretReader } from "./secretStore.js";
+import type { AnyChannelProvider, ConnectionSummary, ResolvedConnection, ResolvedCredential } from "./types.js";
+export declare const CONNECTIONS_FILE_NAME = "connections.yaml";
+/**
+ * Where connections live. Connections are host-level, like provider credentials, so the default is
+ * `$STAGEFLOW_HOME/connections.yaml`. A `connections.yaml` in the project root takes precedence when
+ * it exists (CI and checked-in setups), and `STAGEFLOW_CONNECTIONS_FILE` overrides both.
+ */
+export declare function connectionsFilePath(cwd: string, env?: NodeJS.ProcessEnv): string;
+export declare function defaultSecretStore(): ChannelSecretStore;
+export type ChannelRegistryOptions = {
+    cwd: string;
+    providers?: readonly AnyChannelProvider[];
+    env?: NodeJS.ProcessEnv;
+    /** Owner scope. TODO(multi-tenant): the local default is the workspace path, like email accounts. */
+    scope?: string;
+    file?: string;
+    /** Already parsed content, used to validate an edit before it is written. */
+    parsed?: ConnectionsFile;
+    secretStore?: SecretReader;
+};
+/** Host-owned, read-only view of `connections.yaml`. Reads return copies. */
+export declare class ChannelRegistry {
+    readonly scope: string;
+    private readonly env;
+    private readonly secretStore;
+    private readonly providers;
+    private readonly credentials;
+    private readonly connections;
+    constructor(options: ChannelRegistryOptions);
+    list(): ConnectionSummary[];
+    private summarize;
+    get(id: string, requireEnabled?: boolean): ConnectionSummary;
+    providerById(providerId: string): AnyChannelProvider;
+    /** Environment variable names that connections and credentials point at with `env:` references. */
+    envSecretNames(): string[];
+    providerList(): AnyChannelProvider[];
+    hasCredential(id: string): boolean;
+    /** Resolves a shared credential by id, for providers that reference one. */
+    resolveCredential(id: string): ResolvedCredential;
+    hasConnection(id: string): boolean;
+    providerFor(id: string): AnyChannelProvider;
+    validateTarget(id: string, target: unknown): unknown;
+    /** Reads secrets from the environment at call time. Values are never cached on the registry. */
+    resolve(id: string, requireEnabled?: boolean): ResolvedConnection;
+    private entry;
+    private requireProvider;
+    private addCredential;
+    private addConnection;
+    private checkSecretNames;
+    private checkCredential;
+}
+export declare function sealed<T extends ResolvedConnection>(value: T): T;

package/dist/channels/registry.js

@@ -0,0 +1,186 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { inspect } from "node:util";
+import { loadConnectionsFile } from "./config.js";
+import { ChannelError } from "./errors.js";
+import { channelProviders } from "./providers.js";
+import { resolveSecrets } from "./secrets.js";
+import { ChannelSecretStore } from "./secretStore.js";
+import { globalCredentialRoot, globalStageflowHome } from "../project/globalHome.js";
+export const CONNECTIONS_FILE_NAME = "connections.yaml";
+function hostConnectionsFile(env) {
+    const home = env.STAGEFLOW_HOME?.trim() || (env === process.env ? globalStageflowHome() : undefined);
+    return home ? path.join(path.resolve(home), CONNECTIONS_FILE_NAME) : undefined;
+}
+/**
+ * Where connections live. Connections are host-level, like provider credentials, so the default is
+ * `$STAGEFLOW_HOME/connections.yaml`. A `connections.yaml` in the project root takes precedence when
+ * it exists (CI and checked-in setups), and `STAGEFLOW_CONNECTIONS_FILE` overrides both.
+ */
+export function connectionsFilePath(cwd, env = process.env) {
+    const override = env.STAGEFLOW_CONNECTIONS_FILE?.trim();
+    if (override)
+        return path.isAbsolute(override) ? path.resolve(override) : path.resolve(cwd, override);
+    const project = path.join(path.resolve(cwd), CONNECTIONS_FILE_NAME);
+    if (existsSync(project))
+        return project;
+    return hostConnectionsFile(env) ?? project;
+}
+export function defaultSecretStore() {
+    return new ChannelSecretStore(path.join(globalCredentialRoot(), "channel-secrets.json"));
+}
+/** Host-owned, read-only view of `connections.yaml`. Reads return copies. */
+export class ChannelRegistry {
+    scope;
+    env;
+    secretStore;
+    providers = new Map();
+    credentials = new Map();
+    connections = new Map();
+    constructor(options) {
+        this.scope = options.scope ?? path.resolve(options.cwd);
+        this.env = options.env ?? process.env;
+        for (const provider of options.providers ?? channelProviders())
+            this.providers.set(provider.id, provider);
+        this.secretStore = options.secretStore ?? { get: name => defaultSecretStore().get(name) };
+        const file = options.parsed ?? loadConnectionsFile(options.file ?? connectionsFilePath(options.cwd, this.env));
+        for (const credential of file.credentials)
+            this.addCredential(credential);
+        for (const entry of file.connections)
+            this.addConnection(entry);
+    }
+    list() {
+        return [...this.connections.values()].map(entry => this.summarize(entry));
+    }
+    summarize(loaded) {
+        const identity = this.providers.get(loaded.provider)?.describe?.(loaded.config)?.identity;
+        return {
+            id: loaded.id, scope: this.scope, provider: loaded.provider, displayName: loaded.displayName,
+            enabled: loaded.enabled, ...(identity ? { identity } : {}),
+            ...(loaded.credential ? { credential: loaded.credential } : {}),
+            secrets: Object.fromEntries(Object.entries(loaded.secrets).map(([field, ref]) => [field, ref.startsWith("store:") ? "store" : "env"])),
+        };
+    }
+    get(id, requireEnabled = true) {
+        return this.summarize(this.entry(id, requireEnabled));
+    }
+    providerById(providerId) {
+        return this.requireProvider(providerId);
+    }
+    /** Environment variable names that connections and credentials point at with `env:` references. */
+    envSecretNames() {
+        const names = new Set();
+        for (const entry of [...this.credentials.values(), ...this.connections.values()]) {
+            for (const ref of Object.values(entry.secrets))
+                if (ref.startsWith("env:"))
+                    names.add(ref.slice("env:".length));
+        }
+        return [...names];
+    }
+    providerList() {
+        return [...this.providers.values()];
+    }
+    hasCredential(id) {
+        return this.credentials.has(id);
+    }
+    /** Resolves a shared credential by id, for providers that reference one. */
+    resolveCredential(id) {
+        const entry = this.credentials.get(id);
+        if (!entry)
+            throw new ChannelError("CHANNEL_INVALID_INPUT", false, { field: "credential" });
+        return { id: entry.id, provider: entry.provider, secrets: resolveSecrets(entry.secrets, this.env, `credential:${entry.id}`, this.secretStore) };
+    }
+    hasConnection(id) {
+        return this.connections.has(id);
+    }
+    providerFor(id) {
+        return this.requireProvider(this.entry(id, false).provider);
+    }
+    validateTarget(id, target) {
+        const result = this.providerFor(id).validateTarget(target);
+        if (!result.ok)
+            throw new ChannelError("CHANNEL_TARGET_INVALID", false, { connectionId: id });
+        return result.value;
+    }
+    /** Reads secrets from the environment at call time. Values are never cached on the registry. */
+    resolve(id, requireEnabled = true) {
+        const entry = this.entry(id, requireEnabled);
+        const secrets = resolveSecrets(entry.secrets, this.env, entry.id, this.secretStore);
+        const credentialEntry = entry.credential ? this.credentials.get(entry.credential) : undefined;
+        const credential = credentialEntry && {
+            id: credentialEntry.id,
+            provider: credentialEntry.provider,
+            secrets: resolveSecrets(credentialEntry.secrets, this.env, `credential:${credentialEntry.id}`, this.secretStore),
+        };
+        return sealed({
+            id: entry.id, scope: this.scope, provider: entry.provider, displayName: entry.displayName,
+            config: structuredClone(entry.config), secrets, ...(credential ? { credential } : {}),
+        });
+    }
+    entry(id, requireEnabled) {
+        const entry = this.connections.get(id);
+        if (!entry)
+            throw new ChannelError("CHANNEL_NOT_FOUND", false, { connectionId: id });
+        if (requireEnabled && !entry.enabled)
+            throw new ChannelError("CHANNEL_DISABLED", false, { connectionId: id });
+        return entry;
+    }
+    requireProvider(id) {
+        const provider = this.providers.get(id);
+        if (!provider)
+            throw new ChannelError("CHANNEL_PROVIDER_UNSUPPORTED");
+        return provider;
+    }
+    addCredential(entry) {
+        this.credentials.set(entry.id, entry);
+    }
+    addConnection(entry) {
+        const provider = this.providers.get(entry.provider);
+        if (!provider)
+            throw new ChannelError("CHANNEL_PROVIDER_UNSUPPORTED", false, { connectionId: entry.id });
+        const config = provider.validateConfig(entry.config);
+        if (!config.ok)
+            throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: entry.id, field: "config" });
+        this.checkSecretNames(provider, entry);
+        this.checkCredential(provider, entry);
+        this.connections.set(entry.id, {
+            ...entry, config: config.value, displayName: entry.displayName ?? entry.id,
+        });
+    }
+    checkSecretNames(provider, entry) {
+        const allowed = new Set([...provider.secrets.required, ...(provider.secrets.optional ?? [])]);
+        for (const name of Object.keys(entry.secrets)) {
+            if (!allowed.has(name))
+                throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: entry.id, field: name });
+        }
+        for (const name of provider.secrets.required) {
+            if (!(name in entry.secrets))
+                throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: entry.id, field: name });
+        }
+    }
+    checkCredential(provider, entry) {
+        if (!provider.credentialProvider) {
+            if (entry.credential)
+                throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: entry.id, field: "credential" });
+            return;
+        }
+        const credential = entry.credential ? this.credentials.get(entry.credential) : undefined;
+        if (!credential || credential.provider !== provider.credentialProvider) {
+            throw new ChannelError("CHANNEL_INVALID_INPUT", false, { connectionId: entry.id, field: "credential" });
+        }
+    }
+}
+export function sealed(value) {
+    const { secrets, credential, ...visible } = value;
+    const out = { ...visible };
+    Object.defineProperty(out, "secrets", { value: secrets, enumerable: false });
+    if (credential) {
+        const { secrets: credentialSecrets, ...credentialVisible } = credential;
+        const sealedCredential = { ...credentialVisible };
+        Object.defineProperty(sealedCredential, "secrets", { value: credentialSecrets, enumerable: false });
+        Object.defineProperty(out, "credential", { value: sealedCredential, enumerable: false });
+    }
+    Object.defineProperty(out, "toJSON", { value: () => visible, enumerable: false });
+    Object.defineProperty(out, inspect.custom, { value: () => ({ ...visible, secrets: "[redacted]" }), enumerable: false });
+    return out;
+}

package/dist/channels/secretStore.d.ts

@@ -0,0 +1,21 @@
+export declare const STORE_NAME_PATTERN: RegExp;
+/** Read side used when resolving `store:NAME` references. */
+export interface SecretReader {
+    get(name: string): string | undefined;
+}
+/**
+ * Secrets entered through the console. One JSON file, owner-only, replaced atomically. It lives
+ * in the credential root next to provider auth, so it has the same trust level as that file:
+ * anything running as the same user can read it. Values are never logged or returned by the API.
+ */
+export declare class ChannelSecretStore implements SecretReader {
+    private readonly file;
+    constructor(file: string);
+    private read;
+    private write;
+    get(name: string): string | undefined;
+    has(name: string): boolean;
+    set(name: string, value: string): void;
+    delete(name: string): void;
+    deleteWithPrefix(prefix: string): void;
+}

package/dist/channels/secretStore.js

@@ -0,0 +1,75 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { ChannelError } from "./errors.js";
+export const STORE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+const MAX_STORE_BYTES = 1048576;
+const MAX_SECRET_LENGTH = 8192;
+/**
+ * Secrets entered through the console. One JSON file, owner-only, replaced atomically. It lives
+ * in the credential root next to provider auth, so it has the same trust level as that file:
+ * anything running as the same user can read it. Values are never logged or returned by the API.
+ */
+export class ChannelSecretStore {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    read() {
+        if (!existsSync(this.file))
+            return {};
+        try {
+            if (statSync(this.file).size > MAX_STORE_BYTES)
+                throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+            const parsed = JSON.parse(readFileSync(this.file, "utf8"));
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new ChannelError("CHANNEL_STORAGE_FAILED");
+            const out = {};
+            for (const [name, value] of Object.entries(parsed))
+                if (typeof value === "string")
+                    out[name] = value;
+            return out;
+        }
+        catch (error) {
+            if (error instanceof ChannelError)
+                throw error;
+            throw new ChannelError("CHANNEL_STORAGE_FAILED");
+        }
+    }
+    write(values) {
+        const temporary = `${this.file}.${process.pid}.tmp`;
+        try {
+            mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+            writeFileSync(temporary, JSON.stringify(values), { mode: 0o600 });
+            renameSync(temporary, this.file);
+            chmodSync(this.file, 0o600);
+        }
+        catch {
+            throw new ChannelError("CHANNEL_STORAGE_FAILED");
+        }
+    }
+    get(name) {
+        return this.read()[name];
+    }
+    has(name) {
+        return this.get(name) !== undefined;
+    }
+    set(name, value) {
+        if (!STORE_NAME_PATTERN.test(name) || value.length === 0 || value.length > MAX_SECRET_LENGTH || /[\r\n\0]/.test(value)) {
+            throw new ChannelError("CHANNEL_INVALID_INPUT");
+        }
+        this.write({ ...this.read(), [name]: value });
+    }
+    delete(name) {
+        const values = this.read();
+        if (!(name in values))
+            return;
+        delete values[name];
+        this.write(values);
+    }
+    deleteWithPrefix(prefix) {
+        const values = this.read();
+        const kept = Object.fromEntries(Object.entries(values).filter(([name]) => !name.startsWith(prefix)));
+        if (Object.keys(kept).length !== Object.keys(values).length)
+            this.write(kept);
+    }
+}

package/dist/channels/secrets.d.ts

@@ -0,0 +1,15 @@
+import type { SecretReader } from "./secretStore.js";
+import type { SecretRef } from "./types.js";
+export declare const SECRET_REF_PATTERN: RegExp;
+export declare function isSecretRef(value: unknown): value is SecretRef;
+/**
+ * Resolves `env:NAME` with the repo's `NAME` / `NAME_FILE` convention, or `store:NAME` from the
+ * console secret store. Errors carry the connection id and field only, never a value or path.
+ */
+export declare function resolveSecretRef(ref: SecretRef, env: NodeJS.ProcessEnv, where: {
+    connectionId: string;
+    field: string;
+}, store?: SecretReader): string;
+export declare function resolveSecrets(refs: Readonly<Record<string, SecretRef>>, env: NodeJS.ProcessEnv, connectionId: string, store?: SecretReader): Record<string, string>;
+/** Removes every secret value from text before it reaches an error, log, or tool result. */
+export declare function redactSecrets(text: string, secrets: Iterable<string>): string;

package/dist/channels/secrets.js

@@ -0,0 +1,50 @@
+import { readSecretFromEnvOrFile, SecretFromEnvError } from "../config/secretFromEnvOrFile.js";
+import { ChannelError } from "./errors.js";
+export const SECRET_REF_PATTERN = /^(?:env:[A-Za-z_][A-Za-z0-9_]*|store:[A-Za-z0-9][A-Za-z0-9._-]{0,199})$/;
+export function isSecretRef(value) {
+    return typeof value === "string" && SECRET_REF_PATTERN.test(value);
+}
+/**
+ * Resolves `env:NAME` with the repo's `NAME` / `NAME_FILE` convention, or `store:NAME` from the
+ * console secret store. Errors carry the connection id and field only, never a value or path.
+ */
+export function resolveSecretRef(ref, env, where, store) {
+    let value;
+    if (ref.startsWith("store:")) {
+        try {
+            value = store?.get(ref.slice("store:".length));
+        }
+        catch {
+            throw new ChannelError("CHANNEL_SECRET_UNAVAILABLE", false, where);
+        }
+    }
+    else {
+        const name = ref.slice("env:".length);
+        try {
+            value = readSecretFromEnvOrFile(env, name);
+        }
+        catch (error) {
+            if (error instanceof SecretFromEnvError)
+                throw new ChannelError("CHANNEL_SECRET_UNAVAILABLE", false, where);
+            throw error;
+        }
+    }
+    if (value === undefined || value.length === 0)
+        throw new ChannelError("CHANNEL_SECRET_UNAVAILABLE", false, where);
+    return value;
+}
+export function resolveSecrets(refs, env, connectionId, store) {
+    const out = {};
+    for (const [field, ref] of Object.entries(refs))
+        out[field] = resolveSecretRef(ref, env, { connectionId, field }, store);
+    return out;
+}
+/** Removes every secret value from text before it reaches an error, log, or tool result. */
+export function redactSecrets(text, secrets) {
+    let result = text;
+    for (const secret of secrets) {
+        if (secret.length >= 4)
+            result = result.split(secret).join("[redacted]");
+    }
+    return result;
+}