@harperfast/harper 5.2.0-alpha.4 → 5.2.0-alpha.6

package/components/mcp/tools/application.ts

@@ -84,6 +84,12 @@ interface ResourceClassLike {
 	hidden?: boolean;
 	properties?: Record<string, unknown>;
 	outputSchemas?: { [verb: string]: object };
+	/** The URL path (may carry `:param`/`*wildcard` segments), used to bind path params for contract resources. */
+	path?: string;
+	/** Present when built via `Resource.withSchema` (RFC 0001, Pillar 2) — drives typed tool schemas + binding. */
+	requestContract?: unknown;
+	/** Per-verb `{ query?, body? }` JSON-Schema fragments derived from the request contract. */
+	inputSchemas?: { [verb: string]: { query?: JsonSchemaFragmentLike; body?: JsonSchemaFragmentLike } };
 	mcp?: { annotations?: { [verb: string]: ToolAnnotationsLike } };
 	get?: (target: unknown, request: unknown, data?: unknown) => unknown;
 	put?: (target: unknown, data: unknown, request: unknown) => unknown;
@@ -185,6 +191,119 @@ function isSimpleIdRoute(pattern: string): boolean {
 	return paramCount === 1;
 }
 
+/** A subset of `JsonSchemaFragment` (resources/jsonSchemaTypes.ts) — the shared IR request contracts reduce to. */
+interface JsonSchemaFragmentLike {
+	type?: string | string[];
+	properties?: Record<string, unknown>;
+	required?: readonly string[];
+	items?: unknown;
+	enum?: readonly unknown[];
+}
+
+/** MCP verb → request-contract verb. `search` maps to `get`'s query grammar; others are 1:1. */
+const CONTRACT_VERB: Record<string, 'get' | 'post' | 'put' | 'patch' | 'delete'> = {
+	get: 'get',
+	search: 'get',
+	create: 'post',
+	update: 'put',
+	patch: 'patch',
+	delete: 'delete',
+};
+
+/** Parse `:param`/`*wildcard` segments out of a resource path (mirrors the route matcher). */
+function pathParamNames(path?: string): string[] {
+	if (!path) return [];
+	return path
+		.split('/')
+		.filter((segment) => segment.charAt(0) === ':' || segment.charAt(0) === '*')
+		.map((segment) => (segment.charAt(0) === '*' ? segment.slice(1) || 'wildcard' : segment.slice(1)));
+}
+
+/**
+ * Build an MCP tool input schema from a resource's request contract (RFC 0001, Pillar 2): the path
+ * params (always required strings) plus the verb's declared query and body fields, all off the shared
+ * JsonSchemaFragment. Returns undefined when there is nothing contract-derived to advertise (the caller
+ * then falls back to the generic table-attribute derivation).
+ */
+function contractInputSchema(ResourceClass: ResourceClassLike, contractVerb: string): object | undefined {
+	const input = ResourceClass.inputSchemas?.[contractVerb];
+	const params = pathParamNames(ResourceClass.path);
+	if (!input?.query?.properties && !input?.body?.properties && params.length === 0) return undefined;
+	const properties: Record<string, unknown> = {};
+	const required: string[] = [];
+	for (const param of params) {
+		properties[param] = { type: 'string', description: `Path parameter :${param}.` };
+		required.push(param);
+	}
+	const merge = (fragment?: JsonSchemaFragmentLike) => {
+		if (!fragment?.properties) return;
+		for (const [key, sub] of Object.entries(fragment.properties)) properties[key] = sub;
+		for (const key of fragment.required ?? []) if (!required.includes(key)) required.push(key);
+	};
+	merge(input?.query);
+	merge(input?.body);
+	const schema: { type: string; properties: Record<string, unknown>; required?: string[] } = {
+		type: 'object',
+		properties,
+	};
+	if (required.length) schema.required = required;
+	return schema;
+}
+
+/**
+ * Bind a contract resource's MCP arguments onto the RequestTarget the way the router would: path params
+ * as own properties (`target.id`, `target.n`, …) and declared query params via the URLSearchParams API
+ * (so `withSchema`'s pre-dispatch validation/coercion reads them). No-op for non-contract resources, so
+ * table tools are unaffected.
+ */
+function applyContractInputs(
+	target: Record<string, unknown>,
+	ResourceClass: ResourceClassLike,
+	a: Record<string, unknown>,
+	contractVerb: string
+): void {
+	if (!ResourceClass.requestContract) return;
+	for (const param of pathParamNames(ResourceClass.path)) {
+		if (a[param] !== undefined) target[param] = a[param];
+	}
+	const queryProps = ResourceClass.inputSchemas?.[contractVerb]?.query?.properties;
+	const setter = (target as { set?: (n: string, v: string) => void }).set;
+	const appender = (target as { append?: (n: string, v: string) => void }).append;
+	if (queryProps && typeof setter === 'function') {
+		for (const key of Object.keys(queryProps)) {
+			const val = a[key];
+			if (val === undefined) continue;
+			if (Array.isArray(val) && typeof appender === 'function') {
+				for (const el of val) appender.call(target, key, String(el));
+			} else {
+				setter.call(target, key, String(val));
+			}
+		}
+	}
+}
+
+/**
+ * MCP delivers path params, query params, and body fields flattened into ONE args object. For a
+ * contract resource those non-body keys are already bound onto the target by {@link applyContractInputs};
+ * strip them here so the remaining object is the request body the contract's `additionalProperties:false`
+ * body schema will accept (otherwise a bound `id`/query key poisons body validation). Non-contract
+ * resources pass through unchanged.
+ */
+function contractBody(
+	a: Record<string, unknown>,
+	ResourceClass: ResourceClassLike,
+	contractVerb: string
+): Record<string, unknown> {
+	if (!ResourceClass.requestContract) return a;
+	const exclude = new Set(pathParamNames(ResourceClass.path));
+	const queryProps = ResourceClass.inputSchemas?.[contractVerb]?.query?.properties;
+	if (queryProps) for (const key of Object.keys(queryProps)) exclude.add(key);
+	if (exclude.size === 0) return a;
+	const body: Record<string, unknown> = {};
+	for (const [key, val] of Object.entries(a)) if (!exclude.has(key)) body[key] = val;
+	return body;
+}
+
 /** A compiled parameterised route (e.g. `/widget/:id`), stored outside the base Map. */
 interface ParamRouteEntry {
 	pattern: string;
@@ -363,15 +482,40 @@ function wrapResult(data: unknown): ToolResult {
 }
 
 function wrapError(toolName: string, err: unknown): ToolResult {
-	const e = err as { message?: string; http_resp_msg?: string };
-	const message = e?.http_resp_msg ?? e?.message ?? `${toolName} failed`;
-	harperLogger.trace(`MCP ${toolName} threw: ${(err as Error).stack ?? message}`);
+	// `err` is arbitrary/untrusted — a revoked Proxy or a throwing getter would crash this
+	// error-serialization path if we accessed properties bare. Read everything inside one guard.
+	let message = `${toolName} failed`;
+	let errors: unknown;
+	let code: string | undefined;
+	let stack: string | undefined;
+	try {
+		const e = err as { message?: string; http_resp_msg?: string; errors?: unknown; code?: string; stack?: string };
+		if (e && typeof e === 'object') {
+			message = e.http_resp_msg ?? e.message ?? message;
+			errors = e.errors;
+			code = e.code;
+			stack = e.stack;
+		}
+	} catch (serializeErr) {
+		harperLogger.error(`Failed to read error in wrapError: ${(serializeErr as Error).message}`);
+	}
+	harperLogger.trace(`MCP ${toolName} threw: ${stack ?? message}`);
+	const payload: { kind: string; tool: string; message: string; code?: string; errors?: unknown } = {
+		kind: 'harper_error',
+		tool: toolName,
+		message,
+	};
+	// Pass structured validation issues through rather than flattening to a single string (RFC 0001 §8).
+	if (Array.isArray(errors) && errors.length) {
+		payload.code = code;
+		payload.errors = errors;
+	}
 	return {
 		isError: true,
 		content: [
 			{
 				type: 'text',
-				text: JSON.stringify({ kind: 'harper_error', tool: toolName, message }),
+				text: JSON.stringify(payload),
 			},
 		],
 	};
@@ -387,6 +531,7 @@ function makeGetHandler(toolName: string, path: string, capturedClass: ResourceC
 			const target = makeTarget();
 			target.id = a.id;
 			if (Array.isArray(a.get_attributes)) target.select = a.get_attributes as string[];
+			applyContractInputs(target, ResourceClass, a, 'get');
 			const data = await ResourceClass.get!(target, buildContext(context.user));
 			return wrapResult(data);
 		} catch (err) {
@@ -455,7 +600,12 @@ function makeCreateHandler(toolName: string, path: string, capturedClass: Resour
 			// base `post` throws `missingMethod` ("does not have a post method")
 			// because a record-scoped resource has no insert path (#1317).
 			target.isCollection = true;
-			const data = await ResourceClass.post!(target, a, buildContext(context.user));
+			applyContractInputs(target, ResourceClass, a, 'post');
+			const data = await ResourceClass.post!(
+				target,
+				contractBody(a, ResourceClass, 'post'),
+				buildContext(context.user)
+			);
 			// Standard table create resolves to the new record's primary key (a
 			// scalar). Wrap it as `{ id }` so the result carries `structuredContent`
 			// matching `deriveCreateOutputSchema`; strict SDK clients reject a bare
@@ -477,13 +627,17 @@ function makeUpdateHandler(toolName: string, path: string, capturedClass: Resour
 			const ResourceClass = liveResource(path, capturedClass);
 			const target = makeTarget();
 			target.id = id;
+			applyContractInputs(target, ResourceClass, a, verb);
 			// Call the verb method *on* ResourceClass so `this` stays bound to the
 			// class — detaching it (`const fn = ResourceClass.put`) makes the static
 			// Resource dispatcher read `this.directURLMapping` off undefined and throw.
 			const ctx = buildContext(context.user);
+			// For a contract resource, strip path/query keys from the body (they're bound onto the target
+			// above); otherwise keep the historical `id`-stripped rest.
+			const body = ResourceClass.requestContract ? contractBody(a, ResourceClass, verb) : rest;
 			const data = await (verb === 'put'
-				? ResourceClass.put!(target, rest, ctx)
-				: ResourceClass.patch!(target, rest, ctx));
+				? ResourceClass.put!(target, body, ctx)
+				: ResourceClass.patch!(target, body, ctx));
 			// Table.put/patch resolve to undefined; surface a `{ ok: true }`
 			// acknowledgement so the result has structuredContent matching
 			// derive{Update,Patch}OutputSchema. A custom Resource that returns a
@@ -503,6 +657,7 @@ function makeDeleteHandler(toolName: string, path: string, capturedClass: Resour
 			const ResourceClass = liveResource(path, capturedClass);
 			const target = makeTarget();
 			target.id = a.id;
+			applyContractInputs(target, ResourceClass, a, 'delete');
 			const data = await ResourceClass.delete!(target, buildContext(context.user));
 			// Table.delete resolves to a boolean; wrap it as `{ deleted }` so the
 			// result carries structuredContent matching deriveDeleteOutputSchema. A
@@ -670,14 +825,26 @@ function registerVerbTools(ctx: ResourceContext): number {
 	const primaryKey = ResourceClass.primaryKey;
 	const ctxForVerb: VerbDescriptionContext = { tableDoc, tableName, primaryKey, path };
 
-	const overrideOutput = (verb: Verb): object | undefined => ResourceClass.outputSchemas?.[verb];
+	// `outputSchemas` is authored/keyed by MCP verb (`create`/`update`) for table resources, but a request
+	// contract stores it by HTTP verb (`post`/`put`); fall back to the HTTP-verb key so a contract's
+	// `post.response`/`put.response` reaches the `create_*`/`update_*` output schema.
+	const overrideOutput = (verb: Verb): object | undefined =>
+		ResourceClass.outputSchemas?.[verb] ?? ResourceClass.outputSchemas?.[CONTRACT_VERB[verb]];
+	// When the resource carries a request contract (RFC 0001, Pillar 2), drive the tool INPUT schema off
+	// the contract (path params + declared query/body) instead of the generic table-attribute derivation.
+	// `search_*` is excluded: the contract has no `search` verb and the `search`/`query` static isn't
+	// wrapped by the contract validator, so it keeps the rich generic conditions/sort/limit grammar.
+	const overrideInput = (verb: Verb): object | undefined =>
+		ResourceClass.requestContract && verb !== 'search'
+			? contractInputSchema(ResourceClass, CONTRACT_VERB[verb])
+			: undefined;
 
 	if (verbs.get) {
 		const name = `get_${suffix}`;
 		addTool({
 			name,
 			description: verbDescription('get', ctxForVerb),
-			inputSchema: deriveGetSchema(attributes, undefined),
+			inputSchema: overrideInput('get') ?? deriveGetSchema(attributes, undefined),
 			outputSchema: overrideOutput('get') ?? deriveGetOutputSchema(attributes, undefined),
 			profile: 'application',
 			annotations: mergeAnnotations('get', { readOnlyHint: true }, ResourceClass),
@@ -693,7 +860,7 @@ function registerVerbTools(ctx: ResourceContext): number {
 		addTool({
 			name,
 			description: verbDescription('search', ctxForVerb),
-			inputSchema: deriveSearchSchema(attributes, undefined),
+			inputSchema: overrideInput('search') ?? deriveSearchSchema(attributes, undefined),
 			profile: 'application',
 			annotations: mergeAnnotations('search', { readOnlyHint: true }, ResourceClass),
 			visibleTo: makeVisibleTo(databaseName, tableName, 'read'),
@@ -706,7 +873,7 @@ function registerVerbTools(ctx: ResourceContext): number {
 		addTool({
 			name,
 			description: verbDescription('create', ctxForVerb),
-			inputSchema: deriveCreateSchema(attributes, undefined),
+			inputSchema: overrideInput('create') ?? deriveCreateSchema(attributes, undefined),
 			outputSchema: overrideOutput('create') ?? deriveCreateOutputSchema(attributes, undefined),
 			profile: 'application',
 			annotations: mergeAnnotations('create', {}, ResourceClass),
@@ -720,7 +887,7 @@ function registerVerbTools(ctx: ResourceContext): number {
 		addTool({
 			name,
 			description: verbDescription('update', ctxForVerb),
-			inputSchema: deriveUpdateSchema(attributes, undefined),
+			inputSchema: overrideInput('update') ?? deriveUpdateSchema(attributes, undefined),
 			outputSchema: overrideOutput('update') ?? deriveUpdateOutputSchema(attributes, undefined),
 			profile: 'application',
 			// PUT semantics: replacing with the same payload yields the same state,
@@ -735,7 +902,7 @@ function registerVerbTools(ctx: ResourceContext): number {
 		addTool({
 			name,
 			description: verbDescription('patch', ctxForVerb),
-			inputSchema: deriveUpdateSchema(attributes, undefined),
+			inputSchema: overrideInput('patch') ?? deriveUpdateSchema(attributes, undefined),
 			outputSchema: overrideOutput('patch') ?? derivePatchOutputSchema(attributes, undefined),
 			profile: 'application',
 			// patch_* idempotency depends on partial-update semantics; default
@@ -755,7 +922,7 @@ function registerVerbTools(ctx: ResourceContext): number {
 		addTool({
 			name,
 			description: verbDescription('delete', ctxForVerb),
-			inputSchema: deriveDeleteSchema(attributes, undefined),
+			inputSchema: overrideInput('delete') ?? deriveDeleteSchema(attributes, undefined),
 			outputSchema: overrideOutput('delete') ?? deriveDeleteOutputSchema(attributes),
 			profile: 'application',
 			// delete_* idempotency depends on delete-of-deleted behavior; default
@@ -1148,6 +1315,9 @@ function buildApplicationTools(resources: ResourcesRegistry): void {
 	//          segments yet, so ALL generated verbs are dropped. Author-defined
 	//          mcpTools/mcpPrompts carry their own schemas and handler methods, so they
 	//          register regardless of binding mode.
+	// A request contract (RFC 0001, Pillar 2) LIFTS this: `applyContractInputs` binds arbitrary
+	// path params + declared query itself, so contract resources register their generated verbs on
+	// any route shape — this is the "richer binding rides on the contract" the plain paths defer.
 	const considerEntry = (
 		path: string,
 		entry: ResourceRegistryEntry | undefined,
@@ -1164,14 +1334,18 @@ function buildApplicationTools(resources: ResourcesRegistry): void {
 			return;
 		}
 		const verbs = detectVerbs(ResourceClass);
-		if (paramBinding === 'id') {
-			verbs.search = false;
-			verbs.create = false;
-		} else if (paramBinding === 'none') {
-			harperLogger.trace(
-				`MCP application: '/${path}' generated verb tools skipped — multi-segment/named-wildcard binding not yet supported`
-			);
-			verbs.get = verbs.search = verbs.create = verbs.updatePut = verbs.updatePatch = verbs.delete = false;
+		// A request contract binds arbitrary path params + query (applyContractInputs), so it is exempt
+		// from the generated-handler binding restrictions below.
+		if (!ResourceClass.requestContract) {
+			if (paramBinding === 'id') {
+				verbs.search = false;
+				verbs.create = false;
+			} else if (paramBinding === 'none') {
+				harperLogger.trace(
+					`MCP application: '/${path}' generated verb tools skipped — multi-segment/named-wildcard binding not yet supported`
+				);
+				verbs.get = verbs.search = verbs.create = verbs.updatePut = verbs.updatePatch = verbs.delete = false;
+			}
 		}
 		const hasVerbs = verbs.get || verbs.search || verbs.create || verbs.updatePut || verbs.updatePatch || verbs.delete;
 		const hasCustomTools = Array.isArray(ResourceClass?.mcpTools) && ResourceClass.mcpTools.length > 0;
@@ -1207,7 +1381,7 @@ function buildApplicationTools(resources: ResourcesRegistry): void {
 	// tools — even though it appears in the OpenAPI document, which already iterates `paramRoutes`.
 	// Enumerate them so the tool surface matches the REST surface; the binding mode restricts the
 	// GENERATED verb tools to what their handlers actually bind (see considerEntry), while custom
-	// mcpTools/mcpPrompts register on every route shape.
+	// mcpTools/mcpPrompts (and contract resources) register on every route shape.
 	for (const route of resources.paramRoutes ?? []) {
 		considerEntry(route.pattern, route.entry, isSimpleIdRoute(route.pattern) ? 'id' : 'none');
 	}

package/components/mcp/tools/operations.ts

@@ -276,7 +276,7 @@ function buildDescription(operationName: string, hasCuratedSchema: boolean): str
  * matches the MCP spec's `tools/call` convention so the LLM sees and can
  * adapt to the failure.
  */
-function makeOperationToolHandler(operationName: string) {
+export function makeOperationToolHandler(operationName: string) {
 	return async function operationToolHandler(args: unknown, context: { user: AuthedUser }): Promise<ToolResult> {
 		const body: Record<string, unknown> = {
 			...(args && typeof args === 'object' ? (args as Record<string, unknown>) : {}),

package/components/mcp/tools/schemas/derive.ts

@@ -70,12 +70,16 @@ function harperTypeToJsonSchema(type: string | undefined): { type: string | stri
 
 function attributeToProperty(attr: HarperAttribute): object {
 	let base: { type?: string | string[]; description?: string; [key: string]: unknown };
-	if (attr.type === 'Object' && attr.properties) {
+	// The GraphQL parser emits nested objects via `.properties` (not a capitalized `'Object'` type) and
+	// list types as lowercase `type: 'array'` with `.elements` — the prior `'Object'`/`'Array'` literal
+	// checks never matched, so nested shapes fell through to a bare `{ type: 'string' }`. Detect them the
+	// way the parser actually emits, matching the shared `attributeToFragment` projector.
+	if (attr.properties) {
 		base = {
 			type: 'object',
 			properties: Object.fromEntries(attr.properties.map((p) => [p.name, attributeToProperty(p)])),
 		};
-	} else if (attr.type === 'Array' && attr.elements) {
+	} else if (attr.type === 'array' && attr.elements) {
 		base = {
 			type: 'array',
 			items: attributeToProperty(attr.elements),

package/components/operations.js

@@ -370,15 +370,15 @@ async function deployComponent(req) {
 		throw handleHDBError(validation, validation.message, HTTP_STATUS_CODES.BAD_REQUEST);
 	}
 
-	// Ingest any provided registry token into the secrets store so the credential lives as
+	// Ingest any provided credential token into the secrets store so the credential lives as
 	// replicated ciphertext (reference, not embed); already-reference entries pass through, and with
 	// no custody a literal token stays as a transient, this-node-only fallback (#1158). Peers
 	// re-running a replicated deploy already carry references and never re-ingest.
-	const { ingestRegistryAuth, resolveRegistryAuth } = require('./secretOperations.ts');
-	req.registryAuth = await ingestRegistryAuth(req, req.registryAuth, req.project);
+	const { ingestCredentials, resolveCredentials } = require('./secretOperations.ts');
+	req.credentials = await ingestCredentials(req, req.credentials, req.project);
 	// References are safe to persist (config + deployment row) and replicate; a no-custody literal
 	// token is not — it is used only for this node's install below, then stripped before replication.
-	const registryAuthReferences = (req.registryAuth ?? []).filter((entry) => entry && entry.secret !== undefined);
+	const credentialReferences = (req.credentials ?? []).filter((entry) => entry && entry.secret !== undefined);
 
 	// Write to root config if the request contains a package identifier
 	if (req.package) {
@@ -403,9 +403,9 @@ async function deployComponent(req) {
 			};
 		}
 		if (req.urlPath !== undefined) applicationConfig.urlPath = req.urlPath;
-		// Persist registry-auth references (never tokens) so every cold install of this component —
+		// Persist credential references (never tokens) so every cold install of this component —
 		// reboot, new peer, rollback — re-resolves the credential from the store.
-		if (registryAuthReferences.length) applicationConfig.registryAuth = registryAuthReferences;
+		if (credentialReferences.length) applicationConfig.credentials = credentialReferences;
 		await configUtils.addConfig(req.project, applicationConfig);
 	}
 
@@ -430,8 +430,8 @@ async function deployComponent(req) {
 				package_identifier: req.package ?? null,
 				user: req.hdb_user?.username,
 				restart_mode: req.restart === 'rolling' ? 'rolling' : req.restart ? 'immediate' : null,
-				// Reference form only — the rollback source for re-resolving registry auth.
-				registry_auth: registryAuthReferences.length ? registryAuthReferences : null,
+				// Reference form only — the rollback source for re-resolving the credential.
+				credentials: credentialReferences.length ? credentialReferences : null,
 				emitter,
 			});
 	if (recorder) req._deploymentId = recorder.deploymentId;
@@ -469,17 +469,17 @@ async function deployComponent(req) {
 			extractionPayload = row.payload_blob.stream();
 		}
 
-		// Resolve registryAuth references into concrete tokens for this node's npm pack/install
+		// Resolve credential references into concrete tokens for this node's npm pack/install
 		// (a no-custody literal-token fallback passes through unchanged). On a peer running a
 		// replicated deploy, the referenced hdb_secret row may arrive just behind the deploy op, so
 		// allow a bounded grace period (same budget as the payload-row wait) for it to replicate in.
-		let registryAuthWaitMs = 0;
+		let credentialsWaitMs = 0;
 		if (isReplicatedExecution) {
 			const requested = Number(req.deployment_timeout);
-			registryAuthWaitMs = Number.isFinite(requested) && requested >= 0 ? requested : DEFAULT_AWAIT_ROW_TIMEOUT_MS;
+			credentialsWaitMs = Number.isFinite(requested) && requested >= 0 ? requested : DEFAULT_AWAIT_ROW_TIMEOUT_MS;
 		}
-		const resolvedRegistryAuth = await resolveRegistryAuth(req.registryAuth, req.project, {
-			waitMs: registryAuthWaitMs,
+		const resolvedCredentials = await resolveCredentials(req.credentials, req.project, {
+			waitMs: credentialsWaitMs,
 		});
 
 		const application = new Application({
@@ -498,16 +498,18 @@ async function deployComponent(req) {
 				installCapture.push(manager, stream, line);
 				if (emitter) emit('install', { manager, stream, line });
 			},
-			// Private-registry auth (already resolved above), used here for this node's npm pack/install.
-			registryAuth: resolvedRegistryAuth,
+			// Deploy credentials (already resolved above), used here for this node's npm pack/install:
+			// registry entries via a transient .npmrc, git-host entries via the in-memory credential
+			// socket the clone spawn talks to.
+			credentials: resolvedCredentials,
 		});
-		// Reduce req.registryAuth to references only (never a token) before it can reach an error/log
+		// Reduce req.credentials to references only (never a token) before it can reach an error/log
 		// path or replication: references are what peers resolve from their own replicated hdb_secret
 		// copy; a no-custody literal token is dropped entirely (peers fall back to their fabric-injected
 		// NPM_CONFIG_USERCONFIG, as before). This also fixes the prior success-only strip that leaked a
 		// literal token on a prepare/load failure.
-		if (registryAuthReferences.length) req.registryAuth = registryAuthReferences;
-		else delete req.registryAuth;
+		if (credentialReferences.length) req.credentials = credentialReferences;
+		else delete req.credentials;
 
 		emit('phase', { phase: 'prepare', status: 'start' });
 		await prepareApplication(application);
@@ -556,7 +558,7 @@ async function deployComponent(req) {
 		// ProgressEmitter holds function listeners that can't survive the replication
 		// channel's serialization; strip it unconditionally.
 		delete req.progress;
-		// req.registryAuth was already deleted immediately after the Application ctor (above) so the
+		// req.credentials was already deleted immediately after the Application ctor (above) so the
 		// token never reaches the replication channel or a peer's operation log; peers authenticate
 		// against the private registry via their own fabric-injected NPM_CONFIG_USERCONFIG on reinstall.
 		if (systemReplicated && recorder) {

package/components/operationsValidation.js

@@ -371,6 +371,69 @@ function packageComponentValidator(req) {
 	return validator.validateBySchema(req, packageProjSchema);
 }
 
+// An npm registry-auth credential entry, identified by its `registry` key. `host` is forbidden
+// rather than merely unused: operation validation allows unknown keys, so without this an entry
+// carrying both discriminators would validate as npm registry auth and its git half would be
+// silently dropped.
+const REGISTRY_CREDENTIAL_ENTRY = Joi.object({
+	host: Joi.any().forbidden().messages({
+		'any.unknown': `a credential entry is either npm registry auth ('registry') or git host auth ('host'), not both`,
+	}),
+	// registry and token are written verbatim into the transient .npmrc, which is line-based;
+	// forbid CR/LF so a super_user can't inject extra npm config lines. (registry also accepts
+	// bare hosts and //host/ forms, so a strict URI validator would reject supported inputs — the
+	// newline guard is the right scope here.)
+	registry: Joi.string()
+		.pattern(/^[^\r\n]+$/)
+		.required(),
+	token: Joi.string().pattern(/^[^\r\n]+$/),
+	// A reference into the hdb_secret store; same name grammar as set_secret's `name`.
+	secret: Joi.string()
+		.pattern(ENV_KEY_REGEX)
+		.messages({ 'string.pattern.base': `'secret' must only contain word characters, dots and dashes` }),
+	scope: Joi.string()
+		.pattern(/^@[a-z0-9-_.]+$/)
+		.optional(),
+})
+	.xor('token', 'secret')
+	// The whole operation validates with allowUnknown, but a credential entry must not: an unknown
+	// key here (a typo'd or future secret-bearing field like `password`) would pass through ingest
+	// unchanged and be persisted to config/hdb_deployment and replicated, defeating reference-only.
+	.unknown(false);
+
+// A git-host credential entry, identified by its `host` key (#1792). Used to authenticate the
+// `git clone`/`git ls-remote` npm runs for a git-reference `package` (e.g. `github:org/repo`); the
+// token is served to git from memory, never written to a file or a URL.
+const GIT_CREDENTIAL_ENTRY = Joi.object({
+	// A bare host, optionally with a port — `github.com`, `git.example.com:8443`. A scheme or path is
+	// tolerated and normalized away, but a credential is matched by host, so keep the grammar tight.
+	host: Joi.string()
+		.pattern(/^[^\s/@\\]+$/)
+		.required()
+		.messages({ 'string.pattern.base': `'host' must be a bare git host, e.g. 'github.com'` }),
+	// The username half of git's HTTPS basic auth. Defaults to GitHub's `x-access-token` convention;
+	// GitLab wants `oauth2` and Bitbucket `x-token-auth`.
+	username: Joi.string()
+		.pattern(/^[^\r\n:]+$/)
+		.optional(),
+	// Capped like other secret-bearing fields (SECRET_MAX_LENGTH, above): an unbounded literal token
+	// here feeds straight into synchronous envelope-sealing crypto, so without a cap it's a
+	// resource-exhaustion vector, not just a storage one.
+	token: Joi.string()
+		.pattern(/^[^\r\n]+$/)
+		.max(SECRET_MAX_LENGTH),
+	secret: Joi.string()
+		.pattern(ENV_KEY_REGEX)
+		.messages({ 'string.pattern.base': `'secret' must only contain word characters, dots and dashes` }),
+	// `registry` forbidden for symmetry with the npm entry: an entry carrying both discriminators has
+	// no single kind and must be rejected, not silently treated as git auth.
+	registry: Joi.any().forbidden().messages({
+		'any.unknown': `a credential entry is either npm registry auth ('registry') or git host auth ('host'), not both`,
+	}),
+})
+	.xor('token', 'secret')
+	.unknown(false);
+
 /**
  * Validate deployComponent requests.
  * @param req
@@ -398,33 +461,35 @@ function deployComponentValidator(req) {
 			})
 			.optional()
 			.messages({ 'any.invalid': 'urlPath must not contain ".."' }),
-		// Private-registry auth. Each entry supplies its credential exactly one of two ways:
-		//   - `token`: a literal token, used only for this node's npm pack/install and never
-		//     persisted or replicated (stripped from req before replicateOperation).
+		// Deploy credentials. The array is kind-heterogeneous: an entry's kind is implied by its
+		// identifying key rather than a separate discriminator field, so a new kind is added as
+		// another item alternative here without reshaping the field. Today: npm registry auth
+		// (`registry`) and git host auth for a git-reference package (`host`, #1792).
+		//
+		// Every kind supplies its credential exactly one of two ways:
+		//   - `token`: a literal token, used only for this node's install and never persisted or
+		//     replicated (stripped from req before replicateOperation).
 		//   - `secret`: the name of an hdb_secret row (#1550); the token is resolved by decrypting
 		//     that row on this node at deploy time, so the credential lives in the secrets store
 		//     (reference, not embed) instead of travelling in the operation body.
-		registryAuth: Joi.array()
+		// Dispatched on the presence of `registry` rather than tried as alternatives, so a malformed
+		// entry reports what is actually wrong with it (a newline in the token, an invalid scope) rather
+		// than a generic "no alternative matched".
+		credentials: Joi.array()
 			.items(
-				Joi.object({
-					// registry and token are written verbatim into the transient .npmrc, which is
-					// line-based; forbid CR/LF so a super_user can't inject extra npm config lines.
-					// (registry also accepts bare hosts and //host/ forms, so a strict URI validator
-					// would reject supported inputs — the newline guard is the right scope here.)
-					registry: Joi.string()
-						.pattern(/^[^\r\n]+$/)
-						.required(),
-					token: Joi.string().pattern(/^[^\r\n]+$/),
-					// A reference into the hdb_secret store; same name grammar as set_secret's `name`.
-					secret: Joi.string()
-						.pattern(ENV_KEY_REGEX)
-						.messages({ 'string.pattern.base': `'secret' must only contain word characters, dots and dashes` }),
-					scope: Joi.string()
-						.pattern(/^@[a-z0-9-_.]+$/)
-						.optional(),
-				}).xor('token', 'secret')
+				Joi.alternatives().conditional('.registry', {
+					is: Joi.exist(),
+					then: REGISTRY_CREDENTIAL_ENTRY,
+					otherwise: GIT_CREDENTIAL_ENTRY,
+				})
 			)
 			.optional(),
+		// `registryAuth` was this field's name on the 5.2 dev line before it grew to carry other
+		// credential kinds. Rejected rather than ignored: validation allows unknown keys, so a caller
+		// still sending it would otherwise get a deploy that silently installs with no credentials.
+		registryAuth: Joi.any().forbidden().messages({
+			'any.unknown': `'registryAuth' has been renamed to 'credentials'`,
+		}),
 	}).with('urlPath', 'package');
 
 	return validator.validateBySchema(req, deployProjSchema);