From b99e7737de1d6813e698759e2b024e155e8d1776 Mon Sep 17 00:00:00 2001 From: 2SinceJuly Date: Thu, 19 Nov 2026 02:06:25 +0800 Subject: [PATCH] fix(evidence): derive default authority from subject binding (#10321) * fix(evidence): derive default authority from subject binding evidenceEnvelopeForAdmission defaulted a missing authority to shipped-artifact for every observation, including ones with no artifact subject and ones produced by a live debugger session. An unbound record therefore claimed authority over an artifact it cannot name, and live GDB, Rizin and Cutter observations could never qualify a live-observation contract because that contract accepts only controlled-replay or external-service Evidence. Default to analyst-inference when no subject is bound and keep shipped-artifact when one is, so the default matches what the record can actually support. Declare controlled-replay at the eight live debugger observation sites (GDB 6, Rizin 1, Cutter 1) so those records describe the controlled replay they performed and satisfy the documented contract. * fix(gdb): label retained process-exit observations as controlled replay The GDB command process-exit branch was the only unbound retention path that named no authority, so this branch's new default derived it as analyst-inference. That label cannot support the live-observation contract, and every sibling path (timeout, cancellation, protocol failure, startup) already states controlled-replay. The authority and the unavailable-subject reason now live beside the provider identity so the retention paths read them from one place instead of repeating the literals and drifting apart. * style(evidence): apply repository formatting * fix(cutter): classify command observations as external-service The bridge drives the documented already-running Cutter GUI, whose document state REA neither owns nor resets, so its command observations claim no controlled replay. Label them external-service like the comparable IDA and Frida bridge evidence: live-observation obligations still accept it, while controlled-replay-only verifier contracts and bundle replay scenarios no longer include these observations. * fix(adb): keep device observations at external-service authority The admission default now derives authority from the subject, so a subjectless ADB observation fell to analyst-inference. A device is a service REA attaches to rather than drives, so the observation supports external-service and must stay eligible for live-observation contracts. Carry an explicit authority through AnalysisObservation so a producer that knows its own authority can name it, and set it for every ADB operation. * fix(adb): keep retained observations at external-service authority The admission default derives authority from the subject, and a subjectless observation falls to analyst-inference. createAnalysisExecution never carried an authority field, so every observation the ADB adapter built through it was committed at the subject-derived default instead of the service's. Name the authority once in the domain model, stamp it on every successful execution at the adapter boundary, and route the cleanup-failure and cancellation-retention sites through one helper. Open the execution options field so other providers can name their own authority. Verified: a push whose device digest does not match now retains its receipt at external-service; removing the stamp fails that assertion. check:fast passes. * fix(adb): keep the retained verification receipt at device authority The verificationFailed branch built its retained receipt with createEvidence directly, so the admission default derived the authority from a subjectless target and labelled an observed push as analyst-inference. Pass the device authority through the same way the neighbouring digest-mismatch partial does, so the receipt can still support live-observation verification. * style(adb): apply oxfmt formatting to the authority fix The previous commit wrapped two expressions that oxfmt keeps on one line, so npm run format:check failed on Static checks. --- src/adb/AdbProvider.test.ts | 10 +++- src/adb/AdbProvider.ts | 56 ++++++++++++++----- .../adb/AdbDeviceAnalysisService.test.ts | 2 + .../adb/AdbDeviceAnalysisService.ts | 15 ++++- src/cutter/CutterBridgeService.ts | 1 + src/domain/adb/adbDeviceAnalysis.ts | 8 +++ src/domain/analysisObservation.ts | 9 +++ src/domain/evidence.test.ts | 23 ++++++++ src/domain/evidence.ts | 10 +++- src/gdb/GdbProviderIdentity.ts | 6 ++ src/gdb/GdbSessionManager.ts | 9 ++- src/ports/AnalysisProvider.ts | 7 ++- src/rizin/RizinDebugSessionManager.ts | 1 + .../providers/CutterBridgeService.test.ts | 42 ++++++++++++++ .../GdbSessionManagerCoverage.test.ts | 19 +++++++ 15 files changed, 196 insertions(+), 22 deletions(-) diff --git a/src/adb/AdbProvider.test.ts b/src/adb/AdbProvider.test.ts index 193e4b737f..190ba077a8 100644 --- a/src/adb/AdbProvider.test.ts +++ b/src/adb/AdbProvider.test.ts @@ -1703,6 +1703,9 @@ exit 1`, const evidence = parseEvidence(result.error.partialObservation); expect(evidence).toMatchObject({ operation: "push_adb_file", + // The retained receipt names the service authority, not the subject-derived + // default a partial observation would otherwise fall back to. + authority: "external-service", normalized_result: { local_path: localFile, device_path: "/data/local/tmp/payload.bin", @@ -2698,7 +2701,12 @@ exit 1`, code: "resource_constraint", details: { operation: "push_adb_file" }, }); - expect(result.error.partialObservation).toBeDefined(); + // The retained receipt names the service authority, not the subject-derived + // default a partial observation would otherwise fall back to. + expect(parseEvidence(result.error.partialObservation)).toMatchObject({ + operation: "push_adb_file", + authority: "external-service", + }); }); it("attributes version capture failures to the public operation and retains the prerequisite", async () => { diff --git a/src/adb/AdbProvider.ts b/src/adb/AdbProvider.ts index 5189656c11..d2d2c78ca0 100644 --- a/src/adb/AdbProvider.ts +++ b/src/adb/AdbProvider.ts @@ -35,6 +35,7 @@ import { type AnalysisExecution, } from "../ports/AnalysisProvider.js"; import { providerConfigurationRefusal } from "../domain/providerConfigurationRefusal.js"; +import { ADB_DEVICE_OBSERVATION_AUTHORITY } from "../domain/adb/adbDeviceAnalysis.js"; import type { AdbDisplayNumericIssues, AdbDisplayPartialObservation, @@ -187,6 +188,41 @@ const SCREEN_MAX_OUTPUT_BYTES = 32 * 1024 * 1024; const BUGREPORT_TIMEOUT_MS = 600_000; const BUGREPORT_MAX_OUTPUT_BYTES = 1024 * 1024; +/** + * Commit an ADB observation as Evidence that names the device's authority. Every + * retained receipt and partial travels through here so none can fall back to the + * subject-derived default for a target REA does not own. + */ +const createObservationEvidence = ( + operation: string, + parameters: Record, + execution: AnalysisExecution, +) => + createAnalysisExecutionEvidence( + operation, + parameters, + { + ...execution, + authority: execution.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY, + }, + "observed", + ); + +/** + * Stamp the device's authority on every successful execution at the adapter + * boundary, so a caller-projected or retained observation cannot fall back to a + * subject-derived authority for a target REA does not own. + */ +const observedExecution = ( + result: Result, +): Result => + result.ok + ? ok({ + ...result.value, + authority: result.value.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY, + }) + : result; + /** Carry the exact digest owner through caller-specific partial-result mapping. */ class AdbDigestFailure extends Error { constructor( @@ -989,12 +1025,7 @@ export class AdbProvider { const partialObservation = execution === undefined ? undefined - : createAnalysisExecutionEvidence( - operation, - parameters, - execution, - "observed", - ); + : createObservationEvidence(operation, parameters, execution); return new ProviderCleanupError( ADB_PROVIDER_IDENTITY.id, resources, @@ -1109,12 +1140,7 @@ export class AdbProvider { throw cleanup; }, partial: (completed) => - createAnalysisExecutionEvidence( - operation, - parameters, - completed, - "observed", - ), + createObservationEvidence(operation, parameters, completed), }, ), ); @@ -1246,7 +1272,7 @@ export class AdbProvider { jsonObjectSchema.parse(request.input), ); if (!retried.ok) return retried; - return await this.#executeOperation(request, options); + return observedExecution(await this.#executeOperation(request, options)); } finally { release(); } @@ -2591,6 +2617,8 @@ export class AdbProvider { limitations: completed.limitations, locations: completed.locations, confidence: "observed", + authority: + completed.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY, }, ), ); @@ -2635,6 +2663,8 @@ export class AdbProvider { limitations: completed.limitations, locations: completed.locations, confidence: "observed", + authority: + completed.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY, }, ), }, diff --git a/src/application/adb/AdbDeviceAnalysisService.test.ts b/src/application/adb/AdbDeviceAnalysisService.test.ts index a20303c801..d56e5258fc 100644 --- a/src/application/adb/AdbDeviceAnalysisService.test.ts +++ b/src/application/adb/AdbDeviceAnalysisService.test.ts @@ -127,6 +127,8 @@ it("composes observed Evidence with the caller parameters inline", async () => { expect(evidence.operation).toBe("list_adb_devices"); expect(evidence.parameters).toEqual({}); expect(evidence.confidence).toBe("observed"); + // A device REA attaches to is not one it owns, so the observation names the service rather than a replay. + expect(evidence.authority).toBe("external-service"); }); it("preserves cancellation before execution", async () => { diff --git a/src/application/adb/AdbDeviceAnalysisService.ts b/src/application/adb/AdbDeviceAnalysisService.ts index 0a4fcd3536..ee883f2eaa 100644 --- a/src/application/adb/AdbDeviceAnalysisService.ts +++ b/src/application/adb/AdbDeviceAnalysisService.ts @@ -4,6 +4,7 @@ import type { ExecutionOptions, } from "../../ports/AnalysisProvider.js"; import { + ADB_DEVICE_OBSERVATION_AUTHORITY, adbRequestSchema, adbDeviceListObservationSchema, type AdbOperation, @@ -33,9 +34,17 @@ export class AdbDeviceAnalysisService { { execute: async (request, options) => { const result = await this.provider.execute(request, options); - return result.ok && request.operation === "list_adb_devices" - ? projectDeviceList(result.value) - : result; + if (!result.ok) return result; + // A device is a service REA attaches to and does not own, so what it + // reports is an external observation rather than a replay REA drives. + const observed = { + ...result.value, + authority: + result.value.authority ?? ADB_DEVICE_OBSERVATION_AUTHORITY, + } as const; + return request.operation === "list_adb_devices" + ? projectDeviceList(observed) + : ok(observed); }, }, "observed", diff --git a/src/cutter/CutterBridgeService.ts b/src/cutter/CutterBridgeService.ts index 95f13a663c..f3a6df505e 100644 --- a/src/cutter/CutterBridgeService.ts +++ b/src/cutter/CutterBridgeService.ts @@ -193,6 +193,7 @@ export class CutterBridgeService { identity_status: output.identityStatus, }, rawResult: normalizedOutput, + authority: "external-service", limitations: [ "Cutter exposes no verified stable identity for the active unsaved document or tab.", "Document identity is partial: the bridge uses a plugin instance UUID and observed generation; a same-path tab switch or reload may not be distinguishable.", diff --git a/src/domain/adb/adbDeviceAnalysis.ts b/src/domain/adb/adbDeviceAnalysis.ts index 4d61ef2219..33c532c9af 100644 --- a/src/domain/adb/adbDeviceAnalysis.ts +++ b/src/domain/adb/adbDeviceAnalysis.ts @@ -6,6 +6,14 @@ import { z } from "zod"; import { knownCoverageStatusSchema } from "../coverage.js"; import { localPathStringSchema } from "../localPath.js"; import { IDENTIFIER_PATTERN } from "../stringPatterns.js"; +import type { EvidenceAuthority } from "../evidence.js"; + +/** + * A device is a service REA attaches to and does not own, so what it reports is + * an external observation rather than one bound to a shipped artifact. + */ +export const ADB_DEVICE_OBSERVATION_AUTHORITY: EvidenceAuthority = + "external-service"; /** * Device serials as adb prints them: emulator-5554, USB identifiers, and diff --git a/src/domain/analysisObservation.ts b/src/domain/analysisObservation.ts index acda257ff9..fc47fe761d 100644 --- a/src/domain/analysisObservation.ts +++ b/src/domain/analysisObservation.ts @@ -3,6 +3,7 @@ import { createEvidence, evidenceEnvelopeForAdmission, type Evidence, + type EvidenceAuthority, type EvidenceCreationOptions, type EvidenceLocation, type EvidenceProvider, @@ -29,6 +30,11 @@ export interface AnalysisObservation { * its caller. Explicit null means the observation has no file subject. */ readonly subject?: EvidenceSubjectTarget | null; + /** + * The authority the observation itself supports. Missing derives it from the + * subject, which a service REA does not own cannot name. + */ + readonly authority?: EvidenceAuthority; } /** Build the single borrowed observation used for admission and commitment. */ @@ -49,6 +55,9 @@ const analysisExecutionEvidenceInput = ( ...(execution.relationshipCoverage === undefined ? {} : { relationshipCoverage: execution.relationshipCoverage }), + ...(execution.authority === undefined + ? {} + : { authority: execution.authority }), locations: execution.locations, confidence, }); diff --git a/src/domain/evidence.test.ts b/src/domain/evidence.test.ts index e7b9030345..0275c460ef 100644 --- a/src/domain/evidence.test.ts +++ b/src/domain/evidence.test.ts @@ -832,6 +832,29 @@ it("binds an explicit unknown-subject reason into the semantic Evidence identity expect(parseEvidence(explicit)).toEqual(explicit); }); +it("derives the default authority from whether the subject names a target", () => { + const observation = { operation: "health", parameters: {}, result: true }; + expect(createEvidence(TARGET, PROVIDER, observation).authority).toBe( + "shipped-artifact", + ); + expect( + createEvidence(unknownTarget("not-observed"), PROVIDER, observation) + .authority, + ).toBe("analyst-inference"); + expect( + createEvidence(unknownTarget("not-observed"), PROVIDER, { + ...observation, + authority: "controlled-replay", + }).authority, + ).toBe("controlled-replay"); + expect( + createEvidence(TARGET, PROVIDER, { + ...observation, + authority: "external-service", + }).authority, + ).toBe("external-service"); +}); + it("derives byte-stable bundle manifests independent of record order", () => { const artifactEvidence = createEvidence(TARGET, PROVIDER, { operation: "health", diff --git a/src/domain/evidence.ts b/src/domain/evidence.ts index 063218a48d..c9dc71d303 100644 --- a/src/domain/evidence.ts +++ b/src/domain/evidence.ts @@ -356,7 +356,7 @@ export const evidenceSubjectDisplay = (evidence: { : undefined; }; -type EvidenceAuthority = z.infer; +export type EvidenceAuthority = z.infer; type ExecutionEnvironment = z.infer; export type EvidenceProvider = Readonly>; @@ -608,7 +608,13 @@ export const evidenceEnvelopeForAdmission = ( raw_result: observation.rawResult ?? null, normalized_result: observation.result, confidence: observation.confidence ?? "observed", - authority: observation.authority ?? "shipped-artifact", + // Only a subject that names an identified target can support shipment + // authority; an unknown target names no artifact and claims none. + authority: + observation.authority ?? + (subject.identity.kind === "unknown" + ? "analyst-inference" + : "shipped-artifact"), environment: observation.environment ?? null, limitations: observation.limitations ?? [], ...(observation.relationshipCoverage === undefined diff --git a/src/gdb/GdbProviderIdentity.ts b/src/gdb/GdbProviderIdentity.ts index 39aae64fee..2d9eac2356 100644 --- a/src/gdb/GdbProviderIdentity.ts +++ b/src/gdb/GdbProviderIdentity.ts @@ -7,6 +7,12 @@ export const GDB_PROVIDER_IDENTITY = { version: null, } as const; +/** + * GDB observations come from a session REA runs and whose target it names, so + * every retention path claims the same controlled replay. + */ +export const GDB_OBSERVATION_AUTHORITY = "controlled-replay" as const; + /** Provider identity with the version this GDB reported, or null when unknown. */ export interface GdbProviderIdentity { readonly id: typeof GDB_PROVIDER_IDENTITY.id; diff --git a/src/gdb/GdbSessionManager.ts b/src/gdb/GdbSessionManager.ts index 7b2d8d81bd..1b992aec40 100644 --- a/src/gdb/GdbSessionManager.ts +++ b/src/gdb/GdbSessionManager.ts @@ -21,6 +21,7 @@ import { type GdbMiValue, } from "./GdbMiRecord.js"; import { + GDB_OBSERVATION_AUTHORITY, GDB_PROVIDER_IDENTITY, gdbReportedVersion, type GdbProviderIdentity, @@ -419,13 +420,17 @@ const createGdbSessionEvidence = ( }, ): Evidence => { const { provenance, unobservedReason } = session.launchFile; + const withAuthority = { + ...observation, + authority: observation.authority ?? GDB_OBSERVATION_AUTHORITY, + }; return createEvidence( gdbSessionSubject(session), session.provider, provenance === undefined - ? observation + ? withAuthority : { - ...observation, + ...withAuthority, parameters: { ...observation.parameters, launch_provenance: { ...provenance }, diff --git a/src/ports/AnalysisProvider.ts b/src/ports/AnalysisProvider.ts index 6f7786df23..7abe53b71c 100644 --- a/src/ports/AnalysisProvider.ts +++ b/src/ports/AnalysisProvider.ts @@ -15,6 +15,7 @@ import type { JsonValue } from "../domain/jsonValue.js"; import type { Result } from "../domain/result.js"; import type { Evidence, + EvidenceAuthority, EvidenceLocation, EvidenceSubjectTarget, } from "../domain/evidence.js"; @@ -117,7 +118,7 @@ export interface AnalysisExecution extends AnalysisObservation { readonly siblingUnavailability?: AnalysisCapabilityUnavailableError; } -interface CreateAnalysisExecutionOptions { +export interface CreateAnalysisExecutionOptions { readonly rawResult?: unknown; readonly pseudocodeAbsence?: PseudocodeAbsence; readonly sourceDescriptor?: AnalysisSourceDescriptor; @@ -133,6 +134,7 @@ interface CreateAnalysisExecutionOptions { readonly locations?: readonly EvidenceLocation[]; readonly sourceEvidence?: readonly Evidence[]; readonly subject?: EvidenceSubjectTarget | null; + readonly authority?: EvidenceAuthority; } /** @@ -212,6 +214,9 @@ export function createAnalysisExecution( ? {} : { sourceEvidence: Object.freeze([...options.sourceEvidence]) }), ...(options.subject === undefined ? {} : { subject: options.subject }), + ...(options.authority === undefined + ? {} + : { authority: options.authority }), }; } diff --git a/src/rizin/RizinDebugSessionManager.ts b/src/rizin/RizinDebugSessionManager.ts index ac47aae3fa..c15709b361 100644 --- a/src/rizin/RizinDebugSessionManager.ts +++ b/src/rizin/RizinDebugSessionManager.ts @@ -142,6 +142,7 @@ const createRizinCommandEvidence = ({ }, result: { ...result }, rawResult: { ...result }, + authority: "controlled-replay", limitations: [ RIZIN_SESSION_TARGET_LIMITATION, ...(launchTarget.unobservedReason === undefined diff --git a/tests/boundary/providers/CutterBridgeService.test.ts b/tests/boundary/providers/CutterBridgeService.test.ts index a8a531d5a6..94db8c8da9 100644 --- a/tests/boundary/providers/CutterBridgeService.test.ts +++ b/tests/boundary/providers/CutterBridgeService.test.ts @@ -103,6 +103,48 @@ it.each(["descriptor-first", "command-first"] as const)( }, ); +it("classifies confirmed command observations as external-service, not controlled-replay", async () => { + const service = new CutterBridgeService({ + listSessions: async () => ({ + sessions: [], + bridge_directory: "/private/bridge", + discovery_status: "no_live_bridge_found", + bridge_directory_security: "private_verified", + }), + execute: async () => ({ + requestId: "4b18ce4d-bf31-456e-ae31-e8c547b2f9db", + output: { sections: "4" }, + currentFile: "/fixtures/sample.bin", + documentGeneration: 7, + identityStatus: "partial", + cutterVersion: "Cutter fixture version", + executionState: "complete", + error: null, + message: null, + outputTruncated: false, + }), + }); + + const result = await service.execute({ + session_id: "27d3e3f1-f1e5-49ae-91ec-95af1f343a5a", + expected_generation: 7, + command: "pd 4", + }); + if (!result.ok) throw new Error("Expected confirmed dispatch to succeed"); + + expect(result.value).toMatchObject({ + authority: "external-service", + normalized_result: { + command: "pd 4", + execution_state: "complete", + }, + limitations: expect.arrayContaining([ + "Document identity is partial: the bridge uses a plugin instance UUID and observed generation; a same-path tab switch or reload may not be distinguishable.", + ]), + }); + expect(result.value).not.toHaveProperty("authority", "controlled-replay"); +}); + it("retains uncertain command completion as Evidence without encouraging a retry", async () => { const service = new CutterBridgeService({ listSessions: async () => ({ diff --git a/tests/boundary/providers/GdbSessionManagerCoverage.test.ts b/tests/boundary/providers/GdbSessionManagerCoverage.test.ts index 894576dfb7..77a7419c9c 100644 --- a/tests/boundary/providers/GdbSessionManagerCoverage.test.ts +++ b/tests/boundary/providers/GdbSessionManagerCoverage.test.ts @@ -3398,6 +3398,25 @@ it("retains an exited GDB session when no inferior identity was captured", async expect(manager.status(started.value.session_id)).toBeDefined(); }); +it("labels the retained process-exit observation as controlled replay", async () => { + const manager = await managerFor( + responsiveProvider(` + if (match[2].includes('auto-load off')) process.stdout.write(match[1] + '^done\\n'); + else process.exit(3); + `), + ); + const started = await expectGdbSessionStarted(manager); + + const executed = await manager.execute(started.value.session_id, "exit now"); + expect(executed).toMatchObject({ + ok: false, + error: { + cleanupIncomplete: true, + partialObservation: { authority: "controlled-replay" }, + }, + }); +}); + it("retains a session when closing cannot confirm the debugger process stopped", async () => { let stopCalls = 0; const provider = await createProvider(responsiveProvider());