kobako 0.30.0 → 0.31.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (266) hide show
  1. checksums.yaml +4 -4
  2. data/.release-please-manifest.json +1 -1
  3. data/CHANGELOG.md +335 -0
  4. data/Cargo.lock +469 -11
  5. data/README.md +43 -3
  6. data/ROADMAP.md +1 -1
  7. data/crates/kobako-runtime/CHANGELOG.md +219 -0
  8. data/crates/kobako-runtime/Cargo.toml +51 -3
  9. data/crates/kobako-runtime/README.md +7 -4
  10. data/crates/kobako-runtime/src/cred.rs +124 -0
  11. data/crates/kobako-runtime/src/dispatch.rs +4 -5
  12. data/crates/kobako-runtime/src/endpoint/buffer.rs +153 -44
  13. data/crates/kobako-runtime/src/endpoint/dispatch.rs +80 -41
  14. data/crates/kobako-runtime/src/endpoint/invoke.rs +23 -36
  15. data/crates/kobako-runtime/src/endpoint.rs +137 -36
  16. data/crates/kobako-runtime/src/errno.rs +391 -0
  17. data/crates/kobako-runtime/src/error.rs +31 -10
  18. data/crates/kobako-runtime/src/filesystem/anon_inodes.rs +52 -0
  19. data/crates/kobako-runtime/src/filesystem/bind/lookup.rs +52 -14
  20. data/crates/kobako-runtime/src/filesystem/bind/walk.rs +19 -20
  21. data/crates/kobako-runtime/src/filesystem/bind.rs +437 -245
  22. data/crates/kobako-runtime/src/filesystem/overlay/file.rs +6 -6
  23. data/crates/kobako-runtime/src/filesystem/overlay/path.rs +43 -65
  24. data/crates/kobako-runtime/src/filesystem/overlay/stack/copy_up.rs +9 -16
  25. data/crates/kobako-runtime/src/filesystem/overlay/stack/dir.rs +47 -72
  26. data/crates/kobako-runtime/src/filesystem/overlay/stack/namei.rs +12 -12
  27. data/crates/kobako-runtime/src/filesystem/overlay/stack/readdir.rs +4 -7
  28. data/crates/kobako-runtime/src/filesystem/overlay/stack.rs +121 -37
  29. data/crates/kobako-runtime/src/filesystem/overlay.rs +302 -343
  30. data/crates/kobako-runtime/src/filesystem/pipe.rs +12 -9
  31. data/crates/kobako-runtime/src/filesystem/rdir.rs +15 -32
  32. data/crates/kobako-runtime/src/filesystem/tmpfs/seed.rs +32 -0
  33. data/crates/kobako-runtime/src/filesystem/tmpfs/tmpfile.rs +3 -3
  34. data/crates/kobako-runtime/src/filesystem/tmpfs/whiteout.rs +57 -35
  35. data/crates/kobako-runtime/src/filesystem/tmpfs/xattr.rs +2 -2
  36. data/crates/kobako-runtime/src/filesystem/tmpfs.rs +172 -160
  37. data/crates/kobako-runtime/src/filesystem/wrap.rs +36 -52
  38. data/crates/kobako-runtime/src/filesystem.rs +6 -3
  39. data/crates/kobako-runtime/src/fork.rs +96 -0
  40. data/crates/kobako-runtime/src/grant.rs +3 -0
  41. data/crates/kobako-runtime/src/hashtable.rs +4 -2
  42. data/crates/kobako-runtime/src/lib.rs +18 -7
  43. data/crates/kobako-runtime/src/limits.rs +195 -0
  44. data/crates/kobako-runtime/src/locking.rs +10 -0
  45. data/crates/kobako-runtime/src/memcg.rs +383 -0
  46. data/crates/kobako-runtime/src/mount.rs +67 -9
  47. data/crates/kobako-runtime/src/net/backends.rs +43 -0
  48. data/crates/kobako-runtime/src/net/connections.rs +179 -0
  49. data/crates/kobako-runtime/src/net/credential.rs +125 -0
  50. data/crates/kobako-runtime/src/net/egress.rs +160 -0
  51. data/crates/kobako-runtime/src/net/family.rs +181 -0
  52. data/crates/kobako-runtime/src/net/http.rs +2733 -0
  53. data/crates/kobako-runtime/src/net/lookup.rs +285 -0
  54. data/crates/kobako-runtime/src/net/mock.rs +251 -0
  55. data/crates/kobako-runtime/src/net/namespace.rs +1366 -0
  56. data/crates/kobako-runtime/src/net/reactor.rs +531 -0
  57. data/crates/kobako-runtime/src/net/resolv/darwin.rs +275 -0
  58. data/crates/kobako-runtime/src/net/resolv/stub/tests.rs +469 -0
  59. data/crates/kobako-runtime/src/net/resolv/stub.rs +536 -0
  60. data/crates/kobako-runtime/src/net/resolv/windows.rs +248 -0
  61. data/crates/kobako-runtime/src/net/resolv.rs +227 -0
  62. data/crates/kobako-runtime/src/net/socket.rs +870 -0
  63. data/crates/kobako-runtime/src/net/tcp.rs +1588 -0
  64. data/crates/kobako-runtime/src/net/tls.rs +58 -0
  65. data/crates/kobako-runtime/src/net/transport.rs +279 -0
  66. data/crates/kobako-runtime/src/net/udp.rs +1003 -0
  67. data/crates/kobako-runtime/src/net.rs +42 -0
  68. data/crates/kobako-runtime/src/network/builder.rs +177 -0
  69. data/crates/kobako-runtime/src/network/ruleset.rs +777 -0
  70. data/crates/kobako-runtime/src/network.rs +551 -0
  71. data/crates/kobako-runtime/src/policy.rs +16 -0
  72. data/crates/kobako-runtime/src/profile.rs +29 -144
  73. data/crates/kobako-runtime/src/runtime.rs +3 -5
  74. data/crates/kobako-runtime/src/sched.rs +130 -29
  75. data/crates/kobako-runtime/src/security/entry_policy.rs +22 -0
  76. data/crates/kobako-runtime/src/{vfs/cred.rs → security/hooks.rs} +52 -144
  77. data/crates/kobako-runtime/src/security/mount_policy.rs +158 -0
  78. data/crates/kobako-runtime/src/security.rs +101 -196
  79. data/crates/kobako-runtime/src/snapshot.rs +121 -2
  80. data/crates/kobako-runtime/src/vfs/attr.rs +5 -5
  81. data/crates/kobako-runtime/src/vfs/dentry.rs +143 -89
  82. data/crates/kobako-runtime/src/vfs/file.rs +199 -203
  83. data/crates/kobako-runtime/src/vfs/inode.rs +41 -45
  84. data/crates/kobako-runtime/src/vfs/kern_path.rs +38 -42
  85. data/crates/kobako-runtime/src/vfs/mount.rs +10 -9
  86. data/crates/kobako-runtime/src/vfs/namei.rs +829 -700
  87. data/crates/kobako-runtime/src/vfs/namespace.rs +162 -0
  88. data/crates/kobako-runtime/src/vfs/open_files.rs +69 -0
  89. data/crates/kobako-runtime/src/vfs/openat2.rs +3 -3
  90. data/crates/kobako-runtime/src/vfs/path.rs +6 -6
  91. data/crates/kobako-runtime/src/vfs/readdir.rs +6 -6
  92. data/crates/kobako-runtime/src/vfs/stat.rs +159 -23
  93. data/crates/kobako-runtime/src/vfs/super_block.rs +18 -14
  94. data/crates/kobako-runtime/src/vfs/utimes.rs +37 -27
  95. data/crates/kobako-runtime/src/vfs.rs +9 -6
  96. data/crates/kobako-runtime/src/wait.rs +356 -0
  97. data/crates/kobako-transport/CHANGELOG.md +31 -0
  98. data/crates/kobako-transport/Cargo.toml +1 -1
  99. data/crates/kobako-transport/README.md +3 -4
  100. data/crates/kobako-transport/src/abi.rs +78 -72
  101. data/crates/kobako-transport/src/envelope/bytes.rs +17 -6
  102. data/crates/kobako-transport/src/envelope/call.rs +32 -4
  103. data/crates/kobako-transport/src/envelope/error_record.rs +21 -0
  104. data/crates/kobako-transport/src/envelope/name.rs +99 -0
  105. data/crates/kobako-transport/src/envelope/outcome.rs +9 -9
  106. data/crates/kobako-transport/src/envelope/preamble.rs +24 -21
  107. data/crates/kobako-transport/src/envelope/reply.rs +27 -27
  108. data/crates/kobako-transport/src/envelope/unsupported.rs +10 -10
  109. data/crates/kobako-transport/src/envelope.rs +13 -8
  110. data/crates/kobako-wasmtime/CHANGELOG.md +161 -0
  111. data/crates/kobako-wasmtime/Cargo.toml +26 -7
  112. data/crates/kobako-wasmtime/README.md +3 -2
  113. data/crates/kobako-wasmtime/build/preview2.rs +1339 -0
  114. data/crates/kobako-wasmtime/build.rs +16 -0
  115. data/crates/kobako-wasmtime/src/abi.rs +17 -37
  116. data/crates/kobako-wasmtime/src/ambient.rs +33 -18
  117. data/crates/kobako-wasmtime/src/cache.rs +23 -15
  118. data/crates/kobako-wasmtime/src/config.rs +52 -68
  119. data/crates/kobako-wasmtime/src/driver.rs +48 -63
  120. data/crates/kobako-wasmtime/src/exports.rs +143 -17
  121. data/crates/kobako-wasmtime/src/guest.rs +12 -6
  122. data/crates/kobako-wasmtime/src/guest_binary.rs +14 -0
  123. data/crates/kobako-wasmtime/src/imports.rs +42 -18
  124. data/crates/kobako-wasmtime/src/instance_pre.rs +4 -4
  125. data/crates/kobako-wasmtime/src/invocation.rs +74 -12
  126. data/crates/kobako-wasmtime/src/lib.rs +5 -3
  127. data/crates/kobako-wasmtime/src/limiter.rs +70 -5
  128. data/crates/kobako-wasmtime/src/preview1/descriptors.rs +309 -0
  129. data/crates/kobako-wasmtime/src/preview1/differential/mount.rs +5 -15
  130. data/crates/kobako-wasmtime/src/preview1/differential.rs +27 -31
  131. data/crates/kobako-wasmtime/src/preview1/errno.rs +55 -66
  132. data/crates/kobako-wasmtime/src/preview1/fd.rs +327 -296
  133. data/crates/kobako-wasmtime/src/preview1/memory.rs +21 -12
  134. data/crates/kobako-wasmtime/src/preview1/mount_view/wrap.rs +34 -53
  135. data/crates/kobako-wasmtime/src/preview1/mount_view.rs +231 -217
  136. data/crates/kobako-wasmtime/src/preview1/path.rs +56 -121
  137. data/crates/kobako-wasmtime/src/preview1/poll.rs +244 -120
  138. data/crates/kobako-wasmtime/src/preview1/sock.rs +10 -8
  139. data/crates/kobako-wasmtime/src/preview1/testsuite.rs +5 -15
  140. data/crates/kobako-wasmtime/src/preview1.rs +46 -42
  141. data/crates/kobako-wasmtime/src/preview2/abi.rs +227 -0
  142. data/crates/kobako-wasmtime/src/preview2/error.rs +118 -0
  143. data/crates/kobako-wasmtime/src/preview2/filesystem.rs +122 -0
  144. data/crates/kobako-wasmtime/src/preview2/host.rs +3959 -0
  145. data/crates/kobako-wasmtime/src/preview2/http.rs +1503 -0
  146. data/crates/kobako-wasmtime/src/preview2/io.rs +315 -0
  147. data/crates/kobako-wasmtime/src/preview2/sockets.rs +379 -0
  148. data/crates/kobako-wasmtime/src/preview2/table.rs +305 -0
  149. data/crates/kobako-wasmtime/src/preview2.rs +57 -0
  150. data/crates/kobako-wasmtime/src/trap.rs +24 -9
  151. data/crates/kobako-wasmtime/src/wasi.rs +210 -81
  152. data/crates/kobako-wasmtime/wit/deps/cli.wit +233 -0
  153. data/crates/kobako-wasmtime/wit/deps/clocks.wit +162 -0
  154. data/crates/kobako-wasmtime/wit/deps/filesystem.wit +589 -0
  155. data/crates/kobako-wasmtime/wit/deps/http.wit +733 -0
  156. data/crates/kobako-wasmtime/wit/deps/io.wit +299 -0
  157. data/crates/kobako-wasmtime/wit/deps/random.wit +92 -0
  158. data/crates/kobako-wasmtime/wit/deps/sockets.wit +949 -0
  159. data/data/kobako.wasm +0 -0
  160. data/ext/kobako/Cargo.toml +1 -1
  161. data/ext/kobako/src/{runtime/errors.rs → errors.rs} +34 -26
  162. data/ext/kobako/src/{runtime/escape.rs → escape.rs} +42 -11
  163. data/ext/kobako/src/{runtime/filesystem → filesystem}/grants.rs +30 -26
  164. data/ext/kobako/src/{runtime/filesystem → filesystem}/ruby.rs +149 -168
  165. data/ext/kobako/src/{runtime/filesystem.rs → filesystem.rs} +24 -15
  166. data/ext/kobako/src/gvl.rs +306 -0
  167. data/ext/kobako/src/lib.rs +64 -3
  168. data/ext/kobako/src/network/mock.rs +187 -0
  169. data/ext/kobako/src/network.rs +591 -0
  170. data/ext/kobako/src/runtime/bridge.rs +30 -29
  171. data/ext/kobako/src/runtime/snapshot.rs +4 -4
  172. data/ext/kobako/src/runtime.rs +221 -143
  173. data/ext/kobako/src/wire.rs +42 -0
  174. data/lib/kobako/catalog/extensions.rb +14 -2
  175. data/lib/kobako/catalog/flags.rb +3 -5
  176. data/lib/kobako/catalog/grants.rb +5 -4
  177. data/lib/kobako/catalog/handles.rb +5 -27
  178. data/lib/kobako/catalog/mount.rb +11 -3
  179. data/lib/kobako/catalog/network.rb +35 -0
  180. data/lib/kobako/catalog/replacements.rb +28 -0
  181. data/lib/kobako/catalog/services.rb +5 -19
  182. data/lib/kobako/catalog/snippets.rb +3 -18
  183. data/lib/kobako/catalog.rb +3 -0
  184. data/lib/kobako/codec/{utils.rb → boundary.rb} +4 -2
  185. data/lib/kobako/codec/decoder.rb +4 -4
  186. data/lib/kobako/codec/ext_types.rb +3 -3
  187. data/lib/kobako/codec/handle_walk.rb +3 -43
  188. data/lib/kobako/codec/value_budget.rb +132 -40
  189. data/lib/kobako/codec.rb +1 -1
  190. data/lib/kobako/context.rb +24 -11
  191. data/lib/kobako/errors.rb +15 -12
  192. data/lib/kobako/extension.rb +3 -2
  193. data/lib/kobako/filesystem.rb +9 -2
  194. data/lib/kobako/handle.rb +2 -2
  195. data/lib/kobako/names.rb +28 -0
  196. data/lib/kobako/network.rb +210 -0
  197. data/lib/kobako/outcome.rb +7 -7
  198. data/lib/kobako/pool.rb +45 -23
  199. data/lib/kobako/runtime.rb +3 -2
  200. data/lib/kobako/sandbox.rb +92 -35
  201. data/lib/kobako/sandbox_options.rb +41 -106
  202. data/lib/kobako/transport/argument_wrap.rb +64 -0
  203. data/lib/kobako/transport/block_failure.rb +1 -1
  204. data/lib/kobako/transport/dispatcher.rb +6 -6
  205. data/lib/kobako/transport/exposure.rb +26 -15
  206. data/lib/kobako/transport/reflection.rb +21 -4
  207. data/lib/kobako/transport/run.rb +8 -23
  208. data/lib/kobako/transport/yielder.rb +2 -9
  209. data/lib/kobako/transport.rb +1 -0
  210. data/lib/kobako/version.rb +1 -1
  211. data/lib/kobako.rb +6 -2
  212. data/release-please-config.json +15 -0
  213. data/sig/core/thread.rbs +6 -0
  214. data/sig/kobako/catalog/extensions.rbs +2 -0
  215. data/sig/kobako/catalog/grants.rbs +7 -4
  216. data/sig/kobako/catalog/handles.rbs +0 -2
  217. data/sig/kobako/catalog/mount.rbs +3 -1
  218. data/sig/kobako/catalog/network.rbs +20 -0
  219. data/sig/kobako/catalog/replacements.rbs +14 -0
  220. data/sig/kobako/catalog/services.rbs +0 -4
  221. data/sig/kobako/catalog/snippets.rbs +0 -2
  222. data/sig/kobako/codec/{utils.rbs → boundary.rbs} +2 -2
  223. data/sig/kobako/codec/handle_walk.rbs +0 -6
  224. data/sig/kobako/codec/value_budget.rbs +47 -4
  225. data/sig/kobako/context.rbs +3 -1
  226. data/sig/kobako/errors.rbs +4 -4
  227. data/sig/kobako/filesystem.rbs +21 -3
  228. data/sig/kobako/network.rbs +115 -0
  229. data/sig/kobako/outcome.rbs +1 -1
  230. data/sig/kobako/pool.rbs +7 -3
  231. data/sig/kobako/runtime.rbs +32 -3
  232. data/sig/kobako/sandbox.rbs +19 -2
  233. data/sig/kobako/sandbox_options.rbs +29 -38
  234. data/sig/kobako/transport/argument_wrap.rbs +15 -0
  235. data/sig/kobako/transport/error.rbs +1 -1
  236. data/sig/kobako/transport/exposure.rbs +2 -4
  237. data/sig/kobako/transport/reflection.rbs +10 -0
  238. data/sig/kobako/transport/run.rbs +0 -2
  239. data/sig/kobako/transport/yielder.rbs +0 -3
  240. data/sig/kobako/transport.rbs +1 -1
  241. data/sig/kobako.rbs +13 -0
  242. metadata +84 -35
  243. data/crates/kobako-runtime/src/endpoint/capture.rs +0 -115
  244. data/crates/kobako-runtime/src/endpoint/memory_cap.rs +0 -238
  245. data/crates/kobako-runtime/src/filesystem/path.rs +0 -21
  246. data/crates/kobako-runtime/src/vfs/errno.rs +0 -153
  247. data/crates/kobako-runtime/tests/linux_baseline/calls.rs +0 -171
  248. data/crates/kobako-runtime/tests/linux_baseline/concurrent.rs +0 -276
  249. data/crates/kobako-runtime/tests/linux_baseline/kobako.rs +0 -323
  250. data/crates/kobako-runtime/tests/linux_baseline/linux-baseline-expected.txt +0 -16
  251. data/crates/kobako-runtime/tests/linux_baseline/linux.rs +0 -449
  252. data/crates/kobako-runtime/tests/linux_baseline/main.rs +0 -611
  253. data/crates/kobako-runtime/tests/linux_baseline/permissions.rs +0 -236
  254. data/crates/kobako-wasmtime/src/descriptors.rs +0 -200
  255. data/crates/kobako-wasmtime/tests/integration/compile_posture.rs +0 -43
  256. data/crates/kobako-wasmtime/tests/integration/guest_file.rs +0 -1085
  257. data/crates/kobako-wasmtime/tests/integration/main.rs +0 -29
  258. data/crates/kobako-wasmtime/tests/integration/preamble_flags.rs +0 -70
  259. data/crates/kobako-wasmtime/tests/integration/snippet_compile.rs +0 -95
  260. data/crates/kobako-wasmtime/tests/integration/support/mod.rs +0 -30
  261. data/crates/kobako-wasmtime/tests/integration/unanswered_call.rs +0 -86
  262. data/crates/kobako-wasmtime/tests/integration/unsupported_call.rs +0 -51
  263. data/ext/kobako/src/runtime/gvl.rs +0 -147
  264. data/lib/kobako/constant_name.rb +0 -8
  265. data/sig/kobako/constant_name.rbs +0 -3
  266. /data/ext/kobako/src/{runtime/pinned_value.rs → pinned_value.rs} +0 -0
@@ -0,0 +1,551 @@
1
+ //! The network Grant: one named entry a Host App hands the guest, as Linux's
2
+ //! network namespace holds every socket its tasks open. Each entry is one
3
+ //! Grant, so a Context replaces it by its name, as one Mount by its path.
4
+
5
+ mod builder;
6
+ mod ruleset;
7
+
8
+ use std::fmt;
9
+ use std::net::IpAddr;
10
+ use std::sync::Arc;
11
+
12
+ pub use builder::Builder;
13
+ pub(crate) use ruleset::Host;
14
+ pub(crate) use ruleset::Ruleset;
15
+
16
+ /// The process's open connection limit, which only a Rust Host App moves.
17
+ pub use crate::net::{process_connections, OpenConnections};
18
+
19
+ use crate::policy::Policy;
20
+
21
+ /// One named entry of the network, handed over for an Invocation.
22
+ #[derive(Clone)]
23
+ pub struct Network {
24
+ name: String,
25
+ entry: Arc<dyn Entry>,
26
+ }
27
+
28
+ impl Network {
29
+ /// The entry `entry` under `name`, refused for an empty name, which no
30
+ /// Context could replace it by. The host's trust store is read here the
31
+ /// first time, on the thread building the Sandbox.
32
+ pub fn new(name: impl Into<String>, entry: Arc<dyn Entry>) -> Result<Self, EntryError> {
33
+ let name = name.into();
34
+ if name.is_empty() {
35
+ return Err(EntryError("an entry's name must not be empty".to_string()));
36
+ }
37
+ crate::net::load_platform_verifier();
38
+ Ok(Self { name, entry })
39
+ }
40
+
41
+ /// The name a Context replaces this entry by.
42
+ pub fn name(&self) -> &str {
43
+ &self.name
44
+ }
45
+
46
+ /// What this entry lets the guest reach, as it answers for this
47
+ /// Invocation.
48
+ pub fn endpoints(&self) -> Vec<Endpoint> {
49
+ self.entry.endpoints()
50
+ }
51
+
52
+ /// What this entry's policies judge, as it answers for this Invocation.
53
+ pub fn policies(&self) -> Policies {
54
+ self.entry.policies()
55
+ }
56
+
57
+ /// The credentials this entry swaps into requests bound to its own
58
+ /// endpoints, as it answers for this Invocation.
59
+ pub fn credentials(&self) -> Vec<Credential> {
60
+ self.entry.credentials()
61
+ }
62
+ }
63
+
64
+ /// What a Host App's entry plays. Each role defaults to nothing, so an entry
65
+ /// answers only the roles it plays.
66
+ pub trait Entry: Send + Sync {
67
+ /// What the guest may reach through this entry.
68
+ fn endpoints(&self) -> Vec<Endpoint> {
69
+ Vec::new()
70
+ }
71
+
72
+ /// The hooks this entry's policies answer; one it leaves out has no
73
+ /// opinion.
74
+ fn policies(&self) -> Policies {
75
+ Policies::default()
76
+ }
77
+
78
+ /// The credentials swapped into a request bound to this entry's own
79
+ /// endpoints.
80
+ fn credentials(&self) -> Vec<Credential> {
81
+ Vec::new()
82
+ }
83
+ }
84
+
85
+ /// A value the Host App hands no guest, its `Debug` a mask and its bytes zeroed
86
+ /// as it drops.
87
+ #[derive(Clone, PartialEq, Eq)]
88
+ pub struct Secret(Vec<u8>);
89
+
90
+ impl Secret {
91
+ pub fn new(value: impl Into<Vec<u8>>) -> Self {
92
+ Self(value.into())
93
+ }
94
+
95
+ /// The bytes, for the one header they are swapped into.
96
+ pub fn expose(&self) -> &[u8] {
97
+ &self.0
98
+ }
99
+ }
100
+
101
+ impl fmt::Debug for Secret {
102
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
103
+ f.write_str("Secret(**)")
104
+ }
105
+ }
106
+
107
+ impl Drop for Secret {
108
+ fn drop(&mut self) {
109
+ zeroize::Zeroize::zeroize(&mut self.0);
110
+ }
111
+ }
112
+
113
+ /// Where a credential's value goes: the `authorization` header as a bearer
114
+ /// token or a basic pair, or one named header, as OpenShell's `auth_style`.
115
+ #[derive(Clone, Debug, PartialEq, Eq)]
116
+ #[non_exhaustive]
117
+ pub enum Placement {
118
+ Bearer,
119
+ Basic,
120
+ /// A header by its name, matched in any case.
121
+ Header(String),
122
+ }
123
+
124
+ impl Placement {
125
+ /// The header the value is swapped into.
126
+ pub fn header(&self) -> &str {
127
+ match self {
128
+ Placement::Bearer | Placement::Basic => "authorization",
129
+ Placement::Header(name) => name,
130
+ }
131
+ }
132
+ }
133
+
134
+ /// What resolves a credential's value as a bound request leaves: the value,
135
+ /// `None` to send nothing, or `CredentialUnavailable` when it cannot say,
136
+ /// which refuses the request. Caching and refresh are its own.
137
+ pub trait CredentialSource: Send + Sync {
138
+ fn value_of(&self, request: &Request<'_>) -> Result<Option<Secret>, CredentialUnavailable>;
139
+ }
140
+
141
+ impl<F> CredentialSource for F
142
+ where
143
+ F: Fn(&Request<'_>) -> Result<Option<Secret>, CredentialUnavailable> + Send + Sync,
144
+ {
145
+ fn value_of(&self, request: &Request<'_>) -> Result<Option<Secret>, CredentialUnavailable> {
146
+ self(request)
147
+ }
148
+ }
149
+
150
+ /// A credential's source that failed to answer, so its request leaves
151
+ /// nowhere rather than unauthenticated, as Envoy's credential injector and
152
+ /// OpenShell refuse a request whose credential they could not resolve.
153
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
154
+ pub struct CredentialUnavailable;
155
+
156
+ /// A placement and a placeholder paired with the source of the value that
157
+ /// replaces the placeholder there.
158
+ #[derive(Clone)]
159
+ #[non_exhaustive]
160
+ pub struct Credential {
161
+ pub placement: Placement,
162
+ /// The string the Host App hands the guest in the value's place.
163
+ pub placeholder: String,
164
+ pub source: Arc<dyn CredentialSource>,
165
+ }
166
+
167
+ impl Credential {
168
+ pub fn new(
169
+ placement: Placement,
170
+ placeholder: impl Into<String>,
171
+ source: Arc<dyn CredentialSource>,
172
+ ) -> Self {
173
+ Self {
174
+ placement,
175
+ placeholder: placeholder.into(),
176
+ source,
177
+ }
178
+ }
179
+ }
180
+
181
+ /// An entry's policies, one hook per decision point, as an LSM registers a
182
+ /// hook per kind of object. A policy only narrows what the endpoints allow.
183
+ #[derive(Clone, Default)]
184
+ #[non_exhaustive]
185
+ pub struct Policies {
186
+ /// Asked at each lookup.
187
+ pub resolve: Option<Arc<dyn for<'a> Policy<Name<'a>>>>,
188
+ /// Asked at each connect.
189
+ pub connect: Option<Arc<dyn for<'a> Policy<Connection<'a>>>>,
190
+ /// Asked at each HTTP request.
191
+ pub request: Option<Arc<dyn for<'a> Policy<Request<'a>>>>,
192
+ }
193
+
194
+ /// One HTTP request the guest sends, as the `request?` hook judges it: the
195
+ /// authority, method, scheme, and path it named, and its header names, never
196
+ /// a header's value.
197
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
198
+ #[non_exhaustive]
199
+ pub struct Request<'a> {
200
+ /// The host, lowercase, and the port.
201
+ pub authority: (&'a str, u16),
202
+ /// As the guest sent it, since a method is case-sensitive.
203
+ pub method: &'a str,
204
+ /// `http` or `https`.
205
+ pub scheme: &'a str,
206
+ /// The path, with no query.
207
+ pub path: &'a str,
208
+ /// Lowercase.
209
+ pub header_names: &'a [&'a str],
210
+ }
211
+
212
+ impl<'a> Request<'a> {
213
+ pub fn new(
214
+ authority: (&'a str, u16),
215
+ method: &'a str,
216
+ scheme: &'a str,
217
+ path: &'a str,
218
+ header_names: &'a [&'a str],
219
+ ) -> Self {
220
+ Self {
221
+ authority,
222
+ method,
223
+ scheme,
224
+ path,
225
+ header_names,
226
+ }
227
+ }
228
+ }
229
+
230
+ impl Policies {
231
+ /// These policies with `policy` judging each lookup.
232
+ pub fn with_resolve_policy(self, policy: Arc<dyn for<'a> Policy<Name<'a>>>) -> Self {
233
+ Self {
234
+ resolve: Some(policy),
235
+ ..self
236
+ }
237
+ }
238
+
239
+ /// These policies with `policy` judging each connect.
240
+ pub fn with_connect_policy(self, policy: Arc<dyn for<'a> Policy<Connection<'a>>>) -> Self {
241
+ Self {
242
+ connect: Some(policy),
243
+ ..self
244
+ }
245
+ }
246
+
247
+ /// These policies with `policy` judging each HTTP request.
248
+ pub fn with_request_policy(self, policy: Arc<dyn for<'a> Policy<Request<'a>>>) -> Self {
249
+ Self {
250
+ request: Some(policy),
251
+ ..self
252
+ }
253
+ }
254
+ }
255
+
256
+ /// One name the guest asks to look up, as the `resolve?` hook judges it:
257
+ /// lowercase, with no trailing dot, and an IDN as its A-label.
258
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
259
+ #[non_exhaustive]
260
+ pub struct Name<'a> {
261
+ pub name: &'a str,
262
+ }
263
+
264
+ impl<'a> Name<'a> {
265
+ pub fn new(name: &'a str) -> Self {
266
+ Self { name }
267
+ }
268
+ }
269
+
270
+ /// One connection the guest asks for, as the socket hooks judge it: the host
271
+ /// it named, its port, and its protocol. The host is what the guest named, a
272
+ /// name or a literal address, never a real address it resolved to.
273
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
274
+ #[non_exhaustive]
275
+ pub struct Connection<'a> {
276
+ pub host: &'a str,
277
+ pub port: u16,
278
+ pub protocol: Protocol,
279
+ }
280
+
281
+ impl<'a> Connection<'a> {
282
+ pub fn new(host: &'a str, port: u16, protocol: Protocol) -> Self {
283
+ Self {
284
+ host,
285
+ port,
286
+ protocol,
287
+ }
288
+ }
289
+ }
290
+
291
+ /// What the guest may reach: a host, a port, a protocol, and where the host's
292
+ /// name may lead.
293
+ #[derive(Clone, Debug, PartialEq, Eq)]
294
+ #[non_exhaustive]
295
+ pub struct Endpoint {
296
+ /// An exact name, a label-boundary wildcard, or an address.
297
+ pub host: String,
298
+ pub port: u16,
299
+ pub protocol: Protocol,
300
+ /// Where the host's name may lead.
301
+ pub addresses: Vec<Addresses>,
302
+ /// For an `http` endpoint, the methods and paths it allows and denies;
303
+ /// with none, it allows every request.
304
+ pub rules: Vec<HttpRule>,
305
+ }
306
+
307
+ /// One rule an `http` endpoint judges a request by: a method, or any, and a
308
+ /// path pattern, where `*` stands for one segment and `**` for any number.
309
+ #[derive(Clone, Debug, PartialEq, Eq)]
310
+ #[non_exhaustive]
311
+ pub struct HttpRule {
312
+ /// What the rule does with a request it matches.
313
+ pub action: Action,
314
+ /// Uppercase, or `None` for any method.
315
+ pub method: Option<String>,
316
+ pub path: String,
317
+ }
318
+
319
+ /// What an `HttpRule` does with a request it matches.
320
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
321
+ pub enum Action {
322
+ Allow,
323
+ Deny,
324
+ }
325
+
326
+ impl HttpRule {
327
+ /// A rule taking `action` on `method`, or any, on paths `path` matches.
328
+ pub fn new(action: Action, method: Option<&str>, path: impl Into<String>) -> Self {
329
+ Self {
330
+ action,
331
+ method: method.map(str::to_ascii_uppercase),
332
+ path: path.into(),
333
+ }
334
+ }
335
+
336
+ /// Whether this rule speaks to `method` on `path`, the method in its own
337
+ /// case, as RFC 9110 holds a method case-sensitive.
338
+ pub(crate) fn matches(&self, method: &str, path: &str) -> bool {
339
+ self.method.as_deref().is_none_or(|own| own == method) && glob_matches(&self.path, path)
340
+ }
341
+
342
+ /// Whether this rule speaks to `method` on `path` as a lenient server
343
+ /// routes it, ignoring case and a trailing slash, so that a deny refuses
344
+ /// every spelling such a server serves as the denied method and path.
345
+ pub(crate) fn matches_leniently(&self, method: &str, path: &str) -> bool {
346
+ let (pattern, path) = (self.path.to_ascii_lowercase(), path.to_ascii_lowercase());
347
+ let untrailed = |path: &str| -> String {
348
+ match path.strip_suffix('/') {
349
+ Some(rest) if !rest.is_empty() => rest.to_string(),
350
+ _ => path.to_string(),
351
+ }
352
+ };
353
+ self.method
354
+ .as_deref()
355
+ .is_none_or(|own| own.eq_ignore_ascii_case(method))
356
+ && glob_matches(&untrailed(&pattern), &untrailed(&path))
357
+ }
358
+ }
359
+
360
+ /// Whether `path` fits `pattern`, segment by segment, as a path glob does:
361
+ /// `**` takes any number of segments and `*` one. It walks both once, going
362
+ /// back only to the last `**`, as wildcard matching does, so a path the
363
+ /// guest names costs at most its segments times the pattern's.
364
+ fn glob_matches(pattern: &str, path: &str) -> bool {
365
+ let pattern = pattern.split('/').collect::<Vec<_>>();
366
+ let path = path.split('/').collect::<Vec<_>>();
367
+ let (mut at, mut segment) = (0, 0);
368
+ // Where the pattern resumes past its last `**`, and the path segment
369
+ // that `**` takes up to.
370
+ let mut last_any: Option<(usize, usize)> = None;
371
+ while segment < path.len() {
372
+ match pattern.get(at) {
373
+ Some(&"**") => {
374
+ last_any = Some((at + 1, segment));
375
+ at += 1;
376
+ }
377
+ Some(&own) if own == "*" || own == path[segment] => {
378
+ at += 1;
379
+ segment += 1;
380
+ }
381
+ _ => match last_any {
382
+ Some((resume, taken)) => {
383
+ last_any = Some((resume, taken + 1));
384
+ at = resume;
385
+ segment = taken + 1;
386
+ }
387
+ None => return false,
388
+ },
389
+ }
390
+ }
391
+ pattern[at..].iter().all(|own| *own == "**")
392
+ }
393
+
394
+ /// Refuse port zero, which no connection reaches.
395
+ fn ensure_nonzero_port(host: &str, port: u16) -> Result<(), EntryError> {
396
+ if port == 0 {
397
+ return Err(EntryError(format!(
398
+ "an endpoint's port must not be zero, got {host}:0"
399
+ )));
400
+ }
401
+ Ok(())
402
+ }
403
+
404
+ impl Endpoint {
405
+ /// An endpoint at `host` and `port`, speaking HTTP and leading only to
406
+ /// public addresses, refused for an empty host or port zero, which no
407
+ /// connection reaches.
408
+ pub fn new(host: impl Into<String>, port: u16) -> Result<Self, EntryError> {
409
+ let host = host.into();
410
+ if host.is_empty() {
411
+ return Err(EntryError(
412
+ "an endpoint's host must not be empty".to_string(),
413
+ ));
414
+ }
415
+ ensure_nonzero_port(&host, port)?;
416
+ Ok(Self {
417
+ host,
418
+ port,
419
+ protocol: Protocol::Http,
420
+ addresses: vec![Addresses::Public],
421
+ rules: Vec::new(),
422
+ })
423
+ }
424
+
425
+ /// This endpoint speaking `protocol`.
426
+ pub fn with_protocol(self, protocol: Protocol) -> Self {
427
+ Self { protocol, ..self }
428
+ }
429
+
430
+ /// This endpoint leading to `addresses`.
431
+ pub fn with_addresses(self, addresses: Vec<Addresses>) -> Self {
432
+ Self { addresses, ..self }
433
+ }
434
+
435
+ /// This endpoint judging each request by `rules`.
436
+ pub fn with_rules(self, rules: Vec<HttpRule>) -> Self {
437
+ Self { rules, ..self }
438
+ }
439
+ }
440
+
441
+ /// What an endpoint speaks.
442
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
443
+ #[non_exhaustive]
444
+ pub enum Protocol {
445
+ Http,
446
+ Tcp,
447
+ Udp,
448
+ }
449
+
450
+ /// Where an endpoint's name may lead: an address set, or a CIDR.
451
+ #[derive(Clone, Copy, Debug, PartialEq, Eq)]
452
+ #[non_exhaustive]
453
+ pub enum Addresses {
454
+ /// Globally routable unicast.
455
+ Public,
456
+ /// RFC 1918, CGNAT, and ULA.
457
+ Private,
458
+ /// Loopback and the host's own addresses.
459
+ Local,
460
+ /// The addresses within a prefix.
461
+ Cidr(IpAddr, u8),
462
+ }
463
+
464
+ impl Addresses {
465
+ /// The CIDR `address/prefix` text spells, as an endpoint's host reads
466
+ /// one; `None` for text that spells none, or a prefix past its address.
467
+ pub fn from_cidr(text: &str) -> Option<Self> {
468
+ let (ip, prefix) = ruleset::parse_cidr(text)?.ok()?;
469
+ Some(Self::Cidr(ip, prefix))
470
+ }
471
+ }
472
+
473
+ /// An entry or an endpoint no connection could follow.
474
+ #[derive(Clone, Debug, PartialEq, Eq)]
475
+ pub struct EntryError(String);
476
+
477
+ impl fmt::Display for EntryError {
478
+ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
479
+ f.write_str(&self.0)
480
+ }
481
+ }
482
+
483
+ impl std::error::Error for EntryError {}
484
+
485
+ #[cfg(test)]
486
+ mod tests {
487
+ use super::*;
488
+
489
+ // @behavior NW-007
490
+ #[test]
491
+ fn an_endpoint_reaches_http_and_public_addresses_unless_written_otherwise() {
492
+ let endpoint = Endpoint::new("api.example.com", 443).expect("a host and a port stand");
493
+ assert_eq!(
494
+ (endpoint.protocol, endpoint.addresses),
495
+ (Protocol::Http, vec![Addresses::Public]),
496
+ "Endpoint::new with only a host and a port must speak HTTP and lead to the public set"
497
+ );
498
+ }
499
+
500
+ // @behavior NW-008
501
+ #[test]
502
+ fn a_cidr_reads_as_an_endpoints_host_reads_one() {
503
+ let v4: IpAddr = "10.0.0.0".parse().expect("a literal address");
504
+ let v6: IpAddr = "fd00::".parse().expect("a literal address");
505
+ assert_eq!(
506
+ [
507
+ "10.0.0.0/8",
508
+ "fd00::/128",
509
+ "10.0.0.0/33",
510
+ "net/8",
511
+ "10.0.0.0",
512
+ "10.0.0.0/x"
513
+ ]
514
+ .map(Addresses::from_cidr),
515
+ [
516
+ Some(Addresses::Cidr(v4, 8)),
517
+ Some(Addresses::Cidr(v6, 128)),
518
+ None,
519
+ None,
520
+ None,
521
+ None
522
+ ],
523
+ "an endpoint's addresses must take a CIDR whose prefix fits its address, and no \
524
+ other text"
525
+ );
526
+ }
527
+
528
+ // @behavior NW-157
529
+ #[test]
530
+ fn a_rule_of_several_wildcards_judges_a_long_path_at_once() {
531
+ let rule = HttpRule::new(Action::Allow, None, "/**/**/**/x");
532
+ let path = "/a".repeat(32_767);
533
+ let started = std::time::Instant::now();
534
+ let fits = rule.matches("GET", &path);
535
+ assert!(
536
+ !fits && started.elapsed() < std::time::Duration::from_secs(1),
537
+ "a rule /**/**/**/x must refuse a 32767-segment path that ends elsewhere within a \
538
+ second, not after {:?}",
539
+ started.elapsed()
540
+ );
541
+ }
542
+
543
+ // @behavior NW-008
544
+ #[test]
545
+ fn an_endpoint_with_an_empty_host_or_port_zero_is_refused() {
546
+ assert!(
547
+ Endpoint::new("", 443).is_err() && Endpoint::new("api.example.com", 0).is_err(),
548
+ "Endpoint::new with an empty host or port zero must be refused"
549
+ );
550
+ }
551
+ }
@@ -0,0 +1,16 @@
1
+ //! A Policy: the Host App's decision over one request a Grant's guest makes.
2
+ //! Each kind of Grant names its own request, so this depends on none of them.
3
+
4
+ /// The Host App's decision for one request a Grant's access already allows,
5
+ /// so it can only refuse more, as an LSM hook can. Each kind of Grant brings
6
+ /// its own request, as Linux's LSM has a hook per kind of object.
7
+ pub trait Policy<R: ?Sized>: Send + Sync {
8
+ /// Whether the guest may go on with `request`.
9
+ fn allows(&self, request: &R) -> bool;
10
+ }
11
+
12
+ impl<R: ?Sized, F: Fn(&R) -> bool + Send + Sync> Policy<R> for F {
13
+ fn allows(&self, request: &R) -> bool {
14
+ self(request)
15
+ }
16
+ }