stageflow 0.33.0 → 0.36.0

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;
+}

package/dist/channels/service.d.ts

@@ -0,0 +1,54 @@
+import { type ChannelErrorCode } from "./errors.js";
+import { type ChannelHealthOptions } from "./health.js";
+import type { ConnectionHealth, ConnectionSummary, ProviderMeta } from "./types.js";
+export type ChannelListing = {
+    connections: Array<ConnectionSummary & {
+        health?: ConnectionHealth;
+    }>;
+    /** Set when `connections.yaml` could not be loaded. The file's content is never included. */
+    error?: ChannelErrorCode;
+    limits: {
+        channelsPerStage: number;
+    };
+};
+export type ChannelMeta = {
+    providers: Array<ProviderMeta & {
+        id: string;
+    }>;
+    errors: Record<string, {
+        reason: string;
+        hint?: string;
+    }>;
+};
+export type ChannelService = {
+    /** What the console shows about each provider and each error code. Static; needs no secrets. */
+    meta(): ChannelMeta;
+    list(): ChannelListing;
+    /** Runs one live check now. Returns undefined when the connection is unknown or disabled. */
+    checkNow(id: string): Promise<ConnectionHealth | undefined>;
+    /** Checks entered values without saving anything. */
+    test(input: unknown): Promise<ConnectionHealth>;
+    /** Static check of a pinned recipient for a connection. No network, no secret read. */
+    validateTarget(id: string, input: unknown): {
+        ok: true;
+    } | {
+        ok: false;
+        issues: string[];
+    };
+    create(input: unknown): Promise<{
+        id: string;
+        health: ConnectionHealth;
+    }>;
+    update(id: string, input: unknown): Promise<{
+        health?: ConnectionHealth;
+    }>;
+    remove(id: string): Promise<void>;
+    stop(): Promise<void>;
+};
+/**
+ * Host-side read and edit model for the Connections page. A `connections.yaml` that fails to load
+ * does not stop the host: the listing reports the error code and stages that use channels fail on
+ * their own, while every other stage is unaffected. Edits keep secrets out of the YAML: each value
+ * goes to the secret store and the file gets a `store:NAME` reference.
+ */
+export declare function startChannelService(cwd: string, options?: Pick<ChannelHealthOptions, "intervalMs" | "timeoutMs">): ChannelService;