@rightkit/release 0.6.12 → 0.6.14

package/README.md

@@ -293,13 +293,53 @@ tests: {
 }
 ```
 
-`right-release test` runs every suite in order and stops at the first failure, exiting with that suite's code; each suite prints
+`right-release test` runs every suite in order, collects every reachable failure (see below) and exits with the first failing suite's code; each suite prints
 a JSON line before and after (`{"event":"e2e_suite_completed","suite":"tooling","exitCode":0,"durationMs":1234}`). `--suite a,b`
 (repeatable) selects suites; a group name such as `journeys` selects all its chunks. `--runner vitest -- run --project unit`
+`right-release test` collects every reachable failure instead of stopping at the first: a failed (or unstartable) suite does not hide an independent one, and the run ends non-zero. A suite may declare `requires: ["<earlier suite>"]`; it is skipped, with the reason in the output and an `_suite_skipped` event, when a required suite failed or was skipped. A `sign` step requires the suites it signs, and any other suite after a `sign` step is treated as a consumer of the signed output (nothing that may consume signed bytes runs after a sign step that failed); declare `requires: []` (or the suites it truly needs) to mark a suite independent. Cancellation (a signal) still stops the whole run. A sign step also exports `RIGHTKIT_QA_SIGNED_FILES`, a JSON object of every signed file's declared path to its signed copy.
 runs a runner once with the arguments after `--` (watch mode, one project); `-- <args>` after `--suite` is allowed when exactly
 one suite is selected. `--list [--json]` prints the resolved commands and runs nothing. Wrap it as the repository needs, for
 example `rustright storage run --app <app> -- right-release test`.
 
+#### The `sign` step: one signing identity per product, every build (rightkit#1303)
+
+The route probe (`--to <stage> --route`) judges JSON configs only; a legacy `right-release.config.mjs` is enforced at run time instead (the suite runner before any suite, the dev runner before a target builds). A successful sign step exports `RIGHTKIT_QA_APP_BINARY` and `RIGHTKIT_QA_SIGNING_EVIDENCE` (path of `signing-evidence.json`, kept until the stage ends). On Windows a missing silent Azure token refuses first with `SIGN_WINDOWS_TOKEN_UNAVAILABLE`.
+
+A suite that builds a product (a `tauri build` or `tauri bundle`, or a `cargo build` of the Tauri package or a sidecar package) must be followed by a `sign` step that names it, so a QA run exercises the code identity the release carries (macOS keys privacy grants to the designated requirement):
+
+```js
+suites: [
+  { name: "build-app", cmd: "pnpm", args: ["exec", "tauri", "build", "--target", "aarch64-apple-darwin", "--no-bundle", "--", "--profile", "dev", "--locked"] },
+  // `from` names an EARLIER suite; `path` is relative to the output directory of that suite's carried receipt. The main binary is the file `mainBinaryName` names, else the first.
+  { name: "sign-app", sign: { files: [{ from: "build-app", path: "aarch64-apple-darwin/debug/heardright" }] } },
+  { name: "native-journeys", cmd: "rightkit-qa", args: ["run-tests", "--app", "heardright"] },   // runs with RIGHTKIT_QA_APP_BINARY = the signed copy
+],
+```
+
+- **The identity is derived, never declared.** The product's `tauri.conf.json` `identifier` is the one id (a `tauri.<platform>.conf.json` that changes it is refused; the Mac `development.targets.mac.install.bundleId`, when set, must equal it; a dev or test Tauri `--config` that sets `identifier` is refused). A `sign` step takes no identity, identifier, team or thumbprint key. The Mac signs with the Developer ID Application identity of team `6KLGD3LLKF` through `resolveMacosDevelopmentSigning`, `signMacosEntries` and the signing agent (`runMacCodesignCommands`): there is no fallback to Apple Development or ad hoc signing. The main binary (the file named by `tauri.conf.json` `mainBinaryName` when it declares one, else the first file) is signed with `--identifier <bundle id>`; every other file is a sidecar signed with the identifier `resolveBundleIdentifier` gives it from `sign.identifiers` or `sign.identifierTemplate` (keyed `Contents/MacOS/<name>`; a sidecar the release signs with none is signed with no `--identifier`, as the release does, and must read back as the file name codesign derives). Windows signs through `sign-windows.mjs` (Azure Artifact Signing) and the identity is the signer subject `CN=Damned Ventures LLC`, never a thumbprint.
+- **It runs in-process, in the gate's own session, outside the broker** (like QA: the signing agent, the Keychain and the Azure signer are the session's), and a `sign` step is never a carried step: `build-launch.mjs` refuses it on every route. It verifies the file is in the output directory of the named suite's verified receipts (a path that leaves it, by `..` or a link, is refused), copies it with its sha256 checked into a gate-managed directory outside the snapshot, the checkout and every broker output directory, signs the copy and never the receipt's file, and reads the signature back: Mac `Identifier`, `TeamIdentifier` and the designated requirement, which must equal the release-shaped `expectedDesignatedRequirement(bundleId, team)` (`assertStableDesignatedRequirement`; an unreadable, ad hoc or cdhash-bound requirement is refused too); Windows Authenticode with the signer subject.
+- **Evidence, then the variable.** Only after every file is signed and read back does the step write its `signing` evidence (file, sha256 before and after, identifier, team or subject, requirement) to the carrier's ledger and an evidence file, print a `<prefix>_suite_signed` event, and set `RIGHTKIT_QA_APP_BINARY` to the main binary's signed copy for the suites after it (a step that signs only sidecars sets none). A failed step sets nothing and stops the run; its copies are removed when the run ends.
+- **The gate refuses before it builds, on the Mac and the Dell** (`routePlan`, so `rightkit-gate --to test --route` answers the same; Linux and hosted CI are exempt): a suite that builds a product with no later `sign` step naming it (`RK_SUITE_UNSIGNED_BUILD`), `sign-qa-bundle` or `RIGHTKIT_DEV_SIGNING` ad hoc signing (`RK_SUITE_ADHOC_SIGNING`), an identifier override (`RK_SUITE_IDENTIFIER_OVERRIDE`), a Mac `install.bundleId` that is not the Tauri identifier (`RK_SUITE_IDENTIFIER_MISMATCH`) and a Windows development `install.kind: "tauri"` (`RK_DEV_WIN_UNSIGNED_INSTALL`). A suite that launches a product bin (a `cargo run`, or an integration test that reads `CARGO_BIN_EXE_<bin>`) needs an EARLIER sign step that names that executable: a `sign.files` entry whose `from` is the suite that builds the bin and whose `path` is `<triple>/<profile>/<bin>[.exe]`; a sign step that covers only another binary (the shell, while the test launches the engine) is refused with `RK_SUITE_LAUNCH_UNBOUND`.
+
+`nativeHelpers` entries declare `package` (the app's own SwiftPM package directory, committed in the app) and `product`. `sharedPackage` and `RIGHTKIT_SWIFT_ROOT` are retired (rightkit#1302): a config that uses `sharedPackage` is refused (`NATIVE_HELPERS_INVALID`) with the replacement, `package: "<app SwiftPM package>"` and `product: "rightkit-cloudkit-helper"`, the shared helper pinned by URL and tag through that package's own `Package.swift`.
+
+#### Windows development: `install.kind: "tauri-authenticode"`
+
+The unsigned Windows `tauri` install kind is refused on the Dell. `tauri-authenticode` signs what it installs, in the release's order: `target.build` runs `tauri build --no-bundle` (a build that bundles, or names `--bundles`, is refused), then the bundle marker is patched (before signing), the exe and `install.sidecars` are signed and verified, the carried `tauri bundle --bundles nsis --debug` runs, the installer's payload is checked to embed the signed exe byte for byte, the installer is signed and verified, and only then is it installed and the installed exe verified.
+
+```json
+"install": {
+  "kind": "tauri-authenticode",
+  "productName": "RightApp",
+  "targetTriple": "x86_64-pc-windows-msvc",
+  "manifestPath": "src-tauri/Cargo.toml",
+  "expectedInstalledPath": "{{localAppData}}/RightApp/rightapp.exe",
+  "sidecars": ["rightapp-engine.exe"]
+}
+```
+
+`sidecars` (optional) are paths relative to the build's output directory; no other key is accepted.
+
 ### `right-release build --web` (or `web-build`)
 
 ```js
@@ -490,6 +530,8 @@ enforcement. D4 is ratified; pending activation does not mean pending ratificati
 
 ## QA-only ad hoc bundle signing (`sign-qa-bundle`)
 
+On the Mac and the Dell the gate refuses a gate-run suite or dev build whose config calls this command (`RK_SUITE_ADHOC_SIGNING`, rightkit#1303): a gate-run build is signed with the product's one identity (see the `sign` step in the declared test suites section).
+
 `right-release sign-qa-bundle --app <abs .app> --qa-root <abs dir> [--entitlements <abs plist>] [--out <evidence.json>]` ad hoc signs an assembled QA bundle (for example an Accessibility QA copy) that lives inside a QA scratch root. It exists because `codesign --force --deep --sign -` sent through the signing agent (SSH or non-Aqua session) is refused by design; those refusals are unchanged and this command never calls the agent.
 
 - macOS only. Refused before any command runs: a relative path, `/Applications` or `~/Applications` (lexical or resolved), a bundle whose real path is not inside the real QA root (links are resolved first), a QA root that is `/`, the home directory or an install location, and a target that is not a `.app` directory.
@@ -521,6 +563,12 @@ pnpm add -D @rightkit/release
 pnpm exec right-release deps --check
 ```
 
+Refresh one Cargo.lock after adopting a newly published RightKit crate (rightkit#1305; no build, writes only that workspace's `Cargo.lock`, one request per pin, in the primary checkout):
+
+```sh
+pnpm exec right-release deps --cargo-lock --manifest src-tauri/Cargo.toml --pin rightkit-qa=0.10.0 --pin rightkit-asr=0.4.0
+```
+
 ## MSIX target and Swift app type
 
 Swift (SwiftPM) apps are a first-class project type. `projectType: "swiftpm"` (config or target; auto-detected from a `Package.swift` with no Cargo manifest) replaces the cargo/rustc requirement with `swift`, and skips the Rust target-bridge, sccache and Perl checks. Tauri/Rust targets are unchanged. `makeappx` and `signtool` are required only when `targets.win.msix` is configured.

package/adapter-env.mjs

@@ -0,0 +1,165 @@
+// The request environment of a carried adapter call (rustright#190; rustright-cli shims.rs adapter_environment, rustright-policy adapter.rs
+// check_environment). A `rustright run <adapter> -- <args>` request carries exactly the variables named by RUSTRIGHT_ADAPTER_ENV (a comma
+// list), each set in the client's own environment; the broker accepts a name only when the adapter's registration lists it in `env` and it is
+// not reserved. The forwarded map is the request core's `env` (rustright-protocol attestation.rs request_core), so its values are bound into the
+// attested request digest the gate recomputes (snapshot-request.mjs snapshotRequestCore).
+//
+// The door (build-launch.mjs) sets RUSTRIGHT_ADAPTER_ENV for a step from the env the step itself declares (`adapterEnvLaunch`); the carrier
+// (snapshot-broker.mjs carryBrokerAdapter) reads back what the client will forward (`forwardedAdapterEnv`), with the client's own refusals.
+import path from "node:path";
+
+export const ADAPTER_ENV_VAR = "RUSTRIGHT_ADAPTER_ENV";
+
+/**
+ * RA-08: the path of the transient Android signing-properties file (android-release.mjs ANDROID_SIGNING_PROPERTIES_ENV). It is a typed FILE handoff of the provisioned signer session (native-adapters.mjs
+ * `signingFileProblem`, `nativeSigningFileRefusal`), never an adapter request environment: no adapter registers it (it is `RIGHTKIT_`-prefixed, so reserved), the door refuses a step that declares it, the
+ * carrier's client never receives it, and `RUSTRIGHT_ADAPTER_ENV` never names it. Only the path exists in the environment of a direct host's own Gradle; the file holds the secrets.
+ */
+export const SIGNING_FILE_ENV = "RIGHTKIT_ANDROID_SIGNING_PROPERTIES";
+export const ADAPTER_ENV_SIGNING_FILE = "RK_ADAPTER_ENV_SIGNING_FILE";
+/** Whether `key` names the signing-properties file handoff (case-insensitive, as RustRight compares). */
+export const isSigningFileEnvKey = (key) => String(key).toUpperCase() === SIGNING_FILE_ENV;
+
+export const ADAPTER_ENV_RESERVED = "RK_ADAPTER_ENV_RESERVED";
+export const ADAPTER_ENV_UNSET = "RK_ADAPTER_ENV_UNSET";
+export const ADAPTER_ENV_INVALID = "RK_ADAPTER_ENV_INVALID";
+
+// rustright-policy adapter.rs RESERVED_ENV_KEYS and RESERVED_ENV_PREFIXES at rustright 7b24288, compared upper-case. The prefix list still holds
+// RIGHTKIT_ (marked legacy, "removed by task L-1"): until RustRight drops it, a RIGHTKIT_* name is refused by the broker and cannot be registered.
+const RESERVED_EXACT = new Set([
+  "PATH", "PATHEXT", "HOME", "USERPROFILE", "TMPDIR", "TMP", "TEMP", "SYSTEMROOT", "COMSPEC", "SHELL", "BASH_ENV", "ENV", "PYTHONPATH", "PYTHONHOME",
+  "PYTHONSTARTUP", "PYTHONUSERBASE", "PYTHONEXECUTABLE", "PYTHONINSPECT", "PYTHONSAFEPATH", "NODE_OPTIONS", "NODE_PATH", "RUBYOPT", "RUBYLIB", "GEM_HOME",
+  "GEM_PATH", "PERL5LIB", "PERL5OPT", "PERLLIB", "JAVA_TOOL_OPTIONS", "_JAVA_OPTIONS", "JDK_JAVA_OPTIONS", "CLASSPATH", "GOFLAGS", "GOROOT", "DOTNET_ROOT",
+  "DOTNET_STARTUP_HOOKS", "DOTNET_ADDITIONAL_DEPS", "ERL_FLAGS", "ERL_AFLAGS", "ERL_ZFLAGS", "ELIXIR_ERL_OPTIONS",
+]);
+const RESERVED_PREFIXES = ["RUSTRIGHT_", "RIGHTKIT_", "LD_", "DYLD_", "CARGO", "RUST", "SCCACHE", "COR_", "CORECLR_", "DOTNET_HOST"];
+
+/**
+ * GB-06 (BROKER-CONTRACT section 16): signing material never rides an adapter request. RustRight reserves `TAURI_SIGNING_*` (the empty value that suppresses signing included), the legacy
+ * `TAURI_PRIVATE_KEY` and `TAURI_KEY_PASSWORD` (adapter.rs RESERVED_ENV_PREFIXES): they cannot be registered under an adapter's `env` and a request that names one is refused
+ * (RK_ADAPTER_ENV_DENIED). Signing, the updater seal and their read-back stay in the provisioned signer session, so a carried Tauri build runs unsigned and RightKit seals outside the broker.
+ * `TAURI_DEBUG` and the other Tauri variables are not signing material.
+ */
+export const SIGNING_ENV_PREFIXES = Object.freeze(["TAURI_SIGNING_", "TAURI_PRIVATE_KEY", "TAURI_KEY_PASSWORD"]);
+export const ADAPTER_ENV_SIGNING = "RK_ADAPTER_ENV_SIGNING";
+/** Whether `key` is signing material (case-insensitive, as RustRight compares). */
+export const isSigningEnvKey = (key) => { const upper = String(key).toUpperCase(); return SIGNING_ENV_PREFIXES.some((prefix) => upper.startsWith(prefix)); };
+/** `env` without any signing variable: what a carried call's client process receives (the client forwards only what RUSTRIGHT_ADAPTER_ENV names, but it never needs these to exist). */
+export function withoutSigningEnv(env) {
+  const out = { ...env };
+  for (const key of Object.keys(out)) if (isSigningEnvKey(key) || isSigningFileEnvKey(key)) delete out[key];
+  return out;
+}
+
+/**
+ * The signed-artifact handoff (GB-05; adapter.rs QA_HANDOFF_ENV): the sign step's two outputs reach a consumer under exactly these two names. They are
+ * not secrets and not broker-owned, so the broker exempts exactly these two from the reserved RIGHTKIT_ prefix; they must be registered in the adapter's
+ * `env` and carry an absolute path with no `..`.
+ */
+export const QA_HANDOFF_ENV = Object.freeze(["RIGHTKIT_QA_APP_BINARY", "RIGHTKIT_QA_SIGNING_EVIDENCE"]);
+export const isQaHandoffKey = (key) => QA_HANDOFF_ENV.includes(String(key).toUpperCase());
+export const ADAPTER_ENV_UNREGISTERED = "RK_ADAPTER_ENV_UNREGISTERED";
+export const ADAPTER_ENV_HANDOFF_PATH = "RK_ADAPTER_ENV_HANDOFF_PATH";
+
+/** Whether the broker refuses `key` in a request environment (adapter.rs is_reserved_env_key, case-insensitive; the QA handoff names are exempt). */
+export function isReservedAdapterEnvKey(key) {
+  const upper = String(key).toUpperCase();
+  if (isQaHandoffKey(upper)) return false;
+  return upper === "" || upper.includes("=") || RESERVED_EXACT.has(upper) || RESERVED_PREFIXES.some((prefix) => upper.startsWith(prefix)) || isSigningEnvKey(upper);
+}
+
+/**
+ * The candidate registration manifest of the request-environment keys, per adapter (GB-04): the inventory of every non-reserved key the gate's planners
+ * send, by step. Each adapter's registration must list exactly these in its `env`; the installed registration must equal this manifest, and a key outside
+ * it refuses at planning, before any process. `pnpm` is the reference registration RustRight published (docs/contracts/adapter-argv.fixtures.json
+ * `adapter.env`); `node` takes the same keys (a step script reads the test knob and the signed handoff); `swift` takes none (the gate sends no environment
+ * to a SwiftPM job).
+ *   RK_ISOLATED_CHECKOUT   test knob of a broker-admitted test row (right-suite-contract.test.mjs, release-exports.test.mjs): "1" runs it from an isolated checkout
+ *   RIGHTKIT_QA_APP_BINARY / RIGHTKIT_QA_SIGNING_EVIDENCE   the signed-artifact handoff (GB-05), set by the sign step only
+ */
+export const ADAPTER_ENV_MANIFEST = Object.freeze({
+  "rightkit-pnpm": Object.freeze(["RK_ISOLATED_CHECKOUT", ...QA_HANDOFF_ENV]),
+  "rightkit-node": Object.freeze(["RK_ISOLATED_CHECKOUT", ...QA_HANDOFF_ENV]),
+  "rightkit-swift": Object.freeze([]),
+  // GB-51: the native-tool adapters take no request environment (a step's own environment is refused before launch, naming the key).
+  "rightkit-xcodegen": Object.freeze([]), "rightkit-xcodebuild": Object.freeze([]), "rightkit-gradle": Object.freeze([]), "rightkit-cmake": Object.freeze([]),
+});
+
+/**
+ * Why the broker would refuse this request environment for an adapter whose registration lists `registered` (adapter.rs `check_environment`), or null: a
+ * reserved key (broker-controlled, loader or interpreter path), a signed-artifact handoff key whose value is not an absolute path with no `..`, and any key the
+ * registration does not list. One refusal names every unregistered key and the registered set; nothing is dropped silently.
+ */
+export function adapterEnvRefusal(env, registered) {
+  const keys = Object.keys(env ?? {});
+  const reserved = keys.find((key) => isReservedAdapterEnvKey(key));
+  if (reserved !== undefined) return { code: ADAPTER_ENV_RESERVED, message: `environment key ${JSON.stringify(reserved)} is broker-controlled or redirects code loading, so no adapter request may carry it (reserved: RUSTRIGHT_*, RIGHTKIT_* except the two signed-artifact handoff names, CARGO*, RUST*, PATH, loader and interpreter-path variables)` };
+  const listed = new Set((registered ?? []).map(String));
+  for (const key of keys) {
+    const value = String(env[key]);
+    if (isQaHandoffKey(key) && listed.has(key) && !(isAbsolutePath(value) && !value.split(/[\\/]/).includes(".."))) return { code: ADAPTER_ENV_HANDOFF_PATH, message: `environment key ${JSON.stringify(key)} must be an absolute path with no '..' (the signed artifact's exact path)` };
+  }
+  const unregistered = keys.filter((key) => !listed.has(key));
+  if (unregistered.length === 0) return null;
+  return { code: ADAPTER_ENV_UNREGISTERED, message: `environment key(s) ${unregistered.map((k) => JSON.stringify(k)).join(", ")} are not registered for this adapter (registered: ${[...listed].sort().join(", ") || "none"}); register the key in the adapter's \`env\` (the candidate manifest is ADAPTER_ENV_MANIFEST) or remove it from the step; nothing is dropped to make the call pass` };
+}
+
+function fail(code, message) {
+  const error = new Error(`${code}: ${message}`);
+  error.code = code;
+  throw error;
+}
+
+const isAbsolutePath = (value) => path.isAbsolute(value) || path.posix.isAbsolute(value) || path.win32.isAbsolute(value);
+const validName = (name) => typeof name === "string" && name !== "" && !/[,=\0\s]/.test(name);
+const validValue = (value) => typeof value === "string" && !value.includes("\0");
+
+/**
+ * What the door adds to a carried adapter step's launch environment for the env the step declares: `{}` for none (no RUSTRIGHT_ADAPTER_ENV at
+ * all), else RUSTRIGHT_ADAPTER_ENV naming exactly the step's variables, plus those variables with their values. A reserved name, a name that
+ * cannot ride a comma list, a declared name with no value, or a value that is not a string is refused with a coded error.
+ */
+export function adapterEnvLaunch(stepEnv, { registered = null } = {}) {
+  // GB-06: signing material is never forwarded. A signing variable the step declares with a value is material and refuses the step at planning (the name, never the value, is reported); one the
+  // recipe sets EMPTY only suppresses signing in a direct session, carries nothing, and is not forwarded (the carried build runs unsigned; the seal is made outside the broker).
+  const declared = Object.keys(stepEnv ?? {});
+  const handoff = declared.find((name) => isSigningFileEnvKey(name));
+  if (handoff !== undefined) fail(ADAPTER_ENV_SIGNING_FILE, `step env ${JSON.stringify(handoff)} is the signing-properties file handoff: its path travels only as the typed signing-file handoff of a native job (native-adapters.mjs nativeSigningFileRefusal), never as an adapter request environment, and no adapter registers it`);
+  const material = declared.filter((name) => isSigningEnvKey(name) && String(stepEnv[name] ?? "") !== "");
+  if (material.length) fail(ADAPTER_ENV_SIGNING, `step env ${material.map((n) => JSON.stringify(n)).join(", ")} is signing material: it never rides an adapter request (RustRight reserves TAURI_SIGNING_*, TAURI_PRIVATE_KEY and TAURI_KEY_PASSWORD, RK_ADAPTER_ENV_DENIED); signing and the updater seal stay in the provisioned signer session, and a carried Tauri build runs unsigned`);
+  const droppedSigning = declared.filter((name) => isSigningEnvKey(name)).sort();
+  const names = declared.filter((name) => !isSigningEnvKey(name)).sort();
+  const launch = (value) => { if (droppedSigning.length) Object.defineProperty(value, "signingEnvDropped", { value: droppedSigning, enumerable: false }); return value; };
+  if (names.length === 0) return launch({});
+  for (const name of names) {
+    if (isReservedAdapterEnvKey(name)) fail(ADAPTER_ENV_RESERVED, `step env ${JSON.stringify(name)} is broker-controlled or redirects code loading, so no adapter request may carry it (reserved: RUSTRIGHT_*, RIGHTKIT_* except the two signed-artifact handoff names, CARGO*, RUST*, loader and interpreter-path variables)`);
+    if (!validName(name)) fail(ADAPTER_ENV_INVALID, `step env name ${JSON.stringify(name)} cannot be forwarded to an adapter`);
+    const value = stepEnv[name];
+    if (value === undefined || value === null) fail(ADAPTER_ENV_UNSET, `step env ${name} is declared but has no value`);
+    if (!validValue(String(value))) fail(ADAPTER_ENV_INVALID, `step env ${name} has a value that cannot be forwarded`);
+  }
+  // GB-04: judged against the adapter's registration (its `env`) before anything is launched; one refusal names every unregistered key.
+  if (registered !== null) {
+    const refusal = adapterEnvRefusal(Object.fromEntries(names.map((name) => [name, String(stepEnv[name])])), registered);
+    if (refusal) fail(refusal.code, refusal.message);
+  }
+  return launch({ [ADAPTER_ENV_VAR]: names.join(","), ...Object.fromEntries(names.map((name) => [name, String(stepEnv[name])])) });
+}
+
+/**
+ * The map the RustRight client forwards for a call run with `env` (shims.rs adapter_environment): each name in RUSTRIGHT_ADAPTER_ENV, its value
+ * from `env`. A reserved name, or a named variable that is not set, is refused (the client refuses the same two ways).
+ */
+export function forwardedAdapterEnv(env) {
+  const raw = env?.[ADAPTER_ENV_VAR] ?? "";
+  const forwarded = {};
+  for (const name of String(raw).split(",").map((part) => part.trim()).filter(Boolean)) {
+    if (isSigningFileEnvKey(name)) fail(ADAPTER_ENV_SIGNING_FILE, `${ADAPTER_ENV_VAR} names ${name}, the signing-properties file handoff: its path is never forwarded as an adapter request environment`);
+    if (isSigningEnvKey(name)) fail(ADAPTER_ENV_SIGNING, `${ADAPTER_ENV_VAR} names ${name}, which is signing material and is never forwarded to an adapter (signing stays in the provisioned signer session)`);
+    if (isReservedAdapterEnvKey(name)) fail(ADAPTER_ENV_RESERVED, `${ADAPTER_ENV_VAR} names ${name}, which is broker-controlled and cannot be forwarded to an adapter`);
+    const value = env[name];
+    if (value === undefined) fail(ADAPTER_ENV_UNSET, `${ADAPTER_ENV_VAR} names ${name}, which is not set`);
+    forwarded[name] = String(value);
+  }
+  return forwarded;
+}

package/android-ndk.mjs

@@ -35,6 +35,8 @@ export function validateAndroidNdk(ndk, { root, kind = "release" } = {}) {
     throw new Error(`ndk.abis must be a non-empty list of distinct ABIs from ${ANDROID_ABIS.join(", ")}`);
   }
   if (!nonEmpty(ndk.jniLibs) || path.isAbsolute(ndk.jniLibs) || path.win32.isAbsolute(ndk.jniLibs)) throw new Error("ndk.jniLibs must be a relative path inside the app");
+  // The directory is emptied before every build and holds only generated .so files: a `.git` segment would aim that cleanup (and cargo ndk -o) into repository metadata.
+  if (String(ndk.jniLibs).split(/[\\/]/).some((part) => part.toLowerCase() === ".git")) throw new Error("ndk.jniLibs must not contain a .git path segment: the generated jniLibs directory is emptied before every build and never lives in repository metadata");
   const jniLibs = path.resolve(root, ndk.jniLibs);
   if (!inside(root, jniLibs) || path.basename(jniLibs) !== "jniLibs") throw new Error("ndk.jniLibs must name a generated directory called jniLibs inside the app (it is emptied before every build)");
   if (ndk.manifestPath !== undefined && (!nonEmpty(ndk.manifestPath) || path.isAbsolute(ndk.manifestPath) || path.win32.isAbsolute(ndk.manifestPath) || ndk.manifestPath.split(/[\\/]/).includes(".."))) {
@@ -58,7 +60,9 @@ export function androidNdkCommand(ndk, { profile = "release" } = {}) {
   const args = ["ndk"];
   if (ndk.apiLevel !== undefined) args.push("--platform", String(ndk.apiLevel));
   for (const abi of ndk.abis) args.push("-t", abi);
-  args.push("-o", ndk.jniLibs, "build");
+  // GB-62 (GATE commit exactness; BR20): `--locked` goes at the INNER Cargo build boundary, right after `build`, where cargo-ndk hands its remaining
+  // arguments to Cargo; the outer ABI/API/output options stay as written (`--locked` before `build` would be cargo-ndk's own option to reject).
+  args.push("-o", ndk.jniLibs, "build", "--locked");
   if (profile === "release") args.push("--release");
   if (ndk.manifestPath) args.push("--manifest-path", ndk.manifestPath);
   if (ndk.package) args.push("-p", ndk.package);

package/android-release.mjs

@@ -24,7 +24,12 @@
 //     on Windows and Linux) or from a file outside the repository (mode 0600 on POSIX), then written to a transient
 //     0600 `signing.properties` in a private temp directory. Gradle gets only the file's PATH, in
 //     RIGHTKIT_ANDROID_SIGNING_PROPERTIES; the app's signingConfig reads storeFile/storePassword/keyAlias/keyPassword from it.
-//   - The file is zeroed and removed when Gradle ends, on failure, and on process exit.
+//   - The file is zeroed and removed when Gradle ends, on failure, on cancellation (an AbortSignal, SIGINT, SIGTERM, SIGHUP) and on process exit. It lives in a
+//     private 0700 directory this lane created and owns (`tmpRoot`); signingFileProblem (native-adapters.mjs, the broker's own file rule) must accept it before Gradle sees its path, and a
+//     file that survives cleanup is a refusal of its own (ANDROID_SIGNING_CLEANUP_FAILED), never a warning.
+//   - Gradle runs through the door (release.mjs runCommand -> build-launch.mjs): the path is the typed `signingFile` handoff, never an environment of a broker job. A broker route has no
+//     request field that carries it yet (capability native-signing-file-v1, open policy: the signed Android release phase is OPEN and off), so `native.plan` is asked FIRST, before any
+//     secret is read or any file written, and the typed refusal (RK_NATIVE_SIGNING_FILE_UNSUPPORTED, or the grammar's refusal of bundle<Variant>Release) ends the lane. A direct host's own Gradle gets the path in its environment.
 //
 // After the build the AAB is read in-process (android-aab-scan.mjs): QA/debug markers in every .so, web-bundle mocks,
 // one upload-key signature whose certificate matches expectedCertSha256 (never the Android debug certificate). A receipt
@@ -36,9 +41,14 @@ import path from "node:path";
 import { spawnSync } from "./background-process.mjs";
 import { describeAabProblems, extractNativeLibs, scanAab } from "./android-aab-scan.mjs";
 import { runAndroidNdk, validateAndroidNdk } from "./android-ndk.mjs";
+import { NATIVE_SIGNING_FILE_ENV, signingFileProblem } from "./native-adapters.mjs";
 
 export const ANDROID_SIGNING_CONTRACT = "android-aab-upload-key-v1";
-export const ANDROID_SIGNING_PROPERTIES_ENV = "RIGHTKIT_ANDROID_SIGNING_PROPERTIES";
+export const ANDROID_SIGNING_PROPERTIES_ENV = NATIVE_SIGNING_FILE_ENV; // "RIGHTKIT_ANDROID_SIGNING_PROPERTIES": the one name, shared with the door
+export const ANDROID_SIGNING_FILE_REFUSED = "ANDROID_SIGNING_FILE_REFUSED";
+export const ANDROID_SIGNING_CLEANUP_FAILED = "ANDROID_SIGNING_CLEANUP_FAILED";
+export const ANDROID_SIGNING_ROUTE_REFUSED = "ANDROID_SIGNING_ROUTE_REFUSED";
+export const ANDROID_RELEASE_CANCELLED = "ANDROID_RELEASE_CANCELLED";
 export const ANDROID_RECEIPT_NAME = "android-aab.json";
 export const ANDROID_ENV_SECRET_REFUSED = "ANDROID_ENV_SECRET_REFUSED";
 export const ANDROID_SECRET_MISSING = "ANDROID_SECRET_MISSING";
@@ -245,6 +255,46 @@ export function createSigningProperties({ keystore, alias, storePassword, keyPas
   return { file, dir, cleanup };
 }
 
+// ---- lifetime of the signing file ---------------------------------------------------------------------------------
+// The file must not outlive the signing phase on any exit: normal end, a thrown step, process.exit() (release.mjs ends a failed step with it) or a signal. A signal handler suppresses the
+// default action, so after the cleanup the handlers are removed and the signal is re-raised: the process still dies of the signal, with no secret file left behind.
+const CANCEL_SIGNALS = process.platform === "win32" ? ["SIGINT", "SIGTERM"] : ["SIGINT", "SIGTERM", "SIGHUP"];
+export function holdSigningFile(props, host = process) {
+  const signalHandlers = new Map();
+  const detach = () => {
+    host.removeListener("exit", onExit);
+    for (const [signal, handler] of signalHandlers) host.removeListener(signal, handler);
+    signalHandlers.clear();
+  };
+  const onExit = () => props.cleanup();
+  host.on("exit", onExit);
+  for (const signal of CANCEL_SIGNALS) {
+    const handler = () => { props.cleanup(); detach(); host.kill(host.pid, signal); };
+    signalHandlers.set(signal, handler);
+    host.on(signal, handler);
+  }
+  // release(): cleanup, then stop guarding. Returns true when nothing of the owned directory is left.
+  return () => { props.cleanup(); detach(); return !existsSync(props.dir); };
+}
+
+// Asks the production native runner (build-launch.mjs createNativeRunner) whether the door can carry this Gradle step WITH the signing-file handoff, before any secret is read.
+// The probe path names a file that does not exist and is never created; plan() spawns nothing. Returns the launch, or { refused } with the door's typed reason.
+export function planNativeSigningRoute({ native, gradle, root, tmpRoot }) {
+  if (!native) return null;
+  const probe = path.join(tmpRoot, "rightkit-android-sign-probe", "signing.properties");
+  let launch;
+  try { launch = native.plan(gradle.cmd, gradle.args, { cwd: path.resolve(root, gradle.cwd ?? "."), signingFile: probe }); }
+  catch (error) {
+    if (error?.code === "RK_BUILD_LAUNCH_REFUSED") return { refused: { code: String(error.reason ?? ANDROID_SIGNING_ROUTE_REFUSED), message: String(error.message) } };
+    throw error;
+  }
+  // A direct host launches Gradle itself: its environment must carry exactly the handoff path. A broker route that accepts the file carries it by its own typed capability.
+  if (!launch.native && launch.env?.[NATIVE_SIGNING_FILE_ENV] !== probe) {
+    return { refused: { code: ANDROID_SIGNING_ROUTE_REFUSED, message: `the door's launch of ${gradle.cmd} would not carry ${NATIVE_SIGNING_FILE_ENV}; the signing file is not handed over` } };
+  }
+  return { launch };
+}
+
 // ---- verification, receipt and seal entry ------------------------------------------------------------------------
 const sha256File = (file) => createHash("sha256").update(readFileSync(file)).digest("hex");
 
@@ -284,12 +334,18 @@ export function verifyAndroidReceipt(receiptPath, aabFile) {
 export async function runAndroidRelease({
   root, app = "app", target, dryRun = false, env = process.env, platform = process.platform,
   runGradle, runNdk = runGradle, resolveArtifact = (file) => path.resolve(root, file), scanFiles, receiptDir,
-  allowContentOnlyDevtools = false, credentialStore, tmpRoot = os.tmpdir(), now = () => new Date(), log = console.log,
+  allowContentOnlyDevtools = false, credentialStore, tmpRoot = os.tmpdir(), now = () => new Date(), log = console.log, native, signal,
 }) {
+  const cancelled = () => { if (signal?.aborted) refuse(ANDROID_RELEASE_CANCELLED, "the Android release was cancelled before the signing phase ended; no signing file remains"); };
+  cancelled();
   refuseAndroidEnvSecrets(env);
   const aab = resolveArtifact(target.aab.file);
   const { signing } = target;
+  // RA-08: the door's verdict on the signing-file handoff comes first, before any secret is read or any file or directory is created (a refusal here has nothing to clean up).
+  const route = planNativeSigningRoute({ native, gradle: target.gradle, root, tmpRoot });
+  if (route?.refused && !dryRun) refuse(route.refused.code, `${route.refused.message}; the signed Android release phase did not start: no secret was read and no signing file was written`);
   if (dryRun) {
+    if (route?.refused) log(`right-release: dry-run: the door refuses this Gradle step with the signing-file handoff (${route.refused.code}); a real run stops there before any secret is read`);
     log(`right-release: dry-run: android ${target.task} -> ${aab}; signing passwords would come from ${signing.storePassword.credential ? "the credential store" : "a file"}, never the environment`);
     if (target.ndk) await runAndroidNdk({ ndk: target.ndk, profile: "release", dryRun: true, run: (command) => runNdk(command, {}), log });
     await runGradle(target.gradle, {});
@@ -304,16 +360,25 @@ export async function runAndroidRelease({
   rmSync(aab, { force: true });
   // Native libraries first (no secret involved): cargo-ndk --release per ABI into the generated jniLibs directory.
   if (target.ndk) await runAndroidNdk({ ndk: target.ndk, profile: "release", run: (command) => runNdk(command, {}), log });
+  cancelled();
   const props = createSigningProperties({ keystore: signing.keystorePath, alias: signing.alias, storePassword, keyPassword, tmpRoot });
-  const onExit = () => props.cleanup();
-  process.on("exit", onExit); // release.mjs ends a failed step with process.exit(); the secret file must not outlive it
+  // From here the file is owned by this phase: exit, process.exit() and the cancelling signals all remove it (holdSigningFile).
+  const release = holdSigningFile(props);
+  let built = false;
   try {
+    // The broker's own file rule (signingFileProblem) must accept the file, inside this lane's tmpRoot, before Gradle is handed its path.
+    const shape = signingFileProblem(props.file, { signerRoot: tmpRoot });
+    if (shape) refuse(ANDROID_SIGNING_FILE_REFUSED, `the transient signing file is not acceptable (${shape.replaceAll(props.file, "<signing file>")}); Gradle was not started`);
+    cancelled();
     log(`right-release: android ${target.task} (signing properties passed by path only)`);
-    await runGradle(target.gradle, { [ANDROID_SIGNING_PROPERTIES_ENV]: props.file });
+    await runGradle(target.gradle, { [ANDROID_SIGNING_PROPERTIES_ENV]: props.file }, ...(signal ? [{ signal }] : []));
+    built = true;
   } finally {
-    props.cleanup();
-    process.removeListener("exit", onExit);
+    const clean = release();
+    if (!clean && built) refuse(ANDROID_SIGNING_CLEANUP_FAILED, "the transient signing directory could not be removed after Gradle; the release is refused (the file holds only zeroes if the overwrite succeeded)");
+    if (!clean) log("right-release: WARNING: the transient signing directory could not be removed; remove it by hand (it holds no password if the overwrite succeeded)");
   }
+  cancelled();
   if (!existsSync(aab) || !statSync(aab).isFile()) refuse("ANDROID_AAB_MISSING", `Gradle finished but ${target.aab.file} was not produced`);
 
   const scan = scanAab(aab, { allowContentOnlyDevtools });

package/app-check.mjs

@@ -1206,6 +1206,11 @@ export function exportCommit(repo, commit, dest, { batchBytes = BATCH_BYTES } =
   return entries.map((entry) => entry.path);
 }
 
+/** The repository paths of `commit` as `git ls-tree -r` lists them (files and submodule directories), without reading a blob or writing anything. */
+export function listCommitFiles(repo, commit) {
+  return git(["ls-tree", "-r", "-z", "--name-only", commit], { cwd: repo }).split("\0").filter(Boolean);
+}
+
 /**
  * The tree a compile of `repo` would see, written under `dest`: HEAD plus every tracked and untracked, non-ignored file as it is
  * on disk, put through a throwaway index (the repository's own index is never touched; the blobs land in its object store).
@@ -1368,7 +1373,7 @@ function loadBaseline({ explicit, root, central, repoKey, today }) {
  * `refuse` lists rules whose findings the baseline cannot excuse here, because the build refuses them whatever the baseline says
  * (BUILD_REFUSES); a listed one fails like a new one.
  */
-export function runAppCheck({ repo, mode = "commit", commit, only = null, baseline, printBaseline = false, rules = RULES, tier = null, label = "check", repoKey, central = rightkitCheckout(), now = new Date(), refuse = [] } = {}) {
+export function runAppCheck({ repo, mode = "commit", commit, only = null, baseline, printBaseline = false, rules = RULES, tier = null, label = "check", repoKey, central = rightkitCheckout(), now = new Date(), refuse = [], snapshot = null } = {}) {
   const lines = [];
   const errLines = [];
   if (tier !== null && !TIERS.includes(tier)) { errLines.push(`${label}: --rule-tier must be compile or release, not ${JSON.stringify(tier)}`); return { findings: [], known: [], stale: [], expired: [], found: [], exitCode: 2, lines, text: "", errLines, errText: errLines.join("\n") }; }
@@ -1387,15 +1392,24 @@ export function runAppCheck({ repo, mode = "commit", commit, only = null, baseli
   const key = repoKey ?? (central && sameDirectory(repo, central) ? "rightkit" : path.basename(repo).toLowerCase());
   const started = Date.now();
   let checked, files, root;
+  // `snapshot` (the gate's own directory holding exactly `commit`'s tree, verified by the caller) is read in place: no export, no copy of the
+  // source, nothing written under the temporary directory, and the directory is never removed here (docs/GATE-CONTRACT.md, 2026-10-29).
+  const inPlace = snapshot !== null && mode === "commit";
   try {
-    root = fs.mkdtempSync(path.join(os.tmpdir(), "rk-check-"));
-    if (mode === "worktree") ({ tree: checked, files } = exportWorktree(repo, root));
-    else { checked = resolveCommit(repo, commit ?? "HEAD"); files = exportCommit(repo, checked, root); }
+    if (inPlace) {
+      root = path.resolve(snapshot);
+      checked = resolveCommit(repo, commit ?? "HEAD");
+      files = listCommitFiles(repo, checked);
+    } else {
+      root = fs.mkdtempSync(path.join(os.tmpdir(), "rk-check-"));
+      if (mode === "worktree") ({ tree: checked, files } = exportWorktree(repo, root));
+      else { checked = resolveCommit(repo, commit ?? "HEAD"); files = exportCommit(repo, checked, root); }
+    }
   } catch (error) {
     // HEAD is what both modes start from: a repository that has no commit yet has nothing to read, and "commit first" is the fix.
     const unborn = (mode === "worktree" || (commit ?? "HEAD") === "HEAD") && hasNoCommit(repo);
     errLines.push(unborn ? `${label}: the repository has no commit yet; commit first` : `${label}: could not export the commit to check: ${error.message}`);
-    if (root) fs.rmSync(root, { recursive: true, force: true });
+    if (root && !inPlace) fs.rmSync(root, { recursive: true, force: true });
     return finish(2);
   }
   try {
@@ -1440,7 +1454,7 @@ export function runAppCheck({ repo, mode = "commit", commit, only = null, baseli
     lines.push(`${label}: ${checked.slice(0, 12)} passed ${ruleCount} rules (${tierLabel}) in ${seconds}s${known.length ? ` (${known.length} known finding(s) in ${listed.listedFile}; fix them, then remove their entries)` : ""}`);
     return finish(0, result);
   } finally {
-    fs.rmSync(root, { recursive: true, force: true });
+    if (!inPlace) fs.rmSync(root, { recursive: true, force: true });
   }
 }
 
@@ -1602,7 +1616,7 @@ export function guardCommand({ args, cwd = process.cwd(), run = runAppCheck, sou
  * `--rule-tier` defaults to compile (see TIERS); `--list` prints every rule with its tier. (`--tier patch|update` is the upload tier, elsewhere.)
  * `--repo` defaults to the git top-level of `cwd` (or `defaultRepo`). Returns the exit code: 0 pass, 1 findings, 2 could not run.
  */
-export async function main(argv, { out = (s) => process.stdout.write(`${s}\n`), err = (s) => process.stderr.write(`${s}\n`), label = "check", rules = RULES, defaultRepo = null, cwd = process.cwd(), central, now } = {}) {
+export async function main(argv, { out = (s) => process.stdout.write(`${s}\n`), err = (s) => process.stderr.write(`${s}\n`), label = "check", rules = RULES, defaultRepo = null, cwd = process.cwd(), central, now, snapshot = null } = {}) {
   const arg = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; };
   if (argv.includes("--list")) { for (const r of rules) out(`${r.id} (${r.gap}) ${tierOf(r)}`); return 0; }
   const tier = arg("--rule-tier") ?? "compile";
@@ -1615,7 +1629,7 @@ export async function main(argv, { out = (s) => process.stdout.write(`${s}\n`),
     only: arg("--only")?.split(",").filter(Boolean) ?? null,
     baseline: arg("--baseline"),
     printBaseline: argv.includes("--print-baseline"),
-    rules, tier, label, ...(central === undefined ? {} : { central }), ...(now ? { now } : {}),
+    rules, tier, label, ...(central === undefined ? {} : { central }), ...(now ? { now } : {}), ...(snapshot ? { snapshot } : {}),
   });
   for (const line of result.lines) out(line);
   for (const line of result.errLines) err(line);