@landstrip/landstrip 0.15.0 → 0.15.1

package/README.md

@@ -110,61 +110,71 @@ capabilities; without it the container denies all network access.
 ## Error Output
 
 Failures reported by `landstrip` are printed as JSON objects on standard
-error, one object per line. Each object is tagged by the trap kind, with the
-kind name as the single top-level key.
+error, one object per line. Each object is a flat record with a fixed `kind`
+discriminant and a stable `code`, so consumers can route on `kind` for the
+coarse grouping and on `code` for the specific case.
 
 ```json
-{"Internal":{"file":"policy.json","source":"expected value at line 1 column 1"}}
+{"kind":"internal","code":"INTERNAL_ERROR","detail":{"file":"policy.json","source":"expected value at line 1 column 1"}}
 ```
 
 ```json
-{"Launch":["cargo","No such file or directory"]}
+{"kind":"launch","code":"LAUNCH_FAILED","program":"cargo","message":"No such file or directory"}
 ```
 
 The trap kinds are:
 
-- `Filesystem`: a filesystem access denial object. The stable `code` is
+- `filesystem`: a filesystem access denial. The stable `code` is
   `FS_READ_DENIED` or `FS_WRITE_DENIED`; `operation` is `read` or `write`;
   `path` is the resolved path; `requested_path` is the original path supplied by
   the tool when available; `syscall`, `errno`, `flags`, `reason`,
   `suggested_grant`, and `process` provide machine-readable routing context.
-- `Network`: a denied TCP connect or bind object. The stable `code` is
-  `NET_CONNECT_DENIED`, `NET_BIND_DENIED`, or `NET_DENIED`; `operation` is
-  `connect` or `bind`; `target` is `address:port`; `syscall`, `errno`, and
-  `process` provide routing context.
-- `Launch`: the tool could not be started, as `[program, message]`.
-- `Usage`: a command-line usage error, as a message string. Usage errors exit
-  with status 2.
-- `Internal`: any other policy, platform, or system error, as an object of
-  diagnostic key/value pairs (for example `source`, `file`, or platform API
-  details).
+- `network`: a denied TCP connect or bind. The stable `code` is
+  `NET_CONNECT_DENIED` or `NET_BIND_DENIED`; `operation` is `connect` or `bind`;
+  `target` is `address:port`; `syscall`, `errno`, and `process` provide routing
+  context.
+- `launch`: the tool could not be started. The stable `code` is `LAUNCH_FAILED`;
+  `program` and `message` give the program and the failure detail.
+- `usage`: a command-line usage error. The stable `code` is `USAGE_ERROR`;
+  `message` is the error text. Usage errors exit with status 2.
+- `internal`: any other policy, platform, or system error. The stable `code` is
+  `INTERNAL_ERROR`; `detail` is an object of diagnostic key/value pairs (for
+  example `source`, `file`, or platform API details).
+
+The `reason` field is a platform-independent classification of the policy
+decision, derived from the policy and the requested path rather than from the
+enforcement mechanism. Its stable values are:
+
+- `allow_miss`: the path matched no allow root and was denied by default.
+- `deny_match`: the path matched an explicit deny root that overrides an allow.
+- `unclassified`: a denial occurred but landstrip could not attribute it to a
+  specific rule.
 
 Example of a filesystem denial:
 
 ```json
 {
-  "Filesystem": {
-    "code": "FS_WRITE_DENIED",
-    "operation": "write",
-    "path": "/repo/out",
-    "requested_path": "out",
-    "syscall": "openat",
-    "errno": "EACCES",
-    "flags": [
-      "O_WRONLY",
-      "O_CREAT",
-      "O_TRUNC"
-    ],
-    "reason": "not_in_allow_write",
-    "suggested_grant": {
-      "allowWrite": "/repo/out"
-    },
-    "mechanism": "seccomp",
-    "process": {
-      "pid": 1234,
-      "exe": "/usr/bin/sh",
-      "cwd": "/repo"
-    }
+  "kind": "filesystem",
+  "code": "FS_WRITE_DENIED",
+  "operation": "write",
+  "path": "/repo/out",
+  "requested_path": "out",
+  "syscall": "openat",
+  "errno": "EACCES",
+  "flags": [
+    "O_WRONLY",
+    "O_CREAT",
+    "O_TRUNC"
+  ],
+  "reason": "allow_miss",
+  "suggested_grant": {
+    "allowWrite": "/repo/out"
+  },
+  "mechanism": "seccomp",
+  "process": {
+    "pid": 1234,
+    "exe": "/usr/bin/sh",
+    "cwd": "/repo"
   }
 }
 ```
@@ -189,49 +199,51 @@ emitted with the same object shapes as standard error:
 
 ```json
 {
-  "Filesystem": {
-    "code": "FS_WRITE_DENIED",
-    "operation": "write",
-    "path": "/repo/out",
-    "requested_path": "out",
-    "syscall": "openat",
-    "errno": "EACCES",
-    "flags": [
-      "O_WRONLY",
-      "O_CREAT",
-      "O_TRUNC"
-    ],
-    "reason": "not_in_allow_write",
-    "suggested_grant": {
-      "allowWrite": "/repo/out"
-    },
-    "mechanism": "seccomp",
-    "process": {
-      "pid": 1234,
-      "exe": "/usr/bin/sh",
-      "cwd": "/repo"
-    }
+  "kind": "filesystem",
+  "code": "FS_WRITE_DENIED",
+  "operation": "write",
+  "path": "/repo/out",
+  "requested_path": "out",
+  "syscall": "openat",
+  "errno": "EACCES",
+  "flags": [
+    "O_WRONLY",
+    "O_CREAT",
+    "O_TRUNC"
+  ],
+  "reason": "allow_miss",
+  "suggested_grant": {
+    "allowWrite": "/repo/out"
+  },
+  "mechanism": "seccomp",
+  "process": {
+    "pid": 1234,
+    "exe": "/usr/bin/sh",
+    "cwd": "/repo"
   }
 }
 {
-  "Network": {
-    "code": "NET_CONNECT_DENIED",
-    "operation": "connect",
-    "target": "127.0.0.1:9999",
-    "syscall": "connect",
-    "errno": "EACCES",
-    "mechanism": "seccomp",
-    "process": {
-      "pid": 1234,
-      "exe": "/usr/bin/nc",
-      "cwd": "/repo"
-    }
+  "kind": "network",
+  "code": "NET_CONNECT_DENIED",
+  "operation": "connect",
+  "target": "127.0.0.1:9999",
+  "syscall": "connect",
+  "errno": "EACCES",
+  "mechanism": "seccomp",
+  "process": {
+    "pid": 1234,
+    "exe": "/usr/bin/nc",
+    "cwd": "/repo"
   }
 }
 ```
 
 The `mechanism` field records the kernel enforcement layer that detected the
-denial (e.g. `seccomp` or `landlock`).
+denial. Per-denial `Filesystem` and `Network` traps are always `seccomp`,
+because the user-notification broker is the only layer with a per-denial
+callback; Landlock enforces in-kernel without one. The `landlock` value
+appears only as a `mechanism` detail in an `Internal` trap when Landlock
+ruleset setup fails.
 
 This stream is separate from the sandboxed tool's output. If the option is
 omitted, landstrip is quiet unless it has to report a policy, launch, or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@landstrip/landstrip",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "Sandbox runner using Landlock, Seatbelt, and AppContainer",
   "license": "Apache-2.0 AND LGPL-2.1-or-later",
   "homepage": "https://github.com/landstrip/landstrip#readme",
@@ -24,10 +24,10 @@
     "LICENSE-LGPL-2.1"
   ],
   "optionalDependencies": {
-    "@landstrip/landstrip-darwin-arm64": "0.15.0",
-    "@landstrip/landstrip-darwin-x64": "0.15.0",
-    "@landstrip/landstrip-linux-x64": "0.15.0",
-    "@landstrip/landstrip-win32-x64": "0.15.0"
+    "@landstrip/landstrip-darwin-arm64": "0.15.1",
+    "@landstrip/landstrip-darwin-x64": "0.15.1",
+    "@landstrip/landstrip-linux-x64": "0.15.1",
+    "@landstrip/landstrip-win32-x64": "0.15.1"
   },
   "publishConfig": {
     "access": "public"