1380 lines
44 KiB
TypeScript
1380 lines
44 KiB
TypeScript
import { createHash } from "node:crypto";
|
|
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import { z } from "zod";
|
|
|
|
/** Stable operation names exposed by the Windows native authority boundary. */
|
|
export type WindowsNativeAuthorityOperation =
|
|
| "load_native_authority"
|
|
| "admit_path"
|
|
| "create_private_root"
|
|
| "spawn_owned_process"
|
|
| "observe_process"
|
|
| "wait_for_exit"
|
|
| "close_resource";
|
|
|
|
/** Expected failures translated from the optional native adapter boundary. */
|
|
export type WindowsNativeAuthorityFailureReason =
|
|
| "unavailable"
|
|
| "invalid_input"
|
|
| "policy_rejected"
|
|
| "identity_drift"
|
|
| "access_denied"
|
|
| "resource_exhausted"
|
|
| "timeout"
|
|
| "cancelled"
|
|
| "native_contract_mismatch"
|
|
| "native_failure";
|
|
|
|
/** Provider-neutral failure from one Windows native authority operation. */
|
|
export class WindowsNativeAuthorityError extends Error {
|
|
readonly _tag = "WindowsNativeAuthorityError" as const;
|
|
|
|
constructor(
|
|
readonly operation: WindowsNativeAuthorityOperation,
|
|
readonly reason: WindowsNativeAuthorityFailureReason,
|
|
message: string,
|
|
options?: ErrorOptions,
|
|
) {
|
|
super(message, options);
|
|
}
|
|
}
|
|
|
|
/** Loaded native contract identity used for package and capability diagnostics. */
|
|
export interface WindowsNativeAuthorityIdentity {
|
|
readonly packageName: string;
|
|
readonly packageVersion: string;
|
|
readonly contractVersion: number;
|
|
readonly nodeApiVersion: number;
|
|
readonly artifactSha256: string;
|
|
}
|
|
|
|
/** Cancellation and one absolute deadline shared by every startup phase. */
|
|
export interface WindowsNativeOperationControl {
|
|
readonly deadlineMs: number;
|
|
readonly signal?: AbortSignal;
|
|
}
|
|
|
|
/** Input for atomic path admission under the initial fail-closed policy. */
|
|
export interface WindowsPathAdmissionInput<
|
|
TKind extends "file" | "directory" = "file" | "directory",
|
|
> extends WindowsNativeOperationControl {
|
|
readonly path: string;
|
|
readonly kind: TKind;
|
|
readonly reparsePolicy: "reject_all";
|
|
readonly expectedSha256?: string;
|
|
}
|
|
|
|
interface WindowsAdmittedPathObservation<TKind extends "file" | "directory"> {
|
|
readonly kind: TKind;
|
|
readonly requestedPath: string;
|
|
readonly finalPath: string;
|
|
readonly filesystem: "ntfs";
|
|
readonly volumeIdentity: string;
|
|
readonly fileIdentity: string;
|
|
readonly stableIdentity: string;
|
|
readonly reparseDisposition: "absent";
|
|
}
|
|
|
|
/** Backend observation for a handle-admitted regular file. */
|
|
interface WindowsAdmittedFileObservation
|
|
extends WindowsAdmittedPathObservation<"file"> {
|
|
readonly sha256: string;
|
|
}
|
|
|
|
/** Backend observation for a handle-admitted directory. */
|
|
interface WindowsAdmittedDirectoryObservation
|
|
extends WindowsAdmittedPathObservation<"directory"> {
|
|
readonly sha256: null;
|
|
}
|
|
|
|
const windowsPathIdentitySchema = z.strictObject({
|
|
requestedPath: z.string().min(1),
|
|
finalPath: z.string().min(1),
|
|
filesystem: z.literal("ntfs"),
|
|
volumeIdentity: z.string().regex(/^[0-9a-f]{16}$/u),
|
|
fileIdentity: z.string().regex(/^[0-9a-f]{32}$/u),
|
|
reparseDisposition: z.literal("absent"),
|
|
});
|
|
|
|
const admittedFileObservationSchema = windowsPathIdentitySchema.extend({
|
|
kind: z.literal("file"),
|
|
sha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
|
});
|
|
|
|
const admittedDirectoryObservationSchema = windowsPathIdentitySchema.extend({
|
|
kind: z.literal("directory"),
|
|
sha256: z.null(),
|
|
});
|
|
|
|
const privateDaclObservationSchema = z.strictObject({
|
|
objectKind: z.enum(["directory", "file"]),
|
|
owner: z.literal("current_user"),
|
|
dacl: z.literal("present"),
|
|
protection: z.enum(["protected", "inherited_from_protected_parent"]),
|
|
aceDisposition: z.enum(["explicit", "inherited"]),
|
|
propagation: z.enum(["none", "container_and_object"]),
|
|
additionalTrustees: z.literal("absent"),
|
|
broadAllowEntries: z.literal("absent"),
|
|
currentUserRights: z.enum(["read_execute", "modify"]),
|
|
systemRights: z.literal("full_control"),
|
|
ownerRights: z.literal("write_dac_write_owner_denied"),
|
|
descriptorSha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
|
verifiedObjectCount: z.number().int().nonnegative(),
|
|
policyManifestSha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
|
});
|
|
|
|
const explicitPolicySchema = privateDaclObservationSchema.extend({
|
|
protection: z.literal("protected"),
|
|
aceDisposition: z.literal("explicit"),
|
|
});
|
|
|
|
const rootDirectoryPolicySchema = explicitPolicySchema.extend({
|
|
objectKind: z.literal("directory"),
|
|
propagation: z.literal("none"),
|
|
currentUserRights: z.literal("read_execute"),
|
|
verifiedObjectCount: z.literal(1),
|
|
});
|
|
|
|
const readonlyDirectoryPolicySchema = explicitPolicySchema.extend({
|
|
objectKind: z.literal("directory"),
|
|
propagation: z.literal("container_and_object"),
|
|
currentUserRights: z.literal("read_execute"),
|
|
});
|
|
|
|
const readonlyFilePolicySchema = explicitPolicySchema.extend({
|
|
objectKind: z.literal("file"),
|
|
propagation: z.literal("none"),
|
|
currentUserRights: z.literal("read_execute"),
|
|
});
|
|
|
|
const writableDirectoryPolicySchema = explicitPolicySchema.extend({
|
|
objectKind: z.literal("directory"),
|
|
propagation: z.literal("container_and_object"),
|
|
currentUserRights: z.literal("modify"),
|
|
});
|
|
|
|
const writableFilePolicySchema = privateDaclObservationSchema.extend({
|
|
objectKind: z.literal("file"),
|
|
protection: z.literal("inherited_from_protected_parent"),
|
|
aceDisposition: z.literal("inherited"),
|
|
propagation: z.literal("none"),
|
|
currentUserRights: z.literal("modify"),
|
|
});
|
|
|
|
const privateRootObservationSchema = z.strictObject({
|
|
canonicalPath: z.string().min(1),
|
|
stableIdentity: z.string().min(1),
|
|
state: z.literal("sealed"),
|
|
manifestSha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
|
launchSha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
|
fileCount: z.number().int().nonnegative(),
|
|
directoryCount: z.number().int().nonnegative(),
|
|
totalBytes: z.number().int().nonnegative(),
|
|
entrypoint: z.strictObject({
|
|
relativePath: z.string().min(1),
|
|
sha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
|
stableIdentity: z.string().min(1),
|
|
}),
|
|
security: z.strictObject({
|
|
manifestSha256: z.string().regex(/^[0-9a-f]{64}$/u),
|
|
rootDirectory: rootDirectoryPolicySchema,
|
|
readonlyDirectories: readonlyDirectoryPolicySchema,
|
|
readonlyFiles: readonlyFilePolicySchema,
|
|
writableDirectories: writableDirectoryPolicySchema,
|
|
writableFiles: writableFilePolicySchema,
|
|
}),
|
|
});
|
|
|
|
const jobOwnershipObservationSchema = z.strictObject({
|
|
jobObject: z.literal("dedicated_unnamed"),
|
|
assignment: z.literal("proc_thread_attribute_job_list"),
|
|
processExecution: z.literal("job_assigned_at_creation"),
|
|
killOnJobClose: z.literal("enabled"),
|
|
breakaway: z.literal("disabled"),
|
|
nestedJob: z.literal("absent"),
|
|
ownerHandle: z.literal("retained_non_inheritable"),
|
|
jobHandleOwnership: z.literal("single_rea_handle"),
|
|
inheritedHandles: z.literal("stdio_only"),
|
|
membership: z.literal("verified"),
|
|
});
|
|
|
|
const ownedProcessExitSchema = z.strictObject({
|
|
status: z.enum(["exited", "terminated"]),
|
|
exitCode: z.number().int().nullable(),
|
|
});
|
|
|
|
const ownedProcessCloseSchema = z.strictObject({
|
|
status: z.enum(["already_empty", "terminated"]),
|
|
});
|
|
|
|
const ownedProcessStreamSnapshotSchema = z.strictObject({
|
|
retained: z.instanceof(Uint8Array),
|
|
totalBytes: z.number().int().nonnegative(),
|
|
truncated: z.boolean(),
|
|
});
|
|
|
|
const ownedProcessSnapshotSchema = z.strictObject({
|
|
stdout: ownedProcessStreamSnapshotSchema,
|
|
stderr: ownedProcessStreamSnapshotSchema,
|
|
exit: ownedProcessExitSchema.nullable(),
|
|
});
|
|
|
|
/** Verified provider-neutral policy observations for a private runtime root. */
|
|
interface WindowsPrivateDaclObservation {
|
|
readonly objectKind: "directory" | "file";
|
|
readonly owner: "current_user";
|
|
readonly dacl: "present";
|
|
readonly protection: "protected" | "inherited_from_protected_parent";
|
|
readonly aceDisposition: "explicit" | "inherited";
|
|
readonly propagation: "none" | "container_and_object";
|
|
readonly additionalTrustees: "absent";
|
|
readonly broadAllowEntries: "absent";
|
|
readonly currentUserRights: "read_execute" | "modify";
|
|
readonly systemRights: "full_control";
|
|
readonly ownerRights: "write_dac_write_owner_denied";
|
|
readonly descriptorSha256: string;
|
|
readonly verifiedObjectCount: number;
|
|
readonly policyManifestSha256: string;
|
|
}
|
|
|
|
/** Exact normalized DACL policies read back from a sealed runtime tree. */
|
|
interface WindowsPrivateRootSecurityObservation {
|
|
readonly manifestSha256: string;
|
|
readonly rootDirectory: WindowsPrivateDaclObservation & {
|
|
readonly objectKind: "directory";
|
|
readonly protection: "protected";
|
|
readonly aceDisposition: "explicit";
|
|
readonly propagation: "none";
|
|
readonly currentUserRights: "read_execute";
|
|
readonly verifiedObjectCount: 1;
|
|
};
|
|
readonly readonlyDirectories: WindowsPrivateDaclObservation & {
|
|
readonly objectKind: "directory";
|
|
readonly protection: "protected";
|
|
readonly aceDisposition: "explicit";
|
|
readonly propagation: "container_and_object";
|
|
readonly currentUserRights: "read_execute";
|
|
};
|
|
readonly readonlyFiles: WindowsPrivateDaclObservation & {
|
|
readonly objectKind: "file";
|
|
readonly protection: "protected";
|
|
readonly aceDisposition: "explicit";
|
|
readonly propagation: "none";
|
|
readonly currentUserRights: "read_execute";
|
|
};
|
|
readonly writableDirectories: WindowsPrivateDaclObservation & {
|
|
readonly objectKind: "directory";
|
|
readonly protection: "protected";
|
|
readonly aceDisposition: "explicit";
|
|
readonly propagation: "container_and_object";
|
|
readonly currentUserRights: "modify";
|
|
};
|
|
readonly writableFiles: WindowsPrivateDaclObservation & {
|
|
readonly objectKind: "file";
|
|
readonly protection: "inherited_from_protected_parent";
|
|
readonly aceDisposition: "inherited";
|
|
readonly propagation: "none";
|
|
readonly currentUserRights: "modify";
|
|
};
|
|
}
|
|
|
|
/** Verified provider-neutral policy observations for a private runtime root. */
|
|
interface WindowsPrivateRootObservation {
|
|
readonly canonicalPath: string;
|
|
readonly stableIdentity: string;
|
|
readonly state: "sealed";
|
|
readonly manifestSha256: string;
|
|
readonly launchSha256: string;
|
|
readonly fileCount: number;
|
|
readonly directoryCount: number;
|
|
readonly totalBytes: number;
|
|
readonly entrypoint: Readonly<{
|
|
relativePath: string;
|
|
sha256: string;
|
|
stableIdentity: string;
|
|
}>;
|
|
readonly security: WindowsPrivateRootSecurityObservation;
|
|
}
|
|
|
|
/** Hard bounds applied while projecting admitted runtime inputs. */
|
|
interface WindowsRuntimeProjectionLimits {
|
|
readonly entries: number;
|
|
readonly depth: number;
|
|
readonly bytes: number;
|
|
}
|
|
|
|
/** One admitted directory tree assigned a provider-neutral runtime role. */
|
|
interface WindowsRuntimeTreeProjection {
|
|
readonly role: "ghidra" | "jdk";
|
|
readonly source: WindowsAdmittedDirectory;
|
|
readonly destination: string;
|
|
}
|
|
|
|
/** One admitted file assigned a provider-neutral runtime role. */
|
|
interface WindowsRuntimeFileProjection {
|
|
readonly role: "bridge" | "session" | "target";
|
|
readonly source: WindowsAdmittedFile;
|
|
readonly destination: string;
|
|
}
|
|
|
|
/** Immutable bounds applied before an owned process is started. */
|
|
interface WindowsOwnedProcessLimits {
|
|
readonly stdoutBytes: number;
|
|
readonly stderrBytes: number;
|
|
}
|
|
|
|
/** Final process observation independent of Win32 status structures. */
|
|
interface WindowsOwnedProcessExit {
|
|
readonly status: "exited" | "terminated";
|
|
readonly exitCode: number | null;
|
|
}
|
|
|
|
/** Normalized Job Object policy proven before an owned process is returned. */
|
|
interface WindowsJobOwnershipObservation {
|
|
readonly jobObject: "dedicated_unnamed";
|
|
readonly assignment: "proc_thread_attribute_job_list";
|
|
readonly processExecution: "job_assigned_at_creation";
|
|
readonly killOnJobClose: "enabled";
|
|
readonly breakaway: "disabled";
|
|
readonly nestedJob: "absent";
|
|
readonly ownerHandle: "retained_non_inheritable";
|
|
readonly jobHandleOwnership: "single_rea_handle";
|
|
readonly inheritedHandles: "stdio_only";
|
|
readonly membership: "verified";
|
|
readonly policySha256: string;
|
|
}
|
|
|
|
/** Idempotent close observation for a dedicated process Job Object. */
|
|
interface WindowsOwnedProcessClose {
|
|
readonly status: "already_empty" | "terminated";
|
|
}
|
|
|
|
/** One continuously drained stream with bounded retained bytes. */
|
|
interface WindowsOwnedProcessStreamSnapshot {
|
|
readonly retained: Uint8Array;
|
|
readonly totalBytes: number;
|
|
readonly truncated: boolean;
|
|
}
|
|
|
|
/** Detached bounded output and exit observations for one owned process. */
|
|
export interface WindowsOwnedProcessSnapshot {
|
|
readonly stdout: WindowsOwnedProcessStreamSnapshot;
|
|
readonly stderr: WindowsOwnedProcessStreamSnapshot;
|
|
readonly exit: WindowsOwnedProcessExit | null;
|
|
}
|
|
|
|
/** Adapter-private resource token; application callers never receive it. */
|
|
export interface WindowsNativeBackendResource {
|
|
close(): Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
}
|
|
|
|
/** Adapter-private process token with continuously drained bounded output. */
|
|
export interface WindowsNativeBackendProcess
|
|
extends WindowsNativeBackendResource {
|
|
readonly processId: number;
|
|
readonly ownership: unknown;
|
|
snapshot(): WindowsOwnedProcessSnapshot;
|
|
waitForExit(
|
|
signal?: AbortSignal,
|
|
): Promise<Result<WindowsOwnedProcessExit, WindowsNativeAuthorityError>>;
|
|
closeProcess(): Promise<
|
|
Result<WindowsOwnedProcessClose, WindowsNativeAuthorityError>
|
|
>;
|
|
}
|
|
|
|
/** Backend result for one newly admitted file. */
|
|
interface WindowsNativeAdmittedFile {
|
|
readonly resource: WindowsNativeBackendResource;
|
|
readonly observation: unknown;
|
|
}
|
|
|
|
/** Backend result for one newly admitted directory. */
|
|
interface WindowsNativeAdmittedDirectory {
|
|
readonly resource: WindowsNativeBackendResource;
|
|
readonly observation: unknown;
|
|
}
|
|
|
|
/** Backend result for one newly created private root. */
|
|
interface WindowsNativePrivateRoot {
|
|
readonly resource: WindowsNativeBackendResource;
|
|
readonly observation: unknown;
|
|
}
|
|
|
|
/** Adapter-private admitted tree without application wrapper values. */
|
|
interface WindowsNativeRuntimeTreeProjection {
|
|
readonly role: WindowsRuntimeTreeProjection["role"];
|
|
readonly source: WindowsNativeBackendResource;
|
|
readonly destination: string;
|
|
}
|
|
|
|
/** Adapter-private admitted file without application wrapper values. */
|
|
interface WindowsNativeRuntimeFileProjection {
|
|
readonly role: WindowsRuntimeFileProjection["role"];
|
|
readonly source: WindowsNativeBackendResource;
|
|
readonly destination: string;
|
|
}
|
|
|
|
/** Narrow contract implemented by the optional platform package. */
|
|
export interface WindowsNativeAuthorityBackend {
|
|
readonly identity: WindowsNativeAuthorityIdentity | null;
|
|
admitFile(
|
|
input: WindowsPathAdmissionInput<"file">,
|
|
): Promise<Result<WindowsNativeAdmittedFile, WindowsNativeAuthorityError>>;
|
|
admitDirectory(
|
|
input: WindowsPathAdmissionInput<"directory">,
|
|
): Promise<
|
|
Result<WindowsNativeAdmittedDirectory, WindowsNativeAuthorityError>
|
|
>;
|
|
createPrivateRoot(
|
|
input: Readonly<{
|
|
parent: WindowsNativeBackendResource;
|
|
prefix: string;
|
|
trees: readonly WindowsNativeRuntimeTreeProjection[];
|
|
files: readonly WindowsNativeRuntimeFileProjection[];
|
|
writableDirectories: readonly string[];
|
|
entrypoint: Readonly<{
|
|
treeRole: "jdk";
|
|
relativePath: string;
|
|
}>;
|
|
launch: Readonly<{
|
|
arguments: readonly string[];
|
|
environment: Readonly<Record<string, string>>;
|
|
}>;
|
|
limits: WindowsRuntimeProjectionLimits;
|
|
control: WindowsNativeOperationControl;
|
|
}>,
|
|
): Promise<Result<WindowsNativePrivateRoot, WindowsNativeAuthorityError>>;
|
|
spawnOwnedProcess(input: {
|
|
readonly runtimeProjection: WindowsNativeBackendResource;
|
|
readonly limits: WindowsOwnedProcessLimits;
|
|
readonly control: WindowsNativeOperationControl;
|
|
}): Promise<Result<WindowsNativeBackendProcess, WindowsNativeAuthorityError>>;
|
|
}
|
|
|
|
type ResourceStatus = "open" | "closing" | "closed";
|
|
type ResourceKind = "file" | "directory" | "privateRoot" | "process";
|
|
|
|
interface CloseDeferred {
|
|
readonly promise: Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
readonly resolve: (value: Result<void, WindowsNativeAuthorityError>) => void;
|
|
}
|
|
|
|
interface ResourceState {
|
|
readonly owner: WindowsNativeAuthority;
|
|
readonly backend: WindowsNativeBackendResource;
|
|
readonly closeBackend: () => Promise<
|
|
Result<void, WindowsNativeAuthorityError>
|
|
>;
|
|
readonly kind: ResourceKind;
|
|
status: ResourceStatus;
|
|
leaseCount: number;
|
|
closePromise?: Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
closeDeferred?: CloseDeferred;
|
|
}
|
|
|
|
interface ResolvedResource {
|
|
readonly backend: WindowsNativeBackendResource;
|
|
readonly state: ResourceState;
|
|
}
|
|
|
|
interface ResolvedTreeProjection {
|
|
readonly role: WindowsRuntimeTreeProjection["role"];
|
|
readonly backend: WindowsNativeBackendResource;
|
|
readonly destination: string;
|
|
readonly state: ResourceState;
|
|
}
|
|
|
|
interface ResolvedFileProjection {
|
|
readonly role: WindowsRuntimeFileProjection["role"];
|
|
readonly backend: WindowsNativeBackendResource;
|
|
readonly destination: string;
|
|
readonly state: ResourceState;
|
|
}
|
|
|
|
const resourceStates = new WeakMap<object, ResourceState>();
|
|
const backendTokenStates = new WeakMap<
|
|
WindowsNativeBackendResource,
|
|
ResourceState
|
|
>();
|
|
|
|
/** Handle-admitted regular file scoped to its issuing authority instance. */
|
|
export interface WindowsAdmittedFile extends WindowsAdmittedFileObservation {
|
|
/** Close the retained handle once and make the capability unusable. */
|
|
close(): Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
}
|
|
|
|
/** Handle-admitted directory scoped to its issuing authority instance. */
|
|
export interface WindowsAdmittedDirectory
|
|
extends WindowsAdmittedDirectoryObservation {
|
|
/** Close the retained handle once and make the capability unusable. */
|
|
close(): Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
}
|
|
|
|
/** Private runtime root scoped to its issuing authority instance. */
|
|
export interface WindowsPrivateRoot extends WindowsPrivateRootObservation {
|
|
/** Close the retained root authority once and reject later use. */
|
|
close(): Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
}
|
|
|
|
/** Opaque owned process with bounded output and kill-on-close lifetime. */
|
|
export interface WindowsOwnedProcess {
|
|
/** Provider-neutral process identifier retained for diagnostics only. */
|
|
readonly processId: number;
|
|
|
|
/** Parsed Job Object policy associated atomically with process creation. */
|
|
readonly ownership: WindowsJobOwnershipObservation;
|
|
|
|
/** Read the latest detached, bounded output and exit observation. */
|
|
snapshot(): WindowsOwnedProcessSnapshot;
|
|
|
|
/** Wait for exit; cancellation stops only this wait and never closes the job. */
|
|
waitForExit(
|
|
signal?: AbortSignal,
|
|
): Promise<Result<WindowsOwnedProcessExit, WindowsNativeAuthorityError>>;
|
|
|
|
/** Close the Job Object once and observe whether it terminated processes. */
|
|
close(): Promise<
|
|
Result<WindowsOwnedProcessClose, WindowsNativeAuthorityError>
|
|
>;
|
|
}
|
|
|
|
/** Input for creating one private child beneath an admitted directory. */
|
|
export interface WindowsPrivateRootInput extends WindowsNativeOperationControl {
|
|
readonly parent: WindowsAdmittedDirectory;
|
|
readonly prefix: string;
|
|
readonly trees: readonly WindowsRuntimeTreeProjection[];
|
|
readonly files: readonly WindowsRuntimeFileProjection[];
|
|
readonly writableDirectories: readonly string[];
|
|
readonly entrypoint: Readonly<{
|
|
readonly treeRole: "jdk";
|
|
readonly relativePath: string;
|
|
}>;
|
|
readonly launch: Readonly<{
|
|
readonly arguments: readonly string[];
|
|
readonly environment: Readonly<Record<string, string>>;
|
|
}>;
|
|
readonly limits: WindowsRuntimeProjectionLimits;
|
|
}
|
|
|
|
/** Input for native process creation already assigned to its Job Object. */
|
|
export interface WindowsOwnedProcessInput
|
|
extends WindowsNativeOperationControl {
|
|
readonly runtimeProjection: WindowsPrivateRoot;
|
|
readonly limits: WindowsOwnedProcessLimits;
|
|
}
|
|
|
|
const parseAdmittedFileObservation = (
|
|
value: unknown,
|
|
requestedPath: string,
|
|
): Result<WindowsAdmittedFileObservation, WindowsNativeAuthorityError> => {
|
|
const parsed = admittedFileObservationSchema.safeParse(value);
|
|
if (!parsed.success || parsed.data.requestedPath !== requestedPath)
|
|
return malformedAdmissionObservation();
|
|
return ok({
|
|
...parsed.data,
|
|
stableIdentity: stablePathIdentity(parsed.data),
|
|
});
|
|
};
|
|
|
|
const parseAdmittedDirectoryObservation = (
|
|
value: unknown,
|
|
requestedPath: string,
|
|
): Result<WindowsAdmittedDirectoryObservation, WindowsNativeAuthorityError> => {
|
|
const parsed = admittedDirectoryObservationSchema.safeParse(value);
|
|
if (!parsed.success || parsed.data.requestedPath !== requestedPath)
|
|
return malformedAdmissionObservation();
|
|
return ok({
|
|
...parsed.data,
|
|
stableIdentity: stablePathIdentity(parsed.data),
|
|
});
|
|
};
|
|
|
|
const parsePrivateRootObservation = (
|
|
value: unknown,
|
|
): Result<WindowsPrivateRootObservation, WindowsNativeAuthorityError> => {
|
|
const parsed = privateRootObservationSchema.safeParse(value);
|
|
if (
|
|
!parsed.success ||
|
|
parsed.data.fileCount !==
|
|
parsed.data.security.readonlyFiles.verifiedObjectCount +
|
|
parsed.data.security.writableFiles.verifiedObjectCount ||
|
|
parsed.data.directoryCount !==
|
|
1 +
|
|
parsed.data.security.readonlyDirectories.verifiedObjectCount +
|
|
parsed.data.security.writableDirectories.verifiedObjectCount ||
|
|
parsed.data.security.manifestSha256 !==
|
|
privateSecurityManifestSha256(
|
|
parsed.data.manifestSha256,
|
|
parsed.data.launchSha256,
|
|
parsed.data.security,
|
|
)
|
|
)
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
"create_private_root",
|
|
"native_contract_mismatch",
|
|
"Windows native adapter returned an invalid private DACL observation",
|
|
),
|
|
);
|
|
return ok(parsed.data);
|
|
};
|
|
|
|
const privateSecurityManifestSha256 = (
|
|
projectionManifestSha256: string,
|
|
launchSha256: string,
|
|
security: Omit<WindowsPrivateRootSecurityObservation, "manifestSha256">,
|
|
): string => {
|
|
const commitment = {
|
|
version: 1,
|
|
projectionManifestSha256,
|
|
launchSha256,
|
|
rootDirectory: policyCommitment(security.rootDirectory),
|
|
readonlyDirectories: policyCommitment(security.readonlyDirectories),
|
|
readonlyFiles: policyCommitment(security.readonlyFiles),
|
|
writableDirectories: policyCommitment(security.writableDirectories),
|
|
writableFiles: policyCommitment(security.writableFiles),
|
|
};
|
|
return createHash("sha256").update(JSON.stringify(commitment)).digest("hex");
|
|
};
|
|
|
|
const policyCommitment = (policy: WindowsPrivateDaclObservation) => ({
|
|
verifiedObjectCount: policy.verifiedObjectCount,
|
|
policyManifestSha256: policy.policyManifestSha256,
|
|
});
|
|
|
|
const jobOwnershipPolicySha256 = (
|
|
ownership: Omit<WindowsJobOwnershipObservation, "policySha256">,
|
|
): string =>
|
|
createHash("sha256")
|
|
.update(
|
|
JSON.stringify({
|
|
version: 1,
|
|
jobObject: ownership.jobObject,
|
|
assignment: ownership.assignment,
|
|
processExecution: ownership.processExecution,
|
|
killOnJobClose: ownership.killOnJobClose,
|
|
breakaway: ownership.breakaway,
|
|
nestedJob: ownership.nestedJob,
|
|
ownerHandle: ownership.ownerHandle,
|
|
jobHandleOwnership: ownership.jobHandleOwnership,
|
|
inheritedHandles: ownership.inheritedHandles,
|
|
membership: ownership.membership,
|
|
}),
|
|
)
|
|
.digest("hex");
|
|
|
|
const stablePathIdentity = (identity: {
|
|
readonly filesystem: "ntfs";
|
|
readonly volumeIdentity: string;
|
|
readonly fileIdentity: string;
|
|
}): string =>
|
|
`${identity.filesystem}:${identity.volumeIdentity}:${identity.fileIdentity}`;
|
|
|
|
const malformedAdmissionObservation = <T>(): Result<
|
|
T,
|
|
WindowsNativeAuthorityError
|
|
> =>
|
|
err(
|
|
new WindowsNativeAuthorityError(
|
|
"admit_path",
|
|
"native_contract_mismatch",
|
|
"Windows native adapter returned an invalid path identity observation",
|
|
),
|
|
);
|
|
|
|
/** Application-owned authority wrapper that scopes every native resource. */
|
|
export class WindowsNativeAuthority {
|
|
constructor(readonly backend: WindowsNativeAuthorityBackend) {}
|
|
|
|
/** Loaded native contract identity after package validation. */
|
|
get identity(): WindowsNativeAuthorityIdentity | null {
|
|
return this.backend.identity;
|
|
}
|
|
|
|
/** Admit one file or directory without following a reparse point. */
|
|
admitPath(
|
|
input: WindowsPathAdmissionInput<"file">,
|
|
): Promise<Result<WindowsAdmittedFile, WindowsNativeAuthorityError>>;
|
|
admitPath(
|
|
input: WindowsPathAdmissionInput<"directory">,
|
|
): Promise<Result<WindowsAdmittedDirectory, WindowsNativeAuthorityError>>;
|
|
async admitPath(
|
|
input: WindowsPathAdmissionInput,
|
|
): Promise<
|
|
Result<
|
|
WindowsAdmittedFile | WindowsAdmittedDirectory,
|
|
WindowsNativeAuthorityError
|
|
>
|
|
> {
|
|
const admissionInput: WindowsPathAdmissionInput = {
|
|
path: input.path,
|
|
kind: input.kind,
|
|
reparsePolicy: input.reparsePolicy,
|
|
deadlineMs: input.deadlineMs,
|
|
...(input.expectedSha256 === undefined
|
|
? {}
|
|
: { expectedSha256: input.expectedSha256 }),
|
|
...(input.signal === undefined ? {} : { signal: input.signal }),
|
|
};
|
|
|
|
if (input.kind === "file") {
|
|
const admitted = await this.backend.admitFile(
|
|
admissionInput as WindowsPathAdmissionInput<"file">,
|
|
);
|
|
if (!admitted.ok) return admitted;
|
|
const observation = parseAdmittedFileObservation(
|
|
admitted.value.observation,
|
|
admissionInput.path,
|
|
);
|
|
if (!observation.ok) {
|
|
await poisonAliasedToken(admitted.value.resource, () =>
|
|
admitted.value.resource.close(),
|
|
);
|
|
return observation;
|
|
}
|
|
const resource = createResource({
|
|
authority: this,
|
|
operation: "admit_path",
|
|
kind: "file",
|
|
observation: observation.value,
|
|
backend: admitted.value.resource,
|
|
});
|
|
if (!resource.ok)
|
|
await poisonAliasedToken(admitted.value.resource, () =>
|
|
admitted.value.resource.close(),
|
|
);
|
|
return resource;
|
|
}
|
|
|
|
const admitted = await this.backend.admitDirectory(
|
|
admissionInput as WindowsPathAdmissionInput<"directory">,
|
|
);
|
|
if (!admitted.ok) return admitted;
|
|
const observation = parseAdmittedDirectoryObservation(
|
|
admitted.value.observation,
|
|
admissionInput.path,
|
|
);
|
|
if (!observation.ok) {
|
|
await poisonAliasedToken(admitted.value.resource, () =>
|
|
admitted.value.resource.close(),
|
|
);
|
|
return observation;
|
|
}
|
|
const resource = createResource({
|
|
authority: this,
|
|
operation: "admit_path",
|
|
kind: "directory",
|
|
observation: observation.value,
|
|
backend: admitted.value.resource,
|
|
});
|
|
if (!resource.ok)
|
|
await poisonAliasedToken(admitted.value.resource, () =>
|
|
admitted.value.resource.close(),
|
|
);
|
|
return resource;
|
|
}
|
|
|
|
/** Create and verify a protected runtime root beneath owned authority. */
|
|
async createPrivateRoot(
|
|
input: WindowsPrivateRootInput,
|
|
): Promise<Result<WindowsPrivateRoot, WindowsNativeAuthorityError>> {
|
|
const prefix = input.prefix;
|
|
const writableDirectories = [...input.writableDirectories];
|
|
const entrypoint = {
|
|
treeRole: input.entrypoint.treeRole,
|
|
relativePath: input.entrypoint.relativePath,
|
|
};
|
|
const launch = {
|
|
arguments: [...input.launch.arguments],
|
|
environment: { ...input.launch.environment },
|
|
};
|
|
const limits = {
|
|
entries: input.limits.entries,
|
|
depth: input.limits.depth,
|
|
bytes: input.limits.bytes,
|
|
};
|
|
const controlSnapshot = control(input);
|
|
|
|
const parent = ownedResource(
|
|
this,
|
|
input.parent,
|
|
"create_private_root",
|
|
"directory",
|
|
);
|
|
if (!parent.ok) return parent;
|
|
|
|
const trees = ownedRuntimeTrees(this, input.trees);
|
|
if (!trees.ok) return trees;
|
|
|
|
const files = ownedRuntimeFiles(this, input.files);
|
|
if (!files.ok) return files;
|
|
|
|
const leases: ResourceState[] = [
|
|
parent.value.state,
|
|
...trees.value.map((tree) => tree.state),
|
|
...files.value.map((file) => file.state),
|
|
];
|
|
const leased = acquireLeases(leases, "create_private_root");
|
|
if (!leased.ok) return leased;
|
|
|
|
try {
|
|
const created = await this.backend.createPrivateRoot({
|
|
parent: parent.value.backend,
|
|
prefix,
|
|
trees: trees.value.map((tree) => ({
|
|
role: tree.role,
|
|
source: tree.backend,
|
|
destination: tree.destination,
|
|
})),
|
|
files: files.value.map((file) => ({
|
|
role: file.role,
|
|
source: file.backend,
|
|
destination: file.destination,
|
|
})),
|
|
writableDirectories,
|
|
entrypoint,
|
|
launch,
|
|
limits,
|
|
control: controlSnapshot,
|
|
});
|
|
if (!created.ok) return created;
|
|
const observation = parsePrivateRootObservation(
|
|
created.value.observation,
|
|
);
|
|
if (!observation.ok) {
|
|
await poisonAliasedToken(created.value.resource, () =>
|
|
created.value.resource.close(),
|
|
);
|
|
return observation;
|
|
}
|
|
const resource = createResource({
|
|
authority: this,
|
|
operation: "create_private_root",
|
|
kind: "privateRoot",
|
|
observation: observation.value,
|
|
backend: created.value.resource,
|
|
});
|
|
if (!resource.ok)
|
|
await poisonAliasedToken(created.value.resource, () =>
|
|
created.value.resource.close(),
|
|
);
|
|
return resource;
|
|
} finally {
|
|
releaseLeases(leases);
|
|
}
|
|
}
|
|
|
|
/** Spawn a process atomically assigned to a dedicated kill-on-close job. */
|
|
async spawnOwnedProcess(
|
|
input: WindowsOwnedProcessInput,
|
|
): Promise<Result<WindowsOwnedProcess, WindowsNativeAuthorityError>> {
|
|
const limits = {
|
|
stdoutBytes: input.limits.stdoutBytes,
|
|
stderrBytes: input.limits.stderrBytes,
|
|
};
|
|
const controlSnapshot = control(input);
|
|
|
|
const runtimeProjection = ownedResource(
|
|
this,
|
|
input.runtimeProjection,
|
|
"spawn_owned_process",
|
|
"privateRoot",
|
|
);
|
|
if (!runtimeProjection.ok) return runtimeProjection;
|
|
|
|
const leases: ResourceState[] = [runtimeProjection.value.state];
|
|
const leased = acquireLeases(leases, "spawn_owned_process");
|
|
if (!leased.ok) return leased;
|
|
|
|
try {
|
|
const spawned = await this.backend.spawnOwnedProcess({
|
|
runtimeProjection: runtimeProjection.value.backend,
|
|
limits,
|
|
control: controlSnapshot,
|
|
});
|
|
if (!spawned.ok) return spawned;
|
|
const process = createOwnedProcess(this, spawned.value, limits);
|
|
if (!process.ok)
|
|
await poisonAliasedToken(spawned.value, async () => {
|
|
await spawned.value.closeProcess();
|
|
});
|
|
return process;
|
|
} finally {
|
|
releaseLeases(leases);
|
|
}
|
|
}
|
|
}
|
|
|
|
const registerBackend = (
|
|
authority: WindowsNativeAuthority,
|
|
kind: ResourceKind,
|
|
backend: WindowsNativeBackendResource,
|
|
operation: WindowsNativeAuthorityOperation,
|
|
closeBackend: ResourceState["closeBackend"],
|
|
): Result<ResourceState, WindowsNativeAuthorityError> => {
|
|
const existing = backendTokenStates.get(backend);
|
|
if (existing !== undefined) {
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
operation,
|
|
"native_contract_mismatch",
|
|
existing.kind === kind
|
|
? "Windows native backend token is already registered"
|
|
: "Windows native backend token is registered with a different kind",
|
|
),
|
|
);
|
|
}
|
|
|
|
const state: ResourceState = {
|
|
owner: authority,
|
|
backend,
|
|
closeBackend,
|
|
kind,
|
|
status: "open",
|
|
leaseCount: 0,
|
|
};
|
|
backendTokenStates.set(backend, state);
|
|
return ok(state);
|
|
};
|
|
|
|
const poisonAliasedToken = async (
|
|
backend: WindowsNativeBackendResource,
|
|
cleanup: () => Promise<unknown>,
|
|
): Promise<void> => {
|
|
const existing = backendTokenStates.get(backend);
|
|
if (existing !== undefined) {
|
|
if (existing.status === "closed") return;
|
|
existing.status = "closing";
|
|
if (existing.leaseCount > 0) {
|
|
existing.closeDeferred ??= createDeferredClose();
|
|
return;
|
|
}
|
|
existing.closePromise ??= safeCloseBackend(existing).then((result) => {
|
|
existing.status = "closed";
|
|
return result;
|
|
});
|
|
await existing.closePromise;
|
|
return;
|
|
}
|
|
try {
|
|
await cleanup();
|
|
} catch {
|
|
// The contract mismatch remains the caller-visible failure; the token is
|
|
// poisoned even if the malformed backend also rejects cleanup.
|
|
} finally {
|
|
// A fresh malformed token has no wrapper state to retain.
|
|
}
|
|
};
|
|
|
|
const safeCloseBackend = async (
|
|
state: ResourceState,
|
|
): Promise<Result<void, WindowsNativeAuthorityError>> => {
|
|
try {
|
|
return await state.closeBackend();
|
|
} catch (cause: unknown) {
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
"close_resource",
|
|
"native_failure",
|
|
"Windows native resource cleanup failed",
|
|
{ cause },
|
|
),
|
|
);
|
|
}
|
|
};
|
|
|
|
const ownedResource = (
|
|
authority: WindowsNativeAuthority,
|
|
resource: object,
|
|
operation: WindowsNativeAuthorityOperation,
|
|
expectedKind: ResourceKind,
|
|
): Result<ResolvedResource, WindowsNativeAuthorityError> => {
|
|
const state = resourceStates.get(resource);
|
|
if (state === undefined || state.owner !== authority)
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
operation,
|
|
"invalid_input",
|
|
"Windows native resource does not belong to this authority",
|
|
),
|
|
);
|
|
if (state.status !== "open")
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
operation,
|
|
"identity_drift",
|
|
"Windows native resource is already closed",
|
|
),
|
|
);
|
|
if (state.kind !== expectedKind)
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
operation,
|
|
"native_contract_mismatch",
|
|
`Windows native resource is not a ${expectedKind}`,
|
|
),
|
|
);
|
|
return ok({ backend: state.backend, state });
|
|
};
|
|
|
|
const ownedRuntimeTrees = (
|
|
authority: WindowsNativeAuthority,
|
|
trees: readonly WindowsRuntimeTreeProjection[],
|
|
): Result<readonly ResolvedTreeProjection[], WindowsNativeAuthorityError> => {
|
|
const projected: ResolvedTreeProjection[] = [];
|
|
for (const tree of trees) {
|
|
const source = ownedResource(
|
|
authority,
|
|
tree.source,
|
|
"create_private_root",
|
|
"directory",
|
|
);
|
|
if (!source.ok) return source;
|
|
projected.push({
|
|
role: tree.role,
|
|
backend: source.value.backend,
|
|
destination: tree.destination,
|
|
state: source.value.state,
|
|
});
|
|
}
|
|
return ok(projected);
|
|
};
|
|
|
|
const ownedRuntimeFiles = (
|
|
authority: WindowsNativeAuthority,
|
|
files: readonly WindowsRuntimeFileProjection[],
|
|
): Result<readonly ResolvedFileProjection[], WindowsNativeAuthorityError> => {
|
|
const projected: ResolvedFileProjection[] = [];
|
|
for (const file of files) {
|
|
const source = ownedResource(
|
|
authority,
|
|
file.source,
|
|
"create_private_root",
|
|
"file",
|
|
);
|
|
if (!source.ok) return source;
|
|
projected.push({
|
|
role: file.role,
|
|
backend: source.value.backend,
|
|
destination: file.destination,
|
|
state: source.value.state,
|
|
});
|
|
}
|
|
return ok(projected);
|
|
};
|
|
|
|
const acquireLeases = (
|
|
states: readonly ResourceState[],
|
|
operation: WindowsNativeAuthorityOperation,
|
|
): Result<void, WindowsNativeAuthorityError> => {
|
|
const acquired: ResourceState[] = [];
|
|
for (const state of states) {
|
|
if (state.status !== "open") {
|
|
for (const s of acquired) s.leaseCount--;
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
operation,
|
|
"identity_drift",
|
|
"Windows native resource is already closed",
|
|
),
|
|
);
|
|
}
|
|
state.leaseCount++;
|
|
acquired.push(state);
|
|
}
|
|
return ok(undefined);
|
|
};
|
|
|
|
const releaseLeases = (states: readonly ResourceState[]): void => {
|
|
for (const state of states) {
|
|
state.leaseCount--;
|
|
if (state.leaseCount === 0 && state.status === "closing") {
|
|
state.closePromise = safeCloseBackend(state).then((result) => {
|
|
state.status = "closed";
|
|
state.closeDeferred?.resolve(result);
|
|
return result;
|
|
});
|
|
}
|
|
}
|
|
};
|
|
|
|
/** Construct a fail-closed authority backend when the package is unavailable. */
|
|
export const unavailableWindowsNativeAuthorityBackend = (
|
|
message: string,
|
|
): WindowsNativeAuthorityBackend => ({
|
|
identity: null,
|
|
admitFile: () => Promise.resolve(unavailable("admit_path", message)),
|
|
admitDirectory: () => Promise.resolve(unavailable("admit_path", message)),
|
|
createPrivateRoot: () =>
|
|
Promise.resolve(unavailable("create_private_root", message)),
|
|
spawnOwnedProcess: () =>
|
|
Promise.resolve(unavailable("spawn_owned_process", message)),
|
|
});
|
|
|
|
const createDeferredClose = (): CloseDeferred => {
|
|
let resolve!: (value: Result<void, WindowsNativeAuthorityError>) => void;
|
|
const promise = new Promise<Result<void, WindowsNativeAuthorityError>>(
|
|
(res) => {
|
|
resolve = res;
|
|
},
|
|
);
|
|
return { promise, resolve };
|
|
};
|
|
|
|
const closeResource = (
|
|
resource: object,
|
|
): Promise<Result<void, WindowsNativeAuthorityError>> => {
|
|
const state = resourceStates.get(resource);
|
|
if (state === undefined)
|
|
return Promise.resolve(
|
|
err(
|
|
new WindowsNativeAuthorityError(
|
|
"close_resource",
|
|
"invalid_input",
|
|
"Windows native resource is not owned by REA",
|
|
),
|
|
),
|
|
);
|
|
if (state.status === "closed")
|
|
return state.closePromise ?? Promise.resolve(ok(undefined));
|
|
if (state.status === "closing")
|
|
return (
|
|
state.closeDeferred?.promise ??
|
|
state.closePromise ??
|
|
Promise.resolve(ok(undefined))
|
|
);
|
|
|
|
state.status = "closing";
|
|
if (state.leaseCount === 0) {
|
|
state.closePromise = safeCloseBackend(state).then((result) => {
|
|
state.status = "closed";
|
|
return result;
|
|
});
|
|
return state.closePromise;
|
|
}
|
|
|
|
const deferred = createDeferredClose();
|
|
state.closeDeferred = deferred;
|
|
return deferred.promise;
|
|
};
|
|
|
|
const createResource = <TObservation extends object>(
|
|
input: Readonly<{
|
|
authority: WindowsNativeAuthority;
|
|
operation: WindowsNativeAuthorityOperation;
|
|
kind: Exclude<ResourceKind, "process">;
|
|
observation: TObservation;
|
|
backend: WindowsNativeBackendResource;
|
|
}>,
|
|
): Result<
|
|
TObservation & {
|
|
close(): Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
},
|
|
WindowsNativeAuthorityError
|
|
> => {
|
|
const stateResult = registerBackend(
|
|
input.authority,
|
|
input.kind,
|
|
input.backend,
|
|
input.operation,
|
|
() => input.backend.close(),
|
|
);
|
|
if (!stateResult.ok) return stateResult;
|
|
const resource = {
|
|
...input.observation,
|
|
close: () => closeResource(resource),
|
|
} as TObservation & {
|
|
close(): Promise<Result<void, WindowsNativeAuthorityError>>;
|
|
};
|
|
resourceStates.set(resource, stateResult.value);
|
|
return ok(resource);
|
|
};
|
|
|
|
const createOwnedProcess = (
|
|
authority: WindowsNativeAuthority,
|
|
backend: WindowsNativeBackendProcess,
|
|
limits: WindowsOwnedProcessLimits,
|
|
): Result<WindowsOwnedProcess, WindowsNativeAuthorityError> => {
|
|
const ownership = jobOwnershipObservationSchema.safeParse(backend.ownership);
|
|
if (
|
|
!ownership.success ||
|
|
!Number.isSafeInteger(backend.processId) ||
|
|
backend.processId <= 0
|
|
)
|
|
return err(
|
|
new WindowsNativeAuthorityError(
|
|
"spawn_owned_process",
|
|
"native_contract_mismatch",
|
|
"Windows native adapter returned an invalid Job Object observation",
|
|
),
|
|
);
|
|
const ownershipObservation: WindowsJobOwnershipObservation = {
|
|
...ownership.data,
|
|
policySha256: jobOwnershipPolicySha256(ownership.data),
|
|
};
|
|
const stateResult = registerBackend(
|
|
authority,
|
|
"process",
|
|
backend,
|
|
"spawn_owned_process",
|
|
() =>
|
|
closeOwnedProcess(backend).then((result) =>
|
|
result.ok ? ok(undefined) : result,
|
|
),
|
|
);
|
|
if (!stateResult.ok) return stateResult;
|
|
const state = stateResult.value;
|
|
|
|
let closePromise:
|
|
| Promise<Result<WindowsOwnedProcessClose, WindowsNativeAuthorityError>>
|
|
| undefined;
|
|
const process = {
|
|
processId: backend.processId,
|
|
ownership: ownershipObservation,
|
|
snapshot: () => {
|
|
try {
|
|
return parseProcessSnapshot(backend.snapshot(), limits);
|
|
} catch (cause: unknown) {
|
|
if (cause instanceof WindowsNativeAuthorityError) throw cause;
|
|
throw new WindowsNativeAuthorityError(
|
|
"observe_process",
|
|
"native_failure",
|
|
"Windows native process observation failed",
|
|
{ cause },
|
|
);
|
|
}
|
|
},
|
|
waitForExit: async (signal?: AbortSignal) => {
|
|
try {
|
|
const result = await backend.waitForExit(signal);
|
|
return parseProcessResult<WindowsOwnedProcessExit>(
|
|
result,
|
|
ownedProcessExitSchema,
|
|
"wait_for_exit",
|
|
);
|
|
} catch (cause: unknown) {
|
|
return nativeProcessFailure<WindowsOwnedProcessExit>(
|
|
"wait_for_exit",
|
|
"Windows native process wait failed",
|
|
cause,
|
|
);
|
|
}
|
|
},
|
|
close: () => {
|
|
if (closePromise !== undefined) return closePromise;
|
|
state.status = "closing";
|
|
closePromise = closeOwnedProcess(backend).then((result) => {
|
|
state.status = "closed";
|
|
return result;
|
|
});
|
|
return closePromise;
|
|
},
|
|
};
|
|
resourceStates.set(process, state);
|
|
return ok(process);
|
|
};
|
|
|
|
const parseProcessSnapshot = (
|
|
value: unknown,
|
|
limits: WindowsOwnedProcessLimits,
|
|
): WindowsOwnedProcessSnapshot => {
|
|
const parsed = ownedProcessSnapshotSchema.safeParse(value);
|
|
if (
|
|
!parsed.success ||
|
|
!validStreamSnapshot(parsed.data.stdout, limits.stdoutBytes) ||
|
|
!validStreamSnapshot(parsed.data.stderr, limits.stderrBytes)
|
|
)
|
|
throw new WindowsNativeAuthorityError(
|
|
"observe_process",
|
|
"native_contract_mismatch",
|
|
"Windows native adapter returned an invalid process snapshot",
|
|
);
|
|
return parsed.data;
|
|
};
|
|
|
|
const validStreamSnapshot = (
|
|
stream: WindowsOwnedProcessStreamSnapshot,
|
|
retainedLimit: number,
|
|
): boolean =>
|
|
Number.isSafeInteger(stream.totalBytes) &&
|
|
stream.retained.byteLength <= retainedLimit &&
|
|
stream.retained.byteLength <= stream.totalBytes &&
|
|
stream.truncated === stream.totalBytes > stream.retained.byteLength;
|
|
|
|
const parseProcessResult = <T>(
|
|
value: unknown,
|
|
successSchema: z.ZodType<T>,
|
|
operation: "wait_for_exit" | "close_resource",
|
|
): Result<T, WindowsNativeAuthorityError> => {
|
|
if (typeof value !== "object" || value === null || !("ok" in value))
|
|
return malformedProcessResult(operation);
|
|
const candidate = value as Readonly<Record<string, unknown>>;
|
|
if (candidate.ok === true) {
|
|
if (Object.keys(candidate).length !== 2 || !("value" in candidate))
|
|
return malformedProcessResult(operation);
|
|
const parsed = successSchema.safeParse(candidate.value);
|
|
return parsed.success ? ok(parsed.data) : malformedProcessResult(operation);
|
|
}
|
|
if (
|
|
candidate.ok !== false ||
|
|
Object.keys(candidate).length !== 2 ||
|
|
!(candidate.error instanceof WindowsNativeAuthorityError)
|
|
)
|
|
return malformedProcessResult(operation);
|
|
return err(candidate.error);
|
|
};
|
|
|
|
const malformedProcessResult = <T>(
|
|
operation: "wait_for_exit" | "close_resource",
|
|
): Result<T, WindowsNativeAuthorityError> =>
|
|
err(
|
|
new WindowsNativeAuthorityError(
|
|
operation,
|
|
"native_contract_mismatch",
|
|
"Windows native adapter returned an invalid process result",
|
|
),
|
|
);
|
|
|
|
const nativeProcessFailure = <T>(
|
|
operation: "wait_for_exit" | "close_resource",
|
|
message: string,
|
|
cause: unknown,
|
|
): Result<T, WindowsNativeAuthorityError> =>
|
|
err(
|
|
new WindowsNativeAuthorityError(operation, "native_failure", message, {
|
|
cause,
|
|
}),
|
|
);
|
|
|
|
const closeOwnedProcess = async (
|
|
backend: WindowsNativeBackendProcess,
|
|
): Promise<Result<WindowsOwnedProcessClose, WindowsNativeAuthorityError>> => {
|
|
try {
|
|
return parseProcessResult<WindowsOwnedProcessClose>(
|
|
await backend.closeProcess(),
|
|
ownedProcessCloseSchema,
|
|
"close_resource",
|
|
);
|
|
} catch (cause: unknown) {
|
|
return nativeProcessFailure<WindowsOwnedProcessClose>(
|
|
"close_resource",
|
|
"Windows native process cleanup failed",
|
|
cause,
|
|
);
|
|
}
|
|
};
|
|
|
|
const control = (
|
|
input: WindowsNativeOperationControl,
|
|
): WindowsNativeOperationControl => ({
|
|
deadlineMs: input.deadlineMs,
|
|
...(input.signal === undefined ? {} : { signal: input.signal }),
|
|
});
|
|
|
|
const unavailable = <T>(
|
|
operation: WindowsNativeAuthorityOperation,
|
|
message: string,
|
|
): Result<T, WindowsNativeAuthorityError> =>
|
|
err(new WindowsNativeAuthorityError(operation, "unavailable", message));
|