@delorenj/pjangler 1.3.0 → 1.4.2

package/dist/assets/project-notebook-skill/hooks/session-start.sh

@@ -0,0 +1,228 @@
+#!/usr/bin/python3 -I
+"""Fail-open SessionStart bridge to the fixed PJangler user installation."""
+
+from __future__ import annotations
+
+import grp
+import os
+import pwd
+import signal
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+DISPLAY_EVENT = "SessionStart"
+HOOK_EVENT = "session-start"
+REQUEST_LIMIT_BYTES = 1_048_576
+STREAM_LIMIT_BYTES = REQUEST_LIMIT_BYTES + 1
+CHILD_TIMEOUT_SECONDS = 2.25
+NODE_BINARY = Path("/usr/bin/node")
+AUTH_VARIABLE = "OPEN_NOTEBOOK_PASSWORD"
+
+
+class LauncherError(RuntimeError):
+    """A bounded launcher-validation failure."""
+
+
+def fail_open(reason: str) -> int:
+    print(f"project-notebook: {DISPLAY_EVENT} {reason}", file=sys.stderr)
+    return 0
+
+
+def canonical_identity() -> pwd.struct_passwd:
+    entry = pwd.getpwuid(os.geteuid())
+    if entry.pw_uid != os.geteuid():
+        raise LauncherError("skipped; canonical user identity is invalid")
+    home = Path(entry.pw_dir)
+    if not home.is_absolute() or home == Path("/") or ".." in home.parts:
+        raise LauncherError("skipped; canonical user home is invalid")
+    return entry
+
+
+def private_primary_group(entry: pwd.struct_passwd) -> bool:
+    try:
+        group = grp.getgrgid(entry.pw_gid)
+        primary_users = {
+            candidate.pw_name for candidate in pwd.getpwall() if candidate.pw_gid == entry.pw_gid
+        }
+    except (KeyError, OSError):
+        return False
+    if entry.pw_name not in primary_users:
+        return False
+    writers = primary_users | set(group.gr_mem)
+    return writers <= {entry.pw_name}
+
+
+def path_components(path: Path) -> list[Path]:
+    if not path.is_absolute() or path == Path("/"):
+        raise LauncherError("skipped; trusted path is invalid")
+    components: list[Path] = []
+    current = Path("/")
+    for component in path.parts[1:]:
+        if component in ("", ".", ".."):
+            raise LauncherError("skipped; trusted path is invalid")
+        current /= component
+        components.append(current)
+    return components
+
+
+def reject_symlink_components(path: Path) -> None:
+    for component in path_components(path):
+        try:
+            information = component.lstat()
+        except OSError as exc:
+            raise LauncherError("skipped; trusted path is unavailable") from exc
+        if stat.S_ISLNK(information.st_mode):
+            raise LauncherError("skipped; trusted path contains a symlink")
+
+
+def validate_owned_component(
+    path: Path,
+    entry: pwd.struct_passwd,
+    *,
+    directory: bool,
+    private_group: bool,
+) -> None:
+    try:
+        information = path.lstat()
+    except OSError as exc:
+        raise LauncherError("skipped; trusted path is unavailable") from exc
+    expected_type = stat.S_ISDIR if directory else stat.S_ISREG
+    if stat.S_ISLNK(information.st_mode) or not expected_type(information.st_mode):
+        raise LauncherError("skipped; trusted path has an unsafe type")
+    if information.st_uid != entry.pw_uid or information.st_gid != entry.pw_gid:
+        raise LauncherError("skipped; trusted path ownership is unsafe")
+    mode = stat.S_IMODE(information.st_mode)
+    special = stat.S_ISUID | stat.S_ISGID | stat.S_ISVTX
+    if mode & (special | stat.S_IWOTH):
+        raise LauncherError("skipped; trusted path permissions are unsafe")
+    if mode & stat.S_IWGRP and not private_group:
+        raise LauncherError("skipped; trusted path group is not private")
+    if not directory and not mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH):
+        raise LauncherError("skipped; trusted pj is not executable")
+
+
+def validate_owned_tree(
+    home: Path,
+    target: Path,
+    entry: pwd.struct_passwd,
+    *,
+    final_directory: bool,
+    private_group: bool,
+) -> None:
+    try:
+        relative = target.relative_to(home)
+    except ValueError as exc:
+        raise LauncherError("skipped; resolved pj is outside canonical home") from exc
+    reject_symlink_components(target)
+    validate_owned_component(home, entry, directory=True, private_group=private_group)
+    current = home
+    for index, component in enumerate(relative.parts):
+        current /= component
+        validate_owned_component(
+            current,
+            entry,
+            directory=final_directory or index < len(relative.parts) - 1,
+            private_group=private_group,
+        )
+
+
+def validate_node_binary() -> None:
+    try:
+        information = NODE_BINARY.lstat()
+    except OSError as exc:
+        raise LauncherError("skipped; fixed node runtime is unavailable") from exc
+    mode = stat.S_IMODE(information.st_mode)
+    special = stat.S_ISUID | stat.S_ISGID | stat.S_ISVTX
+    if (
+        stat.S_ISLNK(information.st_mode)
+        or not stat.S_ISREG(information.st_mode)
+        or information.st_uid != 0
+        or mode & (special | stat.S_IWGRP | stat.S_IWOTH)
+        or not mode & (stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    ):
+        raise LauncherError("skipped; fixed node runtime is unsafe")
+
+
+def resolve_launcher(entry: pwd.struct_passwd) -> Path:
+    home = Path(entry.pw_dir)
+    launcher = home / ".local" / "bin" / "pj"
+    private_group = private_primary_group(entry)
+    reject_symlink_components(launcher.parent)
+    validate_owned_tree(
+        home,
+        launcher.parent,
+        entry,
+        final_directory=True,
+        private_group=private_group,
+    )
+    try:
+        resolved = launcher.resolve(strict=True)
+    except OSError as exc:
+        raise LauncherError("skipped; trusted pj launcher cannot be resolved") from exc
+    validate_owned_tree(
+        home,
+        resolved,
+        entry,
+        final_directory=False,
+        private_group=private_group,
+    )
+    return resolved
+
+
+def sanitized_environment(entry: pwd.struct_passwd) -> dict[str, str]:
+    environment = {
+        "HOME": entry.pw_dir,
+        "USER": entry.pw_name,
+        "LOGNAME": entry.pw_name,
+        "PATH": "/usr/bin:/bin",
+        "LANG": "C.UTF-8",
+        "LC_ALL": "C.UTF-8",
+    }
+    authentication = os.environ.get(AUTH_VARIABLE)
+    if authentication is not None:
+        environment[AUTH_VARIABLE] = authentication
+    return environment
+
+
+def invoke(entry: pwd.struct_passwd, launcher: Path, payload: bytes) -> int:
+    process = subprocess.Popen(
+        [str(NODE_BINARY), str(launcher), "notebook", "hook", HOOK_EVENT],
+        stdin=subprocess.PIPE,
+        env=sanitized_environment(entry),
+        close_fds=True,
+        start_new_session=True,
+    )
+    try:
+        process.communicate(payload, timeout=CHILD_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        process.wait()
+        return fail_open("timed out; run pj notebook audit")
+    if process.returncode != 0:
+        return fail_open("failed open; run pj notebook audit")
+    return 0
+
+
+def main() -> int:
+    entry = canonical_identity()
+    validate_node_binary()
+    launcher = resolve_launcher(entry)
+    payload = sys.stdin.buffer.read(STREAM_LIMIT_BYTES)
+    if len(payload) > REQUEST_LIMIT_BYTES:
+        return fail_open("skipped; hook payload exceeds 1048576 bytes")
+    return invoke(entry, launcher, payload)
+
+
+if __name__ == "__main__":
+    try:
+        result = main()
+    except LauncherError as exc:
+        result = fail_open(str(exc))
+    except Exception:
+        result = fail_open("failed open; run pj notebook audit")
+    raise SystemExit(result)

package/dist/assets/project-notebook-skill/references/configuration.md

@@ -0,0 +1,93 @@
+# Project Notebook configuration
+
+## Public commands
+
+```text
+pj notebook status [repo] [--local-only] [--json]
+pj notebook create [repo] --live [--json]
+pj notebook list notes [repo] [--limit N] [--cursor VALUE] [--json]
+pj notebook add note [repo] --title TEXT (--text TEXT | --file PATH) [--json]
+pj notebook get note NOTE_ID [repo] [--json]
+pj notebook update note NOTE_ID [repo] [--title TEXT] (--text TEXT | --file PATH) [--json]
+pj notebook delete note NOTE_ID [repo] [--yes] [--json]
+pj notebook search notes QUERY [repo] [--limit N] [--json]
+pj notebook overview [repo] [--set-file PATH] [--json]
+pj notebook capture list [repo] [--state VALUE] [--json]
+pj notebook capture retry RECEIPT_ID [repo] [--baseline GIT_REF] [--json]
+pj notebook audit [repo] [--local-only] [--json]
+pj notebook migrate [repo] [--apply] [--live] [--json]
+```
+
+The `hook` and `worker` command families are internal compatibility surfaces.
+Do not invoke them for ordinary notebook work.
+
+## Policy and credentials
+
+Effective policy precedence is built-in safe defaults, global Project Registry
+defaults, Project Manifest policy, then an explicit option for one invocation.
+An explicit disable wins for hook behavior.
+
+The Project Registry owns binding identifiers and binding state. The Project
+Manifest mirrors binding fields for inspection and owns repository policy. It
+must not contain a service URL, credential, or derived authentication value.
+Resolve endpoint and authentication at runtime through PJangler's configured
+secret boundary. Never put user content or secrets in argv or logs.
+
+## Canonical Claude projection
+
+Run the projector from this skill directory:
+
+```text
+python3 scripts/project-hooks.py check [--target PATH] [--json]
+python3 scripts/project-hooks.py render
+python3 scripts/project-hooks.py install [--target PATH]
+python3 scripts/project-hooks.py uninstall [--target PATH]
+```
+
+The default target is `~/.claude/settings.json`; tests and packaged installers
+may supply an isolated absolute target. `render` deterministically derives
+`hooks/claude.settings.json` from `hooks/hooks.master.json`. `check` is
+read-only. Install and uninstall take the Project Notebook advisory lock,
+re-read live settings while locked, snapshot the exact preimage, and replace
+the target only when owned semantics change. Directory traversal, private-state
+creation, lock/snapshot access, temporary-file creation, and atomic replacement
+are descriptor-relative with `O_DIRECTORY|O_NOFOLLOW`; an ancestor pathname
+swap cannot redirect a write outside the directory already opened.
+
+The only owned commands are an anchored `PJ_HOOK_OWNER=project-notebook.v1 `
+prefix followed by exactly one recognized wrapper path for the same event:
+
+```text
+SessionStart  "$HOME/.agents/skills/project-notebook/hooks/session-start.sh"  timeout 3
+SessionEnd    "$HOME/.agents/skills/project-notebook/hooks/session-end.sh"    timeout 1
+```
+
+`Stop` is not a session-close event and is always foreign. Prefix-similar,
+unknown-wrapper, extra-argument, and event-mismatched commands are preserved
+and reported rather than claimed.
+
+Despite their stable `.sh` filenames, the wrappers are isolated
+`/usr/bin/python3 -I` launchers. They derive the canonical user home from the
+passwd database, then use only `<canonical-home>/.local/bin/pj`. Intermediate
+launcher-parent symlinks are rejected. The launcher itself may be a symlink,
+but its resolved absolute target and every target-path component must be owned
+by the current user's primary user/group, must not be world-writable or carry
+special mode bits, and the target must be a regular executable file. Private
+primary-group write is accepted only when passwd and group enumeration proves
+that no other group member or primary user can write through that group.
+
+The resolved launcher is executed as an argument to fixed `/usr/bin/node`, not
+through its shebang or inherited `PATH`. The child environment contains only
+canonical `HOME`, `USER`, and `LOGNAME`; fixed `PATH` and locale values; and, if
+present, `OPEN_NOTEBOOK_PASSWORD`. Unattended hooks do not forward an arbitrary
+registry `auth.env_var`; configure this exact allowlisted variable for hook
+authentication or use an interactive/public command path. Inputs such as
+`BASH_ENV`, `NODE_OPTIONS`, `NODE_PATH`, and project-controlled environment
+variables cannot redirect or preload the child.
+
+Hook JSON is never staged to disk. Each wrapper reads at most 1,048,577 bytes;
+if the sentinel byte is present, it fails open before creating a child because
+the 1,048,576-byte request ceiling was exceeded. Valid-size input is sent over
+stdin with an explicit child timeout shorter than the outer hook timeout.
+Resolution, validation, input, timeout, and PJangler failures are bounded and
+fail open without creating wrapper-local state.

package/dist/assets/project-notebook-skill/references/recovery.md

@@ -0,0 +1,54 @@
+# Project Notebook recovery
+
+## Diagnose before repairing
+
+Start with `pj notebook status [repo]`, then run
+`pj notebook audit [repo]`. Use `--local-only` when remote observation is not
+authorized or available. Follow the exact bounded `next_actions` returned by
+the command.
+
+For `PROJECT NOTEBOOK OVERVIEW DRIFT`, treat the stored Overview as stale. Run
+the reported `notebook.overview-note` audit and use
+`pj notebook migrate [repo] --apply --live` only when same-note remote repair is
+intended. Do not create a replacement Overview ID and never copy notebook text
+back over authoritative repository documents.
+
+## Capture receipts and admission pressure
+
+List visible work with `pj notebook capture list [repo]`. Receipt states are
+`queued`, `processing`, `succeeded`, `failed`, `retry-exhausted`, and
+`blocked-missing-baseline`. Retention pressure is a current admission finding,
+not another state.
+
+Never delete or compact unresolved receipts. Succeeded receipts may age out
+under configured retention. At a count or byte cap, the refused session has no
+receipt and was not captured; use the exact list/retry actions in the bounded
+diagnostic. Admission resumes only below both prospective caps.
+
+One explicit `pj notebook capture retry RECEIPT_ID [repo]` invocation grants
+one attempt on that same failed or retry-exhausted receipt. A
+`blocked-missing-baseline` receipt additionally needs a validated explicit
+`--baseline GIT_REF`.
+
+## Restore hook settings
+
+Projector mutations store the exact prior JSON bytes under:
+
+```text
+$XDG_STATE_HOME/pjangler/notebook/v1/hook-install/snapshots/<sha256>.json
+```
+
+The fallback state home is `~/.local/state`. Projector-owned directories are
+mode `0700`; lock and snapshot files are mode `0600`. An absent original target
+is represented by the empty JSON object snapshot. Snapshot filenames are
+content-addressed, so repeated identical preimages do not create duplicates.
+All projector state and target mutations are relative to no-follow directory
+descriptors, so replacing an ancestor pathname with a symlink cannot redirect
+the snapshot, temporary file, or final atomic replacement.
+
+Inspect the target and snapshot before manual restoration. Do not print their
+contents because operator settings may be sensitive. `uninstall` is normally
+safer: it removes only recognized Project Notebook hooks and prunes only the
+group/event made empty by that removal. It leaves the skill source, remote
+notebook, bindings, Bloodbank, Hindsight, Git checkpoint, notifications, and
+all other foreign settings intact.