native_ipc/lib.rs
1#![doc = include_str!("../README.md")]
2
3#[cfg(not(any(
4 all(
5 target_os = "linux",
6 any(target_arch = "aarch64", target_arch = "x86_64")
7 ),
8 all(
9 target_os = "windows",
10 any(target_arch = "aarch64", target_arch = "x86_64")
11 ),
12 all(target_os = "macos", target_arch = "aarch64")
13)))]
14compile_error!("native-ipc supports Linux and Windows on aarch64/x86_64, and macOS on aarch64");
15
16/// Platform-neutral wire, layout, and sequencing primitives.
17pub use native_ipc_core as core;
18
19/// Checked allocation-free runtime access after batch commit.
20pub mod active;
21#[allow(dead_code)]
22/// Atomic transfer-batch construction, expectations, and committed active sets.
23pub mod batch;
24/// Safe audited binding from committed active mappings to core capabilities.
25pub mod binding;
26/// Common native shared-memory allocation, policy, and cleanup interface.
27pub mod memory;
28/// Platform-neutral consuming region ownership states.
29pub mod region;
30/// Finite session limits, target capabilities, and absolute deadlines.
31pub mod session;
32
33mod backend;
34/// Bounded opaque application-control records and validation errors.
35pub mod control;
36#[allow(dead_code)]
37mod liveness;
38#[allow(dead_code)]
39mod negotiation;
40mod protocol;
41
42/// Runs the fixed macOS broker gate executable boundary without callbacks.
43///
44/// This hidden artifact entry performs no launch effect: it validates the
45/// fixed process vector, FIFO reader, and control stream; receives and
46/// acknowledges one canonical launch plan, waits for one start byte, then
47/// retains the reader until service-death EOF. It exists only so a separately
48/// compiled minimal broker executable can enter reviewed crate-private code.
49///
50/// # Safety
51///
52/// This must run in the just-execed dedicated broker before threads, children,
53/// policy, or effect-bearing endpoints. The exact fixed spawner must
54/// exclusively transfer descriptors 3 and 4 and the installed process vector;
55/// no Rust value may already own either descriptor. `installed_path` must be an
56/// absolute compile-time constant in the deployer's broker artifact and must
57/// not derive from request data. Read-only fixture dispatch over `argv[0]` is
58/// permitted before entry.
59#[cfg(all(target_os = "macos", target_arch = "aarch64"))]
60#[doc(hidden)]
61pub unsafe fn __private_macos_broker_gate_main(installed_path: &std::ffi::CStr) -> ! {
62 // SAFETY: the caller supplies the complete fixed process-entry contract.
63 unsafe { backend::macos::run_fixed_broker_gate_process(installed_path) }
64}
65
66/// Runs the complete fixed macOS broker launcher lifecycle without callbacks.
67///
68/// This hidden artifact entry stages and activates the exact parent plan,
69/// pre-creates its fixed clean-exec authentication worker, spawns the fixed
70/// launcher, delivers the plan, verifies the target at its exec trap, reports
71/// the held trace state, and resumes only after the Ready-bound reverse commit.
72/// Public macOS construction uses the direct-spawn session path and does not
73/// call this entry.
74///
75/// # Safety
76///
77/// This must run in the just-execed dedicated broker before threads, children,
78/// policy, or effect-bearing endpoints. The exact fixed spawner must
79/// exclusively transfer descriptors 3 through 5 and the installed process
80/// vector. Each path must be an absolute compile-time constant in the
81/// deployer's broker artifact, must not derive from request data, and must name
82/// the exact replacement-resistant signed image verified by the installation.
83#[cfg(all(target_os = "macos", target_arch = "aarch64"))]
84#[doc(hidden)]
85pub unsafe fn __private_macos_broker_main(
86 installed_path: &std::ffi::CStr,
87 launcher_path: &std::ffi::CStr,
88 auth_worker_path: &std::ffi::CStr,
89) -> ! {
90 // SAFETY: the caller supplies the complete fixed process-entry contract.
91 unsafe {
92 backend::macos::run_fixed_broker_process(installed_path, launcher_path, auth_worker_path)
93 }
94}
95
96/// Runs the fixed macOS trusted-launcher boundary without callbacks.
97///
98/// The launcher exists because the target is foreign code that cannot trace
99/// itself. This image designates the broker as its tracer, stops for identity
100/// proof, contains itself, then becomes the target. It needs no privilege and
101/// refuses to run as root.
102///
103/// # Safety
104///
105/// This must run in the just-execed launcher before threads, children, or
106/// effect-bearing endpoints exist. The fixed spawner must exclusively transfer
107/// descriptor 3 (broker death) and descriptor 4 (plan) plus the installed
108/// process vector; no Rust value may already own either descriptor.
109/// `installed_path` must be an absolute compile-time constant in the deployer's
110/// launcher artifact and must not derive from request data.
111#[cfg(all(target_os = "macos", target_arch = "aarch64"))]
112#[doc(hidden)]
113pub unsafe fn __private_macos_launcher_main(installed_path: &std::ffi::CStr) -> ! {
114 // SAFETY: the caller supplies the complete fixed process-entry contract.
115 unsafe { backend::macos::run_fixed_launcher_process(installed_path) }
116}
117
118/// Runs the fixed macOS clean-exec authentication-worker boundary.
119///
120/// This hidden artifact entry validates one exact inherited request, performs
121/// the installed fixed Security requirement check against its audit token,
122/// emits one canonical result, and exits. It exists only for a separately
123/// compiled minimal signed worker executable.
124///
125/// # Safety
126///
127/// This must run in the just-execed dedicated worker before threads or
128/// Security.framework initialization. `installed_path`, `requirement`, and
129/// `code_identity` must be compile-time installed-policy constants in that
130/// artifact; `installed_path` must be absolute. None may derive from request
131/// data. The exact spawner must exclusively transfer descriptors 3 and 4 plus
132/// the fixed vector.
133#[cfg(all(target_os = "macos", target_arch = "aarch64"))]
134#[doc(hidden)]
135pub unsafe fn __private_macos_auth_worker_main(
136 installed_path: &std::ffi::CStr,
137 requirement: &std::ffi::CStr,
138 code_identity: [u8; 32],
139) -> ! {
140 // SAFETY: the caller supplies the complete fixed process-entry contract.
141 unsafe {
142 backend::macos::run_fixed_auth_worker_process(installed_path, requirement, code_identity)
143 }
144}