π OpenHands: AI-Driven Development
/**
* Admission policy for extension-authored catalog manifests.
*
* A manifest is data authored in a different repository that instructs this host
* to render copy and compose a request. The host therefore decides what a
* manifest is *permitted* to do rather than trusting the file β validation here
* is a trust boundary, not a convenience check, and it deliberately does not
* defer to a schema shipped alongside the manifests it would be validating.
*
* Beyond mirroring the published schema, this adds the invariants the host's own
* derivation depends on: a single trigger kind to read, a repository field for
* an event trigger's source, and field names unique across the form. Without
* them the derived request body would be silently wrong rather than rejected.
*
* A manifest that fails any check is rejected outright. It never renders a
* partial UI, because everything downstream treats its content as instructions.
*/
import {
BUNDLE_CONFIG_FILENAME,
SETUP_PLACEHOLDER_NAMESPACES,
SETUP_VERSION,
} from "./types";
const ENTRY_ID_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
const FIELD_NAME_PATTERN = /^[a-z][A-Za-z0-9]*$/;
/** Copy must never be able to inject markup into the host. */
const MARKUP_PATTERN = /<[A-Za-z/!]/;
/**
* A template version, declared as `version` by a prompt entry and as
* `setup.bundle.version` by a bundle one. Sent to the service as template
* provenance, so it is checked at admission. Full semver, as the spec at
* semver.org states it: a catalog entry published with a pre-release or build
* suffix is still a version this host may forward, and refusing one would drop
* the entry from the registry outright.
*/
const TEMPLATE_VERSION_PATTERN =
/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*)?(?:\+[0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*)?$/;
// The characters a command of plain words and paths is made of. No shell
// metacharacters, which the service rejects anyway and a bundle has no reason
// to need; where those words may point is `isPlainCommand`'s to say.
const BUNDLE_COMMAND_PATTERN = /^[A-Za-z0-9 ._/-]+$/;
const BUNDLE_PATH_PATTERN = /^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
const BUNDLE_SOURCE_PATTERN =
/^(skills|automations|plugins)\/[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/;
/** Every `{{` must open a known namespace and close immediately. */
const UNKNOWN_PLACEHOLDER_PATTERN = new RegExp(
`\\{\\{(?!(?:${SETUP_PLACEHOLDER_NAMESPACES.join("|")})\\.[A-Za-z0-9_.]+\\}\\})`,
);
const SETUP_MODES = ["direct", "assisted"] as const;
const FIELD_TYPES = [
"text",
"textarea",
"select",
"number",
"cron",
"timezone",
"repo-picker",
"llm-profile",
"event-source",
"event-type",
"plugin-sources",
"tarball-upload",
] as const;
const GIT_PROVIDERS = ["github", "gitlab", "bitbucket"] as const;
const TRIGGER_KINDS = ["cron", "event"] as const;
const CONSTRAINT_FORMATS = ["safeExpressionLiteral"] as const;
/** Setup context only, so this can never become a channel for runtime instructions. */
const MAX_MESSAGE_LENGTH = 2000;
export interface SetupValidationResult {
valid: boolean;
errors: string[];
}
type Rec = Record<string, unknown>;
function isRecord(value: unknown): value is Rec {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function isOneOf<T extends readonly string[]>(
value: unknown,
allowed: T,
): value is T[number] {
return (
typeof value === "string" && (allowed as readonly string[]).includes(value)
);
}
function isInteger(value: unknown, minimum: number): boolean {
return (
typeof value === "number" && Number.isInteger(value) && value >= minimum
);
}
class SetupChecker {
readonly errors: string[] = [];
fail(path: string, reason: string): false {
this.errors.push(`${path}: ${reason}`);
return false;
}
/** Literal user-visible copy. Carries no markup. */
copy(value: unknown, path: string): boolean {
if (typeof value !== "string" || value.length === 0) {
return this.fail(path, "must be a non-empty string");
}
if (MARKUP_PATTERN.test(value)) {
return this.fail(path, "must not contain markup");
}
return true;
}
placeholders(value: string, path: string): boolean {
if (UNKNOWN_PLACEHOLDER_PATTERN.test(value)) {
return this.fail(path, "uses an unknown placeholder namespace");
}
return true;
}
/** Copy that may embed `{{namespace.key}}` placeholders. */
templateCopy(value: unknown, path: string): boolean {
return this.copy(value, path) && this.placeholders(value as string, path);
}
/**
* A request-body string that may embed placeholders. Never rendered, so
* expression syntax such as a JMESPath filter is allowed through.
*/
templateValue(value: unknown, path: string): boolean {
if (typeof value !== "string" || value.length === 0) {
return this.fail(path, "must be a non-empty string");
}
return this.placeholders(value, path);
}
absent(container: Rec, key: string, path: string, reason: string): boolean {
if (key in container) return this.fail(`${path}.${key}`, reason);
return true;
}
}
/**
* A relative path that stays inside the archive it names.
*
* The character class alone is not enough: `.` and `..` are made of allowed
* characters, so a segment check is what actually keeps a packed file from
* climbing out of the directory it is extracted into.
*/
function isRelativePath(value: unknown, pattern: RegExp): value is string {
return (
typeof value === "string" &&
pattern.test(value) &&
!value.split("/").some((segment) => segment === "." || segment === "..")
);
}
/**
* A command whose every word stays inside the archive it is run in.
*
* The character class is not what keeps it there: `/` and `.` are allowed
* characters, so `/bin/sh setup.sh` and `python3 ../../etc/x.py` are made of
* them and each names something outside the extracted directory. The segment
* rule packed paths are held to is what refuses those, and requiring a word at
* all is what refuses an entrypoint of nothing but spaces.
*/
function isPlainCommand(value: unknown): value is string {
if (typeof value !== "string" || !BUNDLE_COMMAND_PATTERN.test(value)) {
return false;
}
const words = value.split(" ").filter((word) => word.length > 0);
return (
words.length > 0 &&
words.every(
(word) =>
!word.startsWith("/") &&
!word.split("/").some((segment) => segment === ".."),
)
);
}
function checkRequires(check: SetupChecker, requires: unknown): void {
if (!isRecord(requires)) {
check.fail("requires", "must be an object");
return;
}
const { integrations, features } = requires;
// Empty is meaningful rather than malformed: an automation that needs no
// credential connects to nothing, and the key stays required so that saying
// so is a deliberate statement instead of an omission.
if (!isRecord(integrations)) {
check.fail("requires.integrations", "must be an object");
} else {
Object.entries(integrations).forEach(([id, requirement]) => {
const path = `requires.integrations.${id}`;
if (!isRecord(requirement)) {
check.fail(path, "must be an object");
return;
}
check.copy(requirement.message, `${path}.message`);
if ("required" in requirement && requirement.required !== false) {
check.fail(`${path}.required`, "may only be false");
}
const allowed = ["message", "required"];
Object.keys(requirement)
.filter((key) => !allowed.includes(key))
.forEach((key) => check.fail(`${path}.${key}`, "is not allowed"));
});
}
if (features !== undefined) {
if (!Array.isArray(features) || features.length === 0) {
check.fail("requires.features", "must be a non-empty array");
} else {
features.forEach((feature, index) => {
if (typeof feature !== "string" || feature.length === 0) {
check.fail(
`requires.features[${index}]`,
"must be a non-empty string",
);
}
});
}
}
}
function checkConstraints(
check: SetupChecker,
constraints: unknown,
path: string,
): void {
if (!isRecord(constraints) || Object.keys(constraints).length === 0) {
check.fail(path, "must be a non-empty object");
return;
}
const { minLength, maxLength, min, max, format } = constraints;
if (minLength !== undefined && !isInteger(minLength, 0)) {
check.fail(`${path}.minLength`, "must be a non-negative integer");
}
if (maxLength !== undefined && !isInteger(maxLength, 1)) {
check.fail(`${path}.maxLength`, "must be a positive integer");
}
if (min !== undefined && !isInteger(min, 0)) {
check.fail(`${path}.min`, "must be a non-negative integer");
}
if (max !== undefined && !isInteger(max, 1)) {
check.fail(`${path}.max`, "must be a positive integer");
}
if (format !== undefined && !isOneOf(format, CONSTRAINT_FORMATS)) {
check.fail(`${path}.format`, "is not a supported format");
}
}
function checkField(check: SetupChecker, field: unknown, path: string): void {
if (!isRecord(field)) {
check.fail(path, "must be an object");
return;
}
const { type, label, help, placeholder, required, provider, options } = field;
if (!isOneOf(type, FIELD_TYPES)) {
check.fail(`${path}.type`, "is not a supported field type");
}
check.copy(label, `${path}.label`);
check.copy(help, `${path}.help`);
if (placeholder !== undefined) check.copy(placeholder, `${path}.placeholder`);
if (
field.default !== undefined &&
typeof field.default !== "string" &&
typeof field.default !== "number" &&
typeof field.default !== "boolean" &&
field.default !== null
) {
check.fail(`${path}.default`, "must be a string, number, boolean or null");
}
if (typeof required !== "boolean") {
check.fail(`${path}.required`, "must be a boolean");
}
if (provider !== undefined && !isOneOf(provider, GIT_PROVIDERS)) {
check.fail(`${path}.provider`, "is not a supported provider");
}
if (type === "repo-picker" && provider === undefined) {
check.fail(`${path}.provider`, "is required for a repository field");
}
// The host branches on this key to decide whether a field's value is a list,
// so a field declaring it anywhere else would be seeded with a list and
// rendered as a string.
if (
field.multiple !== undefined &&
(field.multiple !== true || type !== "repo-picker")
) {
check.fail(
`${path}.multiple`,
"may only be true, and only on a repository field",
);
}
if (options !== undefined) {
if (type !== "select") {
check.fail(`${path}.options`, "is only allowed on a select field");
} else if (!Array.isArray(options) || options.length === 0) {
check.fail(`${path}.options`, "must be a non-empty array");
} else {
options.forEach((option, index) => {
const optionPath = `${path}.options[${index}]`;
if (!isRecord(option)) {
check.fail(optionPath, "must be an object");
return;
}
if (typeof option.value !== "string" || option.value.length === 0) {
check.fail(`${optionPath}.value`, "must be a non-empty string");
}
check.copy(option.label, `${optionPath}.label`);
});
}
}
if (field.constraints !== undefined) {
checkConstraints(check, field.constraints, `${path}.constraints`);
}
}
/** Returns the declared field names, so the caller can check them for collisions. */
function checkFields(
check: SetupChecker,
fields: unknown,
path: string,
): string[] {
if (!isRecord(fields) || Object.keys(fields).length === 0) {
check.fail(path, "must be a non-empty object");
return [];
}
return Object.entries(fields).map(([name, field]) => {
if (!FIELD_NAME_PATTERN.test(name)) {
check.fail(`${path}.${name}`, "is not a valid field name");
}
checkField(check, field, `${path}.${name}`);
return name;
});
}
/** Returns the trigger kinds declared, in order. */
function checkForm(
check: SetupChecker,
form: unknown,
): { kinds: string[]; fieldNames: string[] } {
if (!isRecord(form)) {
check.fail("setup.form", "must be an object");
return { kinds: [], fieldNames: [] };
}
if (form.note !== undefined) check.copy(form.note, "setup.form.note");
const names = checkFields(check, form.args, "setup.form.args");
const kinds: string[] = [];
if (form.triggers !== undefined) {
if (!isRecord(form.triggers) || Object.keys(form.triggers).length === 0) {
check.fail("setup.form.triggers", "must be a non-empty object");
} else {
Object.entries(form.triggers).forEach(([kind, fields]) => {
if (!isOneOf(kind, TRIGGER_KINDS)) {
check.fail(`setup.form.triggers.${kind}`, "is not a trigger kind");
return;
}
kinds.push(kind);
names.push(
...checkFields(check, fields, `setup.form.triggers.${kind}`),
);
});
}
}
// The host merges both halves into one value map, so a repeated name would
// silently shadow a field and misaddress every error reported against it.
const duplicates = names.filter(
(name, index) => names.indexOf(name) !== index,
);
Array.from(new Set(duplicates)).forEach((name) =>
check.fail(`setup.form.${name}`, "is declared more than once"),
);
return { kinds, fieldNames: names };
}
function checkActionFeatures(
check: SetupChecker,
features: unknown,
path: string,
): void {
if (!Array.isArray(features) || features.length === 0) {
check.fail(path, "must be a non-empty array");
return;
}
features.forEach((feature, index) => {
if (typeof feature !== "string" || feature.length === 0) {
check.fail(`${path}[${index}]`, "must be a non-empty string");
}
});
}
function checkAction(
check: SetupChecker,
kind: string,
action: unknown,
commonFieldNames: string[],
): void {
const path = `setup.actions.${kind}`;
if (!isRecord(action)) {
check.fail(path, "must be an object");
return;
}
check.copy(action.label, `${path}.label`);
check.copy(action.help, `${path}.help`);
checkActionFeatures(check, action.features, `${path}.features`);
const actionFieldNames = checkFields(check, action.args, `${path}.args`);
actionFieldNames
.filter((name) => commonFieldNames.includes(name))
.forEach((name) =>
check.fail(`${path}.args.${name}`, "is already declared by the form"),
);
if (kind === "prompt") {
check.templateValue(action.prompt, `${path}.prompt`);
} else if (kind === "plugin") {
check.templateValue(action.prompt, `${path}.prompt`);
check.templateValue(action.plugins, `${path}.plugins`);
} else if (kind === "upload") {
check.templateValue(action.tarballPath, `${path}.tarballPath`);
check.templateValue(action.entrypoint, `${path}.entrypoint`);
if (action.setupScript !== undefined) {
check.templateValue(action.setupScript, `${path}.setupScript`);
}
} else {
check.fail(path, "is not a supported action kind");
}
const allowedByKind: Record<string, string[]> = {
prompt: ["label", "help", "features", "args", "prompt"],
plugin: ["label", "help", "features", "args", "prompt", "plugins"],
upload: [
"label",
"help",
"features",
"args",
"tarballPath",
"entrypoint",
"setupScript",
],
};
const allowed = allowedByKind[kind] ?? [];
Object.keys(action)
.filter((key) => !allowed.includes(key))
.forEach((key) => check.fail(`${path}.${key}`, "is not allowed"));
}
function checkActions(
check: SetupChecker,
actions: unknown,
commonFieldNames: string[],
): void {
if (!isRecord(actions) || Object.keys(actions).length === 0) {
check.fail("setup.actions", "must be a non-empty object");
return;
}
Object.entries(actions).forEach(([kind, action]) =>
checkAction(check, kind, action, commonFieldNames),
);
}
function fieldsContainType(fields: unknown, type: string): boolean {
if (!isRecord(fields)) return false;
return Object.values(fields).some(
(field) => isRecord(field) && field.type === type,
);
}
function actionHasRepoPicker(action: unknown): boolean {
return isRecord(action) && fieldsContainType(action.args, "repo-picker");
}
/**
* Whether an event trigger's `source` is derivable for every selectable action.
*
* `buildTrigger` fills `source` from a field named `source` in the event
* trigger, or failing that from the selected action's repo-picker provider. A
* picker in another trigger group (such as `cron`) is never collected for the
* event trigger, and a picker in only some actions is invisible when one of the
* others is selected β so neither may satisfy this check, or the user can end
* up with an empty `source` no form field can fix.
*/
function setupSuppliesEventSource(setup: Rec): boolean {
const form = isRecord(setup.form) ? setup.form : {};
const triggers = isRecord(form.triggers) ? form.triggers : {};
const eventFields = triggers.event;
// An explicit event-source field fills `source` directly, regardless of which
// action is selected.
if (fieldsContainType(eventFields, "event-source")) return true;
// A repo-picker in the event trigger is only collected when `event` is the
// sole trigger kind; with a sibling trigger the derivation reads no trigger
// fields for the picker. `form.args` is shared across every selection, so a
// picker there is always available.
const singleEventTrigger =
"event" in triggers && Object.keys(triggers).length === 1;
if (
(singleEventTrigger && fieldsContainType(eventFields, "repo-picker")) ||
fieldsContainType(form.args, "repo-picker")
) {
return true;
}
// Without a shared or event-trigger picker, every selectable action must
// carry its own repo-picker; otherwise selecting an action without one
// derives `source: ""`.
if (!isRecord(setup.actions) || Object.keys(setup.actions).length === 0) {
return false;
}
return Object.values(setup.actions).every(actionHasRepoPicker);
}
function checkMessage(check: SetupChecker, message: unknown): void {
if (check.templateCopy(message, "setup.message")) {
if ((message as string).length > MAX_MESSAGE_LENGTH) {
check.fail(
"setup.message",
`must be at most ${MAX_MESSAGE_LENGTH} characters`,
);
}
}
}
/**
* The script tarball a direct entry may ship.
*
* The strings here are commands and paths this host acts on, so they are held
* to a closed character set rather than the placeholder rules copy uses: an
* entrypoint with a shell metacharacter, or a packed path that escapes the
* archive, is refused here rather than by the service.
*/
function checkBundle(check: SetupChecker, bundle: unknown): void {
if (!isRecord(bundle)) {
check.fail("setup.bundle", "must be an object");
return;
}
if (
typeof bundle.version !== "string" ||
!TEMPLATE_VERSION_PATTERN.test(bundle.version)
) {
check.fail("setup.bundle.version", "must be a semantic version");
}
if (!isPlainCommand(bundle.entrypoint)) {
check.fail(
"setup.bundle.entrypoint",
"must be a plain command that stays inside the archive",
);
}
if (
bundle.setupScript !== undefined &&
!isRelativePath(bundle.setupScript, BUNDLE_PATH_PATTERN)
) {
check.fail("setup.bundle.setupScript", "must be a relative path");
}
if (bundle.timeout !== undefined && !isInteger(bundle.timeout, 1)) {
check.fail("setup.bundle.timeout", "must be a positive integer");
}
if (!isRecord(bundle.files) || Object.keys(bundle.files).length === 0) {
check.fail("setup.bundle.files", "must be a non-empty object");
} else {
Object.entries(bundle.files).forEach(([packedPath, source]) => {
if (!isRelativePath(packedPath, BUNDLE_PATH_PATTERN)) {
check.fail(`setup.bundle.files.${packedPath}`, "is not a packed path");
}
// The rendered config is packed under this name too, and a tar carrying
// the name twice leaves which one the script reads to whichever
// extractor unpacks it.
if (packedPath === BUNDLE_CONFIG_FILENAME) {
check.fail(
`setup.bundle.files.${packedPath}`,
"is the name the rendered config is packed under",
);
}
if (!isRelativePath(source, BUNDLE_SOURCE_PATTERN)) {
check.fail(
`setup.bundle.files.${packedPath}`,
"must name a file under skills/, automations/, or plugins/",
);
}
});
// A setup script the archive does not carry is a create request the
// service accepts and the first run fails on, and it is also the only
// thing packed executable - naming an unpacked file makes that rule
// unreachable.
if (
typeof bundle.setupScript === "string" &&
!(bundle.setupScript in bundle.files)
) {
check.fail("setup.bundle.setupScript", "must name a packed file");
}
}
if (!isRecord(bundle.config) || Object.keys(bundle.config).length === 0) {
check.fail("setup.bundle.config", "must be a non-empty object");
} else {
checkBundleConfig(check, bundle.config, "setup.bundle.config");
}
}
/** Every string leaf of the config is a payload value: placeholders, no markup rule. */
function checkBundleConfig(
check: SetupChecker,
node: unknown,
path: string,
): void {
if (typeof node === "string") {
check.templateValue(node, path);
return;
}
if (Array.isArray(node)) {
node.forEach((item, index) =>
checkBundleConfig(check, item, `${path}[${index}]`),
);
return;
}
if (isRecord(node)) {
Object.entries(node).forEach(([key, value]) =>
checkBundleConfig(check, value, `${path}.${key}`),
);
return;
}
if (node !== null && typeof node !== "number" && typeof node !== "boolean") {
check.fail(
path,
"must be a string, number, boolean, null, array or object",
);
}
}
function checkMode(
check: SetupChecker,
setup: Rec,
kinds: string[],
commonFieldNames: string[],
): void {
if (!isOneOf(setup.mode, SETUP_MODES)) {
check.fail("setup.mode", "is not a supported mode");
return;
}
if (setup.mode === "direct") {
// A direct entry produces one of three things: a prompt, a script bundle
// the host packs and uploads, or a selectable set of action variants.
// More than one would be ambiguous, and none is nothing to create.
const hasPrompt = setup.prompt !== undefined;
const hasBundle = setup.bundle !== undefined;
const hasActions = setup.actions !== undefined;
const variants = [hasPrompt, hasBundle, hasActions].filter(Boolean);
if (variants.length !== 1) {
check.fail(
"setup",
"must declare exactly one of prompt, bundle or actions for direct setup",
);
} else if (hasBundle) {
checkBundle(check, setup.bundle);
} else if (hasActions) {
checkActions(check, setup.actions, commonFieldNames);
} else {
check.templateValue(setup.prompt, "setup.prompt");
}
// A direct entry may carry a fallback-conversation seed for deployments
// that cannot run the direct path, held to the same rules as an assisted
// message.
if (setup.message !== undefined) checkMessage(check, setup.message);
if (kinds.length === 0) {
check.fail(
"setup.form.triggers",
"must declare at least one trigger kind",
);
}
if (kinds.includes("event") && !setupSuppliesEventSource(setup)) {
check.fail(
"setup.form.triggers.event",
"must declare an event source field or repository picker",
);
}
if (setup.filter !== undefined) {
if (!kinds.includes("event")) {
check.fail("setup.filter", "is only allowed for an event trigger");
} else {
check.templateValue(setup.filter, "setup.filter");
}
}
return;
}
checkMessage(check, setup.message);
check.absent(setup, "prompt", "setup", "is only allowed for direct setup");
check.absent(setup, "bundle", "setup", "is only allowed for direct setup");
check.absent(setup, "actions", "setup", "is only allowed for direct setup");
check.absent(setup, "filter", "setup", "is only allowed for direct setup");
}
/** Whether a catalog entry ships a setup experience at all. It is optional. */
export function hasSetupBlock(candidate: unknown): boolean {
return isRecord(candidate) && candidate.setup !== undefined;
}
/**
* Decide whether this host will act on a catalog manifest.
*
* The version is checked first and fails closed: a format this host does not
* recognise is refused rather than interpreted with today's rules.
*/
export function validateSetupEntry(candidate: unknown): SetupValidationResult {
const check = new SetupChecker();
if (!isRecord(candidate)) {
return { valid: false, errors: ["manifest: must be an object"] };
}
const { setup } = candidate;
if (!isRecord(setup)) {
return { valid: false, errors: ["setup: must be an object"] };
}
if (setup.version !== SETUP_VERSION) {
return {
valid: false,
errors: [`setup.version: must be "${SETUP_VERSION}"`],
};
}
if (
typeof candidate.id !== "string" ||
!ENTRY_ID_PATTERN.test(candidate.id)
) {
check.fail("id", "must be a lowercase slug");
}
check.copy(candidate.name, "name");
check.copy(candidate.description, "description");
if (
candidate.version !== undefined &&
(typeof candidate.version !== "string" ||
!TEMPLATE_VERSION_PATTERN.test(candidate.version))
) {
check.fail("version", "must be a semantic version");
}
if (
candidate.skill !== undefined &&
(typeof candidate.skill !== "string" ||
!ENTRY_ID_PATTERN.test(candidate.skill))
) {
check.fail("skill", "must be a lowercase slug");
}
checkRequires(check, candidate.requires);
const { kinds, fieldNames } = checkForm(check, setup.form);
checkMode(check, setup, kinds, fieldNames);
return { valid: check.errors.length === 0, errors: check.errors };
}