@alfe.ai/integration-manifest 0.3.3 → 0.3.5

package/README.md

@@ -61,6 +61,19 @@ hooks:
 
 Only `id`, `name`, `version`, `description`, and `author` are required — everything else has sensible defaults.
 
+Manifest input is executable control-plane data. Identity fields must be
+unique, record keys must be identifier-safe, and repository-owned hook, skill,
+and command paths must remain relative to the integration checkout. Filesystem
+consumers must additionally resolve real paths before I/O so repository
+symlinks cannot escape that checkout.
+
+`config_schema` validation is strict: undeclared keys are rejected, default
+values must match the declared type/options, and `secret` or `oauth_connect`
+fields cannot declare shared defaults. Consumers must persist the parsed
+validation result, never the original caller object.
+
+`supported_scopes` accepts `agent`, `org`, `team`, and `project`.
+
 ## Custom Connections — `expected_credentials`
 
 For manifests consumed by [Custom Connections](../../services/connect/DEVELOPING.md#custom-connections-pr-8a-of-channels-and-credential-driven-integrations) (`requires_connection: ["custom"]`), the manifest declares the credential fields it needs the tenant operator to fill in via an `expected_credentials` block:
@@ -91,7 +104,7 @@ Supported field `type`s — same vocabulary as the dashboard form renderer:
 |-----------|------------------------------------|-----------------------------------------|
 | `secret`  | KMS-encrypted (`encryptedAccessToken`) | Joined into a JSON bundle by services/connect at write time |
 | `string`  | `providerMetadata.{key}`           | Plain string                            |
-| `url`     | `providerMetadata.{key}`           | Plain string; URL validation client-side |
+| `url`     | `providerMetadata.{key}`           | Plain string; URL validation on client and backend |
 | `number`  | `providerMetadata.{key}`           | Stored as JS number                     |
 | `boolean` | `providerMetadata.{key}`           | Stored as JS boolean                    |
 

package/dist/index.d.ts

@@ -5,8 +5,9 @@ import { z } from "zod";
 /**
  * Connect provider ids that a manifest's `requires_connection` field may
  * reference. The source of truth lives in `services/connect/src/providers/`
- * (one `ProviderDefinition` per id) — this list mirrors that registry so
- * the manifest schema can validate references statically.
+ * (one `ProviderDefinition` per id) — this list mirrors that registry for
+ * authoring, lint, and dashboard tooling. The runtime parser deliberately
+ * accepts unknown provider ids for forward compatibility (see below).
  *
  * **Keep in sync** with `services/connect/src/providers/index.ts`. Adding a
  * new connect provider requires updating both: add the provider definition
@@ -15,7 +16,7 @@ import { z } from "zod";
  * caught at runtime when the integrations service tries to resolve the
  * provider and gets nothing back.
  */
-declare const KNOWN_CONNECT_PROVIDER_IDS: readonly ["atlassian", "bluesky", "ctrader", "custom", "discord", "github", "google", "microsoft", "mobile", "myob", "notion", "salesforce", "slack", "xero"];
+declare const KNOWN_CONNECT_PROVIDER_IDS: readonly ["atlassian", "bluesky", "ctrader", "custom", "discord", "github", "google", "microsoft", "mobile", "myob", "notion", "salesforce", "shopify", "slack", "x", "xero"];
 type KnownConnectProviderId = (typeof KNOWN_CONNECT_PROVIDER_IDS)[number];
 /**
  * `custom` is a special provider id: it doesn't correspond to a fixed
@@ -79,7 +80,7 @@ declare const ConfigSchemaFieldSchema: z.ZodObject<{
   label: z.ZodString;
   description: z.ZodOptional<z.ZodString>;
   required: z.ZodDefault<z.ZodBoolean>;
-  default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+  default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
   editable: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
     admin: "admin";
     agent: "agent";
@@ -91,6 +92,8 @@ declare const ConfigSchemaFieldSchema: z.ZodObject<{
     label: z.ZodString;
   }, z.core.$strip>>>;
   oauth_provider: z.ZodOptional<z.ZodString>;
+  oauth_scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  oauth_integration_id: z.ZodOptional<z.ZodString>;
   depends_on_field: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     key: z.ZodString;
     value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
@@ -240,7 +243,7 @@ declare const IntegrationManifestSchema: z.ZodObject<{
     label: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     required: z.ZodDefault<z.ZodBoolean>;
-    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodArray<z.ZodString>]>>;
     editable: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
       admin: "admin";
       agent: "agent";
@@ -252,6 +255,8 @@ declare const IntegrationManifestSchema: z.ZodObject<{
       label: z.ZodString;
     }, z.core.$strip>>>;
     oauth_provider: z.ZodOptional<z.ZodString>;
+    oauth_scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    oauth_integration_id: z.ZodOptional<z.ZodString>;
     depends_on_field: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
       key: z.ZodString;
       value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
@@ -355,7 +360,7 @@ interface ConfigSchemaField {
   label: string;
   description?: string;
   required: boolean;
-  default?: string | number | boolean;
+  default?: string | number | boolean | string[];
   /** Who can mutate this field at runtime. Default: 'admin' */
   editable: 'admin' | 'agent';
   /** Only used when type === 'enum' */
@@ -516,7 +521,7 @@ interface IntegrationManifest {
    * Default: ['agent'] (per-agent only).
    * 'org' means it can be installed at the org level and cascades to all agents.
    */
-  supported_scopes?: ('agent' | 'org')[];
+  supported_scopes?: ('agent' | 'org' | 'team' | 'project')[];
   /**
    * Connect provider ids whose credentials this integration resolves at
    * runtime. OR-semantics: any one in the list satisfies activation. See

package/dist/index.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { readFileSync } from "node:fs";
 import { parse } from "yaml";
+import { posix } from "node:path";
 //#region src/schema.ts
 /**
 * Zod validation schema for the Alfe integration manifest.
@@ -9,11 +10,54 @@ import { parse } from "yaml";
 * Used by the parser and by the lifecycle manager to ensure manifest
 * correctness before installation.
 */
+const IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+const INTEGRATION_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+const UNSAFE_RECORD_KEYS = new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const HttpsUrlSchema = z.url().refine((value) => {
+	const url = new URL(value);
+	return url.protocol === "https:" && url.username === "" && url.password === "";
+}, "URL must use HTTPS and must not contain embedded credentials");
+/**
+* Repository-owned file references are portable relative paths. They may use
+* `./`, but may not be absolute or walk above the integration checkout.
+* Consumers still need realpath checks before filesystem I/O because a cloned
+* repository can contain symlinks.
+*/
+const RepositoryRelativePathSchema = z.string().min(1, "Path must not be empty").refine((value) => {
+	if (value.includes("\0")) return false;
+	const portable = value.replaceAll("\\", "/");
+	if (portable.startsWith("/") || /^[a-zA-Z]:\//.test(portable)) return false;
+	let depth = 0;
+	for (const segment of portable.split("/")) {
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			depth -= 1;
+			if (depth < 0) return false;
+		} else depth += 1;
+	}
+	return depth > 0;
+}, "Path must stay within the integration directory");
+function addDuplicateIssues(values, ctx, path, label) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, value] of values.entries()) {
+		if (seen.has(value)) ctx.addIssue({
+			code: "custom",
+			path: [...path, index],
+			message: `Duplicate ${label}: ${value}`
+		});
+		seen.add(value);
+	}
+}
 /**
 * Connect provider ids that a manifest's `requires_connection` field may
 * reference. The source of truth lives in `services/connect/src/providers/`
-* (one `ProviderDefinition` per id) — this list mirrors that registry so
-* the manifest schema can validate references statically.
+* (one `ProviderDefinition` per id) — this list mirrors that registry for
+* authoring, lint, and dashboard tooling. The runtime parser deliberately
+* accepts unknown provider ids for forward compatibility (see below).
 *
 * **Keep in sync** with `services/connect/src/providers/index.ts`. Adding a
 * new connect provider requires updating both: add the provider definition
@@ -35,7 +79,9 @@ const KNOWN_CONNECT_PROVIDER_IDS = [
 	"myob",
 	"notion",
 	"salesforce",
+	"shopify",
 	"slack",
+	"x",
 	"xero"
 ];
 /**
@@ -85,7 +131,7 @@ const SelectOptionSchema = z.object({
 	label: z.string().min(1)
 });
 const ConfigSchemaFieldSchema = z.object({
-	key: z.string().min(1, "Config key must not be empty"),
+	key: z.string().min(1, "Config key must not be empty").regex(IDENTIFIER_RE, "Config key must be a valid identifier").refine((key) => !UNSAFE_RECORD_KEYS.has(key), "Config key must be a valid identifier"),
 	type: ConfigFieldTypeSchema,
 	label: z.string().min(1, "Config label must not be empty"),
 	description: z.string().optional(),
@@ -93,15 +139,18 @@ const ConfigSchemaFieldSchema = z.object({
 	default: z.union([
 		z.string(),
 		z.number(),
-		z.boolean()
+		z.boolean(),
+		z.array(z.string())
 	]).optional(),
 	editable: z.enum(["admin", "agent"]).optional().default("admin"),
 	hidden: z.boolean().optional(),
-	options: z.array(z.string()).optional(),
+	options: z.array(z.string().min(1, "Enum option must not be empty")).optional(),
 	select_options: z.array(SelectOptionSchema).optional(),
 	oauth_provider: z.string().optional(),
-	depends_on_field: z.union([z.string(), z.object({
-		key: z.string().min(1),
+	oauth_scopes: z.array(z.string().min(1, "OAuth scope must not be empty")).optional(),
+	oauth_integration_id: z.string().regex(INTEGRATION_ID_RE, "OAuth integration id must be a valid integration id").refine((id) => !UNSAFE_RECORD_KEYS.has(id), "OAuth integration id is reserved").optional(),
+	depends_on_field: z.union([z.string().regex(IDENTIFIER_RE, "Dependency key must be a valid identifier").refine((key) => !UNSAFE_RECORD_KEYS.has(key), "Dependency key must be a valid identifier"), z.object({
+		key: z.string().regex(IDENTIFIER_RE, "Dependency key must be a valid identifier").refine((key) => !UNSAFE_RECORD_KEYS.has(key), "Dependency key must be a valid identifier"),
 		value: z.union([
 			z.string(),
 			z.number(),
@@ -118,7 +167,47 @@ const ConfigSchemaFieldSchema = z.object({
 }, { message: "Select/multi_select fields must have at least one option in select_options" }).refine((field) => {
 	if (field.type === "oauth_connect") return field.oauth_provider !== void 0 && field.oauth_provider.length > 0;
 	return true;
-}, { message: "oauth_connect fields must specify an oauth_provider" });
+}, { message: "oauth_connect fields must specify an oauth_provider" }).superRefine((field, ctx) => {
+	if (field.options) addDuplicateIssues(field.options, ctx, ["options"], "enum option");
+	if (field.select_options) addDuplicateIssues(field.select_options.map((option) => option.value), ctx, ["select_options"], "select option value");
+	if (field.oauth_scopes) addDuplicateIssues(field.oauth_scopes, ctx, ["oauth_scopes"], "OAuth scope");
+	if (field.type !== "oauth_connect" && (field.oauth_scopes || field.oauth_integration_id)) ctx.addIssue({
+		code: "custom",
+		path: ["type"],
+		message: "OAuth scope and integration metadata is only valid on oauth_connect fields"
+	});
+	if (field.default === void 0) return;
+	let valid = false;
+	switch (field.type) {
+		case "string":
+			valid = typeof field.default === "string";
+			break;
+		case "secret":
+		case "oauth_connect":
+			valid = false;
+			break;
+		case "number":
+			valid = typeof field.default === "number";
+			break;
+		case "boolean":
+			valid = typeof field.default === "boolean";
+			break;
+		case "enum":
+			valid = typeof field.default === "string" && (field.options?.includes(field.default) ?? false);
+			break;
+		case "select":
+			valid = typeof field.default === "string" && (field.select_options?.some((option) => option.value === field.default) ?? false);
+			break;
+		case "multi_select":
+			valid = Array.isArray(field.default) && field.default.every((value) => field.select_options?.some((option) => option.value === value));
+			break;
+	}
+	if (!valid) ctx.addIssue({
+		code: "custom",
+		path: ["default"],
+		message: `Default value is invalid for config field type ${field.type}`
+	});
+});
 /**
 * A field a manifest's owner expects the user to fill in when creating
 * a Custom Connection. Used ONLY by manifests authored against the
@@ -139,7 +228,7 @@ const CredentialFieldTypeSchema = z.enum([
 	"boolean"
 ]);
 const CredentialFieldSpecSchema = z.object({
-	key: z.string().min(1, "Credential field key must not be empty").regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Credential field key must be a valid identifier (letters, digits, underscores; not starting with a digit)"),
+	key: z.string().min(1, "Credential field key must not be empty").regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, "Credential field key must be a valid identifier (letters, digits, underscores; not starting with a digit)").refine((key) => !UNSAFE_RECORD_KEYS.has(key), "Credential field key must be a valid identifier"),
 	type: CredentialFieldTypeSchema,
 	label: z.string().min(1, "Credential field label must not be empty"),
 	description: z.string().optional(),
@@ -148,25 +237,25 @@ const CredentialFieldSpecSchema = z.object({
 	pattern: z.string().max(256).optional()
 });
 const McpServerDeclarationSchema = z.object({
-	id: z.string().min(1, "MCP server id must not be empty").regex(/^[a-z0-9][a-z0-9-]*$/, "MCP server id must be lowercase alphanumeric with hyphens"),
+	id: z.string().min(1, "MCP server id must not be empty").regex(INTEGRATION_ID_RE, "MCP server id must be lowercase alphanumeric with hyphens").refine((id) => !UNSAFE_RECORD_KEYS.has(id), "MCP server id is reserved"),
 	command: z.string().min(1, "MCP server command must not be empty"),
 	args: z.array(z.string()).optional().default([]),
-	env: z.record(z.string(), z.string()).optional(),
+	env: z.record(z.string().regex(IDENTIFIER_RE, "MCP environment keys must be valid identifiers").refine((key) => !UNSAFE_RECORD_KEYS.has(key), "MCP environment keys must be valid identifiers"), z.string()).optional(),
 	cwd: z.string().optional(),
 	requires_credentials: z.string().min(1).optional(),
 	hook_managed: z.boolean().optional().default(false)
 });
 const CommandDeclarationSchema = z.object({
 	name: z.string().min(1, "Command name must not be empty").regex(/^[a-z][a-z0-9]*\.[a-z][a-z0-9_]*$/, "Command name must be dot-namespaced (e.g. \"support.diagnostic\")"),
-	handler: z.string().min(1, "Handler path must not be empty"),
-	method: z.string().optional().default("handle"),
-	timeout_ms: z.number().int().positive().optional().default(3e4),
+	handler: RepositoryRelativePathSchema,
+	method: z.string().regex(IDENTIFIER_RE, "Handler method must be a valid identifier").refine((method) => !UNSAFE_RECORD_KEYS.has(method), "Handler method must be a valid identifier").optional().default("handle"),
+	timeout_ms: z.number().int().positive().max(1800 * 1e3).optional().default(3e4),
 	description: z.string().optional()
 });
 const SkillInstallSchema = z.object({
-	path: z.string().min(1, "Skill path must not be empty").optional(),
+	path: RepositoryRelativePathSchema.optional(),
 	clawhub: z.string().min(1, "ClawHub skill slug must not be empty").optional()
-}).refine((data) => data.path ?? data.clawhub, { message: "Skill must have either a path or clawhub slug" });
+}).refine((data) => Number(data.path !== void 0) + Number(data.clawhub !== void 0) === 1, { message: "Skill must have exactly one of path or clawhub slug" });
 const PluginInstallSchema = z.object({ package: z.string().min(1, "Plugin package name must not be empty") });
 /** Per-runtime install overrides */
 const RuntimeInstallSchema = z.object({
@@ -175,19 +264,19 @@ const RuntimeInstallSchema = z.object({
 	config: z.record(z.string(), z.unknown()).optional()
 });
 /** Runtime key: lowercase alphanumeric + hyphens */
-const RuntimeKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "Runtime key must be lowercase alphanumeric with hyphens");
+const RuntimeKeySchema = z.string().regex(/^[a-z0-9][a-z0-9-]*$/, "Runtime key must be lowercase alphanumeric with hyphens").refine((key) => !UNSAFE_RECORD_KEYS.has(key), "Runtime key is reserved");
 const InstallTargetsSchema = z.object({
 	skills: z.array(SkillInstallSchema).optional().default([]),
 	plugins: z.array(PluginInstallSchema).optional().default([]),
 	runtimes: z.record(RuntimeKeySchema, RuntimeInstallSchema).optional()
 });
 const IntegrationHooksSchema = z.object({
-	pre_install: z.string().optional(),
-	post_install: z.string().optional(),
-	post_activate: z.string().optional(),
-	pre_uninstall: z.string().optional(),
-	post_uninstall: z.string().optional(),
-	health_check: z.string().optional()
+	pre_install: RepositoryRelativePathSchema.optional(),
+	post_install: RepositoryRelativePathSchema.optional(),
+	post_activate: RepositoryRelativePathSchema.optional(),
+	pre_uninstall: RepositoryRelativePathSchema.optional(),
+	post_uninstall: RepositoryRelativePathSchema.optional(),
+	health_check: RepositoryRelativePathSchema.optional()
 });
 const IntegrationPricingPlanSchema = z.object({
 	name: z.string().min(1),
@@ -220,13 +309,13 @@ const IntegrationAuthorSchema = z.union([z.string().min(1, "Author must not be e
 })]);
 const SemverSchema = z.string().regex(/^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/, "Must be a valid semver version (e.g. 1.0.0)");
 const IntegrationManifestSchema = z.object({
-	id: z.string().min(1, "Integration id must not be empty").regex(/^[a-z0-9][a-z0-9-]*$/, "id must be lowercase alphanumeric with hyphens"),
+	id: z.string().min(1, "Integration id must not be empty").regex(INTEGRATION_ID_RE, "id must be lowercase alphanumeric with hyphens").refine((id) => !UNSAFE_RECORD_KEYS.has(id), "Integration id is reserved"),
 	name: z.string().min(1, "Integration name must not be empty"),
 	version: SemverSchema,
 	description: z.string().min(1, "Description must not be empty"),
 	author: IntegrationAuthorSchema,
 	license: z.string().default("MIT"),
-	depends_on: z.array(z.string()).optional().default([]),
+	depends_on: z.array(z.string().regex(INTEGRATION_ID_RE, "Dependency must be a valid integration id").refine((id) => !UNSAFE_RECORD_KEYS.has(id), "Dependency id is reserved")).optional().default([]),
 	min_gateway_version: SemverSchema.optional().default("0.1.0"),
 	installs: InstallTargetsSchema.optional().default({
 		skills: [],
@@ -240,7 +329,7 @@ const IntegrationManifestSchema = z.object({
 	requires_connection: z.array(z.string().min(1)).optional(),
 	channel_type: z.string().min(1).optional(),
 	expected_credentials: z.array(CredentialFieldSpecSchema).optional(),
-	repository: z.url().optional(),
+	repository: HttpsUrlSchema.optional(),
 	supported_agents: z.array(RuntimeKeySchema).optional(),
 	supported_scopes: z.array(z.enum([
 		"agent",
@@ -253,14 +342,85 @@ const IntegrationManifestSchema = z.object({
 	pricing: IntegrationPricingSchema.optional(),
 	preview_images: z.array(z.string()).optional(),
 	features: z.array(z.string()).optional()
+}).superRefine((manifest, ctx) => {
+	addDuplicateIssues(manifest.depends_on, ctx, ["depends_on"], "dependency");
+	addDuplicateIssues(manifest.config_schema.map((field) => field.key), ctx, ["config_schema"], "config key");
+	addDuplicateIssues(manifest.commands.map((command) => command.name), ctx, ["commands"], "command name");
+	addDuplicateIssues(manifest.mcp_servers.map((server) => server.id), ctx, ["mcp_servers"], "MCP server id");
+	addDuplicateIssues(manifest.capabilities, ctx, ["capabilities"], "capability");
+	addDuplicateIssues(manifest.requires_connection ?? [], ctx, ["requires_connection"], "connection requirement");
+	addDuplicateIssues(manifest.supported_agents ?? [], ctx, ["supported_agents"], "supported agent");
+	addDuplicateIssues(manifest.supported_scopes, ctx, ["supported_scopes"], "supported scope");
+	if (manifest.depends_on.includes(manifest.id)) ctx.addIssue({
+		code: "custom",
+		path: ["depends_on"],
+		message: "An integration cannot depend on itself"
+	});
+	const configKeys = new Set(manifest.config_schema.map((field) => field.key));
+	for (const [index, field] of manifest.config_schema.entries()) {
+		if (!field.depends_on_field) continue;
+		const dependencyKey = typeof field.depends_on_field === "string" ? field.depends_on_field : field.depends_on_field.key;
+		if (!configKeys.has(dependencyKey)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"config_schema",
+				index,
+				"depends_on_field"
+			],
+			message: `Config dependency does not exist: ${dependencyKey}`
+		});
+		else if (dependencyKey === field.key) ctx.addIssue({
+			code: "custom",
+			path: [
+				"config_schema",
+				index,
+				"depends_on_field"
+			],
+			message: "A config field cannot depend on itself"
+		});
+	}
+	if (manifest.expected_credentials) {
+		addDuplicateIssues(manifest.expected_credentials.map((field) => field.key), ctx, ["expected_credentials"], "credential key");
+		if (!manifest.requires_connection?.includes("custom")) ctx.addIssue({
+			code: "custom",
+			path: ["expected_credentials"],
+			message: "expected_credentials requires requires_connection to include custom"
+		});
+	}
+	const validateInstallDuplicates = (install, path) => {
+		addDuplicateIssues(install.plugins.map((plugin) => plugin.package), ctx, [...path, "plugins"], "plugin package");
+		addDuplicateIssues(install.skills.map((skill) => skill.path ?? `clawhub:${skill.clawhub ?? ""}`), ctx, [...path, "skills"], "skill source");
+	};
+	validateInstallDuplicates(manifest.installs, ["installs"]);
+	for (const [runtime, install] of Object.entries(manifest.installs.runtimes ?? {})) {
+		validateInstallDuplicates(install, [
+			"installs",
+			"runtimes",
+			runtime
+		]);
+		addDuplicateIssues([...manifest.installs.plugins.map((plugin) => plugin.package), ...install.plugins.map((plugin) => plugin.package)], ctx, [
+			"installs",
+			"runtimes",
+			runtime,
+			"plugins"
+		], "effective plugin package");
+		addDuplicateIssues([...manifest.installs.skills.map((skill) => skill.path ?? `clawhub:${skill.clawhub ?? ""}`), ...install.skills.map((skill) => skill.path ?? `clawhub:${skill.clawhub ?? ""}`)], ctx, [
+			"installs",
+			"runtimes",
+			runtime,
+			"skills"
+		], "effective skill source");
+	}
 });
 /**
 * Validate user-provided config values against a manifest's config_schema.
 * Returns a Zod schema dynamically built from the manifest's config_schema.
 */
 function buildConfigValidationSchema(configSchema) {
-	const shape = {};
+	const shape = Object.create(null);
 	for (const field of configSchema) {
+		if (!IDENTIFIER_RE.test(field.key) || UNSAFE_RECORD_KEYS.has(field.key)) throw new Error(`Invalid config schema key: ${field.key}`);
+		if (Object.hasOwn(shape, field.key)) throw new Error(`Duplicate config schema key: ${field.key}`);
 		let fieldSchema;
 		switch (field.type) {
 			case "secret":
@@ -298,7 +458,7 @@ function buildConfigValidationSchema(configSchema) {
 		if (!field.required) fieldSchema = fieldSchema.optional();
 		shape[field.key] = fieldSchema;
 	}
-	return z.object(shape);
+	return z.object(shape).strict();
 }
 //#endregion
 //#region src/parser.ts
@@ -406,11 +566,23 @@ function isRelativePath(path) {
 */
 function resolveAssetUrl(assetPath, repoUrl, commitHash, subdir) {
 	if (!isRelativePath(assetPath)) return assetPath;
-	const repoMatch = /^https?:\/\/github\.com\/([^/]+)\/([^/]+)/.exec(repoUrl);
-	if (!repoMatch) return assetPath;
-	const [, owner, repo] = repoMatch;
-	const normalizedPath = assetPath.replace(/^\.\//, "");
-	return `https://raw.githubusercontent.com/${owner}/${repo}/${commitHash}/${subdir ? `${subdir.replace(/\/$/, "")}/${normalizedPath}` : normalizedPath}`;
+	let repository;
+	try {
+		repository = new URL(repoUrl);
+	} catch {
+		return assetPath;
+	}
+	const repoParts = repository.pathname.split("/").filter(Boolean);
+	const owner = repoParts[0];
+	const repo = repoParts[1]?.replace(/\.git$/, "");
+	if (!["http:", "https:"].includes(repository.protocol) || repository.hostname.toLowerCase() !== "github.com" || repository.username !== "" || repository.password !== "" || repository.port !== "" || repository.search !== "" || repository.hash !== "" || repoParts.length !== 2 || !owner || !repo || !/^[A-Za-z0-9_.-]+$/.test(owner) || !/^[A-Za-z0-9_.-]+$/.test(repo)) return assetPath;
+	const portableSubdir = subdir.replaceAll("\\", "/");
+	const portableAssetPath = assetPath.replaceAll("\\", "/");
+	if (portableSubdir.startsWith("/") || portableAssetPath.startsWith("/") || /^[A-Za-z]:\//.test(portableSubdir) || /^[A-Za-z]:\//.test(portableAssetPath)) return assetPath;
+	const fullPath = posix.normalize(posix.join(portableSubdir, portableAssetPath));
+	if (fullPath === "." || fullPath === ".." || fullPath.startsWith("../")) return assetPath;
+	const encodedPath = fullPath.split("/").map(encodeURIComponent).join("/");
+	return `https://raw.githubusercontent.com/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(commitHash)}/${encodedPath}`;
 }
 //#endregion
 //#region src/interpolation.ts
@@ -430,14 +602,33 @@ const TEMPLATE_RE = /\{\{integration\.([a-z0-9-]+)\.([a-z0-9_]+)\}\}/g;
 */
 function interpolateConfig(config, ctx) {
 	const result = {};
-	for (const [key, value] of Object.entries(config)) if (typeof value === "string") result[key] = value.replace(TEMPLATE_RE, (_match, integrationId, field) => {
-		const integrationConfig = ctx.integrations[integrationId];
-		if (!integrationConfig) return _match;
-		const resolved = integrationConfig[field];
-		if (resolved == null) return _match;
-		return typeof resolved === "string" ? resolved : JSON.stringify(resolved);
+	for (const [key, value] of Object.entries(config)) if (typeof value === "string") {
+		const interpolated = value.replace(TEMPLATE_RE, (_match, integrationId, field) => {
+			if (!Object.hasOwn(ctx.integrations, integrationId)) return _match;
+			const integrationConfig = ctx.integrations[integrationId];
+			if (!integrationConfig || !Object.hasOwn(integrationConfig, field)) return _match;
+			const resolved = integrationConfig[field];
+			if (resolved == null) return _match;
+			if (typeof resolved === "string") return resolved;
+			try {
+				const serialized = JSON.stringify(resolved);
+				return typeof serialized === "string" ? serialized : _match;
+			} catch {
+				return _match;
+			}
+		});
+		Object.defineProperty(result, key, {
+			configurable: true,
+			enumerable: true,
+			value: interpolated,
+			writable: true
+		});
+	} else Object.defineProperty(result, key, {
+		configurable: true,
+		enumerable: true,
+		value,
+		writable: true
 	});
-	else result[key] = value;
 	return result;
 }
 /**
@@ -459,12 +650,38 @@ function extractTemplateReferences(config) {
 }
 //#endregion
 //#region src/migration.ts
+function schemaByKey(fields, label) {
+	const result = /* @__PURE__ */ new Map();
+	for (const field of fields) {
+		if (result.has(field.key)) throw new Error(`Duplicate ${label} config schema key: ${field.key}`);
+		result.set(field.key, field);
+	}
+	return result;
+}
+function setOwn(target, key, value) {
+	Object.defineProperty(target, key, {
+		configurable: true,
+		enumerable: true,
+		value,
+		writable: true
+	});
+}
+function isValidFieldValue(field, value) {
+	try {
+		return buildConfigValidationSchema([{
+			...field,
+			required: true
+		}]).safeParse({ [field.key]: value }).success;
+	} catch {
+		return false;
+	}
+}
 /**
 * Diff two config schemas to determine what changed between versions.
 */
 function diffConfigSchemas(oldSchema, newSchema) {
-	const oldMap = new Map(oldSchema.map((f) => [f.key, f]));
-	const newMap = new Map(newSchema.map((f) => [f.key, f]));
+	const oldMap = schemaByKey(oldSchema, "old");
+	const newMap = schemaByKey(newSchema, "new");
 	const added = [];
 	const removed = [];
 	const changed = [];
@@ -499,12 +716,20 @@ function diffConfigSchemas(oldSchema, newSchema) {
 function migrateConfig(currentConfig, diff) {
 	const config = {};
 	const warnings = [];
-	for (const field of diff.unchanged) if (field.key in currentConfig) config[field.key] = currentConfig[field.key];
+	for (const field of diff.unchanged) if (Object.hasOwn(currentConfig, field.key)) setOwn(config, field.key, currentConfig[field.key]);
 	for (const change of diff.changed) if (change.breaking) {
-		if (change.newSchema.default !== void 0) config[change.field] = change.newSchema.default;
+		if (change.newSchema.default !== void 0) setOwn(config, change.field, change.newSchema.default);
 		warnings.push(`Field "${change.field}" type changed from "${change.oldSchema.type}" to "${change.newSchema.type}" — value reset`);
-	} else if (change.field in currentConfig) config[change.field] = currentConfig[change.field];
-	for (const field of diff.added) if (field.default !== void 0) config[field.key] = field.default;
+	} else if (Object.hasOwn(currentConfig, change.field)) {
+		const currentValue = currentConfig[change.field];
+		if (isValidFieldValue(change.newSchema, currentValue)) setOwn(config, change.field, currentValue);
+		else {
+			if (change.newSchema.default !== void 0) setOwn(config, change.field, change.newSchema.default);
+			warnings.push(`Field "${change.field}" no longer accepts its existing value — value reset`);
+		}
+	} else if (change.newSchema.required) if (change.newSchema.default !== void 0) setOwn(config, change.field, change.newSchema.default);
+	else warnings.push(`Field "${change.field}" is now required and has no default — user input needed`);
+	for (const field of diff.added) if (field.default !== void 0) setOwn(config, field.key, field.default);
 	else if (field.required) warnings.push(`New required field "${field.key}" has no default — user input needed`);
 	return {
 		config,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfe.ai/integration-manifest",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Integration manifest schema, types, and parser for Alfe integration platform",
   "type": "module",
   "main": "./dist/index.js",