@gajae-code/coding-agent 0.12.21 → 0.13.0

package/src/sdk/guides/cli.ts

@@ -0,0 +1,235 @@
+import { getAgentDir } from "@gajae-code/utils";
+import { readGuideCache } from "./cache";
+import { BUNDLED_GUIDE_MANIFESTS, GuideCatalog, guideFetchPolicy, isGuideFetchUrlAllowed } from "./catalog";
+import { GUIDE_CLIENT_VERSION, GUIDE_PINNED_KEYS } from "./verify";
+
+/**
+ * `gjc sdk guides` command family (routing lives in `src/commands/sdk.ts`).
+ *
+ * Verbs:
+ *   refresh --url <https url>  fetch + verify the online manifest and advisory
+ *                              text, install the verified cache, report selection.
+ *                              Fails operationally (exit 1) whenever the online
+ *                              manifest is not selected: fallback cache/bundled
+ *                              content is reported as a failure, never as a
+ *                              successful refresh
+ *   list                       offline selection: verified cache, else bundled
+ *   show <guideId>             render the advisory text for one guide (data only)
+ *   status                     selection provenance, cache health, fetch policy
+ *   trust                      pinned key ids and the no-credential fetch boundary
+ *
+ * The subsystem is advisory-text only: it never executes guide content, never
+ * mutates configuration, and never accepts or emits credentials. The only
+ * state it writes is the verified guide cache during `refresh`.
+ */
+export type SdkGuidesCliAction = "refresh" | "list" | "show" | "status" | "trust";
+
+export interface SdkGuidesCliArgs {
+	action?: string;
+	/** Guide id for `show`. */
+	guideId?: string;
+	/** Online manifest URL for `refresh`; must satisfy the HTTPS allowlist. */
+	url?: string;
+	agentDir?: string;
+	/** Bounded fetch timeout for `refresh`. */
+	timeoutMs?: number;
+	/** Fetch implementation override for `refresh` (test seam); defaults to the global fetch. */
+	fetchImpl?: typeof fetch;
+}
+
+const GUIDE_CLI_ACTIONS: readonly string[] = ["refresh", "list", "show", "status", "trust"];
+
+class SdkGuidesCliError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+		readonly exitCode: 1 | 2,
+	) {
+		super(message);
+	}
+}
+
+function writeJson(value: unknown): void {
+	process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function usageFailure(message: string): SdkGuidesCliError {
+	return new SdkGuidesCliError("usage", message, 2);
+}
+
+function operationalFailure(code: string, message: string): SdkGuidesCliError {
+	return new SdkGuidesCliError(code, message, 1);
+}
+
+/**
+ * Usage-shaped errors (bad verb, missing argument, URL outside the allowlist)
+ * exit 2; every verification/operational failure exits 1. Fail-closed codes
+ * from the verification pipeline map to exit 1 so scripts observe a hard
+ * failure on tamper, unknown key, rollback, expiry, or corrupt cache.
+ */
+function toCliError(error: unknown): SdkGuidesCliError {
+	if (error instanceof SdkGuidesCliError) return error;
+	const code = error instanceof Error && "code" in error ? String((error as { code: unknown }).code) : undefined;
+	const message = error instanceof Error ? error.message : String(error);
+	switch (code) {
+		case "usage":
+		case "invalid_input":
+		case "fetch_forbidden":
+			return new SdkGuidesCliError(code ?? "operation_failed", message, 2);
+		default:
+			return operationalFailure(code ?? "operation_failed", message);
+	}
+}
+
+function requireValue(value: string | undefined, flag: string): string {
+	if (value === undefined || value.length === 0) throw usageFailure(`${flag} is required.`);
+	return value;
+}
+
+function manifestSummary(manifest: {
+	manifestId: string;
+	keyId: string;
+	sequence: number;
+	issuedAt: number;
+	expiresAt: number;
+	minimumSdkVersion: number;
+}) {
+	return {
+		manifestId: manifest.manifestId,
+		keyId: manifest.keyId,
+		sequence: manifest.sequence,
+		issuedAt: manifest.issuedAt,
+		expiresAt: manifest.expiresAt,
+		minimumSdkVersion: manifest.minimumSdkVersion,
+	};
+}
+
+async function runRefresh(agentDir: string, args: SdkGuidesCliArgs): Promise<unknown> {
+	const url = requireValue(args.url, "--url");
+	if (!isGuideFetchUrlAllowed(url)) throw usageFailure(`--url ${url} is outside the HTTPS allowlist.`);
+	const catalog = new GuideCatalog({
+		agentDir,
+		onlineUrl: url,
+		timeoutMs: args.timeoutMs,
+		fetchImpl: args.fetchImpl,
+	});
+	const result = await catalog.refresh();
+	if (!result.ok) throw operationalFailure(result.error.code, result.error.message);
+	const selection = result.value;
+	if (selection.source !== "online") {
+		const reasons = selection.warnings.length > 0 ? ` ${selection.warnings.join("; ")}` : "";
+		throw operationalFailure(
+			"online_refresh_failed",
+			`Online refresh did not select an online source (selected ${selection.source} instead)${reasons}.`,
+		);
+	}
+	return {
+		source: selection.source,
+		manifest: manifestSummary(selection.manifest),
+		guides: selection.guides.map(guide => ({ id: guide.id, title: guide.title, sha256: guide.sha256 })),
+		warnings: selection.warnings,
+	};
+}
+
+async function runList(agentDir: string): Promise<unknown> {
+	const catalog = new GuideCatalog({ agentDir });
+	const result = await catalog.load();
+	if (!result.ok) throw operationalFailure(result.error.code, result.error.message);
+	const selection = result.value;
+	return {
+		source: selection.source,
+		manifest: manifestSummary(selection.manifest),
+		guides: selection.guides.map(guide => ({ id: guide.id, title: guide.title, sha256: guide.sha256 })),
+		warnings: selection.warnings,
+	};
+}
+
+async function runShow(agentDir: string, args: SdkGuidesCliArgs): Promise<unknown> {
+	const guideId = requireValue(args.guideId, "<guideId>");
+	const catalog = new GuideCatalog({ agentDir });
+	const result = await catalog.advisory(guideId);
+	if (!result.ok) throw operationalFailure(result.error.code, result.error.message);
+	return {
+		source: result.value.source,
+		guideId: result.value.guideId,
+		title: result.value.title,
+		text: result.value.text,
+	};
+}
+
+async function runStatus(agentDir: string): Promise<unknown> {
+	const now = Date.now();
+	const cache = await readGuideCache({ agentDir, now });
+	const cacheView =
+		!cache.ok && cache.error.code === "missing_cache"
+			? { present: false }
+			: {
+					present: true,
+					verified: cache.ok,
+					code: cache.ok ? undefined : cache.error.code,
+					manifestId: cache.ok ? cache.value.manifest.manifestId : undefined,
+					sequence: cache.ok ? cache.value.manifest.sequence : undefined,
+					expiresAt: cache.ok ? cache.value.manifest.expiresAt : undefined,
+				};
+	const catalog = new GuideCatalog({ agentDir });
+	const selection = await catalog.load();
+	return {
+		clientVersion: GUIDE_CLIENT_VERSION,
+		source: selection.ok ? selection.value.source : undefined,
+		manifest: selection.ok ? manifestSummary(selection.value.manifest) : undefined,
+		cache: cacheView,
+		bundled: BUNDLED_GUIDE_MANIFESTS.length,
+		fetch: guideFetchPolicy(),
+		warnings: selection.ok ? selection.value.warnings : [],
+	};
+}
+
+function runTrust(): unknown {
+	return {
+		clientVersion: GUIDE_CLIENT_VERSION,
+		pinnedKeys: GUIDE_PINNED_KEYS.map(key => ({ keyId: key.keyId, source: key.source })),
+		fetch: guideFetchPolicy(),
+	};
+}
+
+/**
+ * Runs the `gjc sdk guides` command family. Exported for command routing from
+ * `src/commands/sdk.ts` and for direct service use; the injected `write` /
+ * `setExitCode` hooks keep the surface testable without touching stdout or
+ * the process exit code.
+ */
+export async function runSdkGuidesCli(
+	args: SdkGuidesCliArgs,
+	writeOutput: (value: unknown) => void = writeJson,
+	setExitCode: (exitCode: 1 | 2) => void = exitCode => {
+		process.exitCode = exitCode;
+	},
+): Promise<void> {
+	try {
+		const action = args.action;
+		if (action === undefined || !GUIDE_CLI_ACTIONS.includes(action))
+			throw usageFailure(`Expected one of: ${GUIDE_CLI_ACTIONS.join(", ")}.`);
+		const agentDir = args.agentDir ?? getAgentDir();
+		switch (action) {
+			case "refresh":
+				writeOutput({ ok: true, result: await runRefresh(agentDir, args) });
+				return;
+			case "list":
+				writeOutput({ ok: true, result: await runList(agentDir) });
+				return;
+			case "show":
+				writeOutput({ ok: true, result: await runShow(agentDir, args) });
+				return;
+			case "status":
+				writeOutput({ ok: true, result: await runStatus(agentDir) });
+				return;
+			case "trust":
+				writeOutput({ ok: true, result: runTrust() });
+				return;
+		}
+	} catch (error) {
+		const cliError = toCliError(error);
+		writeOutput({ ok: false, error: { code: cliError.code, message: cliError.message } });
+		setExitCode(cliError.exitCode);
+	}
+}

package/src/sdk/guides/manifest.ts

@@ -0,0 +1,152 @@
+/**
+ * Trusted advisory guide manifest: types, canonical encoding, and parsing.
+ *
+ * A manifest is a signed, time-boxed bundle of advisory guide bindings. Each
+ * entry binds a stable guide id to the SHA-256 digest of its advisory text, so
+ * the advisory content can be fetched separately and verified against the
+ * signed manifest. Manifests are advisory text only: they never carry
+ * instructions to execute or configuration to apply.
+ */
+export const GUIDES_MANIFEST_VERSION = 1;
+
+/** Maximum byte length of a single advisory text file. */
+export const GUIDE_ADVISORY_MAX_BYTES = 256 * 1024;
+/** Maximum number of guides bound by a single manifest. */
+export const GUIDE_MANIFEST_MAX_ENTRIES = 256;
+/** Maximum manifest JSON byte length (enforced at fetch and cache read time). */
+export const GUIDE_MANIFEST_MAX_BYTES = 1024 * 1024;
+export const GUIDE_ID_MAX_LENGTH = 128;
+export const GUIDE_TITLE_MAX_LENGTH = 256;
+
+export interface GuideEntryV1 {
+	/** Path-safe, stable guide id, e.g. "troubleshooting/socket". */
+	id: string;
+	/** Human-readable advisory title. */
+	title: string;
+	/** Hex SHA-256 of the advisory text bytes; binds content to the signed manifest. */
+	sha256: string;
+}
+
+export interface GuideManifestV1 {
+	version: 1;
+	/** Stable channel identity the signature binds to; the rollback floor is per manifestId. */
+	manifestId: string;
+	/** Key id of the pinned Ed25519 public key that detached-signed the canonical manifest bytes. */
+	keyId: string;
+	/** Monotonic per-manifestId sequence; the cache refuses installs at or below the floor. */
+	sequence: number;
+	/** Milliseconds since epoch; the manifest is not authoritative before this instant. */
+	issuedAt: number;
+	/** Milliseconds since epoch; the manifest is not authoritative after this instant. */
+	expiresAt: number;
+	/** Minimum SDK advisory client version required to consume this manifest. */
+	minimumSdkVersion: number;
+	guides: GuideEntryV1[];
+}
+
+const SHA256_HEX = /^[a-f0-9]{64}$/;
+const GUIDE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*(?:\/[a-z0-9][a-z0-9._-]*){0,15}$/;
+const MANIFEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+/**
+ * Deterministic UTF-8 encoding of a guide manifest. Object keys are sorted,
+ * separators are compact, and the output is byte-identical for semantically
+ * equal manifests regardless of the original JSON formatting. The detached
+ * Ed25519 signature is verified over exactly these bytes, so a re-formatted
+ * manifest file still verifies while any semantic change breaks the signature.
+ */
+export function canonicalGuideManifestBytes(manifest: GuideManifestV1): Buffer {
+	return Buffer.from(canonicalGuideJson(manifest), "utf8");
+}
+
+function canonicalGuideJson(value: unknown): string {
+	if (value === null || typeof value !== "object") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map(canonicalGuideJson).join(",")}]`;
+	const record = value as Record<string, unknown>;
+	return `{${Object.keys(record)
+		.sort()
+		.map(key => `${JSON.stringify(key)}:${canonicalGuideJson(record[key])}`)
+		.join(",")}}`;
+}
+
+export type GuideManifestParseResult =
+	| { ok: true; manifest: GuideManifestV1 }
+	| { ok: false; error: { code: "invalid_manifest" | "unsupported_version"; message: string } };
+
+function manifestParseFailure(
+	code: "invalid_manifest" | "unsupported_version",
+	message: string,
+): GuideManifestParseResult {
+	return { ok: false, error: { code, message } };
+}
+
+/**
+ * Strict shape validation for a parsed manifest value. Fails closed on any
+ * out-of-bounds field; a manifest for a newer format version is refused with
+ * `unsupported_version` so callers can distinguish "too new" from "malformed".
+ */
+export function parseGuideManifest(value: unknown): GuideManifestParseResult {
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		return manifestParseFailure("invalid_manifest", "Guide manifest must be a JSON object.");
+	const record = value as Record<string, unknown>;
+	if (!Number.isSafeInteger(record.version))
+		return manifestParseFailure("invalid_manifest", "Guide manifest version must be an integer.");
+	const version = record.version as number;
+	if (version > GUIDES_MANIFEST_VERSION)
+		return manifestParseFailure(
+			"unsupported_version",
+			`Guide manifest version ${version} is newer than the supported version ${GUIDES_MANIFEST_VERSION}.`,
+		);
+	if (version !== GUIDES_MANIFEST_VERSION)
+		return manifestParseFailure(
+			"invalid_manifest",
+			`Guide manifest version ${version} is not supported (expected ${GUIDES_MANIFEST_VERSION}).`,
+		);
+	if (typeof record.manifestId !== "string" || !MANIFEST_ID_PATTERN.test(record.manifestId))
+		return manifestParseFailure("invalid_manifest", "Guide manifestId is malformed.");
+	if (typeof record.keyId !== "string" || !SHA256_HEX.test(record.keyId))
+		return manifestParseFailure("invalid_manifest", "Guide manifest keyId must be a SHA-256 hex digest.");
+	if (!Number.isSafeInteger(record.sequence) || (record.sequence as number) < 1)
+		return manifestParseFailure("invalid_manifest", "Guide manifest sequence must be a positive integer.");
+	if (!Number.isSafeInteger(record.issuedAt) || (record.issuedAt as number) < 0)
+		return manifestParseFailure("invalid_manifest", "Guide manifest issuedAt must be a non-negative timestamp.");
+	if (!Number.isSafeInteger(record.expiresAt) || (record.expiresAt as number) <= (record.issuedAt as number))
+		return manifestParseFailure("invalid_manifest", "Guide manifest expiresAt must be after issuedAt.");
+	if (!Number.isSafeInteger(record.minimumSdkVersion) || (record.minimumSdkVersion as number) < 1)
+		return manifestParseFailure("invalid_manifest", "Guide manifest minimumSdkVersion must be a positive integer.");
+	if (!Array.isArray(record.guides) || record.guides.length === 0 || record.guides.length > GUIDE_MANIFEST_MAX_ENTRIES)
+		return manifestParseFailure(
+			"invalid_manifest",
+			`Guide manifest guides must contain between 1 and ${GUIDE_MANIFEST_MAX_ENTRIES} entries.`,
+		);
+	const guides: GuideEntryV1[] = [];
+	const seenIds = new Set<string>();
+	for (const rawEntry of record.guides) {
+		if (typeof rawEntry !== "object" || rawEntry === null || Array.isArray(rawEntry))
+			return manifestParseFailure("invalid_manifest", "Guide entry must be a JSON object.");
+		const entry = rawEntry as Record<string, unknown>;
+		if (typeof entry.id !== "string" || entry.id.length > GUIDE_ID_MAX_LENGTH || !GUIDE_ID_PATTERN.test(entry.id))
+			return manifestParseFailure("invalid_manifest", "Guide entry id is malformed.");
+		if (seenIds.has(entry.id))
+			return manifestParseFailure("invalid_manifest", `Guide entry id ${entry.id} is duplicated.`);
+		if (typeof entry.title !== "string" || entry.title.length === 0 || entry.title.length > GUIDE_TITLE_MAX_LENGTH)
+			return manifestParseFailure("invalid_manifest", "Guide entry title is malformed.");
+		if (typeof entry.sha256 !== "string" || !SHA256_HEX.test(entry.sha256))
+			return manifestParseFailure("invalid_manifest", "Guide entry sha256 must be a SHA-256 hex digest.");
+		seenIds.add(entry.id);
+		guides.push({ id: entry.id, title: entry.title, sha256: entry.sha256 });
+	}
+	return {
+		ok: true,
+		manifest: {
+			version: GUIDES_MANIFEST_VERSION,
+			manifestId: record.manifestId,
+			keyId: record.keyId,
+			sequence: record.sequence as number,
+			issuedAt: record.issuedAt as number,
+			expiresAt: record.expiresAt as number,
+			minimumSdkVersion: record.minimumSdkVersion as number,
+			guides,
+		},
+	};
+}

package/src/sdk/guides/verify.ts

@@ -0,0 +1,178 @@
+import { createHash, createPublicKey, verify as cryptoVerify, type KeyObject } from "node:crypto";
+import {
+	canonicalGuideManifestBytes,
+	GUIDES_MANIFEST_VERSION,
+	type GuideEntryV1,
+	type GuideManifestV1,
+} from "./manifest";
+
+/**
+ * Version of the SDK advisory guide client. Manifests carry a
+ * `minimumSdkVersion` compatibility floor; a manifest that requires a newer
+ * client is refused (`incompatible`) instead of being partially understood.
+ */
+export const GUIDE_CLIENT_VERSION = 1;
+
+/** Ed25519 detached signatures are always exactly 64 bytes. */
+export const GUIDE_SIGNATURE_BYTES = 64;
+
+export interface GuidePinnedKey {
+	keyId: string;
+	/** DER-encoded SPKI public key, hex. */
+	spkiDerHex: string;
+	source: "bundled";
+}
+
+/**
+ * Pinned Ed25519 public keys accepted for guide manifests. A manifest whose
+ * `keyId` is not in this registry is refused (`unknown_key`) — the registry is
+ * compiled into the binary and is the only trust root for advisory content.
+ * Private key material is never shipped; manifests are signed out-of-band.
+ */
+const guidePinnedKeys: GuidePinnedKey[] = [
+	{
+		keyId: "6c4b134ff9fb86a52d55cb6bb7c2fab938405b53b4148afc4249a2cb6f504bce",
+		spkiDerHex: "302a300506032b6570032100ef665d05c6795341dfc893866d8fe5be4b48891c0ed0d125940d7032de37723e",
+		source: "bundled",
+	},
+];
+export const GUIDE_PINNED_KEYS: readonly GuidePinnedKey[] = Object.freeze(
+	guidePinnedKeys.map(key => Object.freeze({ ...key })),
+);
+
+export const GUIDE_PINNED_KEY_IDS: readonly string[] = Object.freeze(GUIDE_PINNED_KEYS.map(key => key.keyId));
+
+export type GuideVerificationErrorCode =
+	| "invalid_manifest"
+	| "unsupported_version"
+	| "unknown_key"
+	| "corrupt_signature"
+	| "invalid_signature"
+	| "not_yet_valid"
+	| "expired"
+	| "incompatible"
+	| "rollback"
+	| "hash_mismatch"
+	| (string & {});
+
+export type GuideVerificationResult<T> =
+	| { ok: true; value: T }
+	| { ok: false; error: { code: GuideVerificationErrorCode; message: string } };
+
+function guideFailure<T>(code: GuideVerificationErrorCode, message: string): GuideVerificationResult<T> {
+	return { ok: false, error: { code, message } };
+}
+
+const guideKeyCache = new Map<string, KeyObject>();
+
+/** Test-only override: installs an additional trusted key for deterministic tests. */
+export function addTestGuidePinnedKey(key: GuidePinnedKey): void {
+	if (process.env.GJC_TEST_GUIDE_KEYS !== "1") throw new Error("Test guide key injection is disabled.");
+	guideKeyCache.delete(key.keyId);
+	guidePinnedKeys.push(key);
+}
+
+/** Test-only override: removes a previously installed test key. */
+export function removeTestGuidePinnedKey(keyId: string): void {
+	if (process.env.GJC_TEST_GUIDE_KEYS !== "1") throw new Error("Test guide key injection is disabled.");
+	guideKeyCache.delete(keyId);
+	const index = guidePinnedKeys.findIndex(key => key.keyId === keyId);
+	if (index >= 0) guidePinnedKeys.splice(index, 1);
+}
+
+function pinnedGuideKey(keyId: string): GuidePinnedKey | undefined {
+	return guidePinnedKeys.find(key => key.keyId === keyId);
+}
+
+function guidePublicKey(pinned: GuidePinnedKey): KeyObject {
+	const cached = guideKeyCache.get(pinned.keyId);
+	if (cached) return cached;
+	const key = createPublicKey({ key: Buffer.from(pinned.spkiDerHex, "hex"), format: "der", type: "spki" });
+	guideKeyCache.set(pinned.keyId, key);
+	return key;
+}
+
+/**
+ * Verifies a guide manifest end to end and fails closed on the first broken
+ * property. Order matters: identity and tamper checks (unknown key, malformed
+ * or mismatched signature) run before temporal and compatibility checks, so a
+ * tampered or untrusted manifest is never masked by an expiry message.
+ */
+export function verifyGuideManifest(params: {
+	manifest: GuideManifestV1;
+	signatureBytes: Uint8Array;
+	now: number;
+}): GuideVerificationResult<{ keyId: string }> {
+	const { manifest, signatureBytes, now } = params;
+	if (manifest.version !== GUIDES_MANIFEST_VERSION)
+		return guideFailure(
+			"unsupported_version",
+			`Guide manifest version ${manifest.version} is newer than the supported version ${GUIDES_MANIFEST_VERSION}.`,
+		);
+	const pinned = pinnedGuideKey(manifest.keyId);
+	if (!pinned) return guideFailure("unknown_key", `Guide manifest keyId ${manifest.keyId} is not pinned.`);
+	if (signatureBytes.length !== GUIDE_SIGNATURE_BYTES)
+		return guideFailure(
+			"corrupt_signature",
+			`Detached signature must be exactly ${GUIDE_SIGNATURE_BYTES} bytes (Ed25519), got ${signatureBytes.length}.`,
+		);
+	const canonical = canonicalGuideManifestBytes(manifest);
+	let valid: boolean;
+	try {
+		valid = cryptoVerify(null, canonical, guidePublicKey(pinned), signatureBytes);
+	} catch {
+		return guideFailure("invalid_signature", "Detached signature verification failed.");
+	}
+	if (!valid)
+		return guideFailure("invalid_signature", "Detached signature does not match the canonical manifest bytes.");
+	if (!Number.isSafeInteger(now) || now < manifest.issuedAt)
+		return guideFailure("not_yet_valid", "Guide manifest is not authoritative until its issuedAt instant.");
+	if (now > manifest.expiresAt)
+		return guideFailure("expired", "Guide manifest has expired and is no longer authoritative.");
+	if (manifest.minimumSdkVersion > GUIDE_CLIENT_VERSION)
+		return guideFailure(
+			"incompatible",
+			`Guide manifest requires SDK advisory client ${manifest.minimumSdkVersion}, this client is ${GUIDE_CLIENT_VERSION}.`,
+		);
+	return { ok: true, value: { keyId: manifest.keyId } };
+}
+
+/**
+ * Monotonic floor check: a candidate manifest for a channel must strictly
+ * advance that channel's sequence, otherwise an older (but still validly
+ * signed) manifest is refused as a rollback.
+ */
+export function guideRollbackCheck(
+	previous: { manifestId: string; sequence: number } | undefined,
+	candidate: GuideManifestV1,
+): GuideVerificationResult<{ monotonic: boolean }> {
+	if (previous && previous.manifestId === candidate.manifestId && candidate.sequence <= previous.sequence)
+		return guideFailure(
+			"rollback",
+			`Guide manifest sequence ${candidate.sequence} does not advance the cached floor ${previous.sequence} for ${candidate.manifestId}.`,
+		);
+	return { ok: true, value: { monotonic: true } };
+}
+
+export function guideAdvisoryDigest(text: Uint8Array): string {
+	return createHash("sha256").update(text).digest("hex");
+}
+
+/**
+ * Per-guide SHA-256 binding: the advisory text must match the digest the
+ * signed manifest binds for that guide id. This is the tamper check for the
+ * advisory payload itself — the manifest signature cannot cover content that
+ * is fetched separately, so every advisory is hash-verified against it.
+ */
+export function verifyGuideAdvisoryText(
+	entry: GuideEntryV1,
+	text: Uint8Array,
+): GuideVerificationResult<{ sha256: string }> {
+	const digest = guideAdvisoryDigest(text);
+	if (digest !== entry.sha256)
+		return guideFailure(
+			"hash_mismatch",
+			`Advisory ${entry.id} digest ${digest} does not match the manifest binding ${entry.sha256}.`,
+		);
+	return { ok: true, value: { sha256: digest } };
+}

package/src/sdk/host/control/dispatch.ts

@@ -3,6 +3,7 @@ import {
 	DEFAULT_MODEL_SELECTION_RECOVERY_MESSAGE,
 	parseDefaultModelSelectionRecovery,
 } from "../../../session/default-model-selection";
+import { isElevationAllowlisted } from "../../elevation/allowlist";
 import { OPERATIONS, type Operation } from "../../protocol/operation-registry";
 import type { ControlInput, ControlSurface, ControlValue } from "./operations";
 
@@ -13,6 +14,8 @@ export interface ControlRequest {
 	expectedRevision?: string;
 	idempotencyKey?: string;
 	confirm?: boolean;
+	/** Top-level elevation claim selector, preserved from the control frame. */
+	elevationRequestId?: string;
 }
 
 export type ControlErrorCode = string;
@@ -105,6 +108,22 @@ function failure(
 function isInput(value: unknown): value is ControlInput {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+/**
+ * Build the typed control request from a wire frame. Every runtime transport
+ * mapper uses this helper so the top-level elevation claim selector cannot
+ * drift between callsites.
+ */
+export function controlRequestFromFrame(frame: Record<string, unknown>): ControlRequest {
+	return {
+		id: typeof frame.id === "string" ? frame.id : "",
+		operation: typeof frame.operation === "string" ? frame.operation : "",
+		input: frame.input,
+		expectedRevision: typeof frame.expectedRevision === "string" ? frame.expectedRevision : undefined,
+		idempotencyKey: typeof frame.idempotencyKey === "string" ? frame.idempotencyKey : undefined,
+		confirm: frame.confirm === true,
+		elevationRequestId: typeof frame.elevationRequestId === "string" ? frame.elevationRequestId : undefined,
+	};
+}
 
 function canonicalize(value: unknown): unknown {
 	if (Array.isArray(value)) return value.map(canonicalize);
@@ -134,6 +153,7 @@ function invoke(
 	input: ControlInput,
 	confirm: boolean | undefined,
 	idempotencyKey: string | undefined,
+	elevationRequestId: string | undefined,
 ): Promise<ControlValue> | ControlValue {
 	switch (operation) {
 		case "turn.prompt":
@@ -154,9 +174,15 @@ function invoke(
 				input.response,
 				input.expectedSessionId as string | undefined,
 				idempotencyKey,
+				elevationRequestId,
 			);
 		case "workflow.plan_approve":
-			return surface.approvePlan(text(input, "id"), input.choice, input.expectedSessionId as string | undefined);
+			return surface.approvePlan(
+				text(input, "id"),
+				input.choice,
+				input.expectedSessionId as string | undefined,
+				elevationRequestId,
+			);
 		case "skill.invoke":
 			return surface.invokeSkill(
 				text(input, "name"),
@@ -303,6 +329,7 @@ async function execute(surface: ControlSurface, row: Operation, request: Control
 				request.input as ControlInput,
 				request.confirm,
 				request.idempotencyKey,
+				request.elevationRequestId,
 			),
 		};
 	} catch (error) {
@@ -379,6 +406,27 @@ export function dispatchControl(
 		);
 	if (!isInput(request.input))
 		return Promise.resolve(failure(request.id, "invalid_input", "Control input must be an object."));
+	const elevationEnabled =
+		process.env.GJC_SDK_ELEVATION_ENABLED === "1" || process.env.GJC_SDK_ELEVATION_ENABLED === "true";
+	const elevationAllowlisted = isElevationAllowlisted("control", row.sdkId);
+	const elevationRequired = elevationEnabled && elevationAllowlisted;
+	if (elevationRequired && request.elevationRequestId === undefined)
+		return Promise.resolve(failure(request.id, "elevation_required", `${row.sdkId} requires an elevation grant.`));
+	if (request.elevationRequestId !== undefined) {
+		const claim = request.elevationRequestId.trim();
+		if (!claim || claim.length > 128)
+			return Promise.resolve(
+				failure(request.id, "invalid_input", "elevationRequestId must be a non-empty bounded string."),
+			);
+		if (!elevationAllowlisted)
+			return Promise.resolve(
+				failure(request.id, "invalid_input", "Only allowlisted elevation operations may carry elevationRequestId."),
+			);
+		if (!surface.authorizeElevationClaim?.(row.sdkId, request.input, claim))
+			return Promise.resolve(
+				failure(request.id, "elevation_required", "The elevation claim is not broker-authorized for this control."),
+			);
+	}
 	if ((row.sdkId === "context.clear" || row.sdkId === "session.delete") && request.confirm !== true)
 		return Promise.resolve(
 			failure(request.id, "invalid_input", "confirm: true is required for this destructive operation."),

package/src/sdk/host/control/index.ts

@@ -4,6 +4,7 @@ export {
 	type ControlErrorCode,
 	type ControlRequest,
 	type ControlResponse,
+	controlRequestFromFrame,
 	dispatchControl,
 	TypedControlError,
 } from "./dispatch";