backend-skeleton 1.0.0-beta.2 → 1.0.0-beta.4

package/handles/audit.mjs

@@ -0,0 +1,83 @@
+// O7/B2 (D-handle-audit-report): live query over `sbf_handle`/`sbf_handle_snapshot` -- the tables
+// O4's `HandleService.recordSnapshot`/`@RecordHandleSnapshot` (java-spring, python-fastapi) already
+// write to, when a target app opts into recording. Both providers' migration.sql.tmpl/tables.py.tmpl
+// generate the SAME table names and columns (confirmed by reading both templates directly, not
+// assumed) -- one query works regardless of which provider backed a given feature.
+// Reuses A4/D-db-schema-plane's own `pg`/connection conventions unchanged: `Client`, one connection,
+// sequential queries, `BEGIN TRANSACTION READ ONLY` as structural defense-in-depth (this is a
+// read-only report; the transaction means the DB itself refuses any write attempt, not just "we
+// didn't write any queries that would").
+import pg from 'pg';
+
+const { Client } = pg;
+
+const HANDLES_SQL_BASE = `
+	SELECT
+		h.handle_uid, h.kind, h.resource_type, h.resource_uid, h.pointer,
+		h.operation_id, h.contract_ref, h.created_at, h.revoked_at, h.revoked_reason,
+		count(s.snapshot_id)::int AS snapshot_count,
+		max(s.recorded_at) AS last_recorded_at
+	FROM sbf_handle h
+	LEFT JOIN sbf_handle_snapshot s ON s.handle_uid = h.handle_uid
+	WHERE h.feature_uid = $1`;
+
+// `= ANY($2)` -- an array bind, not string-interpolated -- for the multi-value --resource filter,
+// matching `handles plan`/`handles emit`'s own `--resource type1,type2` convention exactly (see
+// bin/bskel.mjs's existing `flags.resource.split(',')...` idiom) rather than inventing a
+// singular `--resource-type` flag.
+const RESOURCE_FILTER_SQL = ' AND h.resource_type = ANY($2)';
+const GROUP_ORDER_SQL = ' GROUP BY h.handle_uid ORDER BY h.created_at DESC';
+
+// Postgres error code for "relation does not exist" -- the real, expected shape when a target
+// app's migration.sql was never applied (D-migration-scope: bskel never applies it automatically).
+const UNDEFINED_TABLE = '42P01';
+
+export function isMissingHandleTables(err) {
+	return err?.code === UNDEFINED_TABLE;
+}
+
+// `GROUP BY h.handle_uid` then selecting other `h.*` columns is valid Postgres (functional
+// dependency on the grouped table's own primary key) -- verified live against a real Postgres
+// (see D-handle-audit-report's verification note), not assumed from the SQL standard alone, since
+// this specific form is a Postgres extension MySQL/older engines don't share.
+export async function auditHandles({ connectionString, featureUid, resourceTypes }) {
+	const client = new Client({ connectionString });
+	await client.connect();
+	try {
+		await client.query('BEGIN TRANSACTION READ ONLY');
+		const params = [featureUid];
+		let sql = HANDLES_SQL_BASE;
+		if (resourceTypes && resourceTypes.length > 0) {
+			params.push(resourceTypes);
+			sql += RESOURCE_FILTER_SQL;
+		}
+		sql += GROUP_ORDER_SQL;
+		const res = await client.query(sql, params);
+		await client.query('COMMIT');
+		return res.rows.map((row) => ({
+			handle_uid: row.handle_uid,
+			kind: row.kind,
+			resource_type: row.resource_type,
+			resource_uid: row.resource_uid,
+			pointer: row.pointer,
+			operation_id: row.operation_id,
+			contract_ref: row.contract_ref,
+			created_at: row.created_at,
+			revoked_at: row.revoked_at,
+			revoked_reason: row.revoked_reason,
+			snapshot_count: row.snapshot_count,
+			last_recorded_at: row.last_recorded_at,
+		}));
+	} finally {
+		await client.end();
+	}
+}
+
+export function summarizeAudit(rows) {
+	return {
+		total_handles: rows.length,
+		revoked_handles: rows.filter((r) => r.revoked_at !== null).length,
+		never_snapshotted: rows.filter((r) => r.snapshot_count === 0).length,
+		total_snapshots: rows.reduce((sum, r) => sum + r.snapshot_count, 0),
+	};
+}

package/handles/codec.mjs

@@ -90,12 +90,18 @@ export function uuidv5(namespaceUuid, name) {
 }
 
 // The plain-UUID identity of a handle (for use as a DB primary key / foreign key), derivable
-// offline without a DB round-trip: kind=r handles ARE the resource's own uuid (no derivation
-// needed -- a resource handle and the entity's own PK are the same identity); kind=f handles
-// derive a UUIDv5 from type+uuid+pointer, so the same field always gets the same handle_uid
-// without ever needing to look it up first.
+// offline without a DB round-trip. O3 (D-handle-uid-type-binding): ALL three kinds now hash a
+// `type:uuid[:...]` discriminant through UUIDv5 -- kind=r used to return `uuid` verbatim (no type
+// binding at all), so two different resource TYPES sharing the same resourceUid derived the SAME
+// handle_uid and collided on the same `sbf_handle` primary key (silently blending their
+// featureUid/operationId/contractRef, and letting HandleService.revoke() on one type's handle
+// also revoke the other's -- the literal same row). Provably collision-free across kinds without
+// a token-format change: kind=f's discriminant always has a pointer segment starting with "/"
+// (RFC 6901), kind=o's always ends in the literal ":o" with no leading slash, and kind=r's never
+// has a third segment at all -- no two different (kind, type, uuid, pointer) tuples can ever
+// produce the same discriminant string.
 export function deriveHandleUid({ kind, type, uuid, pointer }) {
-	if (kind === 'r') return uuid;
+	if (kind === 'r') return uuidv5(NS_SBF_FIELD, `${type}:${uuid}`);
 	if (kind === 'f') {
 		if (!pointer) throw new Error('field handles require a pointer to derive handle_uid');
 		return uuidv5(NS_SBF_FIELD, `${type}:${uuid}:${pointer}`);

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

@@ -106,7 +106,7 @@ function writeUnit(target, content) {
 // featureId/module/resourceFilter) -- never a blanket, unscoped force. `resourceFilter` (the same
 // array plan() was called with, or null) turns off orphan detection when non-null, since a scoped
 // run would otherwise report every OTHER resource's resolver as orphaned.
-export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false }) {
+export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false, enforceRegistry = false }) {
 	const javaSrcRoot = path.join(repoRoot, 'src', 'main', 'java', ...basePackage.split('.'));
 
 	// A3 (D-patch-strategy): loaded/detected once per emit call -- approvals are feature-scoped
@@ -120,7 +120,11 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 		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 }),
+		// O3 (D-handle-registry-enforcement): ENFORCE_REGISTRY only appears in
+		// HandleController.java.tmpl -- applied to every infra file uniformly anyway, matching
+		// how BASE_PACKAGE/JACKSON_PACKAGE already do (render()'s replaceAll is a harmless no-op
+		// for a token absent from a given template, e.g. JACKSON_PACKAGE inside HandleCodec.java.tmpl).
+		rendered: render(path.join(TEMPLATES_DIR, f.template), { BASE_PACKAGE: basePackage, JACKSON_PACKAGE: jacksonPackage, ENFORCE_REGISTRY: String(enforceRegistry) }),
 	}));
 
 	// O4 (D-handle-lifecycle): every resource in THIS feature shares the same contract file and
@@ -160,6 +164,9 @@ export function emitJavaSpring({ repoRoot, featureId, plan, basePackage, resourc
 				SERVICE_FIELD: serviceField,
 				FETCH_METHOD: resource.fetchOperation.method,
 				REQUIRED_AUTHORITY: resource.requiredAuthority,
+				// O5 (D-resolver-authorization-action-aware): independently derived from the UPDATE
+				// endpoint's own @PreAuthorize -- see plan.mjs's own computation.
+				REQUIRED_AUTHORITY_PATCH: resource.requiredAuthorityForPatch,
 				FEATURE_ID: featureId,
 				CONTRACT_REF: contractRef,
 				FEATURE_UID: featureUid,

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

@@ -239,6 +239,17 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 		const service = findServiceFile(javaSrcRoot, targetModule.module, entity.className);
 		const serviceParamCount = (service && fetchOp) ? countServiceMethodParams(service.file, fetchOp.method) : null;
 
+		// O5 (D-resolver-authorization-action-aware): the SAME extraction, run again against the
+		// UPDATE (PATCH/PUT) endpoint instead of the fetch (GET) one -- previously nothing ever
+		// looked at the update endpoint's own @PreAuthorize at all, so patch() silently reused
+		// whichever role fetch() happened to require. Computed independently of planPatchable()'s
+		// own (conditional, gated on serviceParamCount===1) call to findUpdateOperation() below --
+		// requiredAuthorityForPatch is meaningful even when resolver codegen itself ends up
+		// blocked, exactly like requiredAuthority already is unconditional above.
+		const updateOpForAuthority = findUpdateOperation(targetModule.controllers, entity.className);
+		const patchAuthorityResult = findRequiredAuthority(updateOpForAuthority?.controllerFile ?? null, updateOpForAuthority?.method ?? null);
+		const requiredAuthorityForPatch = patchAuthorityResult.authority;
+
 		if (!fetchOp) {
 			notes.push(`${entity.className}: no single-resource GET endpoint found on a controller whose name contains "${entity.className}" -- fetch() will need to be hand-written`);
 		} else if (authorityResult.unsupported) {
@@ -246,6 +257,11 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 		} else if (!requiredAuthority) {
 			notes.push(`${entity.className}: no method-level or class-level @PreAuthorize(hasRole(...)) found for ${fetchOp.controllerClassName}.${fetchOp.method} -- requiredAuthority() defaults to "TODO_ROLE", fix before relying on it`);
 		}
+		if (updateOpForAuthority && patchAuthorityResult.unsupported) {
+			notes.push(`${entity.className}: @PreAuthorize found on ${updateOpForAuthority.controllerClassName}.${updateOpForAuthority.method} (or its class) but not in the simple hasRole('X') shape this scanner understands -- requiredAuthorityForPatch() defaults to "TODO_ROLE" (fails closed) until a human fixes it`);
+		} else if (updateOpForAuthority && !requiredAuthorityForPatch) {
+			notes.push(`${entity.className}: no method-level or class-level @PreAuthorize(hasRole(...)) found for ${updateOpForAuthority.controllerClassName}.${updateOpForAuthority.method} -- requiredAuthorityForPatch() defaults to "TODO_ROLE", fix before relying on it`);
+		}
 		if (!service) {
 			notes.push(`${entity.className}: no ${entity.className}Service found under domain/${targetModule.module}/application/ -- resolver NOT generated for this entity (would produce a broken import). Emit it by hand once the right service is identified.`);
 		} else if (fetchOp && serviceParamCount !== 1) {
@@ -299,6 +315,10 @@ export function planHandles({ javaSrcRoot, scanReport, module: moduleName, resou
 			updateDtoFile: patchResult.updateDtoFile ?? null,
 			updateServiceBlockedReason: patchResult.updateServiceBlockedReason,
 			requiredAuthority: requiredAuthority ?? 'TODO_ROLE',
+			// O5 (D-resolver-authorization-action-aware): independently derived from the UPDATE
+			// endpoint's own @PreAuthorize, not copied from requiredAuthority above -- see the
+			// computation and its own notes earlier in this loop.
+			requiredAuthorityForPatch: requiredAuthorityForPatch ?? 'TODO_ROLE',
 			service,
 			willGenerateResolver: Boolean(fetchOp && service && serviceParamCount === 1),
 		});

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

@@ -89,14 +89,22 @@ public final class HandleCodec {
 	}
 
 	/**
-	 * The plain-UUID identity of a handle, for use as a DB primary/foreign key. {@code kind=r}
-	 * handles ARE the resource's own uuid; {@code kind=f} handles derive a UUIDv5 from
-	 * type+uuid+pointer, so the same field always derives the same handle_uid without a DB
-	 * round-trip.
+	 * The plain-UUID identity of a handle, for use as a DB primary/foreign key. O3
+	 * ({@code D-handle-uid-type-binding}): ALL three kinds hash a {@code type:uuid[:...]}
+	 * discriminant through UUIDv5 -- {@code kind=r} used to return {@code uuid} verbatim (no type
+	 * binding at all), so two different resource TYPES sharing the same {@code resourceUid}
+	 * derived the SAME {@code handle_uid} and collided on the same {@code sbf_handle} primary key
+	 * (silently blending their featureUid/operationId/contractRef, and letting
+	 * {@link HandleService#revoke} on one type's handle also revoke the other's -- the literal
+	 * same row). Provably collision-free across kinds without a token-format change: {@code
+	 * kind=f}'s discriminant always has a pointer segment starting with "/" (RFC 6901), {@code
+	 * kind=o}'s always ends in the literal ":o" with no leading slash, and {@code kind=r}'s never
+	 * has a third segment at all -- no two different (kind, type, uuid, pointer) tuples can ever
+	 * produce the same discriminant string.
 	 */
 	public static UUID deriveHandleUid(String kind, String type, UUID uuid, String pointer) {
 		return switch (kind) {
-			case "r" -> uuid;
+			case "r" -> uuidv5(NS_SBF_FIELD, type + ":" + uuid);
 			case "f" -> {
 				if (pointer == null || pointer.isEmpty()) {
 					throw new IllegalArgumentException("field handles require a pointer to derive handle_uid");

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

@@ -19,7 +19,6 @@ import org.springframework.web.server.ResponseStatusException;
 import java.time.Instant;
 import java.util.List;
 import java.util.Map;
-import java.util.Objects;
 import java.util.Optional;
 import java.util.UUID;
 
@@ -45,11 +44,24 @@ public class HandleController {
 	private final HandleSnapshotRepository handleSnapshotRepository;
 	private final ObjectMapper objectMapper;
 
+	// O3 (D-handle-registry-enforcement, part 2 of 2): opt-in, defaults false -- baked in at
+	// `bskel handles emit --enforce-registry on` time, matching every other per-target-repo
+	// codegen constant this project bakes in (e.g. ResourceResolver#contractRef()/featureUid()).
+	// `HandleService.register()` is only ever called by generated code from HandleAspect (an app
+	// that opted into @RecordHandleSnapshot) or a target app's own hand-written calls -- an app
+	// that mints handles through neither path gets fully working fetch()/patch() with zero
+	// registry involvement today; flipping this on unconditionally would 404 every one of their
+	// existing handles. Stays a deliberate, informed choice a target app's own maintainer makes.
+	private static final boolean ENFORCE_REGISTRY = {{ENFORCE_REGISTRY}};
+
 	@GetMapping("/{handle}")
 	public ResponseEntity<Object> fetch(@PathVariable String handle) {
 		HandleCodec.Decoded decoded = decodeOrThrow(handle);
 		ResourceResolver resolver = resolverFor(decoded.type());
 		requireAuthority(resolver.requiredAuthority());
+		if (ENFORCE_REGISTRY) {
+			requireRegisteredOrThrow(decoded);
+		}
 
 		Object resource = resolver.fetch(decoded.uuid());
 		if (decoded.pointer() == null) {
@@ -83,7 +95,13 @@ public class HandleController {
 			throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "cannot PATCH a resource-level handle (kind=r) -- only field handles (kind=f) support PATCH");
 		}
 		ResourceResolver resolver = resolverFor(decoded.type());
-		requireAuthority(resolver.requiredAuthority());
+		// O5 (D-resolver-authorization-action-aware): the PATCH-specific authority, independently
+		// derived from the entity's own UPDATE endpoint -- NOT resolver.requiredAuthority(), which
+		// is fetch()/recover()'s own value and may legitimately require a different role.
+		requireAuthority(resolver.requiredAuthorityForPatch());
+		if (ENFORCE_REGISTRY) {
+			requireRegisteredOrThrow(decoded);
+		}
 
 		resolver.patchField(decoded.uuid(), decoded.pointer(), value);
 		return ResponseEntity.noContent().build();
@@ -95,24 +113,12 @@ public class HandleController {
 		ResourceResolver resolver = resolverFor(decoded.type());
 		requireAuthority(resolver.requiredAuthority());
 
-		UUID handleUid = HandleCodec.deriveHandleUid(decoded.kind(), decoded.type(), decoded.uuid(), decoded.pointer());
-
-		// D-security-9: handleUid alone does not prove WHAT is being recovered -- kind=r's
-		// derivation returns the resource UUID verbatim (no type binding baked into the hash), so
-		// an attacker who controls `type` in the handle token (as long as it names a real,
-		// registered resolver whose requiredAuthority() they can pass) can request the snapshot
-		// history of a DIFFERENT, more sensitive resource type that happens to share the same
-		// UUID. Found by the Codex security review. Fix: cross-check the decoded type/kind/pointer
-		// against the registry row this handleUid was actually registered under, and 404 on ANY
-		// disagreement -- without saying which field mismatched, so the error can't be used to
-		// probe which part was wrong. A revoked handle is rejected the same way; it must not be
-		// recoverable at all.
-		HandleRegistry registry = handleRegistryRepository.findById(handleUid)
-				.filter(r -> r.getResourceType().equals(decoded.type()))
-				.filter(r -> r.getKind().equals(decoded.kind()))
-				.filter(r -> Objects.equals(r.getPointer(), decoded.pointer()))
-				.filter(r -> !r.isRevoked())
-				.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "no snapshot recorded for this handle"));
+		// D-security-9 / O3 (D-handle-registry-enforcement): recover() structurally REQUIRES a
+		// registry row to find a snapshot's own primary key -- there is no "unenforced" mode for
+		// it, unlike fetch()/patch() above. Always calls the same shared cross-check those two now
+		// optionally call, so the two paths can never silently drift apart.
+		HandleRegistry registry = requireRegisteredOrThrow(decoded);
+		UUID handleUid = registry.getHandleUid();
 
 		List<HandleSnapshot> snapshots = handleSnapshotRepository.findByHandleUidOrderByRecordedAtDesc(handleUid);
 		Optional<HandleSnapshot> match = at == null
@@ -166,6 +172,34 @@ public class HandleController {
 				.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "no resolver registered for handle type \"" + type + "\""));
 	}
 
+	// D-security-9 / O3 (D-handle-registry-enforcement): always looks up the PARENT RESOURCE's own
+	// registry row (kind=r, pointer=null) -- deliberately NOT the exact (kind, pointer) of the
+	// requested handle. Found live, not assumed: HandleAspect (the ONLY thing that ever registers
+	// automatically) always calls HandleService.register("r", ..., null, ...) regardless of which
+	// handle actually triggered it -- a kind=f field handle is NEVER auto-registered under its OWN
+	// derived UID, only the whole-resource kind=r one is. Requiring an exact (kind, pointer) match
+	// (this check's original shape) made a fresh app's very FIRST field-level PATCH structurally
+	// impossible under enforcement: the check runs BEFORE resolver.patchField() is ever called, so
+	// the very call that would (via the aspect) register something never gets the chance to. This
+	// is also the semantically correct model, not merely a workaround -- revocation is a
+	// RESOURCE-level concept (HandleService.revoke() takes one handleUid representing the whole
+	// resource), so a field-level handle's access is properly gated by "is the resource itself
+	// registered and non-revoked", the same way `fetch()`'s own kind=f path already fetches the
+	// WHOLE resource and narrows client-side with a pointer, never treating a field as its own
+	// separately-trusted object. `resourceType` is still exactly cross-checked (the real
+	// protection D-security-9 exists for -- an attacker-controlled `type` in the token can't claim
+	// a different, more sensitive resource's registration by UUID coincidence); the `kind`/
+	// `pointer` cross-check served no purpose beyond that once every real registration is
+	// confirmed to be resource-level, so removing it is not a narrowed security posture, just a
+	// closer match to how registration actually works in this system.
+	private HandleRegistry requireRegisteredOrThrow(HandleCodec.Decoded decoded) {
+		UUID resourceHandleUid = HandleCodec.deriveHandleUid("r", decoded.type(), decoded.uuid(), null);
+		return handleRegistryRepository.findById(resourceHandleUid)
+				.filter(r -> r.getResourceType().equals(decoded.type()))
+				.filter(r -> !r.isRevoked())
+				.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND, "no active registration for this handle"));
+	}
+
 	private void requireAuthority(String requiredRole) {
 		boolean granted = SecurityContextHolder.getContext().getAuthentication().getAuthorities().stream()
 				.map(GrantedAuthority::getAuthority)

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

@@ -32,9 +32,25 @@ public interface ResourceResolver {
 	 */
 	void patchField(UUID resourceUid, String pointer, Object value);
 
-	/** Spring Security role name (no "ROLE_" prefix) required to fetch/patch this resource type via a handle. */
+	/**
+	 * Spring Security role name (no "ROLE_" prefix) required to {@code fetch}/{@code recover}
+	 * this resource type via a handle. O5 (D-resolver-authorization-action-aware): derived from
+	 * the entity's FETCH (GET) endpoint's own {@code @PreAuthorize} -- deliberately NOT reused
+	 * for {@link #patchField}, which has its own {@link #requiredAuthorityForPatch()} derived
+	 * from the entity's real UPDATE endpoint instead, since a real app's GET and PATCH endpoints
+	 * can (and often do) require genuinely different roles.
+	 */
 	String requiredAuthority();
 
+	/**
+	 * O5 (D-resolver-authorization-action-aware): the {@code patchField} counterpart to {@link
+	 * #requiredAuthority()} -- derived independently from the entity's UPDATE (PATCH/PUT)
+	 * endpoint's own {@code @PreAuthorize}, not copied from the fetch endpoint's role. Before this
+	 * existed, {@link HandleController#patch} silently reused {@link #requiredAuthority()},
+	 * enforcing the wrong role whenever a real app's GET and PATCH endpoints genuinely differed.
+	 */
+	String requiredAuthorityForPatch();
+
 	/**
 	 * O4 (D-handle-lifecycle): the content hash of the feature contract this resolver was
 	 * generated from -- baked in at {@code bskel handles emit} time (regenerated every run, so a

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

@@ -65,6 +65,11 @@ public class {{RESOURCE_TYPE}}Resolver implements ResourceResolver {
 		return "{{REQUIRED_AUTHORITY}}";
 	}
 
+	@Override
+	public String requiredAuthorityForPatch() {
+		return "{{REQUIRED_AUTHORITY_PATCH}}";
+	}
+
 	@Override
 	public String contractRef() {
 		return CONTRACT_REF;

package/handles/providers/java-spring.mjs

@@ -15,7 +15,7 @@ export const provider = {
 	requiresCapabilities: ['resource.fetch'],
 	outputs: { spec: ['handles/migration.sql'] },
 	plan,
-	emit({ repoRoot, featureId, plan: handlesPlan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false }) {
-		return emitJavaSpring({ repoRoot, featureId, plan: handlesPlan, basePackage: handlesPlan.basePackage, resourceFilter, force, reason, dryRun, computeDiff });
+	emit({ repoRoot, featureId, plan: handlesPlan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false, enforceRegistry = false }) {
+		return emitJavaSpring({ repoRoot, featureId, plan: handlesPlan, basePackage: handlesPlan.basePackage, resourceFilter, force, reason, dryRun, computeDiff, enforceRegistry });
 	},
 };

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

@@ -43,7 +43,7 @@ function dottedModulePath(file, importRoot) {
 // but the router itself is infra -- generated once, independent of which resolvers exist -- so it
 // needs its own guard for the "found zero resolvers, and specifically because no SessionDep
 // exists" case).
-export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false }) {
+export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter = null, force = false, reason = '', dryRun = false, computeDiff = false, enforceRegistry = false }) {
 	const handlesDir = path.join(plan.importRoot, plan.topPackage, 'handles');
 	const resolversDir = path.join(handlesDir, 'resolvers');
 
@@ -70,6 +70,10 @@ export function emitPythonFastApi({ repoRoot, featureId, plan, resourceFilter =
 				PKG: plan.topPackage,
 				SESSION_DEP_MODULE: dottedModulePath(sessionDep.file, plan.importRoot),
 				SESSION_DEP_NAME: sessionDep.name,
+				// O3 (D-handle-registry-enforcement): a Python boolean LITERAL ("True"/"False",
+				// capitalized) -- render()'s plain String(value) would produce JS-style lowercase
+				// "true"/"false", invalid Python syntax.
+				ENFORCE_REGISTRY: enforceRegistry ? 'True' : 'False',
 			}),
 		});
 	}

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

@@ -76,9 +76,17 @@ def decode_handle(token: str) -> DecodedHandle:
     return DecodedHandle(kind.lower(), type_, resource_uuid.lower(), pointer)
 
 
+# O3 (D-handle-uid-type-binding): ALL three kinds hash a "type:uuid[:...]" discriminant through
+# UUIDv5 -- kind="r" used to return resource_uuid verbatim (no type binding at all), so two
+# different resource TYPES sharing the same resourceUid derived the SAME handle_uid and collided
+# on the same sbf_handle primary key. Provably collision-free across kinds without a token-format
+# change: kind="f"'s discriminant always has a pointer segment starting with "/" (RFC 6901),
+# kind="o"'s always ends in the literal ":o" with no leading slash, and kind="r"'s never has a
+# third segment at all -- no two different (kind, type, uuid, pointer) tuples can ever produce the
+# same discriminant string.
 def derive_handle_uid(kind: str, type_: str, resource_uuid: str, pointer: str | None) -> str:
     if kind == "r":
-        return resource_uuid
+        return str(uuid.uuid5(NS_SBF_FIELD, f"{type_}:{resource_uuid}"))
     if kind == "f":
         if not pointer:
             raise ValueError("field handles require a pointer to derive handle_uid")

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

@@ -20,6 +20,38 @@ from {{SESSION_DEP_MODULE}} import {{SESSION_DEP_NAME}}
 
 router = APIRouter(prefix="/handles", tags=["handles"])
 
+# O3 (D-handle-registry-enforcement, part 2 of 2): opt-in, defaults False -- baked in at
+# `bskel handles emit --enforce-registry on` time, matching every other per-target-repo codegen
+# constant this project bakes in. HandleService.register()'s Python equivalent is only ever
+# called from record_snapshot.py.tmpl's opt-in @record_snapshot decorator or a target app's own
+# hand-written calls -- an app that mints handles through neither path gets fully working
+# fetch_handle/patch_handle with zero registry involvement today; flipping this on
+# unconditionally would 404 every one of their existing handles.
+ENFORCE_REGISTRY = {{ENFORCE_REGISTRY}}
+
+
+# D-security-9 parity / O3 (D-handle-registry-enforcement): always looks up the PARENT RESOURCE's
+# own registry row (kind="r", pointer=None) -- deliberately NOT the exact (kind, pointer) of the
+# requested handle. Found live, not assumed: the record_snapshot decorator (the ONLY thing that
+# ever registers automatically) always calls register("r", ..., None, ...) regardless of which
+# handle actually triggered it -- a kind="f" field handle is NEVER auto-registered under its OWN
+# derived UID, only the whole-resource kind="r" one is. Requiring an exact (kind, pointer) match
+# (this check's original shape) made a fresh app's very FIRST field-level PATCH structurally
+# impossible under enforcement: the check ran BEFORE patch_field() was ever called, so the very
+# call that would (via the decorator) register something never got the chance to. This is also
+# the semantically correct model, not merely a workaround -- revocation is a RESOURCE-level
+# concept, so a field-level handle's access is properly gated by "is the resource itself
+# registered and non-revoked", the same way fetch_handle()'s own kind="f" path already fetches
+# the WHOLE resource and narrows client-side with a pointer. resource_type is still exactly
+# cross-checked (the real protection D-security-9 exists for); the kind/pointer cross-check
+# served no purpose beyond that once every real registration is confirmed to be resource-level.
+def _require_registered_or_404(session, decoded) -> HandleRegistry:
+    resource_handle_uid = uuid.UUID(derive_handle_uid("r", decoded.type, decoded.uuid, None))
+    registry = session.get(HandleRegistry, resource_handle_uid)
+    if registry is None or registry.resource_type != decoded.type or registry.is_revoked:
+        raise HTTPException(status_code=404, detail="no active registration for this handle")
+    return registry
+
 
 @router.get("/{handle}")
 def fetch_handle(handle: str, session: {{SESSION_DEP_NAME}}):
@@ -36,6 +68,8 @@ def fetch_handle(handle: str, session: {{SESSION_DEP_NAME}}):
     if obj is None:
         raise HTTPException(status_code=404, detail="resource not found")
     resolver.check_access(session, obj)
+    if ENFORCE_REGISTRY:
+        _require_registered_or_404(session, decoded)
     public = resolver.to_public(obj)
     if decoded.pointer is None:
         return public
@@ -75,18 +109,16 @@ def patch_handle(handle: str, session: {{SESSION_DEP_NAME}}, value: dict):
     if obj is None:
         raise HTTPException(status_code=404, detail="resource not found")
     resolver.check_access(session, obj)
+    if ENFORCE_REGISTRY:
+        _require_registered_or_404(session, decoded)
     resolver.patch_field(session, obj, decoded.pointer, value)
 
 
-# G4 follow-up (D-handles-providers): mirrors HandleController.recover() including its full
-# D-security-9 cross-check -- never weakened. handle_uid alone does not prove WHAT is being
-# recovered (kind="r"'s derivation returns the resource UUID verbatim, no type binding baked into
-# the hash), so an attacker who controls `type` in the token (as long as it names a real,
-# registered resolver whose check_access() they can pass) could otherwise request the snapshot
-# history of a DIFFERENT, more sensitive resource type sharing the same UUID. Fix: cross-check the
-# decoded type/kind/pointer against the registry row this handle_uid was actually registered
-# under, and 404 on ANY disagreement -- without saying which field mismatched, so the error can't
-# be used to probe which part was wrong. A revoked handle is rejected the same way.
+# G4 follow-up (D-handles-providers) / O3 (D-handle-registry-enforcement): mirrors
+# HandleController.recover() -- structurally REQUIRES a registry row to find a snapshot's own
+# primary key, so there is no "unenforced" mode for it, unlike fetch_handle/patch_handle above.
+# Always calls the same shared _require_registered_or_404() those two now optionally call, so the
+# paths can never silently drift apart.
 #
 # Ecosystem-honest gap, not silently resolved: Java's role check is resource-existence-independent
 # (recovering history of a since-deleted resource is legitimate), so it never calls fetch() at
@@ -109,16 +141,8 @@ def recover_handle(handle: str, session: {{SESSION_DEP_NAME}}, at: datetime | No
     obj = resolver.fetch(session, decoded.uuid)
     resolver.check_access(session, obj)
 
-    handle_uid = uuid.UUID(derive_handle_uid(decoded.kind, decoded.type, decoded.uuid, decoded.pointer))
-    registry = session.get(HandleRegistry, handle_uid)
-    if (
-        registry is None
-        or registry.resource_type != decoded.type
-        or registry.kind != decoded.kind
-        or registry.pointer != decoded.pointer
-        or registry.is_revoked
-    ):
-        raise HTTPException(status_code=404, detail="no snapshot recorded for this handle")
+    registry = _require_registered_or_404(session, decoded)
+    handle_uid = registry.handle_uid
 
     query = select(HandleSnapshot).where(HandleSnapshot.handle_uid == handle_uid)
     if at is not None:

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

@@ -89,8 +89,17 @@ export function uuidv5(namespaceUuid: string, name: string): string {
   return bytesToUuid(bytes);
 }
 
+// O3 (D-handle-uid-type-binding): ALL three kinds hash a "type:uuid[:...]" discriminant through
+// UUIDv5 -- kind='r' used to return uuid verbatim (no type binding at all), so two different
+// resource TYPES sharing the same uuid derived the SAME handle_uid and would collide on the same
+// registry primary key, were this provider to ever gain one (parity fix only -- this provider has
+// no HandleRegistry table today, see D-typescript-express-provider). Provably collision-free
+// across kinds without a token-format change: kind='f''s discriminant always has a pointer
+// segment starting with "/" (RFC 6901), kind='o''s always ends in the literal ":o" with no
+// leading slash, and kind='r''s never has a third segment at all -- no two different (kind, type,
+// uuid, pointer) tuples can ever produce the same discriminant string.
 export function deriveHandleUid(kind: string, type: string, uuid: string, pointer: string | null): string {
-  if (kind === 'r') return uuid;
+  if (kind === 'r') return uuidv5(NS_SBF_FIELD, `${type}:${uuid}`);
   if (kind === 'f') {
     if (!pointer) throw new Error('field handles require a pointer to derive handle_uid');
     return uuidv5(NS_SBF_FIELD, `${type}:${uuid}:${pointer}`);

package/lib/cli.mjs

@@ -82,6 +82,16 @@ export const COMMANDS = {
 		options: { feature: { type: 'string', default: REPO_GATE_ID } },
 		allowPositionals: true,
 	},
+	// D-gate-export: unlike `gate show`, always feature-scoped -- the whole point is one feature's
+	// own evidence trail across all 5 gates, not a single gate/repo-level snapshot.
+	'gate export': {
+		usage: 'bskel gate export --feature <id> [--out <path>] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			out: { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	scan: {
 		usage: 'bskel scan [--feature <id>] [--terms a,b,c] [--json] [--accept-low-confidence] [--db [--database-url-env <NAME>] [--schema public]]',
 		options: {
@@ -152,13 +162,18 @@ export const COMMANDS = {
 		allowPositionals: true,
 	},
 	'contract emit': {
-		usage: 'bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0]',
+		usage: 'bskel contract emit --feature <id> [--module <name>] [--json] [--openapi-file <path>] [--path-prefix /api/v0] [--descriptions]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			module: { type: 'string', default: null },
 			json: { type: 'boolean', default: false },
 			'openapi-file': { type: 'string', default: null },
 			'path-prefix': { type: 'string', default: null },
+			// A10 (D-openapi-description): the one source-backed field that is NOT default-on --
+			// measured real cost (2,442.7 bytes/operation average) is larger than every other field
+			// this whole passthrough effort copies combined, so it stays opt-in rather than joining
+			// A7/A8/A9's default-on behavior.
+			descriptions: { type: 'boolean', default: false },
 		},
 	},
 	// A6 (D-openapi-export): the export direction. `--allow-unprefixed` is deliberately NOT a
@@ -176,14 +191,26 @@ export const COMMANDS = {
 			json: { type: 'boolean', default: false },
 		},
 	},
+	// D-contract-history: read-only, so no --module/--openapi-file/etc -- it only ever reads what
+	// git already recorded for this feature's own contract file.
+	'contract history': {
+		usage: 'bskel contract history --feature <id> [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			json: { type: 'boolean', default: false },
+		},
+	},
 	'contract waive': {
-		usage: 'bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path" | --all) --reason "..."',
+		usage: 'bskel contract waive --feature <id> --code <CODE> (--subject "VERB /path" | --all) --reason "..." [--expires <Nd>]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			code: { type: 'string', default: null, required: true },
 			subject: { type: 'string', default: null },
 			all: { type: 'boolean', default: false },
 			reason: { type: 'string', default: '' },
+			// D-waiver-expiry: no default -- an un-timed waiver never expires, same "opt-in only,
+			// never silently starts a clock" posture --max-age-minutes already takes elsewhere.
+			expires: { type: 'string', default: null },
 			json: { type: 'boolean', default: false },
 		},
 	},
@@ -230,7 +257,7 @@ export const COMMANDS = {
 		},
 	},
 	'handles emit': {
-		usage: 'bskel handles emit --feature <id> [--module <name>] [--resource type1,type2] [--force --reason "..."] [--check] [--diff]',
+		usage: 'bskel handles emit --feature <id> [--module <name>] [--resource type1,type2] [--force --reason "..."] [--check] [--diff] [--enforce-registry on|off [--reason "..."]]',
 		options: {
 			feature: { type: 'string', default: null, required: true },
 			module: { type: 'string', default: null },
@@ -239,6 +266,27 @@ export const COMMANDS = {
 			reason: { type: 'string', default: '' },
 			check: { type: 'boolean', default: false },
 			diff: { type: 'boolean', default: false },
+			// O3 (D-handle-registry-enforcement): repo-wide, singleton state (java-spring/
+			// python-fastapi's shared global/handle infra, not per-feature) -- omitted entirely
+			// (default null) reuses whatever `.sbf/handles-manifest.json` last recorded, so a
+			// re-emit that doesn't mention this flag never silently reverts a previously-enabled
+			// protection. An explicit `on`->`off` transition requires the SAME `--reason` flag
+			// `--force` already uses, not a new one -- mirrors that convention rather than adding
+			// a second audited-override mechanism.
+			'enforce-registry': { type: 'string', default: null },
+			json: { type: 'boolean', default: false },
+		},
+	},
+	// O7 (D-handle-audit-report): read-only, requires --database-url-env (unlike `scan --db`,
+	// there is no meaningful "run without a live connection" mode for this command -- its entire
+	// purpose IS the live query). Reuses `--resource type1,type2`'s exact multi-value convention
+	// from `handles plan`/`handles emit` rather than a new singular flag name.
+	'handles audit': {
+		usage: 'bskel handles audit --feature <id> --database-url-env <NAME> [--resource type1,type2] [--json]',
+		options: {
+			feature: { type: 'string', default: null, required: true },
+			'database-url-env': { type: 'string', default: null, required: true },
+			resource: { type: 'string', default: '' },
 			json: { type: 'boolean', default: false },
 		},
 	},