@namzu/cli 29.0.1 → 29.1.0

package/dist/schedule/floor.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The scheduled-run floor: what no scheduled run may do, whatever its rules
+ * say.
+ *
+ * A scheduled run must not reach its own scheduler — stop, disable or remove
+ * the service, or run a `namzu schedule` subcommand that changes something —
+ * and must not name `NAMZU_HOME`, where its job, its history, the daemon's
+ * endpoint token and the credentials beside them live, nor the Windows
+ * browser's profile folder (`%LOCALAPPDATA%\namzu`), where namzu keeps the
+ * profiles it drives from WSL with the cookies of every site the operator
+ * signed in to.
+ *
+ * ## Why this is code and not patterns
+ *
+ * The floor used to be regular expressions over the command line's text.
+ * A pattern about what a line RUNS has to re-implement the shell's quoting to
+ * see through `'sched'ule`, `$'\x73'chedule`, `sche\<newline>dule` and
+ * `namzu --add-dir ';' schedule stop`, and each review round found another
+ * form it missed, plus a pattern that backtracked quadratically. The SDK
+ * reads a command line once, with the lexer the gate itself uses
+ * (`lexShellCommandLine`, checked against real bash), and this module decides
+ * on what that lexer reports: the words bash will pass to each simple
+ * command, after quote removal and `$'…'` decoding, the payload of a nested
+ * `bash -c`, every redirection target, and the words of `for` lists and
+ * `case` statements. Quoting is the lexer's business; this file never
+ * mentions a quote character except in the tripwire below.
+ *
+ * ## What is decided, and how
+ *
+ * - **Scheduler commands**, on each simple command's words in order,
+ *   anywhere in the command, so `sudo`, `env`, `nohup` or `timeout` in front
+ *   changes nothing: `systemctl` + a stopping verb + a unit naming namzu (or
+ *   a glob), `launchctl` + a removing verb + a namzu label, `schtasks` with a
+ *   `/delete`, `/change` or `/end` switch and a namzu task in any order,
+ *   `pkill`/`killall` with a pattern that could match the daemon,
+ *   `busctl`/`dbus-send`/`gdbus` naming namzu, and the CLI (`namzu` or a path
+ *   to it, `@namzu/cli`, a `bin.js`, or a JavaScript runtime) with `schedule`
+ *   followed by anything but a read-only verb. A word that expands at
+ *   runtime (`$V`) stands for any word in any of those places; one whose only
+ *   expansion is locale quoting (`$"stop"`) is read as its text.
+ * - **NAMZU_HOME**, on every word, redirection target, `for` list and `case`
+ *   word: `~` (where bash expands it), `$HOME`, `${HOME}`, `$NAMZU_HOME` and
+ *   `$PWD` are expanded here from known values, as are variables the line
+ *   itself assigns; `..` and `.` are resolved; a relative path is resolved
+ *   against the job's folder and every directory a `cd` before it names.
+ *   Where a word still holds an unknown expansion or a glob, it is denied
+ *   when the known part before it could lead into NAMZU_HOME (`~/.nam*`,
+ *   `~/$X`, `/$X`), or the text after it names NAMZU_HOME's last segment. An
+ *   assignment standing alone reaches no program and is judged where the
+ *   variable is used; one that is exported is judged where it stands.
+ * - **What the lexer cannot account for** — an opaque line (a command
+ *   substitution, `eval`-like constructs, a syntax error, a construct it does
+ *   not model), a command whose name expands, or a program that runs text as
+ *   code (`sh` reading its input, `sudo bash -c`, `python`, `xargs`, `watch`
+ *   …) — is denied when the line's text mentions anything the floor
+ *   protects: a scheduler word, `namzu`, NAMZU_HOME's name or a path into it.
+ *   That is the tripwire, deliberately textual and cheap. Text such a program
+ *   may run — an argument, a here-string, a here-document's body — is also
+ *   read as a command line of its own, so an escape only the inner shell
+ *   undoes does not hide it.
+
+ * - **The Windows browser's profiles**, on the same words, spellings and
+ *   directories: a path whose segments run `AppData/Local/namzu` (any user,
+ *   any drive, `/mnt/c/Users/<you>/…` or `C:\Users\<you>\…`, either slash,
+ *   any letter case), with `%LOCALAPPDATA%`, `$env:LOCALAPPDATA` and
+ *   `$LOCALAPPDATA` spelled out. The user folder above it is not known here,
+ *   so the three segments are what is matched. Where a word holds an unknown
+ *   expansion or a glob, it is denied when its segments could still read
+ *   `AppData/Local/namzu` and one of them is spelled out, or when an unknown
+ *   expansion is followed by a `namzu` segment.
+
+ * Every other tool's arguments are strings, not shell: each is searched for
+ * NAMZU_HOME and the browser's profiles by path, in any letter case, with
+ * `~`, `$HOME`, `$NAMZU_HOME` and `%LOCALAPPDATA%` spelled out, and once more
+ * with shell quotes and backslashes dropped, in case the tool hands it to a
+ * shell.
+ *
+ * Everything here is linear in the input.
+ */
+import { type AuthorizationPredicateCall, type AuthorizationRule } from '@namzu/sdk';
+/** Scheduler verbs a run may use: they read, they change nothing. */
+export declare const READ_ONLY_VERBS: readonly string[];
+export interface FloorOptions {
+    /** The scheduler's `NAMZU_HOME`. */
+    readonly namzuHome: string;
+    /** The home directory `~` and `$HOME` name. */
+    readonly userHome: string;
+    /**
+     * The directories a relative path starts from before any `cd`: the job's
+     * folder (as written and canonical). Absent, a relative path is resolved
+     * against nothing and only an absolute one is checked.
+     */
+    readonly folders?: readonly string[];
+    /**
+     * The command line the scheduler daemon runs under, for `pkill -f`.
+     * Defaults to this process's own node and entry script.
+     */
+    readonly daemonCommandLine?: string;
+}
+/** What the floor keeps a run's paths out of. */
+export type FloorProtected = 'NAMZU_HOME' | 'the browser profiles';
+/** Why the floor denied a call: for tests and diagnostics. */
+export type FloorReason = `names ${FloorProtected}` | 'scheduler command' | `word names ${FloorProtected}` | `assigned value names ${FloorProtected}` | `redirection names ${FloorProtected}` | `loop or case word names ${FloorProtected}` | 'opaque line mentions a protected name' | 'unread text mentions a protected name' | 'too many spellings';
+/** The floor's reason for denying a call, or null: what the rule below decides on. */
+export declare function scheduledRunFloorVerdict(options: FloorOptions): (call: AuthorizationPredicateCall) => FloorReason | null;
+/** Whether `rule` is the floor's, and so can only deny. */
+export declare function isFloorRule(rule: AuthorizationRule): boolean;
+/** The floor as one gate rule. */
+export declare function scheduledRunFloorRule(options: FloorOptions): AuthorizationRule;
+/**
+ * The Windows browser's profiles in free text: a path through
+ * `AppData/Local/namzu` or `%LOCALAPPDATA%\namzu`, in any letter case, either
+ * slash; and again with quotes and backslashes dropped, as a shell would.
+ */
+export declare function textNamesProfile(text: string): boolean;
+//# sourceMappingURL=floor.d.ts.map

package/dist/schedule/floor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"floor.d.ts","sourceRoot":"","sources":["../../src/schedule/floor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,EACN,KAAK,0BAA0B,EAC/B,KAAK,iBAAiB,EAQtB,MAAM,YAAY,CAAA;AAEnB,qEAAqE;AACrE,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAkD,CAAA;AAE/F,MAAM,WAAW,YAAY;IAC5B,oCAAoC;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CACnC;AAED,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,sBAAsB,CAAA;AAElE,8DAA8D;AAC9D,MAAM,MAAM,WAAW,GACpB,SAAS,cAAc,EAAE,GACzB,mBAAmB,GACnB,cAAc,cAAc,EAAE,GAC9B,wBAAwB,cAAc,EAAE,GACxC,qBAAqB,cAAc,EAAE,GACrC,2BAA2B,cAAc,EAAE,GAC3C,uCAAuC,GACvC,uCAAuC,GACvC,oBAAoB,CAAA;AAEvB,sFAAsF;AACtF,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,YAAY,GACnB,CAAC,IAAI,EAAE,0BAA0B,KAAK,WAAW,GAAG,IAAI,CAG1D;AAQD,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAE5D;AAED,kCAAkC;AAClC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,iBAAiB,CAS9E;AAk3BD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAStD"}