Files
reverse-engineering-anything/src/application/javascript/StaticObservedEndpointComparisonService.ts
T
morluto 2826592759 refactor(application): build application cancellations with a required reason (#10574)
* refactor(application): build application cancellations with a required reason

Migrate every AnalysisCancelledError construction under src/application
to cancelledBy and lower the guard baseline from 671 to 442.

Shutdown refusals in BinarySession report OwnerCancellation.ownerClosed
when the caller did not abort, instead of an undefined reason.
ReverseEngineeringService and DesktopBuildOwnedWork close their work
with the typed owner reason. SharedStartupAttempt returns the departing
caller's reason with a cancelled wait. One shared isAborted predicate
replaces eleven local copies and narrows a checked signal for
cancelledBy.

* refactor(desktop): drop an unused cancellation import from desktop capture state
2026-11-15 18:38:24 +08:00

239 lines
8.9 KiB
TypeScript

import type { WebNetworkCapture } from "../../domain/webNetworkCapture.js";
import { setImmediate } from "node:timers/promises";
import { compareStaticObservedEndpointsRequestSchema } from "../../contracts/javascript/applicationWorkflowInputContracts.js";
import { createEvidence, type Evidence } from "../../domain/evidence.js";
import { readImmutableEvidence } from "../../domain/evidenceValidation.js";
import type { AnalysisError } from "../../domain/analysisErrorBase.js";
import type { EvidenceWorkflowExecution } from "../investigation/EvidenceWorkflowExecution.js";
import {
AnalysisInputError,
cancelledBy,
} from "../../domain/analysisErrorCore.js";
import { digestCanonicalValue } from "../../domain/canonicalDigest.js";
import { err, ok, type Result } from "../../domain/result.js";
import { JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER } from "../../domain/investigationProviders.js";
import { WebNetworkApiSurfaceAccumulator } from "../../domain/analysisView/WebNetworkApiSurfaceAccumulator.js";
import { admitHarCaptureParent } from "../../domain/analysisView/WebNetworkProjectionAccumulator.js";
import { compareStaticObservedEndpoints } from "../../domain/javascript/staticObservedEndpoints.js";
import type { StaticObservedEndpointComparison } from "../../domain/javascript/staticObservedEndpointSchemas.js";
import {
resolveEvidenceRequest,
type EvidenceLookup,
} from "../EvidenceInputResolver.js";
import {
applicationGraphEvidenceInputError,
parseApplicationGraphEvidence,
type ApplicationGraphEvidenceSource,
} from "./JavaScriptApplicationEvidenceGraph.js";
const OPERATION = "compare_static_and_observed_endpoints";
interface EndpointComparisonExecution extends EvidenceWorkflowExecution {
readonly result: StaticObservedEndpointComparison;
}
interface ComparisonSources {
readonly application: ApplicationGraphEvidenceSource;
readonly capture: WebNetworkCapture;
readonly captureEvidence: Evidence;
readonly origin: string | undefined;
}
type ComparisonOptions = { readonly signal?: AbortSignal };
type ComparisonFacts = Pick<
StaticObservedEndpointComparison,
"static_endpoints" | "observed_groups" | "matches" | "summary"
>;
const readSources = (
rawInput: unknown,
lookup: EvidenceLookup | undefined,
accumulator: WebNetworkApiSurfaceAccumulator,
options: ComparisonOptions,
): Result<ComparisonSources, AnalysisError> => {
const request = resolveEvidenceRequest(
OPERATION,
rawInput,
compareStaticObservedEndpointsRequestSchema,
lookup,
{
...options,
readEvidence: (value) => {
const admitted = accumulator.admitInlineEvidence(value);
return admitted.ok ? readImmutableEvidence(value) : admitted;
},
},
);
if (!request.ok) return request;
const input = request.value.input;
const source = parseApplicationGraphEvidence(input.application, [
"application",
]);
if (!source.ok)
return err(applicationGraphEvidenceInputError(OPERATION, source.error));
if (source.value.kind !== "static-application")
return err(
new AnalysisInputError(OPERATION, undefined, [
{
path: ["application"],
reason: "invalid_value",
message:
"Use analyze_javascript_application Evidence; reconciled, managed and web-bundle graphs are outside this comparison's static scope.",
},
]),
);
const captureEvidence = input.capture;
const admitted = admitHarCaptureParent(
{
evidenceId: captureEvidence.evidence_id,
operation: captureEvidence.operation,
predicateType: captureEvidence.predicate_type,
normalizedResult: captureEvidence.normalized_result,
subject: captureEvidence.subject,
parameters: captureEvidence.parameters,
limitations: captureEvidence.limitations,
},
"api-surface",
accumulator,
{ operation: OPERATION, sourceField: "capture" },
);
if (!admitted.ok) return admitted;
return ok({
application: source.value,
capture: admitted.value,
captureEvidence,
origin: input.origin,
});
};
const sourceCoverage = (
{ application, capture, captureEvidence }: ComparisonSources,
excluded: number,
): StaticObservedEndpointComparison["source_coverage"] => ({
application: {
status: application.graph.coverage.status,
truncated: application.graph.coverage.truncated,
omitted_count: application.graph.coverage.omitted_count,
limit_count: application.graph.coverage.limits.length,
limitation_count: new Set([
...application.evidence.limitations,
...application.graph.limitations,
]).size,
},
capture_limitation_count: new Set([
...captureEvidence.limitations,
...capture.limitations,
]).size,
observed_records_examined: capture.records.length,
observed_records_total: capture.total_records,
observed_records_excluded: excluded,
});
const createComparison = (
sources: ComparisonSources,
comparison: ComparisonFacts,
accumulator: WebNetworkApiSurfaceAccumulator,
): Result<EndpointComparisonExecution, AnalysisError> => {
const { application, capture, captureEvidence, origin } = sources;
const evidenceLinks = [
application.evidence.evidence_id,
captureEvidence.evidence_id,
].sort();
const limitations = [
"Source-specific limitation details remain on the two source Evidence records; source_coverage reports their counts without copying unrelated capture or graph text.",
"Not-observed-in-capture refers only to this capture; it does not establish unused, hidden, inaccessible or absent server behavior.",
"Template-compatible pairs are inferred format matches, not handler identity or runtime execution proof. Unknown static methods are never filled from observed methods.",
"Observed-without-static-match means no confirmed correspondence in the supplied static observations; incomplete static discovery can miss code references.",
...(origin === undefined
? []
: [
"The origin for root-relative static targets is a caller assertion, not an observed application base URL.",
]),
].sort();
const admittedLimitations = accumulator.addLimitations(limitations);
if (!admittedLimitations.ok) return admittedLimitations;
const parameters = {
application_evidence_id: application.evidence.evidence_id,
capture_evidence_id: captureEvidence.evidence_id,
origin: origin ?? null,
};
const result: StaticObservedEndpointComparison = {
comparison_id: `endpoint_comparison_${digestCanonicalValue(parameters)}`,
application: {
evidence_id: application.evidence.evidence_id,
graph_id: application.graph.graph_id,
},
capture: {
evidence_id: captureEvidence.evidence_id,
artifact: {
path: capture.artifact.path,
sha256: capture.artifact.sha256,
},
},
declared_origin: origin ?? null,
...comparison,
source_coverage: sourceCoverage(
sources,
accumulator.comparisonCoverage().excluded_records,
),
evidence_links: evidenceLinks,
limitations,
};
const evidence: Evidence = createEvidence(
undefined,
JAVASCRIPT_APPLICATION_WORKFLOW_PROVIDER,
{
predicateType: "rea.static-observed-endpoint-comparison",
operation: OPERATION,
parameters,
result,
rawResult: null,
confidence: "inferred",
authority: "analyst-inference",
environment: null,
limitations,
evidenceLinks,
},
);
return ok({
evidence,
result,
sources: [application.evidence, captureEvidence],
});
};
/** Authenticate sources once, group cooperatively, then publish the completed comparison. */
export const compareStaticAndObservedEndpointsEvidence = async (
rawInput: unknown,
lookup?: EvidenceLookup,
options: ComparisonOptions = {},
): Promise<Result<EndpointComparisonExecution, AnalysisError>> => {
const accumulator = new WebNetworkApiSurfaceAccumulator(undefined, false, {
operation: OPERATION,
});
const admitted = readSources(rawInput, lookup, accumulator, options);
if (!admitted.ok) return admitted;
const sources = admitted.value;
const { capture, captureEvidence } = sources;
for (const [index, record] of capture.records.entries()) {
if (index % 256 === 0) {
await setImmediate();
if (options.signal?.aborted)
return err(cancelledBy(OPERATION, options.signal));
}
const added = accumulator.add(record);
if (!added.ok) return added;
}
const compared = compareStaticObservedEndpoints({
applicationEvidenceId: sources.application.evidence.evidence_id,
captureEvidenceId: captureEvidence.evidence_id,
graph: sources.application.graph,
accumulator,
...(sources.origin === undefined ? {} : { origin: sources.origin }),
captureComplete: capture.records.length === capture.total_records,
});
if (!compared.ok) return compared;
await setImmediate();
if (options.signal?.aborted)
return err(cancelledBy(OPERATION, options.signal));
return createComparison(sources, compared.value, accumulator);
};