modelos-secure 0.1.2 → 0.3.0

package/README.md

@@ -6,18 +6,37 @@ Tests an AI system for Security, Safety and Quality. One command in the system's
 npx modelos-secure scan .
 ```
 
-It reads the code, draws the system's map and asks only what it cannot work out. Everything it decides goes into `modelos-secure.yaml`. Before it sends anything it says exactly what leaves the machine, and `--explain` prints the outline without sending it. `--offline` keeps everything on your machine.
-
-| Command                                       | Does                                                           |
-| --------------------------------------------- | -------------------------------------------------------------- |
-| `modelos-secure login`                        | Saves a workspace token, and signs in with Google if needed.   |
-| `modelos-secure scan .`                       | Connects this repository. `--offline`, `--explain`, `--yes`.   |
-| `modelos-secure review`                       | Starts a review of this system. `--quick`, `--ci`, `--budget`. |
-| `modelos-secure replay F-031`                 | Replays one finding.                                           |
-| `modelos-secure doctor`                       | Checks the setup and fixes what it can.                        |
-| `modelos-secure export R-1179 --format sarif` | Writes a review's findings as SARIF or JSON.                   |
-
-During a review, actions are held and never run. Outside a review the hooks do nothing. Requires Node 20 or newer. Python apps need Python 3.10 or newer.
+It reads the code the way an engineer would, starting where the app starts, draws the system's map and asks only what it cannot work out. Everything it decides goes into `modelos-secure.yaml`.
+
+Before it sends anything it asks once whether a model may read the code it needs, or only an outline of it, or nothing. Every answer it sends passes a filter that takes secrets out, and settings files, keys and credentials are never read. `.modelos-secure/sent.jsonl` lists what was sent, `--explain` shows the outline and what may and may not be read without sending anything, and `--offline` keeps everything on your machine.
+
+At a terminal, `modelos-secure` on its own starts a session about the app in the folder: ask about it in your own words, and each answer cites the files and lines it rests on, checked against the code.
+
+| Command                                       | Does                                                               |
+| --------------------------------------------- | ------------------------------------------------------------------ |
+| `modelos-secure`                              | At a terminal, a session about the app in this folder.             |
+| `modelos-secure login`                        | Saves a workspace token, and signs in with Google if needed.       |
+| `modelos-secure scan .`                       | Connects this repository. `--offline`, `--explain`, `--yes`.       |
+| `modelos-secure review`                       | Starts a review of this system. `--quick`, `--ci`, `--budget`.     |
+| `modelos-secure replay F-031`                 | Replays one finding.                                               |
+| `modelos-secure doctor`                       | Checks the setup and fixes what it can.                            |
+| `modelos-secure runner`                       | Serves a review's attempts from this machine, in the app's folder. |
+| `modelos-secure export R-1179 --format sarif` | Writes a review's findings as SARIF or JSON.                       |
+| `modelos-secure --version`                    | Prints this CLI's version.                                         |
+
+A review of an app connected by the scan reaches it through a runner on the machine that runs it. `modelos-secure review` starts one itself, and keeps it while the review is paused; a review started from the app needs `modelos-secure runner` running in the app's folder, and says so if none is. A start command is checked before it runs and saved only once the app has started with it.
+
+During a review, actions are held and never run. Outside a review the hooks do nothing. Requires Node 22 or newer. Python apps need Python 3.10 or newer.
+
+Every command says what it takes with `--help`, such as `modelos-secure scan --help`, and refuses a flag it does not take.
+
+| Exit code | Means                                                          |
+| --------- | -------------------------------------------------------------- |
+| 0         | Done.                                                          |
+| 1         | Something failed, or a fix check found a break.                |
+| 2         | The command was used wrongly.                                  |
+| 3         | There are questions only a person can answer, as `--ci` lists. |
+| 130       | Stopped with Ctrl-C. What was done is kept.                    |
 
 ## Signing in
 

package/dist/README.md

@@ -0,0 +1,60 @@
+# modelos-secure
+
+Tests an AI system for Security, Safety and Quality. One command in the system's repository connects it, with no code changes:
+
+```bash
+npx modelos-secure scan .
+```
+
+It reads the code the way an engineer would, starting where the app starts, draws the system's map and asks only what it cannot work out. Everything it decides goes into `modelos-secure.yaml`.
+
+Before it sends anything it asks once whether a model may read the code it needs, or only an outline of it, or nothing. Every answer it sends passes a filter that takes secrets out, and settings files, keys and credentials are never read. `.modelos-secure/sent.jsonl` lists what was sent, `--explain` shows the outline and what may and may not be read without sending anything, and `--offline` keeps everything on your machine.
+
+At a terminal, `modelos-secure` on its own starts a session about the app in the folder: ask about it in your own words, and each answer cites the files and lines it rests on, checked against the code.
+
+| Command                                       | Does                                                               |
+| --------------------------------------------- | ------------------------------------------------------------------ |
+| `modelos-secure`                              | At a terminal, a session about the app in this folder.             |
+| `modelos-secure login`                        | Saves a workspace token, and signs in with Google if needed.       |
+| `modelos-secure scan .`                       | Connects this repository. `--offline`, `--explain`, `--yes`.       |
+| `modelos-secure review`                       | Starts a review of this system. `--quick`, `--ci`, `--budget`.     |
+| `modelos-secure replay F-031`                 | Replays one finding.                                               |
+| `modelos-secure doctor`                       | Checks the setup and fixes what it can.                            |
+| `modelos-secure runner`                       | Serves a review's attempts from this machine, in the app's folder. |
+| `modelos-secure export R-1179 --format sarif` | Writes a review's findings as SARIF or JSON.                       |
+| `modelos-secure --version`                    | Prints this CLI's version.                                         |
+
+A review of an app connected by the scan reaches it through a runner on the machine that runs it. `modelos-secure review` starts one itself, and keeps it while the review is paused; a review started from the app needs `modelos-secure runner` running in the app's folder, and says so if none is. A start command is checked before it runs and saved only once the app has started with it.
+
+During a review, actions are held and never run. Outside a review the hooks do nothing. Requires Node 22 or newer. Python apps need Python 3.10 or newer.
+
+Every command says what it takes with `--help`, such as `modelos-secure scan --help`, and refuses a flag it does not take.
+
+| Exit code | Means                                                          |
+| --------- | -------------------------------------------------------------- |
+| 0         | Done.                                                          |
+| 1         | Something failed, or a fix check found a break.                |
+| 2         | The command was used wrongly.                                  |
+| 3         | There are questions only a person can answer, as `--ci` lists. |
+| 130       | Stopped with Ctrl-C. What was done is kept.                    |
+
+## Signing in
+
+Copy the login command from the workspace tokens page in the app. It has the app's address and, when the app is behind Google sign-in, the Google client to sign in with:
+
+```bash
+npx modelos-secure login --url <address> --client-id <client ID> --client-secret <client secret>
+```
+
+Paste the workspace token when it asks. The token is never typed on the command line. Your browser then opens for you to sign in with Google. The address, the token and the Google sign-in are kept in `~/.modelos-secure/credentials.json`, readable only by you, and the sign-in is renewed as it runs out. Without `--client-id`, as on a local stack, there is no Google sign-in.
+
+When the app is reached at an IP address and its certificate is issued for a name, the login command also has `--tls-name` and that name. The CLI then connects to the address and checks the certificate against the name: its chain, its dates and the name are all still checked. `MODELOS_SECURE_TLS_NAME` does the same for one run. When something cannot be reached, the CLI says why in plain words.
+
+`MODELOS_SECURE_URL` and `MODELOS_SECURE_TOKEN` take the place of the saved address and token. `modelos-secure doctor` says who is signed in to Google, and why a request was turned away.
+
+## In CI
+
+CI has no browser, so it signs in to Google as a service account. The service account needs IAP-secured Web App User on the app, and the client ID must be the one on the tokens page. Set `MODELOS_SECURE_URL` and `MODELOS_SECURE_TOKEN`, then one of these:
+
+- `MODELOS_SECURE_CLIENT_ID`, the client ID from the tokens page, with gcloud signed in as the service account. The CLI runs `gcloud auth print-identity-token --audiences=<client ID>` and runs it again as the token runs out, so it suits reviews of any length. It does not work with a person's own gcloud sign-in.
+- `MODELOS_SECURE_IAP_TOKEN`, an ID token for the service account with the client ID as its audience. It is sent as it is and never renewed, and it lasts about an hour. In GitHub Actions, `google-github-actions/auth` makes one with `token_format: id_token`, `id_token_audience` set to the client ID and `id_token_include_email: true`.

package/dist/assets/login-CvPyhFJ7.js

@@ -0,0 +1 @@
+export { t as loginCommand } from "./login-DeAJGhiN.js";

package/{assets/login-JPkrnvZC.js → dist/assets/login-DeAJGhiN.js}

@@ -5,7 +5,7 @@ import { execFile, spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import { emitKeypressEvents } from "node:readline";
-import { request } from "node:https";
+import { request as request$1 } from "node:https";
 import { checkServerIdentity } from "node:tls";
 // src/ui.ts
 var color = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -17,12 +17,35 @@ var grey = (t) => paint("90", t);
 var bold = (t) => paint("1", t);
 var interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY) && !process.env.CI;
 var pointer = unicode ? "›" : ">";
-var dash = unicode ? "–" : "-";
 function say(line = "") {
 	console.log(line);
 }
 var STEP_WIDTH = 13;
+var lastStep = "";
+/** The last step that finished, so a stop can say where it happened. */
+var lastFinishedStep = () => lastStep;
+/** Work to finish before the process ends on Ctrl-C, such as stopping a review it started. */
+var onStop = [];
+function beforeStopping(work) {
+	onStop.push(work);
+	return () => {
+		onStop.splice(onStop.indexOf(work), 1);
+	};
+}
+async function finishBeforeStopping() {
+	await Promise.race([Promise.allSettled(onStop.map((work) => work())), new Promise((resolve) => setTimeout(resolve, 5e3))]);
+}
+/**
+* One line that changes in place while work goes on, at a terminal only: what is being read now.
+* An empty line clears it. Off a terminal it writes nothing, so a log holds only finished steps.
+*/
+function status(line) {
+	if (!process.stdout.isTTY) return;
+	const width = Math.max(20, (process.stdout.columns || 80) - 4);
+	process.stdout.write(`\r\u001b[2K${line ? `  ${grey(line.slice(0, width))}` : ""}`);
+}
 function step(name, detail, state = "done") {
+	if (state === "done") lastStep = name;
 	const right = state === "done" ? "done" : "";
 	say(`  ${bold(name.padEnd(STEP_WIDTH))}${detail}${right ? `  ${grey(right)}` : ""}`);
 }
@@ -83,15 +106,19 @@ async function ask(question, why, choices) {
 async function askText(question, secret = false) {
 	process.stdout.write(`  ${question} `);
 	if (!interactive()) return "";
-	return new Promise((resolve) => {
+	return new Promise((resolve, reject) => {
 		let value = "";
 		emitKeypressEvents(process.stdin);
 		process.stdin.setRawMode(true);
 		process.stdin.resume();
 		const onKey = (text, key) => {
 			if (key.ctrl && key.name === "c") {
+				process.stdin.off("keypress", onKey);
 				process.stdin.setRawMode(false);
-				process.exit(130);
+				process.stdin.pause();
+				process.stdout.write("\n");
+				reject(new Interrupted());
+				return;
 			}
 			if (key.name === "return") {
 				process.stdin.off("keypress", onKey);
@@ -101,7 +128,10 @@ async function askText(question, secret = false) {
 				resolve(value.trim());
 				return;
 			}
-			if (key.name === "backspace") value = value.slice(0, -1);
+			if (key.name === "backspace") {
+				if (value && !secret) process.stdout.write("\b \b");
+				value = value.slice(0, -1);
+			} else if (key.name === "tab") return;
 			else if (text && !key.ctrl) {
 				value += text;
 				if (!secret) process.stdout.write(text);
@@ -282,7 +312,7 @@ function gcloudIdentityToken(audience) {
 /** A fetch that connects to the URL's host and checks its certificate against `name`. */
 function fetchCheckingName(name) {
 	return (url, init = {}) => new Promise((resolve, reject) => {
-		const outgoing = request(new URL(url), {
+		const outgoing = request$1(new URL(url), {
 			method: init.method ?? "GET",
 			headers: init.headers,
 			servername: name,
@@ -521,7 +551,15 @@ var IapRefusal = class extends ApiError {
 		this.kind = kind;
 	}
 };
+/** Hosts a token may reach over plain http: this machine only, as in local development. */
+var LOCAL_HOSTS = /* @__PURE__ */ new Set([
+	"localhost",
+	"127.0.0.1",
+	"[::1]"
+]);
 function apiClient(connection, options = {}) {
+	const target = new URL(connection.url);
+	if (target.protocol === "http:" && !LOCAL_HOSTS.has(target.hostname)) throw new Error(`The address ${target.origin} starts with http://, so your token would travel in clear. Use its https:// address.`);
 	const proxy = proxyCredentials(connection.google, {
 		saved: (google) => saveRenewed(connection.url, google),
 		...options
@@ -639,4 +677,4 @@ async function loginCommand(given = {}) {
 	const who = connection.google?.email;
 	say(`Saved. This machine now works in ${me.workspace}${who ? `, signed in to Google as ${who}` : ""}.`);
 }
-export { step as _, apiClient as a, Interrupted as c, blue as d, bold as f, say as g, red as h, IapRefusal as i, ask as l, grey as m, parseLoginLine as n, atAddress as o, dash as p, ApiError as r, readConnection as s, loginCommand as t, askText as u };
+export { lastFinishedStep as _, apiClient as a, status as b, Interrupted as c, beforeStopping as d, blue as f, interactive as g, grey as h, IapRefusal as i, ask as l, finishBeforeStopping as m, parseLoginLine as n, atAddress as o, bold as p, ApiError as r, readConnection as s, loginCommand as t, askText as u, red as v, step as x, say as y };