@wardby/cli 0.7.0 → 0.9.0

package/dist/providers/host-tools/registry.js

@@ -0,0 +1,362 @@
+/**
+ * Registering a tool-backed host provider, approving its tools, and reading it back.
+ * Registering copies each tool's code and schema: Wardby only ever runs that copy, so
+ * update_tool changes nothing until approved, and a stray edit can't take a provider down.
+ * Views carry secret names and metadata, never a value.
+ */
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { isValidHostProviderName } from "../../coding/code-host.js";
+import { isExactHostname, parseSecretBrokerConfig } from "../../core/secret-broker-config.js";
+import { MIN_WEBHOOK_SECRET_LENGTH } from "../../core/secrets.js";
+import { HOST_TOOL_CONTRACT_VERSION, isHostOperation, REQUIRED_OPERATIONS } from "./operations.js";
+export class HostProviderError extends Error {
+    code;
+    detail;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+        this.detail = detail;
+        this.name = "HostProviderError";
+    }
+}
+const HTTP_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
+const REPOSITORY_PATTERN = /^[a-z0-9][a-z0-9._-]{0,99}\/(?:\*|[a-z0-9][a-z0-9._-]{0,99})$/;
+const SECRET_NAME = z.string().min(1).max(1024);
+const hostname = z
+    .string()
+    .transform((h) => h.toLowerCase())
+    .refine(isExactHostname, "must be an exact hostname, with no scheme, port, wildcard or IP");
+/** Each of `fields` once, and no other `{...}`. */
+function hasExactlyFields(template, fields) {
+    const found = [...template.matchAll(/\{([^{}]*)\}/g)].map((m) => m[1]).sort();
+    return JSON.stringify(found) === JSON.stringify([...fields].sort());
+}
+const apiPath = (fields) => z
+    .string()
+    .max(512)
+    .startsWith("/")
+    .refine((p) => hasExactlyFields(p, fields), `must contain ${fields.map((f) => `{${f}}`).join(" and ")} once each`)
+    // eslint-disable-next-line no-control-regex
+    .refine((p) => !/[?#\\\x00-\x20\x7f]|%2f|%5c|\.\./i.test(p), "must be a plain path");
+export const RegisterHostProviderSchema = z
+    .object({
+    provider: z.string().refine(isValidHostProviderName, "reserved or badly formed provider name"),
+    gitHost: hostname,
+    apiHosts: z.array(hostname).min(1).max(8),
+    // Refused: a name git's password prompt would contain, since scripts/git-askpass.sh answers by matching "Username".
+    gitUsername: z
+        .string()
+        .regex(/^[A-Za-z0-9._-]{1,64}$/)
+        .refine((u) => !/username/i.test(u), 'must not contain "username"'),
+    pullRequestUrlTemplate: z.string().max(512),
+    repositoryApiPath: apiPath(["repository"]),
+    permissionApiPath: apiPath(["workspace", "repo"]).optional(),
+    webhook: z
+        .object({
+        header: z.string().regex(HTTP_TOKEN),
+        algorithm: z.literal("sha256"),
+        deliveryHeader: z.string().regex(HTTP_TOKEN),
+        eventHeader: z.string().regex(HTTP_TOKEN),
+        secret: SECRET_NAME,
+    })
+        .strict(),
+    credentials: z
+        .array(z
+        .object({
+        repositories: z
+            .string()
+            .transform((r) => r.toLowerCase())
+            .refine((r) => REPOSITORY_PATTERN.test(r), 'must be "workspace/repo" or "workspace/*"'),
+        secret: SECRET_NAME,
+    })
+        .strict())
+        .min(1)
+        .max(32),
+    permissionCredential: SECRET_NAME.optional(),
+    trustedAccounts: z
+        .array(z.string().regex(/^[A-Za-z0-9:{}_-]{1,128}$/))
+        .max(256)
+        .optional(),
+    tools: z.record(z.string(), z.string().min(1).max(200)),
+})
+    .strict()
+    .superRefine((input, ctx) => {
+    let template = null;
+    try {
+        template = new URL(input.pullRequestUrlTemplate.replaceAll(/[{}]/g, ""));
+    }
+    catch {
+        // reported below
+    }
+    if (!template ||
+        template.protocol !== "https:" ||
+        template.hostname !== input.gitHost ||
+        template.username ||
+        template.password ||
+        template.port ||
+        !hasExactlyFields(input.pullRequestUrlTemplate, ["repository", "number"])) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["pullRequestUrlTemplate"],
+            message: "must be an https URL on gitHost, with no credentials or port, and with {repository} and {number} once each",
+        });
+    }
+    if ((input.permissionCredential === undefined) !== (input.permissionApiPath === undefined)) {
+        ctx.addIssue({
+            code: "custom",
+            path: ["permissionApiPath"],
+            message: "permissionCredential and permissionApiPath go together",
+        });
+    }
+    const patterns = input.credentials.map((c) => c.repositories);
+    if (new Set(patterns).size !== patterns.length) {
+        ctx.addIssue({ code: "custom", path: ["credentials"], message: "a repository pattern is listed twice" });
+    }
+});
+export function findCredential(credentials, repositoryPath) {
+    const parts = repositoryPath.split("/");
+    if (parts.length !== 2)
+        return null;
+    return (credentials.find((c) => c.repositoryPattern === repositoryPath) ??
+        credentials.find((c) => c.repositoryPattern === `${parts[0]}/*`) ??
+        null);
+}
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+// A tool's timeoutMs is part of what is approved; a snapshot without one hashes as before.
+const snapshotHash = (s) => sha256(`${s.paramsZod}\u0000${s.code}${s.timeoutMs === null ? "" : `\u0000${s.timeoutMs}`}`);
+async function requireSecret(tx, ownerId, name) {
+    const secret = await tx.secret.findUnique({ where: { ownerId_name: { ownerId, name } } });
+    if (!secret)
+        throw new HostProviderError("host_provider_secret_not_found", `secret "${name}" not found`);
+    return secret;
+}
+function requireBroker(name, stored, hosts) {
+    if (stored === null || stored === undefined) {
+        throw new HostProviderError("host_provider_secret_not_brokered", `secret "${name}" must be brokered`);
+    }
+    const broker = parseSecretBrokerConfig(stored);
+    if (broker.placement.kind !== "header" && broker.placement.kind !== "query") {
+        throw new HostProviderError("host_provider_secret_placement", `secret "${name}" must be placed in a header or query parameter`);
+    }
+    const missing = hosts.filter((h) => !broker.hosts.includes(h));
+    if (missing.length > 0) {
+        throw new HostProviderError("host_provider_secret_hosts", `secret "${name}" must allow ${missing.join(", ")}`);
+    }
+    return broker;
+}
+export async function registerHostProvider(db, cipher, principalId, input) {
+    const bound = Object.keys(input.tools);
+    const unknown = bound.filter((name) => !isHostOperation(name));
+    if (unknown.length > 0) {
+        throw new HostProviderError("host_provider_operation_not_bound", `unknown operations: ${unknown.join(", ")}`);
+    }
+    const required = input.permissionCredential
+        ? [...REQUIRED_OPERATIONS, "getRepositoryPermission"]
+        : REQUIRED_OPERATIONS;
+    const missing = required.filter((name) => !bound.includes(name));
+    if (missing.length > 0) {
+        throw new HostProviderError("host_provider_missing_operation", `missing operations: ${missing.join(", ")}`);
+    }
+    await db.$transaction(async (tx) => {
+        const credentials = [];
+        for (const credential of input.credentials) {
+            const secret = await requireSecret(tx, principalId, credential.secret);
+            requireBroker(credential.secret, secret.broker, [...input.apiHosts, input.gitHost]);
+            if ((await cipher.decrypt(secret.ciphertext)) === input.gitUsername) {
+                throw new HostProviderError("host_provider_username_is_secret", "gitUsername must not be a credential's value");
+            }
+            credentials.push({ repositoryPattern: credential.repositories, secretId: secret.id });
+        }
+        let permissionSecretId = null;
+        if (input.permissionCredential) {
+            const secret = await requireSecret(tx, principalId, input.permissionCredential);
+            requireBroker(input.permissionCredential, secret.broker, input.apiHosts);
+            permissionSecretId = secret.id;
+            if (credentials.some((c) => c.secretId === secret.id) ||
+                (await tx.hostProviderCredential.count({
+                    where: { secretId: secret.id, provider: { not: input.provider } },
+                })) > 0) {
+                throw new HostProviderError("host_provider_permission_secret_shared", "the permission secret must not also be a credential of any provider, so no other operation can reach it");
+            }
+        }
+        if ((await tx.hostProvider.count({
+            where: {
+                permissionSecretId: {
+                    in: [...credentials.map((c) => c.secretId), ...(permissionSecretId ? [permissionSecretId] : [])],
+                },
+                name: { not: input.provider },
+            },
+        })) > 0) {
+            throw new HostProviderError("host_provider_permission_secret_shared", "another provider's permission secret must not be a credential or permission secret here");
+        }
+        const webhookSecret = await requireSecret(tx, principalId, input.webhook.secret);
+        if (credentials.some((c) => c.secretId === webhookSecret.id) ||
+            permissionSecretId === webhookSecret.id ||
+            (await tx.agentSecret.count({ where: { secretId: webhookSecret.id } })) > 0 ||
+            (await tx.hostProviderCredential.count({
+                where: { secretId: webhookSecret.id, provider: { not: input.provider } },
+            })) > 0 ||
+            (await tx.hostProvider.count({
+                where: { permissionSecretId: webhookSecret.id, name: { not: input.provider } },
+            })) > 0 ||
+            (await tx.hostProvider.count({
+                where: {
+                    webhookSecretId: {
+                        in: [...credentials.map((c) => c.secretId), ...(permissionSecretId ? [permissionSecretId] : [])],
+                    },
+                    name: { not: input.provider },
+                },
+            })) > 0) {
+            throw new HostProviderError("host_provider_webhook_secret_shared", "the webhook secret must not be shared with any other provider's credentials or attached to an agent, so no tool can read it");
+        }
+        if ((await cipher.decrypt(webhookSecret.ciphertext)).length < MIN_WEBHOOK_SECRET_LENGTH) {
+            throw new HostProviderError("host_provider_webhook_secret_short", `the webhook secret needs at least ${MIN_WEBHOOK_SECRET_LENGTH} characters`);
+        }
+        const operations = [];
+        for (const [operation, name] of Object.entries(input.tools)) {
+            const tool = await tx.tool.findUnique({ where: { ownerId_name: { ownerId: principalId, name } } });
+            if (!tool)
+                throw new HostProviderError("host_provider_tool_not_found", `tool "${name}" not found`);
+            operations.push({
+                operation,
+                toolId: tool.id,
+                code: tool.code,
+                paramsZod: tool.paramsZod,
+                timeoutMs: tool.timeoutMs,
+                approvedById: principalId,
+            });
+        }
+        const { secret: _webhookSecretName, ...webhook } = input.webhook;
+        const fields = {
+            contractVersion: HOST_TOOL_CONTRACT_VERSION,
+            gitHost: input.gitHost,
+            apiHosts: input.apiHosts,
+            gitUsername: input.gitUsername,
+            pullRequestUrlTemplate: input.pullRequestUrlTemplate,
+            repositoryApiPath: input.repositoryApiPath,
+            permissionApiPath: input.permissionApiPath ?? null,
+            webhook,
+            webhookSecretId: webhookSecret.id,
+            permissionSecretId,
+            createdById: principalId,
+        };
+        await tx.hostProvider.upsert({
+            where: { name: input.provider },
+            create: { name: input.provider, ...fields },
+            update: fields,
+        });
+        await tx.hostProviderOperation.deleteMany({ where: { provider: input.provider } });
+        await tx.hostProviderCredential.deleteMany({ where: { provider: input.provider } });
+        await tx.hostProviderTrustedAccount.deleteMany({ where: { provider: input.provider } });
+        await tx.hostProviderOperation.createMany({ data: operations.map((o) => ({ provider: input.provider, ...o })) });
+        await tx.hostProviderCredential.createMany({
+            data: credentials.map((c) => ({ provider: input.provider, credentialKind: "static", ...c })),
+        });
+        await tx.hostProviderTrustedAccount.createMany({
+            data: [...new Set(input.trustedAccounts ?? [])].map((accountId) => ({
+                provider: input.provider,
+                accountId,
+                addedById: principalId,
+            })),
+        });
+    }, { isolationLevel: "Serializable" });
+    return (await getHostProviderView(db, input.provider));
+}
+export async function approveHostProviderTools(db, principalId, provider, operations) {
+    await db.$transaction(async (tx) => {
+        if (!(await tx.hostProvider.findUnique({ where: { name: provider } }))) {
+            throw new HostProviderError("host_provider_not_found", `provider "${provider}" not found`);
+        }
+        for (const operation of operations) {
+            const row = await tx.hostProviderOperation.findUnique({
+                where: { provider_operation: { provider, operation } },
+                include: { tool: true },
+            });
+            if (!row)
+                throw new HostProviderError("host_provider_operation_not_bound", `"${operation}" isn't bound`);
+            if (!row.tool)
+                throw new HostProviderError("host_provider_tool_deleted", `"${operation}"'s tool was deleted`);
+            await tx.hostProviderOperation.update({
+                where: { provider_operation: { provider, operation } },
+                data: {
+                    code: row.tool.code,
+                    paramsZod: row.tool.paramsZod,
+                    timeoutMs: row.tool.timeoutMs,
+                    approvedById: principalId,
+                    approvedAt: new Date(),
+                },
+            });
+        }
+    }, { isolationLevel: "Serializable" });
+    return (await getHostProviderView(db, provider));
+}
+export async function getHostProviderView(db, provider, options = {}) {
+    const row = await db.hostProvider.findUnique({
+        where: { name: provider },
+        include: {
+            webhookSecret: { select: { name: true } },
+            permissionSecret: { select: { name: true } },
+            credentials: { include: { secret: { select: { name: true } } }, orderBy: { repositoryPattern: "asc" } },
+            trustedAccounts: { orderBy: { accountId: "asc" } },
+            operations: { include: { tool: true }, orderBy: { operation: "asc" } },
+        },
+    });
+    if (!row)
+        return null;
+    return {
+        provider: row.name,
+        contractVersion: row.contractVersion,
+        gitHost: row.gitHost,
+        apiHosts: row.apiHosts,
+        gitUsername: row.gitUsername,
+        pullRequestUrlTemplate: row.pullRequestUrlTemplate,
+        repositoryApiPath: row.repositoryApiPath,
+        permissionApiPath: row.permissionApiPath,
+        mode: row.permissionSecretId ? "permission" : "allowlist",
+        webhook: row.webhook,
+        webhookSecret: row.webhookSecret.name,
+        permissionSecret: row.permissionSecret?.name ?? null,
+        credentials: row.credentials.map((c) => ({
+            repositories: c.repositoryPattern,
+            secret: c.secret.name,
+            kind: c.credentialKind,
+        })),
+        trustedAccounts: row.trustedAccounts.map((a) => a.accountId),
+        operations: row.operations.map((o) => {
+            const approvedSha256 = snapshotHash(o);
+            const currentSha256 = o.tool ? snapshotHash(o.tool) : null;
+            return {
+                operation: o.operation,
+                toolName: o.tool?.name ?? null,
+                status: !o.tool ? "tool_deleted" : currentSha256 === approvedSha256 ? "approved" : "changed",
+                approvedAt: o.approvedAt,
+                approvedById: o.approvedById,
+                approvedSha256,
+                currentSha256,
+                approvedTimeoutMs: o.timeoutMs,
+                currentTimeoutMs: o.tool?.timeoutMs ?? null,
+                ...(options.includeCode
+                    ? {
+                        approvedCode: o.code,
+                        approvedParamsZod: o.paramsZod,
+                        ...(o.tool && currentSha256 !== approvedSha256
+                            ? { currentCode: o.tool.code, currentParamsZod: o.tool.paramsZod }
+                            : {}),
+                    }
+                    : {}),
+            };
+        }),
+    };
+}
+export async function deleteHostProvider(db, provider) {
+    await db.$transaction(async (tx) => {
+        if (!(await tx.hostProvider.findUnique({ where: { name: provider } }))) {
+            throw new HostProviderError("host_provider_not_found", `provider "${provider}" not found`);
+        }
+        const links = await tx.agentRepository.count({ where: { provider } });
+        if (links > 0)
+            throw new HostProviderError("host_provider_in_use", `${links} agent link(s) use this provider`);
+        await tx.hostProvider.delete({ where: { name: provider } });
+    }, { isolationLevel: "Serializable" });
+}

package/dist/providers/host-tools/request-guard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where one bound tool's request may go: the provider's API hosts, inside the path of
+ * the repository this call is for, using the operation's own methods. Wardby picks
+ * the repository, so a tool can't point a token at another one. Pure.
+ */
+export declare const MAX_HOST_TOOL_FETCHES = 3;
+export interface HostToolRequestScope {
+    apiHosts: readonly string[];
+    pathPrefix: string;
+    methods: readonly string[];
+}
+export declare class HostToolRequestDenied extends Error {
+    constructor();
+}
+export declare function assertHostToolRequest(url: string, method: string, scope: HostToolRequestScope): void;
+/** Request headers a bound tool may set: no override, routing or credential headers. */
+export declare function assertHostToolHeaders(headers: unknown): void;

package/dist/providers/host-tools/request-guard.js

@@ -0,0 +1,99 @@
+/**
+ * Where one bound tool's request may go: the provider's API hosts, inside the path of
+ * the repository this call is for, using the operation's own methods. Wardby picks
+ * the repository, so a tool can't point a token at another one. Pure.
+ */
+export const MAX_HOST_TOOL_FETCHES = 3;
+export class HostToolRequestDenied extends Error {
+    constructor() {
+        super("host_tool_request_denied");
+        this.name = "HostToolRequestDenied";
+    }
+}
+export function assertHostToolRequest(url, method, scope) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new HostToolRequestDenied();
+    }
+    if (parsed.protocol !== "https:" || parsed.port !== "" || parsed.username || parsed.password) {
+        throw new HostToolRequestDenied();
+    }
+    if (!scope.apiHosts.includes(parsed.hostname.toLowerCase()))
+        throw new HostToolRequestDenied();
+    if (!scope.methods.includes(method.toUpperCase()))
+        throw new HostToolRequestDenied();
+    // Some frameworks read the method from these, which would turn a checked GET into a write.
+    for (const key of parsed.searchParams.keys()) {
+        const name = key.toLowerCase();
+        if (name === "_method" || name.startsWith("x-http-method"))
+            throw new HostToolRequestDenied();
+    }
+    const prefix = scope.pathPrefix.toLowerCase();
+    if (!prefix.startsWith("/"))
+        throw new HostToolRequestDenied();
+    // The repository is matched literally on the raw path; decoding is only for the segment rules.
+    const raw = parsed.pathname.toLowerCase();
+    if (raw !== prefix && !raw.startsWith(`${prefix}/`))
+        throw new HostToolRequestDenied();
+    assertSafeSegments(parsed.pathname);
+}
+const MAX_DECODE_ROUNDS = 8;
+const ALLOWED_HEADERS = ["accept", "content-type", "if-match", "if-none-match"];
+const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+/** Decodes every run of valid %XX escapes as UTF-8 bytes; a stray % stays literal. */
+function decodeOnce(text) {
+    return text.replace(/(?:%[0-9a-f]{2})+/gi, (run) => {
+        const bytes = Uint8Array.from(run.match(/%([0-9a-f]{2})/gi) ?? [], (hex) => parseInt(hex.slice(1), 16));
+        return utf8.decode(bytes);
+    });
+}
+/**
+ * The path as a server may finally read it: decoded and NFKC-normalized together to
+ * stable (a fullwidth percent sign becomes a real one), then judged per segment. Servers and proxies disagree on what a segment "is" (encoded or
+ * Unicode lookalike separators, stripped whitespace or format characters, trailing
+ * delimiters), so a segment that is only dots once those are removed is refused, and so
+ * is anything that changes the segment count. Ordinary names with odd characters pass.
+ */
+function assertSafeSegments(pathname) {
+    let current = pathname;
+    for (let round = 0;; round++) {
+        if (round > MAX_DECODE_ROUNDS)
+            throw new HostToolRequestDenied();
+        let next;
+        try {
+            next = decodeOnce(current).normalize("NFKC");
+        }
+        catch {
+            throw new HostToolRequestDenied();
+        }
+        if (next === current)
+            break;
+        current = next;
+    }
+    // eslint-disable-next-line no-control-regex
+    if (/[\\\u0000\u2215\u2044]/.test(current))
+        throw new HostToolRequestDenied();
+    const segments = current.split("/");
+    if (segments.length !== pathname.split("/").length)
+        throw new HostToolRequestDenied();
+    for (const segment of segments) {
+        // % is stripped too: a stray % must not turn "..%" into a passing name.
+        const bare = segment.replace(/[\p{Z}\p{C}%]/gu, "");
+        if (/^\.+(?:[;?#,:].*)?$/.test(bare))
+            throw new HostToolRequestDenied();
+    }
+}
+/** Request headers a bound tool may set: no override, routing or credential headers. */
+export function assertHostToolHeaders(headers) {
+    if (headers === undefined)
+        return;
+    if (typeof headers !== "object" || headers === null || Array.isArray(headers))
+        throw new HostToolRequestDenied();
+    for (const name of Object.keys(headers)) {
+        if (!ALLOWED_HEADERS.includes(name.toLowerCase()))
+            throw new HostToolRequestDenied();
+    }
+}

package/dist/providers/host-tools/self-test.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Calling a provider's approved snapshots, and the read-only checks test_host_provider reports.
+ * A report holds an operation, its repository, an outcome and a fixed code, so it can be shared
+ * from a team whose host we can't reach, carrying nothing else.
+ */
+import type { PrismaClient, Secret } from "#prisma";
+import { safeFetch } from "../../sandbox/safe-fetch.js";
+import type { SecretCipher } from "../secrets/types.js";
+import { type HostToolResult } from "./invoke.js";
+import { type HostOperation } from "./operations.js";
+type StoredSecret = Pick<Secret, "ciphertext" | "broker">;
+export interface LoadedProvider {
+    name: string;
+    apiHosts: string[];
+    repositoryApiPath: string;
+    permissionApiPath: string | null;
+    permissionSecret: StoredSecret | null;
+    credentials: {
+        repositoryPattern: string;
+        secret: StoredSecret;
+    }[];
+    operations: {
+        operation: string;
+        code: string;
+        paramsZod: string;
+        timeoutMs?: number | null;
+    }[];
+}
+/**
+ * The fetch for bound tools: the real one, or under WARDBY_TEST_SIMULATORS the simulator's. Under
+ * the switch only `sim-` credentials are sent, as the switch refuses every other real credential.
+ */
+export declare function hostToolFetch(env?: NodeJS.ProcessEnv): {
+    fetchImpl?: typeof safeFetch;
+    simulated: boolean;
+};
+export declare function loadProviderForCalls(db: PrismaClient, name: string): Promise<LoadedProvider | null>;
+/** The repository is compared in its normalized form, so callers must pass one. */
+export declare function callHostOperation(provider: LoadedProvider, cipher: SecretCipher, repository: string, operation: HostOperation, fields: Record<string, unknown>, options?: {
+    fetchImpl?: typeof safeFetch;
+    simulated?: boolean;
+}): Promise<HostToolResult>;
+export interface SelfTestInput {
+    repository: string;
+    pullRequest?: number;
+    headRef?: string;
+    ref?: string;
+    accountId?: string;
+}
+export interface SelfTestReport {
+    provider: string;
+    repository: string;
+    mode: "permission" | "allowlist";
+    results: {
+        operation: string;
+        outcome: "pass" | "fail" | "skipped";
+        code?: string;
+    }[];
+}
+export declare function selfTestHostProvider(provider: LoadedProvider, cipher: SecretCipher, input: SelfTestInput, options?: {
+    fetchImpl?: typeof safeFetch;
+    simulated?: boolean;
+}): Promise<SelfTestReport>;
+export {};