mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 20:53:00 +00:00
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.
This commit is contained in:
1 parent
204056f21a
commit
b99e7737de
15 files changed
+196
-22
No files matched your search
@@ -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 () => {
|
||||
|
||||
+43
-13
@@ -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<string, JsonValue>,
|
||||
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<AnalysisExecution, AnalysisError>,
|
||||
): Result<AnalysisExecution, AnalysisError> =>
|
||||
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,
|
||||
},
|
||||
),
|
||||
},
|
||||
|
||||
@@ -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 () => {
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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.",
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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,
|
||||
});
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -356,7 +356,7 @@ export const evidenceSubjectDisplay = (evidence: {
|
||||
: undefined;
|
||||
};
|
||||
|
||||
type EvidenceAuthority = z.infer<typeof evidenceAuthoritySchema>;
|
||||
export type EvidenceAuthority = z.infer<typeof evidenceAuthoritySchema>;
|
||||
type ExecutionEnvironment = z.infer<typeof executionEnvironmentSchema>;
|
||||
|
||||
export type EvidenceProvider = Readonly<z.output<typeof providerSchema>>;
|
||||
@@ -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
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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 },
|
||||
|
||||
@@ -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 }),
|
||||
};
|
||||
}
|
||||
|
||||
|
||||
@@ -142,6 +142,7 @@ const createRizinCommandEvidence = ({
|
||||
},
|
||||
result: { ...result },
|
||||
rawResult: { ...result },
|
||||
authority: "controlled-replay",
|
||||
limitations: [
|
||||
RIZIN_SESSION_TARGET_LIMITATION,
|
||||
...(launchTarget.unobservedReason === undefined
|
||||
|
||||
@@ -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 () => ({
|
||||
|
||||
@@ -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());
|
||||
|
||||
Reference in new issue
Block a user