humanish 0.16.0 → 0.17.0

package/README.md

@@ -9,10 +9,13 @@ It creates committed simulation source under `humanish/`, ignored run evidence
 under `.humanish/`, a watchable Observer UI, verification gates, and public-safe
 feedback drafts.
 
-![Humanish Observer synthetic technical sample with four lanes for UI, CLI, TUI, and Codex UI](https://unpkg.com/humanish@0.15.2/docs/assets/humanish-observer-hero.png)
+![Humanish Observer grid of a live four-persona drawDB study: four completed lanes, each showing its final full-desktop screenshot and outcome](https://unpkg.com/humanish@0.16.0/docs/assets/humanish-drawdb-hero.png)
 
-This synthetic technical sample demonstrates the Observer's four-lane layout;
-it is not a completed real-application study.
+A live four-persona study of [drawDB](https://github.com/drawdb-io/drawdb), a
+public open-source database diagram editor, driven against a commit-pinned
+local checkout. Every lane is a real computer-use session on a hosted desktop;
+the captions are each persona's own final report. drawDB is the application
+studied; it is not a Humanish adopter or endorser.
 
 ## Install
 
@@ -112,6 +115,41 @@ The CI-safe equivalent is:
 npx humanish watch --json --no-open
 ```
 
+## Serve the Library
+
+`humanish watch` follows one attached run; `humanish serve` serves the whole
+local run library under `.humanish/runs/` — a library index plus every run's
+Observer page:
+
+```bash
+npx humanish serve
+npx humanish serve --expose --tunnel ngrok --tunnel-domain observer.example.dev
+npx humanish serve --safe --expose --auth none --tunnel ngrok
+```
+
+The first serves the library on loopback only. The second is the phone path:
+it prints a secret capability link once; tapping the link mints a session
+cookie, and every request without a valid session is refused. The third is a
+secretless safe observer: no link required, but only runs whose `humanish
+verify` shareSafety is `share_ready` exist at all — everything else is absent
+and 404s.
+
+In every mode the server binds `127.0.0.1`; exposure only ever happens through
+a tunnel forwarding to the loopback port. The capability link is minted fresh
+per process: Ctrl-C revokes the link and all sessions, and restarting mints a
+new link.
+
+Send the capability link by AirDrop or manual entry rather than a chat app:
+link unfurlers prefetch URLs server-side, and the link is deliberately not
+single-use for exactly that reason — a preview fetch must not burn the link
+before you tap it. On iOS, the first tap can land in an in-app webview whose
+partitioned cookies do not carry over to the real browser; re-tapping the link
+in the real browser mints a fresh session.
+
+Live desktop stream URLs are never served in any mode; remote viewers see
+persisted evidence (screenshots, events, terminal tails) only. See
+[Serve architecture](docs/architecture/serve.md).
+
 ## Commands
 
 | Command | Purpose |
@@ -121,6 +159,7 @@ npx humanish watch --json --no-open
 | `humanish run --dry-run` | Generate a synthetic run bundle without browser, keys, or provider spend. |
 | `humanish run --app-url http://127.0.0.1:<port>` | Capture live desktop/mobile browser evidence against a running local app. |
 | `humanish watch [lab]` | Run sims or a named lab, open Observer, and keep watching. |
+| `humanish serve` | Serve the local run library over loopback; optional capability-link or share-safe exposure. |
 | `humanish lab list` | List committed and ignored lab manifests. |
 | `humanish lab inspect <lab>` | Show the source manifest for a lab without running it. |
 | `humanish lab preflight <lab>` | Check lab routing and optional target reachability before actor/model spend. |
@@ -430,6 +469,7 @@ preserve historical mechanisms and carry explicit amendments near the top.
 - [Ramp for future contributors and agents](docs/ramp/README.md)
 - [Project layout](docs/architecture/project-layout.md)
 - [Observer architecture](docs/architecture/observer.md)
+- [Serve: the run library surface](docs/architecture/serve.md)
 - [Actor contract (first-party registry and extension direction)](docs/architecture/actor-contract.md)
 - [State-driven executor (drive a local app, no E2B/vision)](docs/architecture/state-driven-executor.md)
 - [OSS lab design record (historical; see its current safety amendment)](docs/architecture/oss-lab-poc.md)

package/dist/observer-auth.d.ts

@@ -0,0 +1,21 @@
+export declare const SERVE_COOKIE_NAME = "humanish_serve";
+export interface ServeSessionStore {
+    mint(): {
+        cookieValue: string;
+    };
+    validate(cookieHeader: string | undefined): boolean;
+    revokeAll(): void;
+    sessionCount(): number;
+}
+export declare function mintServeToken(): string;
+export declare function sha256Digest(value: string): Buffer;
+export declare function verifyTokenDigest(candidate: string, digest: Buffer): boolean;
+export declare function createServeSessionStore(options: {
+    ttlMs: number;
+    now?: () => number;
+}): ServeSessionStore;
+export declare function parseCookies(header: string | undefined): Record<string, string>;
+export declare function buildSessionCookie(cookieValue: string, options: {
+    ttlSeconds: number;
+    secure: boolean;
+}): string;

package/dist/observer-auth.js

@@ -0,0 +1,92 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+export const SERVE_COOKIE_NAME = "humanish_serve";
+export function mintServeToken() {
+    return randomBytes(32).toString("base64url");
+}
+export function sha256Digest(value) {
+    return createHash("sha256").update(value, "utf8").digest();
+}
+// Hash-first comparison: both sides become fixed-length digests before
+// timingSafeEqual, so an attacker-controlled candidate can neither throw on
+// length mismatch nor learn the token length.
+export function verifyTokenDigest(candidate, digest) {
+    return timingSafeEqual(sha256Digest(candidate), digest);
+}
+export function createServeSessionStore(options) {
+    const now = options.now ?? (() => Date.now());
+    const sessions = new Map();
+    return {
+        mint() {
+            // Sweep expired records on each mint so the map cannot grow without bound
+            // when many links are tapped: without this, a record is only pruned when
+            // its own cookie is presented again, which an abandoned session never is.
+            const currentTime = now();
+            for (const [digest, record] of sessions) {
+                if (record.expiresAt <= currentTime) {
+                    sessions.delete(digest);
+                }
+            }
+            const cookieValue = randomBytes(32).toString("base64url");
+            sessions.set(sha256Digest(cookieValue).toString("hex"), {
+                expiresAt: currentTime + options.ttlMs,
+                scope: "viewer"
+            });
+            return { cookieValue };
+        },
+        validate(cookieHeader) {
+            const cookieValue = parseCookies(cookieHeader)[SERVE_COOKIE_NAME];
+            if (!cookieValue) {
+                return false;
+            }
+            const record = sessions.get(sha256Digest(cookieValue).toString("hex"));
+            if (!record || record.scope !== "viewer") {
+                return false;
+            }
+            if (record.expiresAt <= now()) {
+                sessions.delete(sha256Digest(cookieValue).toString("hex"));
+                return false;
+            }
+            return true;
+        },
+        revokeAll() {
+            sessions.clear();
+        },
+        sessionCount() {
+            return sessions.size;
+        }
+    };
+}
+export function parseCookies(header) {
+    if (!header) {
+        return {};
+    }
+    const cookies = {};
+    for (const part of header.split(";")) {
+        const separator = part.indexOf("=");
+        if (separator <= 0) {
+            continue;
+        }
+        const name = part.slice(0, separator).trim();
+        const value = part.slice(separator + 1).trim();
+        if (name) {
+            cookies[name] = value;
+        }
+    }
+    return cookies;
+}
+export function buildSessionCookie(cookieValue, options) {
+    const attributes = [
+        `${SERVE_COOKIE_NAME}=${cookieValue}`,
+        "Path=/",
+        "HttpOnly",
+        "SameSite=Lax",
+        `Max-Age=${options.ttlSeconds}`
+    ];
+    if (options.secure) {
+        attributes.push("Secure");
+    }
+    // Deliberately no Domain attribute: a host-only cookie on the public origin
+    // can never leak to sibling subdomains of a shared tunnel domain.
+    return attributes.join("; ");
+}
+//# sourceMappingURL=observer-auth.js.map

package/dist/observer-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-auth.js","sourceRoot":"","sources":["../src/observer-auth.ts"],"names":[],"mappings":"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"}

package/dist/observer-library.d.ts

@@ -0,0 +1,19 @@
+export interface LibraryHistory {
+    latestRunId: string | null;
+    runs: Array<{
+        runId: string;
+        createdAt: string | null;
+        mode: string | null;
+        href: string;
+        status: string;
+        streamCount: number;
+    }>;
+}
+export interface LibraryRenderOptions {
+    mode: "loopback" | "capability-link" | "share-safe-open";
+    safe: boolean;
+    capabilities: {
+        actions: boolean;
+    };
+}
+export declare function renderLibraryHtml(history: LibraryHistory, opts: LibraryRenderOptions): string;

package/dist/observer-library.js

@@ -0,0 +1,189 @@
+const STATUS_TONES = {
+    passed: "#3fb970",
+    running: "#4f8ff7",
+    failed: "#e5534b",
+    blocked: "#d29922",
+    timed_out: "#d29922"
+};
+export function renderLibraryHtml(history, opts) {
+    const emptyState = opts.safe
+        ? "No share_ready runs yet — run `humanish verify` to see why."
+        : "No runs yet — run `humanish watch` to create one.";
+    return `<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
+<title>Humanish Library</title>
+<style>${libraryCss()}</style>
+</head>
+<body>
+<header class="bar">
+  <span class="mark">humanish</span>
+  <span class="title">Run Library</span>
+  <span class="mode">${escapeHtml(modeLabel(opts))}</span>
+</header>
+<main>
+  <p class="note" id="note" hidden></p>
+  <ul class="runs" id="runs"></ul>
+  <p class="empty" id="empty" hidden>${escapeHtml(emptyState)}</p>
+</main>
+<script type="application/json" id="serve-capabilities">${escapeJsonScript(opts.capabilities)}</script>
+<script type="application/json" id="library-data">${escapeJsonScript(history)}</script>
+<script>${libraryClientJs()}</script>
+</body>
+</html>
+`;
+}
+function modeLabel(opts) {
+    const auth = opts.mode === "capability-link" ? "capability link" : opts.mode === "share-safe-open" ? "open" : "loopback";
+    return opts.safe ? `${auth} · share_ready only` : auth;
+}
+function libraryCss() {
+    return `
+:root { color-scheme: dark; }
+* { box-sizing: border-box; margin: 0; }
+body {
+  background: #0c0e12; color: #e6e8ec; min-height: 100vh;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+}
+.bar {
+  display: flex; align-items: baseline; gap: 0.6rem;
+  padding: 1rem 1.1rem; border-bottom: 1px solid #1e222b;
+  position: sticky; top: 0; background: rgba(12,14,18,0.95); backdrop-filter: blur(6px);
+}
+.mark { font-family: ui-monospace, "SF Mono", Menlo, monospace; font-weight: 600; color: #9aa3b2; }
+.title { font-weight: 600; }
+.mode { margin-left: auto; font-size: 0.75rem; color: #9aa3b2; font-family: ui-monospace, "SF Mono", Menlo, monospace; }
+main { padding: 1rem 1.1rem 3rem; max-width: 44rem; margin: 0 auto; }
+.note { font-size: 0.8rem; color: #d29922; padding: 0.5rem 0; }
+.runs { list-style: none; padding: 0; display: grid; gap: 0.6rem; }
+.runs a {
+  display: block; text-decoration: none; color: inherit;
+  border: 1px solid #1e222b; border-radius: 10px; padding: 0.8rem 0.9rem; background: #11141a;
+}
+.runs a:active { background: #171b23; }
+.run-top { display: flex; align-items: center; gap: 0.5rem; }
+.pip { width: 9px; height: 9px; border-radius: 50%; flex: none; }
+.pip.running { animation: pulse 1.6s ease-in-out infinite; }
+@keyframes pulse { 50% { opacity: 0.35; } }
+.run-id {
+  font-family: ui-monospace, "SF Mono", Menlo, monospace; font-size: 0.8rem;
+  overflow-wrap: anywhere;
+}
+.badge {
+  margin-left: auto; flex: none; font-size: 0.65rem; text-transform: uppercase; letter-spacing: 0.06em;
+  border: 1px solid #2c5f8a; color: #7cb8ec; border-radius: 999px; padding: 0.1rem 0.5rem;
+}
+.badge.latest { border-color: #3fb970; color: #7ee2a8; }
+.run-meta { margin-top: 0.35rem; font-size: 0.75rem; color: #9aa3b2; }
+.empty { color: #9aa3b2; font-size: 0.85rem; padding: 2rem 0; text-align: center; }
+`;
+}
+function libraryClientJs() {
+    const tones = JSON.stringify(STATUS_TONES);
+    return `
+(function () {
+  var TONES = ${tones};
+  var POLL_MS = 15000;
+  var stopped = false;
+
+  function render(history) {
+    var list = document.getElementById("runs");
+    var empty = document.getElementById("empty");
+    list.textContent = "";
+    var runs = history.runs || [];
+    empty.hidden = runs.length !== 0;
+    for (var i = 0; i < runs.length; i += 1) {
+      var run = runs[i];
+      var item = document.createElement("li");
+      var link = document.createElement("a");
+      link.href = run.href;
+      var top = document.createElement("div");
+      top.className = "run-top";
+      var pip = document.createElement("span");
+      pip.className = run.status === "running" ? "pip running" : "pip";
+      pip.style.background = TONES[run.status] || "#57606f";
+      var id = document.createElement("span");
+      id.className = "run-id";
+      id.textContent = run.runId;
+      top.appendChild(pip);
+      top.appendChild(id);
+      if (run.runId === history.latestRunId) {
+        var latest = document.createElement("span");
+        latest.className = "badge latest";
+        latest.textContent = "latest";
+        top.appendChild(latest);
+      } else if (run.status === "running") {
+        var live = document.createElement("span");
+        live.className = "badge";
+        live.textContent = "live";
+        top.appendChild(live);
+      }
+      var meta = document.createElement("div");
+      meta.className = "run-meta";
+      meta.textContent = [run.mode || "unknown", run.streamCount + " lanes", run.createdAt || ""].filter(Boolean).join(" \\u00b7 ");
+      link.appendChild(top);
+      link.appendChild(meta);
+      item.appendChild(link);
+      list.appendChild(item);
+    }
+  }
+
+  function note(text) {
+    var element = document.getElementById("note");
+    element.hidden = !text;
+    element.textContent = text || "";
+  }
+
+  function poll() {
+    if (stopped) return;
+    fetch("/_humanish/history.json", { cache: "no-store" }).then(function (response) {
+      if (response.status === 401) {
+        stopped = true;
+        note("session expired \\u2014 tap your capability link again");
+        return null;
+      }
+      return response.json();
+    }).then(function (history) {
+      if (history) {
+        note("");
+        render(history);
+      }
+    }).catch(function () {
+      note("connection lost \\u2014 retrying");
+    }).then(function () {
+      if (!stopped) setTimeout(poll, POLL_MS);
+    });
+  }
+
+  render(JSON.parse(document.getElementById("library-data").textContent));
+  setTimeout(poll, POLL_MS);
+})();
+`;
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case "\"":
+                return "&quot;";
+            default:
+                return "&#39;";
+        }
+    });
+}
+function escapeJsonScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}
+//# sourceMappingURL=observer-library.js.map

package/dist/observer-library.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-library.js","sourceRoot":"","sources":["../src/observer-library.ts"],"names":[],"mappings":"AAkBA,MAAM,YAAY,GAA2B;IAC3C,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,SAAS;IAClB,MAAM,EAAE,SAAS;IACjB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,SAAS;CACrB,CAAC;AAEF,MAAM,UAAU,iBAAiB,CAAC,OAAuB,EAAE,IAA0B;IACnF,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI;QAC1B,CAAC,CAAC,6DAA6D;QAC/D,CAAC,CAAC,mDAAmD,CAAC;IAExD,OAAO;;;;;;SAMA,UAAU,EAAE;;;;;;uBAME,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;;;;;uCAKX,UAAU,CAAC,UAAU,CAAC;;0DAEH,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC;oDACzC,gBAAgB,CAAC,OAAO,CAAC;UACnE,eAAe,EAAE;;;CAG1B,CAAC;AACF,CAAC;AAED,SAAS,SAAS,CAAC,IAA0B;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,iBAAiB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC;IACzH,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC;AACzD,CAAC;AAED,SAAS,UAAU;IACjB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsCR,CAAC;AACF,CAAC;AAED,SAAS,eAAe;IACtB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAC3C,OAAO;;gBAEO,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4EpB,CAAC;AACF,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE;QACxC,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,GAAG;gBACN,OAAO,OAAO,CAAC;YACjB,KAAK,GAAG;gBACN,OAAO,MAAM,CAAC;YAChB,KAAK,GAAG;gBACN,OAAO,MAAM,CAAC;YAChB,KAAK,IAAI;gBACP,OAAO,QAAQ,CAAC;YAClB;gBACE,OAAO,OAAO,CAAC;QACnB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;SACzB,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC;SACxB,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC;SACxB,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC;SACxB,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC;SAC7B,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;AACnC,CAAC"}

package/dist/observer-serve.d.ts

@@ -0,0 +1,111 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { PinnedDirectory } from "./observer.js";
+import type { ServeSessionStore } from "./observer-auth.js";
+import type { LibraryHistory } from "./observer-library.js";
+import { verifyRun } from "./run.js";
+export declare const SERVE_SCHEMA = "humanish.serve-result.v1";
+export type ServeMode = "loopback" | "capability-link" | "share-safe-open";
+export type ServeErrorCode = "HUMANISH_INVALID_PORT" | "HUMANISH_SERVE_INVALID_TTL" | "HUMANISH_SERVE_OPTION_CONFLICT" | "HUMANISH_SERVE_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN" | "HUMANISH_SERVE_OPEN_REQUIRES_SAFE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED" | "HUMANISH_RUN_NOT_FOUND" | "HUMANISH_SERVE_RUN_NOT_SHAREABLE";
+export interface ServeResult {
+    schema: typeof SERVE_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    mode: ServeMode;
+    safe: boolean;
+    host: "127.0.0.1";
+    port?: number;
+    url?: string;
+    capabilityUrl?: string;
+    publicUrl?: string;
+    publicCapabilityUrl?: string;
+    tunnel?: {
+        provider: "ngrok";
+        url: string;
+    };
+    ttlMinutes?: number;
+    runsListed: number;
+    shareReadyCount?: number;
+    entryRunId?: string;
+    opened?: boolean;
+    openCommand?: string;
+    warnings: string[];
+    error?: {
+        code: ServeErrorCode;
+        message: string;
+    };
+}
+export interface ServeControlPlane {
+    startRun?(request: {
+        labId: string;
+        dryRun: boolean;
+    }): Promise<{
+        accepted: boolean;
+        runId?: string;
+    }>;
+}
+export interface ShareSafetyAdmission {
+    admit(runId: string): Promise<boolean>;
+}
+export declare function createShareSafetyAdmission(cwd: string, options?: {
+    verifyImpl?: typeof verifyRun;
+    ttlMs?: number;
+    now?: () => number;
+}): ShareSafetyAdmission;
+export declare function buildServeSecurityHeaders(): Record<string, string>;
+export declare function hostAllowed(hostHeader: string | undefined, allowlist: ReadonlySet<string>): boolean;
+export declare function parsePublicOrigin(value: string): {
+    origin: string;
+    host: string;
+    scheme: "http" | "https";
+} | null;
+export interface ServeAuthContext {
+    tokenDigest: Buffer;
+    sessions: ServeSessionStore;
+    ttlSeconds: number;
+    publicScheme?: "http" | "https";
+}
+export interface ServeRequestHandlerOptions {
+    proofRoot: PinnedDirectory;
+    safe: boolean;
+    admit: (runId: string) => Promise<boolean>;
+    auth?: ServeAuthContext | null;
+    hostAllowlist: ReadonlySet<string>;
+    entryRunId?: string;
+    renderLibrary: (history: LibraryHistory) => string;
+    controlPlane?: ServeControlPlane;
+}
+export declare function createServeRequestHandler(options: ServeRequestHandlerOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+export interface ServeLibraryOptions {
+    port: number;
+    safe: boolean;
+    expose: boolean;
+    authMode: "link" | "none";
+    ttlMinutes: number;
+    publicOrigin?: string;
+    entryRunId?: string;
+    controlPlane?: ServeControlPlane;
+    verifyImpl?: typeof verifyRun;
+    now?: () => number;
+}
+export interface ServeLibraryServer {
+    url: string;
+    port: number;
+    mode: ServeMode;
+    capabilityToken?: string;
+    runsListed: number;
+    shareReadyCount?: number;
+    entryRunId?: string;
+    addPublicOrigin(origin: string): void;
+    close(): Promise<void>;
+}
+export type ServeLibraryStart = {
+    ok: true;
+    server: ServeLibraryServer;
+} | {
+    ok: false;
+    error: {
+        code: ServeErrorCode;
+        message: string;
+    };
+};
+export declare function serveObserverLibrary(cwdInput: string, options: ServeLibraryOptions): Promise<ServeLibraryStart>;