diffninja 0.3.1 → 0.4.0

package/dist/review/connected.js

@@ -11,6 +11,7 @@ const reviewSchema = z.object({
     snapshotId: z.string(), event: z.enum(["COMMENT", "APPROVE", "REQUEST_CHANGES"]), body: z.string(),
     comments: z.array(z.object({ path: z.string(), line: z.number().int().positive(), side: z.enum(["LEFT", "RIGHT"]), body: z.string() }).strict()),
 }).strict();
+const viewedSchema = z.object({ snapshotId: z.string(), path: z.string(), viewed: z.boolean() }).strict();
 const emptySchema = z.object({}).strict();
 const tokenSchema = z.string().regex(/^[a-f0-9]{64}$/);
 function described(state) {
@@ -62,31 +63,60 @@ function requestIsTrusted(req, origin) {
     const site = req.headers["sec-fetch-site"];
     return !site || ["same-origin", "none"].includes(String(site));
 }
+/**
+ * The part of a request path after this session's secret prefix, or undefined
+ * when the path does not start with it. Every route of the session lives under
+ * `/<256-bit secret>/`: a process that can reach the loopback port but was never
+ * handed the link (another local user, a script the reviewed code runs) finds
+ * nothing to read and nothing to post. Host, Origin and the CSRF token below
+ * only defend against browsers; this is what defends against the rest.
+ */
+function routeOf(url, secret) {
+    if (url === undefined || url.length < secret.length + 2 || url[0] !== "/" || url[secret.length + 1] !== "/")
+        return undefined;
+    const presented = Buffer.from(url.slice(1, secret.length + 1));
+    const expected = Buffer.from(secret);
+    if (presented.length !== expected.length || !timingSafeEqual(presented, expected))
+        return undefined;
+    return url.slice(secret.length + 2);
+}
 /** A single ephemeral session; never exposes a general GitHub API proxy. */
 export async function serveConnected(review = new ConnectedReview(), options = {}) {
     const csrf = randomBytes(32).toString("hex");
+    const secret = randomBytes(32).toString("hex");
+    const base = `/${secret}/`;
     let origin = "";
     const server = createServer(async (req, res) => {
         res.setHeader("Cache-Control", "no-store");
         res.setHeader("X-Content-Type-Options", "nosniff");
         res.setHeader("X-Frame-Options", "DENY");
         res.setHeader("Referrer-Policy", "no-referrer");
-        res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${csrf}'; style-src 'nonce-${csrf}'; connect-src 'self'; frame-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`);
+        res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+        res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
+        res.setHeader("Content-Security-Policy", "default-src 'none'; frame-ancestors 'none'");
         const json = (code, value) => { res.writeHead(code, { "Content-Type": "application/json" }); res.end(JSON.stringify(withDescription(value))); };
         if (!requestIsTrusted(req, origin)) {
             json(403, { error: "Untrusted Host or Origin." });
             return;
         }
-        if (req.method === "GET" && req.url === "/") {
+        const route = routeOf(req.url, secret);
+        if (route === undefined) {
+            json(404, { error: "Not found." });
+            return;
+        }
+        if (req.method === "GET" && route === "") {
+            // A fresh nonce per response, never the CSRF token the script carries.
+            const nonce = randomBytes(16).toString("base64url");
+            res.setHeader("Content-Security-Policy", `default-src 'none'; script-src 'nonce-${nonce}'; style-src 'nonce-${nonce}'; connect-src 'self'; frame-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'`);
             res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-            res.end(renderConnectedPage(csrf));
+            res.end(renderConnectedPage({ csrf, nonce, base }));
             return;
         }
-        if (req.method === "GET" && req.url === "/api/state") {
+        if (req.method === "GET" && route === "api/state") {
             json(200, review.getState());
             return;
         }
-        if (req.method === "GET" && req.url === "/api/analysis") {
+        if (req.method === "GET" && route === "api/analysis") {
             try {
                 json(200, options.analysis === undefined ? NO_ANALYSIS : await options.analysis());
             }
@@ -95,8 +125,8 @@ export async function serveConnected(review = new ConnectedReview(), options = {
             }
             return;
         }
-        if (req.method === "GET" && (req.url ?? "").startsWith("/flow?")) {
-            const query = new URL(req.url ?? "", origin).searchParams;
+        if (req.method === "GET" && route.startsWith("flow?")) {
+            const query = new URL(route, origin).searchParams;
             const snapshotId = query.get("snapshot") ?? "";
             const file = query.get("file") ?? undefined;
             const view = query.get("view") === "business" ? "business" : "flow";
@@ -118,8 +148,8 @@ export async function serveConnected(review = new ConnectedReview(), options = {
             res.end(html);
             return;
         }
-        const routes = ["/api/load", "/api/preview", "/api/submit", "/api/reconcile"];
-        if (req.method !== "POST" || !routes.includes(req.url ?? "")) {
+        const routes = ["api/load", "api/preview", "api/submit", "api/reconcile", "api/viewed"];
+        if (req.method !== "POST" || !routes.includes(route)) {
             json(404, { error: "Not found." });
             return;
         }
@@ -131,16 +161,19 @@ export async function serveConnected(review = new ConnectedReview(), options = {
         try {
             const text = await readBody(req);
             let result;
-            switch (req.url) {
-                case "/api/load":
+            switch (route) {
+                case "api/load":
                     result = await review.load(loadSchema.parse(JSON.parse(text)).url);
                     break;
-                case "/api/preview":
+                case "api/preview":
                     result = await review.preview(reviewSchema.parse(JSON.parse(text)));
                     break;
-                case "/api/submit":
+                case "api/submit":
                     result = await review.submit(reviewSchema.parse(JSON.parse(text)));
                     break;
+                case "api/viewed":
+                    result = await review.setViewed(viewedSchema.parse(JSON.parse(text)));
+                    break;
                 default:
                     emptySchema.parse(JSON.parse(text));
                     result = await review.reconcile();
@@ -158,5 +191,5 @@ export async function serveConnected(review = new ConnectedReview(), options = {
     await new Promise((resolve, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", () => { server.removeListener("error", reject); resolve(); }); });
     const address = z.object({ port: z.number().int().positive() }).parse(server.address());
     origin = `http://127.0.0.1:${address.port}`;
-    return { server, url: origin + "/" };
+    return { server, url: origin + base };
 }

package/dist/review/escape-html.d.ts

@@ -1,2 +1,6 @@
-/** Escape untrusted text for HTML element and attribute contexts. */
+/**
+ * Escape untrusted text for HTML element and attribute contexts. Bidirectional
+ * and other invisible control characters are shown as visible markers, so a page
+ * never lets untrusted text reorder or hide what a reviewer reads.
+ */
 export declare function escapeHtml(text: string): string;

package/dist/review/escape-html.js

@@ -1,6 +1,11 @@
-/** Escape untrusted text for HTML element and attribute contexts. */
+import { visibleControls } from "./hidden-characters.js";
+/**
+ * Escape untrusted text for HTML element and attribute contexts. Bidirectional
+ * and other invisible control characters are shown as visible markers, so a page
+ * never lets untrusted text reorder or hide what a reviewer reads.
+ */
 export function escapeHtml(text) {
-    return text
+    return visibleControls(text)
         .replaceAll("&", "&")
         .replaceAll("<", "&lt;")
         .replaceAll(">", "&gt;")

package/dist/review/explanation.d.ts

@@ -105,6 +105,10 @@ export interface ExplanationCounts {
     readonly steps: number;
     readonly rules: number;
 }
+/**
+ * The id is minted the way the agent is shown it, hidden characters as
+ * ⟦U+XXXX⟧ markers, so the id it sends back names the same function.
+ */
 export declare function functionId(file: string, name: string): string;
 /** The function id a call-flow node's resolved definition has, or undefined when it resolved none. */
 export declare function nodeFunctionId(node: CallFlowNode): string | undefined;

package/dist/review/explanation.js

@@ -14,6 +14,7 @@
  * attributed to the client that wrote it, as its reading.
  */
 import { testLikeFile } from "./file-role.js";
+import { visibleControls } from "./hidden-characters.js";
 /** Most functions one review asks the agent to explain; changed code first. */
 export const MAX_EXPLAINED_FUNCTIONS = 40;
 /** Most processes one explanation draws: the flows a pull request actually touches. */
@@ -39,8 +40,12 @@ function shortName(name) {
     const segments = bare.split(/[.:#]+/).filter((segment) => segment !== "");
     return segments.length === 0 ? bare : segments[segments.length - 1];
 }
+/**
+ * The id is minted the way the agent is shown it, hidden characters as
+ * ⟦U+XXXX⟧ markers, so the id it sends back names the same function.
+ */
 export function functionId(file, name) {
-    return `${file}#${shortName(name)}`;
+    return visibleControls(`${file}#${shortName(name)}`);
 }
 /** The function id a call-flow node's resolved definition has, or undefined when it resolved none. */
 export function nodeFunctionId(node) {

package/dist/review/github.d.ts

@@ -82,12 +82,41 @@ export interface ConnectedReceipt {
  * reconciliation may resolve it.
  */
 export type ConnectedStatus = "empty" | "ready" | "submitting" | "unknown" | "submitted";
+/** GitHub's Viewed mark for one changed file, as the signed-in account has it. */
+export interface ViewedFile {
+    path: string;
+    viewed: boolean;
+}
+/**
+ * The signed-in account's Viewed marks on the loaded pull request, one entry
+ * per changed file. Unavailable when GitHub did not offer them, with a short
+ * fixed reason and never GitHub's own words.
+ */
+export type ViewedState = {
+    available: true;
+    files: ViewedFile[];
+} | {
+    available: false;
+    reason: string;
+};
+/** What the page sends to mark a file Viewed or not Viewed; it owns nothing else about the write. */
+export interface ViewedInput {
+    snapshotId: string;
+    path: string;
+    viewed: boolean;
+}
+export interface ViewedReceipt {
+    path: string;
+    viewed: boolean;
+}
 export interface ConnectedState {
     identity?: ConnectedIdentity;
     snapshot?: ConnectedSnapshot;
     status: ConnectedStatus;
     receipt?: ConnectedReceipt;
     message?: string;
+    /** Present for a reviewable snapshot; a load reads it, a successful mark updates it. */
+    viewed?: ViewedState;
 }
 /** Lowest `gh` release whose `pr view --json` fields and `api --input -` this code needs. */
 export declare const MIN_GH_VERSION = "2.45.0";
@@ -118,6 +147,12 @@ export interface ConnectedReviewDeps {
     runner?: GhRunner;
     timeoutMs?: number;
 }
+/**
+ * No prompt, no pager, no update notice, no usage telemetry (gh reports each
+ * command, its flag names, a device id and which agent runs it to GitHub unless
+ * told not to), and never a host other than github.com.
+ */
+export declare function ghEnvironment(): NodeJS.ProcessEnv;
 /** Runs the real `gh` with an explicit argv (never a shell) and a hard deadline. */
 export declare function ghCliRunner(): GhRunner;
 /** The JSON data model, used to validate each `gh` payload field by field. */
@@ -125,6 +160,14 @@ export type GhJson = string | number | boolean | null | GhJson[] | GhObject;
 export interface GhObject {
     readonly [key: string]: GhJson;
 }
+/**
+ * The only GraphQL documents diffninja sends, fixed text. A file path, a cursor
+ * and the pull request's node id travel as separate `-f` variables and are never
+ * placed in a document.
+ */
+export declare const VIEWED_FILES_QUERY = "query($pullRequestId: ID!, $after: String) { node(id: $pullRequestId) { ... on PullRequest { files(first: 100, after: $after) { nodes { path viewerViewedState } pageInfo { hasNextPage endCursor } } } } }";
+export declare const MARK_VIEWED_MUTATION = "mutation($pullRequestId: ID!, $path: String!) { markFileAsViewed(input: { pullRequestId: $pullRequestId, path: $path }) { clientMutationId } }";
+export declare const UNMARK_VIEWED_MUTATION = "mutation($pullRequestId: ID!, $path: String!) { unmarkFileAsViewed(input: { pullRequestId: $pullRequestId, path: $path }) { clientMutationId } }";
 /**
  * One connected review session. Every method serializes behind the previous
  * one, so an in-flight submission can never be double-fired.
@@ -144,6 +187,7 @@ export declare class ConnectedReview {
     /** Review ids that already existed before this session's write attempt. */
     private preexistingReviewIds;
     private queue;
+    private viewedSync;
     constructor(deps?: ConnectedReviewDeps);
     getState(): ConnectedState;
     /** Canonical patch from the last successfully bound snapshot, for static export. */
@@ -152,6 +196,8 @@ export declare class ConnectedReview {
     preview(input: ReviewInput): Promise<ReviewPayload>;
     submit(input: ReviewInput): Promise<ConnectedState>;
     reconcile(): Promise<ConnectedState>;
+    /** Mark one changed file of the loaded snapshot Viewed, or not, on GitHub. */
+    setViewed(input: ViewedInput): Promise<ViewedReceipt>;
     /** Run `work` after everything already queued; failures never break the chain. */
     private serialize;
     private call;
@@ -181,6 +227,16 @@ export declare class ConnectedReview {
     private runLoad;
     private runPreview;
     private runSubmit;
+    /** One `gh api graphql` run: a fixed document plus its variables, each a separate raw `-f` argument. */
+    private graphql;
+    /** The Viewed marks for the files of a fresh snapshot; a read that fails costs the sync, never the load. */
+    private readViewed;
+    /** Path to viewed, over every page of the pull request's files; VIEWED counts, UNVIEWED and DISMISSED do not. */
+    private readViewedMarks;
+    private runSetViewed;
+    /** A write that may or may not have landed: the marks stay unread until the pull request is loaded again. */
+    private unfinishedMark;
+    private viewedState;
     private postReview;
     /**
      * Resolve an ambiguous write. This never retries and never assumes: it looks