backend-skeleton 1.1.1 → 1.3.0

package/contracts/csv.mjs

@@ -0,0 +1,100 @@
+// D-contract-csv: a spreadsheet-shaped projection of a feature contract -- one row per operation,
+// opened by someone who will never read a JSON Schema. Pure module, no I/O, no gate awareness, no
+// process -- mirrors contracts/export.mjs's own contract (see that file's header comment) exactly,
+// so this file can be unit-tested with hand-built `contract` objects and nothing else.
+//
+// C1: a fixed 14-column header, always -- see C2 in DECISIONS.md for why a column is never
+// dropped just because every operation leaves it blank (a scan-only contract's `summary`/`tags`/
+// `security` columns ARE the finding "nobody stated these", not something to hide by omitting the
+// column). C3: `description` is deliberately NOT a column (measured average 2,442.7 bytes/op,
+// larger than every other copied field combined -- see D-openapi-description).
+export const CSV_COLUMNS = Object.freeze([
+	{ name: 'operation_id', extract: (op, operationId) => operationId },
+	{ name: 'verb', extract: (op) => op.verb },
+	{ name: 'path', extract: (op) => op.path },
+	{ name: 'path_params', extract: (op) => sortedKeys(op.pathParams?.properties).join(', ') },
+	{ name: 'path_params_unverified', extract: (op) => (op.pathParamsHeuristic ?? []).join(', ') },
+	{ name: 'body', extract: (op) => String(op.body) },
+	{ name: 'request_body_required', extract: (op) => (op.requestBodyRequired == null ? '' : String(op.requestBodyRequired)) },
+	{ name: 'request_body_fields', extract: (op) => sortedKeys(op.requestBodySchema?.properties).join(', ') },
+	{ name: 'response_fields', extract: (op) => sortedKeys(op.responseSchema?.properties).join(', ') },
+	{ name: 'error_fields', extract: (op) => sortedKeys(op.errorSchema?.properties).join(', ') },
+	{ name: 'provenance', extract: (op) => op.provenance },
+	{ name: 'summary', extract: (op) => op.sourceSummary ?? '' },
+	{ name: 'tags', extract: (op) => (op.sourceTags ?? []).join(', ') },
+	{ name: 'security', extract: (op) => extractSecurity(op.sourceSecurity) },
+]);
+
+function sortedKeys(properties) {
+	return properties ? Object.keys(properties).sort() : [];
+}
+
+// `security: []` is a genuine positive claim ("this operation declared no auth requirement") --
+// see schemas/feature-contract.schema.json's own sourceSecurity description. An ABSENT
+// sourceSecurity means the source document said nothing about security for this operation at all.
+// The two must render distinguishably, or a reviewer cannot tell "confirmed open" from "unknown".
+function extractSecurity(sourceSecurity) {
+	if (sourceSecurity == null) return '';
+	if (sourceSecurity.length === 0) return '(source-declared: none)';
+	const schemeNames = new Set();
+	for (const requirement of sourceSecurity) {
+		for (const scheme of Object.keys(requirement)) schemeNames.add(scheme);
+	}
+	return [...schemeNames].sort().join(', ');
+}
+
+// C4: RFC 4180, hand-rolled -- quote a field iff it contains a double quote, comma, CR, or LF;
+// an embedded double quote is escaped by doubling it. Deliberately does NOT quote a field that
+// needs none of this (the negative case is what catches an over-eager escaper in tests). No new
+// dependency: this is the entire rule CSV has needed since RFC 4180 (2005).
+export function escapeCsvField(value) {
+	const str = String(value);
+	if (/["\n\r,]/.test(str)) {
+		return `"${str.replaceAll('"', '""')}"`;
+	}
+	return str;
+}
+
+// C4: LF line terminator (not RFC 4180's CRLF) -- every other artifact this project writes is
+// LF, and these files get committed/diffed. No comment/provenance preamble: line 1 is always the
+// header row, because a leading `#`/comment line breaks `pandas.read_csv`/`csv.DictReader`/every
+// spreadsheet importer's default settings -- provenance goes to stderr/`--json`, never into the
+// file itself.
+export function toCsv(header, rows) {
+	const lines = [header, ...rows].map((row) => row.map(escapeCsvField).join(','));
+	return `${lines.join('\n')}\n`;
+}
+
+// C5: deliberately does NOT check gate state, does NOT read a scan report, does NOT look at
+// path-prefix signals -- this is a pure projection of an already-loaded `contract` object. The
+// caller (bin/bskel.mjs's cmdContractExportCsv) owns every refusal/warning decision; this
+// function only ever succeeds or reports "there's nothing to export" for a genuinely empty
+// contract.
+export function buildContractCsv({ contract }) {
+	const operationIds = Object.keys(contract.operations).sort((a, b) => a.localeCompare(b));
+	if (operationIds.length === 0) {
+		return { ok: false, error: 'contract has zero operations' };
+	}
+
+	const header = CSV_COLUMNS.map((c) => c.name);
+	const rows = operationIds.map((operationId) => {
+		const op = contract.operations[operationId];
+		return CSV_COLUMNS.map((c) => c.extract(op, operationId));
+	});
+
+	// C2: coverage is reported alongside the file, never inferred by a reader staring at blank
+	// cells wondering whether the tool is broken.
+	const columns = CSV_COLUMNS.map((c, i) => ({
+		name: c.name,
+		populatedRows: rows.filter((row) => row[i] !== '').length,
+	}));
+	const emptyColumns = columns.filter((c) => c.populatedRows === 0).map((c) => c.name);
+
+	return {
+		ok: true,
+		csv: toCsv(header, rows),
+		rowCount: rows.length,
+		columns,
+		emptyColumns,
+	};
+}

package/handles/providers/java-spring/observe.mjs

@@ -24,6 +24,10 @@ const INFRA_FILES = [
 	{ template: 'ContractCheck.java.tmpl', target: 'global/observe/ContractCheck.java' },
 	{ template: 'ObserveSchemaLoader.java.tmpl', target: 'global/observe/ObserveSchemaLoader.java' },
 	{ template: 'ContractObservationAspect.java.tmpl', target: 'global/observe/ContractObservationAspect.java' },
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): JDK-stdlib-only Ed25519
+	// signer, used by ContractObservationAspect -- see that template's own javadoc for why this is
+	// a hand-rolled canonicalizer, not a Jackson mapper feature.
+	{ template: 'ReceiptSigner.java.tmpl', target: 'global/observe/ReceiptSigner.java' },
 ];
 
 function render(templatePath, vars) {
@@ -51,12 +55,21 @@ function writeUnit(target, content) {
 export function emitObserveJavaSpring({ repoRoot, featureId, contract, basePackage, force = false, reason = '', dryRun = false, computeDiff = false }) {
 	const javaSrcRoot = path.join(repoRoot, 'src', 'main', 'java', ...basePackage.split('.'));
 	const jacksonPackage = detectJacksonPackage(repoRoot);
+	// D-runtime-conformance-receipts (Jackson 2/3 JsonNode field-iteration parity): Jackson 3's
+	// JsonNode has no #fields()/#fieldNames() at all (confirmed live via javap against real
+	// jackson-databind 3.1.5 -- only #properties(), a Set); Jackson 2's #fields() exists across
+	// every real version checked (2.14 through 2.21), but #properties() does NOT exist on the
+	// older ones (2.14 lacks it, 2.17+ has it) -- so the safe, version-spanning choice per major is
+	// #fields() for Jackson 2, #properties() for Jackson 3, never the other way around.
+	const jacksonFieldsOfImpl = jacksonPackage === 'tools.jackson.databind'
+		? 'return node.properties();'
+		: 'return () -> node.fields();';
 
 	const infraUnits = INFRA_FILES.map((f) => ({
 		id: f.template,
 		templatePath: path.join(TEMPLATES_DIR, f.template),
 		targetAbs: path.join(javaSrcRoot, f.target),
-		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage }),
+		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage, JACKSON_FIELDS_OF_IMPL: jacksonFieldsOfImpl }),
 	}));
 
 	const result = emitUnits({ repoRoot, featureId, provider: 'java-spring', force, reason, infraUnits, resolverUnits: [], orphanScan: null, dryRun, computeDiff });
@@ -89,6 +102,7 @@ export function emitObserveJavaSpring({ repoRoot, featureId, contract, basePacka
 			'NOT done automatically: route the "bskel.observe.receipts" SLF4J logger to wherever you want receipt lines collected (a dedicated logback/log4j2 appender to a file, your existing log pipeline, etc.) -- bskel never edits your logging config. Point `bskel observe import --receipts <path>` at whatever that logger\'s output ends up as.',
 			`Contract-conformance checking only covers path params always, plus a bounded slice of request/response/error body shape -- and only when this contract was emitted with --openapi-file. See the emitted ${path.relative(repoRoot, schemaPath)}'s own "unsupported" markers for exactly what is skipped for this feature.`,
 			'NOT done automatically: apply @ObserveContract(operationId = "...") to whichever existing controller/service methods you want observed -- nothing is annotated for you (D-resolver-scope: never guess which method implements which operation).',
+			'NOT done automatically: to sign receipts, set the `bskel.observe.signing-key-pem` Spring property (e.g. an env var via Spring\'s own relaxed binding: BSKEL_OBSERVE_SIGNING_KEY_PEM=...) to a PKCS#8 Ed25519 private key PEM -- `bskel attest keygen --out <dir>` already generates one in this exact format. Unset means every receipt stays unsigned (backward compatible). Verify with `bskel observe import --pubkey <path/to/attest-public.pem>`.',
 		],
 	};
 }

package/handles/providers/java-spring/templates/ContractObservationAspect.java.tmpl

@@ -5,11 +5,13 @@ import {{JACKSON_PACKAGE}}.ObjectMapper;
 import {{JACKSON_PACKAGE}}.node.ArrayNode;
 import {{JACKSON_PACKAGE}}.node.ObjectNode;
 import {{BASE_PACKAGE}}.global.observe.ObserveSchemaLoader.ObservedOperation;
+import jakarta.annotation.PostConstruct;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.aspectj.lang.ProceedingJoinPoint;
 import org.aspectj.lang.annotation.Around;
 import org.aspectj.lang.annotation.Aspect;
+import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
 import org.springframework.stereotype.Component;
 import org.springframework.web.bind.annotation.RequestBody;
@@ -49,6 +51,10 @@ import java.util.Map;
  * deliberately deferred, same unexamined assumption {@code HandleAspect} already carries for
  * {@code @Around} advice generally. See DECISIONS.md D-runtime-conformance-receipts.
  *
+ * <p>Optionally signs each receipt (Ed25519, via {@link ReceiptSigner}) when {@code
+ * bskel.observe.signing-key-pem} is set -- see that class's own javadoc. Unset means every
+ * receipt stays unsigned, exactly like before this capability existed.
+ *
  * <p>Generated by backend-skeleton ({@code bskel observe emit}). Requires {@code
  * spring-boot-starter-aop} on the classpath -- see {@link ObserveContract}'s own javadoc.
  */
@@ -63,6 +69,21 @@ public class ContractObservationAspect {
 	private final ObserveSchemaLoader schemaLoader;
 	private final ObjectMapper objectMapper;
 
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): a plain, non-final,
+	// separately field-injected member -- NOT routed through the @RequiredArgsConstructor-generated
+	// constructor above. @Value on a `final` constructor-injected field alongside
+	// @RequiredArgsConstructor is a documented Lombok/Spring interop gap (the generated constructor
+	// does not reliably propagate the annotation); this is the standard, real-world-safe pattern for
+	// @Value-injected simple config even in classes that otherwise use constructor injection.
+	// Empty (the default) means every receipt stays unsigned -- see ReceiptSigner's own javadoc.
+	@Value("${bskel.observe.signing-key-pem:}")
+	private String signingKeyPem;
+
+	@PostConstruct
+	private void configureReceiptSigning() {
+		ReceiptSigner.configure(signingKeyPem);
+	}
+
 	@Around("@annotation(observeContract)")
 	public Object observe(ProceedingJoinPoint joinPoint, ObserveContract observeContract) throws Throwable {
 		String operationId = observeContract.operationId();
@@ -159,9 +180,26 @@ public class ContractObservationAspect {
 			vn.put("keyword", v.keyword());
 			vn.put("message", v.message());
 		}
+		safelySign(receipt);
 		safelyLog(receipt);
 	}
 
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): its OWN inner try/catch,
+	// separate from safelyLog()'s -- a signing failure (bad/missing key config, malformed PEM) must
+	// fall back to logging the receipt UNSIGNED, not silently drop the whole receipt the way sharing
+	// safelyLog()'s catch block would.
+	private void safelySign(ObjectNode receipt) {
+		if (!ReceiptSigner.isConfigured()) return;
+		try {
+			String signatureValue = ReceiptSigner.sign(receipt);
+			ObjectNode signature = receipt.putObject("signature");
+			signature.put("algorithm", "ed25519");
+			signature.put("value", signatureValue);
+		} catch (Exception e) {
+			log.warn("ContractObservationAspect: could not sign a receipt -- logging it unsigned instead", e);
+		}
+	}
+
 	private void safelyLog(Object receipt) {
 		try {
 			RECEIPTS.info(objectMapper.writeValueAsString(receipt));

package/handles/providers/java-spring/templates/ObserveSchemaLoader.java.tmpl

@@ -11,7 +11,6 @@ import java.io.IOException;
 import java.io.InputStream;
 import java.util.ArrayList;
 import java.util.HashMap;
-import java.util.Iterator;
 import java.util.List;
 import java.util.Map;
 import java.util.regex.Pattern;
@@ -69,9 +68,7 @@ public class ObserveSchemaLoader {
 			String featureId = root.path("feature_id").asText(null);
 			String featureUid = root.path("feature_uid").asText(null);
 			String contractRef = root.path("contract_ref").asText(null);
-			Iterator<Map.Entry<String, JsonNode>> ops = root.path("operations").fields();
-			while (ops.hasNext()) {
-				Map.Entry<String, JsonNode> entry = ops.next();
+			for (Map.Entry<String, JsonNode> entry : fieldsOf(root.path("operations"))) {
 				String operationId = entry.getKey();
 				JsonNode op = entry.getValue();
 				String body = op.path("body").asText("unknown");
@@ -99,9 +96,7 @@ public class ObserveSchemaLoader {
 		List<String> required = parseStringList(node.path("required"));
 		List<String> unsupported = new ArrayList<>(parseStringList(node.path("unsupported")));
 		Map<String, ObservedProperty> properties = new HashMap<>();
-		Iterator<Map.Entry<String, JsonNode>> props = node.path("properties").fields();
-		while (props.hasNext()) {
-			Map.Entry<String, JsonNode> entry = props.next();
+		for (Map.Entry<String, JsonNode> entry : fieldsOf(node.path("properties"))) {
 			JsonNode propSchema = entry.getValue();
 			String type = propSchema.path("type").asText(null);
 			String patternText = propSchema.has("pattern") ? propSchema.get("pattern").asText() : null;
@@ -119,6 +114,17 @@ public class ObserveSchemaLoader {
 		return new ObservedObject(required, properties, unsupported);
 	}
 
+	// D-runtime-conformance-receipts (Jackson 2/3 JsonNode field-iteration parity): Jackson 2's
+	// JsonNode#fields() (an Iterator) does not exist on Jackson 3's JsonNode at all -- Jackson 3
+	// replaced it with #properties() (a Set, no Iterator wrapper needed). Neither API exists on
+	// EVERY version of the other major (older Jackson 2.x, e.g. 2.14, has no #properties() either),
+	// so this can't be unified into one call safely -- {{JACKSON_PACKAGE}} already tells us which
+	// major is on this target's real classpath (detectJacksonPackage() in emit.mjs), so that same
+	// signal picks the one real, correct implementation body at emit time.
+	private static Iterable<Map.Entry<String, JsonNode>> fieldsOf(JsonNode node) {
+		{{JACKSON_FIELDS_OF_IMPL}}
+	}
+
 	private static List<String> parseStringList(JsonNode node) {
 		List<String> values = new ArrayList<>();
 		if (node != null && node.isArray()) {

package/handles/providers/java-spring/templates/ReceiptSigner.java.tmpl

@@ -0,0 +1,174 @@
+package {{BASE_PACKAGE}}.global.observe;
+
+import {{JACKSON_PACKAGE}}.JsonNode;
+import {{JACKSON_PACKAGE}}.node.ObjectNode;
+
+import java.nio.charset.StandardCharsets;
+import java.security.KeyFactory;
+import java.security.PrivateKey;
+import java.security.Signature;
+import java.security.spec.PKCS8EncodedKeySpec;
+import java.util.ArrayList;
+import java.util.Base64;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * D-runtime-conformance-receipts (cryptographic receipt attestation): signs a receipt at emission
+ * time so {@code bskel observe import --pubkey <path>} can prove it genuinely came from this
+ * running app, not a hand-fabricated file. JDK-stdlib-only ({@link Signature}, Ed25519 -- standard
+ * since JDK 15) -- zero new dependency, matching this project's own JDK 17 floor.
+ *
+ * <p>Canonicalization must be byte-identical to {@code bskel observe import}'s own verification
+ * side (Node's {@code lib/attest.mjs} {@code canonicalize()}: deep-sorted keys, compact JSON,
+ * non-ASCII left unescaped) -- proven cross-language-compatible by direct execution against a real
+ * receipt containing a forward slash, a quote, and non-ASCII text (see DECISIONS.md
+ * D-runtime-conformance-receipts). Jackson's own {@code MapperFeature.SORT_PROPERTIES_ALPHABETICALLY}
+ * does NOT sort an {@link ObjectNode}'s own tree-model field order -- confirmed live, it only
+ * affects bean/POJO introspection -- so this class hand-walks the {@link JsonNode} tree instead of
+ * relying on a mapper feature that would silently no-op.
+ *
+ * <p>The private key is never baked into generated source (that would commit a secret to the
+ * repo) -- see {@link #configure(String)}'s own javadoc for how a human wires this in.
+ */
+public final class ReceiptSigner {
+
+	private static volatile PrivateKey privateKey;
+
+	private ReceiptSigner() {
+	}
+
+	/**
+	 * NOT called by any generated code -- a human calls this once, themselves, at application
+	 * startup (see {@code ContractObservationAspect}'s own {@code @PostConstruct} wiring), passing a
+	 * PKCS#8 PEM private key string -- the exact format {@code bskel attest keygen} already writes.
+	 * Never hardcode a real key value in source; read it from wherever you already keep secrets (an
+	 * env var, a mounted file, a secrets manager). Unconfigured (the default) means every receipt
+	 * stays unsigned -- backward compatible with every already-deployed app using this feature
+	 * before signing existed.
+	 */
+	public static void configure(String privateKeyPem) {
+		privateKey = (privateKeyPem == null || privateKeyPem.isBlank()) ? null : parsePkcs8(privateKeyPem);
+	}
+
+	static boolean isConfigured() {
+		return privateKey != null;
+	}
+
+	/**
+	 * Returns the base64 Ed25519 signature over the canonicalized receipt. Callers must pass a node
+	 * that does not yet carry a {@code "signature"} field (this class never strips one itself --
+	 * {@code ContractObservationAspect} only ever calls this before adding one).
+	 */
+	static String sign(ObjectNode receiptWithoutSignature) {
+		try {
+			Signature signer = Signature.getInstance("Ed25519");
+			signer.initSign(privateKey);
+			signer.update(canonicalize(receiptWithoutSignature).getBytes(StandardCharsets.UTF_8));
+			return Base64.getEncoder().encodeToString(signer.sign());
+		} catch (Exception e) {
+			throw new IllegalStateException("could not sign receipt", e);
+		}
+	}
+
+	private static PrivateKey parsePkcs8(String pem) {
+		try {
+			String base64 = pem
+					.replace("-----BEGIN PRIVATE KEY-----", "")
+					.replace("-----END PRIVATE KEY-----", "")
+					.replaceAll("\\s", "");
+			byte[] der = Base64.getDecoder().decode(base64);
+			KeyFactory keyFactory = KeyFactory.getInstance("Ed25519");
+			return keyFactory.generatePrivate(new PKCS8EncodedKeySpec(der));
+		} catch (Exception e) {
+			throw new IllegalArgumentException("not a usable PKCS#8 Ed25519 private key PEM", e);
+		}
+	}
+
+	// Recursively sorts every object's field names, preserves array order (matching lib/gates.mjs's
+	// own sortKeysDeep() semantics exactly on the Node verification side), emits compact JSON by
+	// hand. The schema this signs has exactly one numeric field (a plain integer HTTP status) and
+	// nothing else numeric anywhere -- no float-formatting cross-language risk exists here.
+	static String canonicalize(JsonNode node) {
+		StringBuilder sb = new StringBuilder();
+		canonicalizeInto(node, sb);
+		return sb.toString();
+	}
+
+	private static void canonicalizeInto(JsonNode node, StringBuilder sb) {
+		if (node == null || node.isNull()) {
+			sb.append("null");
+		} else if (node.isObject()) {
+			List<String> names = new ArrayList<>();
+			for (Map.Entry<String, JsonNode> entry : fieldsOf(node)) {
+				names.add(entry.getKey());
+			}
+			Collections.sort(names);
+			sb.append('{');
+			for (int i = 0; i < names.size(); i++) {
+				if (i > 0) sb.append(',');
+				sb.append(jsonString(names.get(i))).append(':');
+				canonicalizeInto(node.get(names.get(i)), sb);
+			}
+			sb.append('}');
+		} else if (node.isArray()) {
+			sb.append('[');
+			for (int i = 0; i < node.size(); i++) {
+				if (i > 0) sb.append(',');
+				canonicalizeInto(node.get(i), sb);
+			}
+			sb.append(']');
+		} else if (node.isTextual()) {
+			sb.append(jsonString(node.asText()));
+		} else if (node.isBoolean()) {
+			sb.append(node.asBoolean());
+		} else if (node.isNumber()) {
+			sb.append(node.numberValue());
+		} else {
+			sb.append(jsonString(node.asText()));
+		}
+	}
+
+	// D-runtime-conformance-receipts (Jackson 2/3 JsonNode field-iteration parity): Jackson 2's
+	// JsonNode#fields() (an Iterator) does not exist on Jackson 3's JsonNode at all -- Jackson 3
+	// replaced it with #properties() (a Set, no Iterator wrapper needed). Neither API exists on
+	// EVERY version of the other major (older Jackson 2.x, e.g. 2.14, has no #properties() either),
+	// so this can't be unified into one call safely -- {{JACKSON_PACKAGE}} already tells us which
+	// major is on this target's real classpath (detectJacksonPackage() in emit.mjs), so that same
+	// signal picks the one real, correct implementation body at emit time. Mirrors
+	// ObserveSchemaLoader's own identically-named, identically-reasoned helper exactly.
+	private static Iterable<Map.Entry<String, JsonNode>> fieldsOf(JsonNode node) {
+		{{JACKSON_FIELDS_OF_IMPL}}
+	}
+
+	// Standard JSON string escaping (RFC 8259) -- the same set Node's JSON.stringify and Python's
+	// json.dumps(ensure_ascii=False) both already apply, proven byte-identical live. Non-ASCII is
+	// deliberately left UNESCAPED to match (ensure_ascii=False on the Python side is the analogous,
+	// load-bearing requirement there -- Python's own json.dumps default would otherwise diverge).
+	private static String jsonString(String s) {
+		StringBuilder sb = new StringBuilder(s.length() + 2);
+		sb.append('"');
+		for (int i = 0; i < s.length(); i++) {
+			char c = s.charAt(i);
+			switch (c) {
+				case '"' -> sb.append("\\\"");
+				case '\\' -> sb.append("\\\\");
+				case '\b' -> sb.append("\\b");
+				case '\f' -> sb.append("\\f");
+				case '\n' -> sb.append("\\n");
+				case '\r' -> sb.append("\\r");
+				case '\t' -> sb.append("\\t");
+				default -> {
+					if (c < 0x20) {
+						sb.append(String.format("\\u%04x", (int) c));
+					} else {
+						sb.append(c);
+					}
+				}
+			}
+		}
+		sb.append('"');
+		return sb.toString();
+	}
+}

package/handles/providers/python-fastapi/observe.mjs

@@ -26,6 +26,10 @@ const INFRA_FILES = [
 	{ template: 'observed_schema.py.tmpl', target: 'observed_schema.py' },
 	{ template: 'contract_check.py.tmpl', target: 'contract_check.py' },
 	{ template: 'observe_contract.py.tmpl', target: 'observe_contract.py' },
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): Ed25519 signer used by
+	// observe_contract.py -- imports the `cryptography` package lazily, only if actually configured
+	// with a real key (see receipt_sign.py's own docstring for why).
+	{ template: 'receipt_sign.py.tmpl', target: 'receipt_sign.py' },
 ];
 
 function render(templatePath, vars) {
@@ -92,6 +96,7 @@ export function emitObservePythonFastApi({ repoRoot, featureId, contract, plan,
 			'NOT done automatically: route the "bskel.observe.receipts" logger (Python\'s standard logging module) to wherever you want receipt lines collected (a dedicated handler to a file, your existing log pipeline, etc.) -- bskel never edits your logging config. Point `bskel observe import --receipts <path>` at whatever that logger\'s output ends up as.',
 			`Contract-conformance checking only covers path params always, plus a bounded slice of request/response/error body shape -- and only when this contract was emitted with --openapi-file. See the emitted ${path.relative(repoRoot, schemaPath)}'s own "unsupported" markers for exactly what is skipped for this feature.`,
 			'NOT done automatically: apply @observe_contract(operation_id="...") to whichever existing route handlers you want observed -- nothing is decorated for you (D-resolver-scope: never guess which function implements which operation). For a request body to be checked, also pass body_param="<the argument name>" explicitly -- Python has no @RequestBody-equivalent marker to infer it from.',
+			'NOT done automatically: to sign receipts, call receipt_sign.configure(os.environ.get("BSKEL_OBSERVE_SIGNING_KEY_PEM")) yourself at application startup, with a PKCS#8 Ed25519 private key PEM -- `bskel attest keygen --out <dir>` already generates one in this exact format. This also requires `pip install cryptography` (Python\'s stdlib has no Ed25519 signing -- receipt_sign.py imports it lazily, only when configure() is actually called with a real key). Unconfigured means every receipt stays unsigned (backward compatible). Verify with `bskel observe import --pubkey <path/to/attest-public.pem>`.',
 		],
 	};
 }

package/handles/providers/python-fastapi/templates/observe_contract.py.tmpl

@@ -32,6 +32,10 @@ return value transparently, unmodified, even without inspecting it) -- FastAPI r
 commonly `async def`, so getting this wrong breaks production traffic, not just the conformance
 check.
 
+Optionally signs each receipt (Ed25519, via receipt_sign.py) once `receipt_sign.configure(...)`
+has been called with a real key -- see that module's own docstring. Unconfigured means every
+receipt stays unsigned, exactly like before this capability existed.
+
 Example:
     @observe_contract(operation_id="items-read_item")
     async def read_item(session: SessionDep, id: str):
@@ -48,6 +52,7 @@ from starlette.exceptions import HTTPException as StarletteHTTPException
 
 from . import contract_check
 from . import observed_schema
+from . import receipt_sign
 
 logger = logging.getLogger(__name__)
 _RECEIPTS = logging.getLogger("bskel.observe.receipts")
@@ -102,11 +107,25 @@ def _emit_receipt(op: dict, operation_id: str, request_violations: list, respons
             receipt["status"] = status
         if error_class is not None:
             receipt["error_class"] = error_class
+        _sign_receipt(receipt)
         _RECEIPTS.info(json.dumps(receipt))
     except Exception:
         logger.warning("observe_contract: could not emit a receipt -- the wrapped call already returned unaffected", exc_info=True)
 
 
+def _sign_receipt(receipt: dict) -> None:
+    # D-runtime-conformance-receipts (cryptographic receipt attestation): its OWN inner try/except,
+    # separate from _emit_receipt()'s outer one -- a signing failure (bad/missing key config,
+    # malformed PEM) must fall back to logging the receipt UNSIGNED, not silently drop the whole
+    # receipt the way sharing the outer except block would.
+    if not receipt_sign.is_configured():
+        return
+    try:
+        receipt["signature"] = {"algorithm": "ed25519", "value": receipt_sign.sign(receipt)}
+    except Exception:
+        logger.warning("observe_contract: could not sign a receipt -- logging it unsigned instead", exc_info=True)
+
+
 def observe_contract(*, operation_id: str, body_param: str | None = None):
     def decorator(fn):
         signature = inspect.signature(fn)

package/handles/providers/python-fastapi/templates/receipt_sign.py.tmpl

@@ -0,0 +1,68 @@
+"""Generated by backend-skeleton (bskel observe emit). Do not hand-edit -- change the source
+template and regenerate.
+
+D-runtime-conformance-receipts (cryptographic receipt attestation): signs a receipt at emission
+time so `bskel observe import --pubkey <path>` can prove it genuinely came from this running app,
+not a hand-fabricated file. Uses the `cryptography` package's Ed25519 primitives -- Python's
+stdlib has no Ed25519 signing at all, so this is a genuinely new, first-of-its-kind third-party
+dependency for this provider's generated runtime code (same honest framing this project already
+gave `pg`, its own first-ever database dependency -- see DECISIONS.md
+D-runtime-conformance-receipts). The import is deliberately LAZY (inside configure(), not at
+module level) so this module -- and observe_contract.py, which imports it unconditionally --
+stays importable even when `cryptography` is not installed, as long as signing is never
+configured. Only pip-install `cryptography` if you actually call configure() with a real key.
+
+Canonicalization must be byte-identical to `bskel observe import`'s own verification side (Node's
+`lib/attest.mjs` canonicalize(): deep-sorted keys, compact JSON, non-ASCII left unescaped) --
+`json.dumps(receipt, sort_keys=True, separators=(",", ":"), ensure_ascii=False)` is exactly that,
+proven cross-language-compatible by direct execution against a real receipt containing a forward
+slash, a quote, and non-ASCII text (see DECISIONS.md D-runtime-conformance-receipts).
+`ensure_ascii=False` is load-bearing -- Python's own json.dumps default (True) escapes non-ASCII
+as `\\uXXXX`, which neither Node's JSON.stringify nor Jackson's default writer do; without this
+flag, signatures would never cross-verify on any receipt whose message contains non-ASCII text.
+
+The private key is never baked into generated source (that would commit a secret to the repo) --
+see configure()'s own docstring for how a human wires this in.
+"""
+import base64
+import json
+
+_private_key = None
+
+
+def configure(private_key_pem):
+    """NOT called by any generated code -- a human calls this once, themselves, at application
+    startup (e.g. `receipt_sign.configure(os.environ.get("BSKEL_OBSERVE_SIGNING_KEY_PEM"))`),
+    passing a PKCS#8 PEM private key string -- the exact format `bskel attest keygen` already
+    writes. Never hardcode a real key value in source; read it from wherever you already keep
+    secrets (an env var, a mounted file, a secrets manager). Unconfigured (the default, including
+    a None/blank string) means every receipt stays unsigned -- backward compatible with every
+    already-deployed app using this feature before signing existed.
+    """
+    global _private_key
+    if not private_key_pem or not private_key_pem.strip():
+        _private_key = None
+        return
+    from cryptography.hazmat.primitives import serialization
+
+    _private_key = serialization.load_pem_private_key(private_key_pem.encode("utf-8"), password=None)
+
+
+def is_configured():
+    return _private_key is not None
+
+
+def canonicalize(receipt_without_signature):
+    # The schema this signs has exactly one numeric field (a plain integer HTTP status) and
+    # nothing else numeric anywhere -- no float-formatting cross-language risk exists here.
+    return json.dumps(
+        receipt_without_signature, sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+
+
+def sign(receipt_without_signature):
+    """Returns the base64 Ed25519 signature over the canonicalized receipt. Callers must pass a
+    dict that does not yet carry a "signature" key -- this module never strips one itself.
+    """
+    signature_bytes = _private_key.sign(canonicalize(receipt_without_signature))
+    return base64.b64encode(signature_bytes).decode("ascii")

package/handles/providers/typescript-express/observe.mjs

@@ -28,6 +28,10 @@ const INFRA_FILES = [
 	{ template: 'contractCheck.ts.tmpl', target: 'contractCheck.ts' },
 	{ template: 'observedSchema.ts.tmpl', target: 'observedSchema.ts' },
 	{ template: 'observeContract.ts.tmpl', target: 'observeContract.ts' },
+	// D-runtime-conformance-receipts (cryptographic receipt attestation): node:crypto-only Ed25519
+	// signer used by observeContract.ts -- a self-contained port of lib/attest.mjs, never imported
+	// directly (this runs inside a deployed target app, a foreign process from this CLI's own).
+	{ template: 'receiptSign.ts.tmpl', target: 'receiptSign.ts' },
 ];
 
 function render(templatePath, vars) {
@@ -97,6 +101,7 @@ export function emitObserveTypeScriptExpress({ repoRoot, featureId, contract, pl
 			'error_class is never populated in this provider\'s receipts (always omitted) -- Express middleware runs BEFORE the route handler and is structurally unable to observe a thrown error the way java\'s @Around/python\'s except block can (by the time a handler throws or calls next(err), this middleware\'s own call frame has already returned). See DECISIONS.md D-runtime-conformance-receipts.',
 			'Response-body checking only covers a handler that calls res.json(...) or res.send(<object>) (Express\'s own res.send delegates to res.json for a plain-object body) -- a handler that calls res.send(<string>)/res.end(...) directly, or whose response is produced by Express\'s own default/generic error handler, has its response check silently skipped, never guessed.',
 			'OpenAPI reconciliation for this adapter matches scanned Express route strings EXACTLY against the OpenAPI document\'s own path keys (contracts/openapi.mjs has no ":id" <-> "{id}" translation) -- a real, standards-compliant OpenAPI document (which must use "{id}") will not match a scanned ":id"/":id([0-9]+)" route unless the document\'s own path key happens to already read that way. Unlike python-fastapi, this is not "for free."',
+			'NOT done automatically: to sign receipts, call setSigningKey(pem) yourself at application startup (import { setSigningKey } from \'./observe/receiptSign\';), with a PKCS#8 Ed25519 private key PEM -- `bskel attest keygen --out <dir>` already generates one in this exact format. Unconfigured means every receipt stays unsigned (backward compatible). Verify with `bskel observe import --pubkey <path/to/attest-public.pem>`.',
 		],
 	};
 }

package/handles/providers/typescript-express/templates/observeContract.ts.tmpl

@@ -34,12 +34,17 @@
 // (req.body is Express's own unambiguous body once body-parsing middleware has run -- no
 // python-style explicit body_param argument needed here).
 //
+// Optionally signs each receipt (Ed25519, via receiptSign.ts) once setSigningKey() has been
+// called with a real key -- see that module's own doc comment. Unconfigured means every
+// receipt stays unsigned, exactly like before this capability existed.
+//
 // Example:
 //   router.get('/users/:id', [checkJwt, observeContract('users-show')], showUser);
 
 import type { RequestHandler, Request, Response } from 'express';
 import * as contractCheck from './contractCheck';
 import * as observedSchema from './observedSchema';
+import * as receiptSign from './receiptSign';
 import type { ObservedOperation } from './observedSchema';
 import type { Violation } from './contractCheck';
 
@@ -90,12 +95,26 @@ function emitReceipt(op: ObservedOperation, operationId: string, requestViolatio
 			recorded_at: new Date().toISOString(),
 			violations: allViolations,
 		};
+		signReceipt(receipt);
 		receiptSink(JSON.stringify(receipt));
 	} catch (err) {
 		console.warn(`observeContract: could not emit a receipt for "${operationId}"`, err);
 	}
 }
 
+// D-runtime-conformance-receipts (cryptographic receipt attestation): its OWN inner try/catch,
+// separate from emitReceipt()'s outer one -- a signing failure (bad/missing key config, malformed
+// PEM) must fall back to sending the receipt UNSIGNED, not silently drop the whole receipt the way
+// sharing the outer catch would.
+function signReceipt(receipt: Record<string, unknown>): void {
+	if (!receiptSign.isConfigured()) return;
+	try {
+		receipt.signature = { algorithm: 'ed25519', value: receiptSign.sign(receipt) };
+	} catch (err) {
+		console.warn('observeContract: could not sign a receipt -- sending it unsigned instead', err);
+	}
+}
+
 export function observeContract(operationId: string): RequestHandler {
 	return (req: Request, res: Response, next) => {
 		let op: ObservedOperation | undefined;