mrplex 0.0.1

package/dist/shell/proxy-policy.js

@@ -0,0 +1,120 @@
+/**
+ * Route-aware REST policy classification for proxy mode — auth-shell plan §1
+ * "Serve mode: fronting proxy", WS4.
+ *
+ * The fronting proxy is mrplex-aware (not a generic reverse proxy): it parses
+ * the known REST routes to decide what an entitlement must permit. Crucially,
+ * on the REST surface the URL path is *authoritative* for writes — a
+ * `PUT /repos/notes/docs/drafts/x.md` names its target path directly, and a
+ * MOVE carries source (URL) + destination (`Destination` header). So the proxy
+ * can replay the guard's §8.2 rules (both-endpoints on move, sigil paths
+ * skipped, write ≠ read) WITHOUT a kernel handle — unlike the opaque MCP tool
+ * args, which is why MCP writes stay in embedded mode.
+ *
+ * This module is pure request classification — no I/O, no forwarding — so it is
+ * unit-testable and the proxy transport composes it.
+ */
+/**
+ * Classify a REST request into its policy requirement. `pathname` is the raw
+ * URL path (no query); `destination` is the `Destination` header value, needed
+ * for MOVE both-endpoints. Percent-encoded segments are decoded per-segment.
+ */
+export function classifyRestRequest(method, pathname, destination) {
+    const segments = splitPath(pathname);
+    const m = method.toUpperCase();
+    // Root liveness ping, /query.
+    if (segments.length === 0)
+        return { kind: "read" };
+    if (segments[0] === "query")
+        return { kind: "read" };
+    if (segments[0] !== "repos")
+        return { kind: "unknown" };
+    // /repos  (GET list, POST create)
+    if (segments.length === 1) {
+        if (m === "GET")
+            return { kind: "read" };
+        if (m === "POST")
+            return { kind: "destructive" }; // repos.create
+        return { kind: "unknown" };
+    }
+    const repo = segments[1];
+    // /repos/{repo}  (GET, MOVE rename, DELETE)
+    if (segments.length === 2) {
+        if (m === "GET")
+            return { kind: "read" };
+        if (m === "MOVE" || m === "DELETE")
+            return { kind: "destructive" }; // rename / delete
+        return { kind: "unknown" };
+    }
+    // /repos/{repo}/config  (PUT → set_path_config). There is no REST route for
+    // set_link_config — it's only reachable via the MCP repos_set_link_config
+    // tool, and the proxy refuses /mcp entirely, so no branch for it here.
+    if (segments.length === 3 && segments[2] === "config") {
+        if (m === "PUT")
+            return { kind: "destructive" };
+        return { kind: "unknown" };
+    }
+    // /repos/{repo}/versions | history | diff  — all reads
+    if (segments.length >= 3 && ["versions", "history", "diff"].includes(segments[2])) {
+        return { kind: "read" };
+    }
+    // /repos/{repo}/docs/{...path}
+    if (segments.length >= 4 && segments[2] === "docs") {
+        const path = segments.slice(3).join("/");
+        if (m === "GET")
+            return { kind: "read" };
+        if (m === "PUT")
+            return { kind: "write", repo, paths: [path] }; // create or update
+        if (m === "DELETE")
+            return { kind: "write", repo, paths: [path] };
+        if (m === "MOVE") {
+            // Both endpoints: source (URL path) + destination. A cross-repo or
+            // malformed destination is caught downstream by the engine; for policy
+            // we require write on both the source and whatever dest we can parse.
+            const destPath = parseDocDestinationPath(destination, repo);
+            const paths = destPath === null ? [path] : [path, destPath];
+            return { kind: "write", repo, paths };
+        }
+        return { kind: "unknown" };
+    }
+    return { kind: "unknown" };
+}
+function splitPath(pathname) {
+    const raw = pathname.replace(/^\//, "").replace(/\/$/, "");
+    if (raw === "")
+        return [];
+    return raw.split("/").map((s) => {
+        try {
+            return decodeURIComponent(s);
+        }
+        catch {
+            return s;
+        }
+    });
+}
+/**
+ * Extract the destination document path from a `Destination` header of the form
+ * `/repos/{repo}/docs/{...path}` (mirrors the REST surface's own parser). Returns
+ * null when absent/unparseable; the engine remains the authority on validity.
+ */
+function parseDocDestinationPath(headerValue, repo) {
+    if (headerValue === undefined)
+        return null;
+    let pathname;
+    try {
+        pathname = new URL(headerValue, "http://x").pathname;
+    }
+    catch {
+        // Not an absolute URL — treat as a bare path.
+        pathname = headerValue;
+    }
+    const decoded = splitPath(pathname);
+    if (decoded.length < 4)
+        return null;
+    if (decoded[0] !== "repos" || decoded[2] !== "docs")
+        return null;
+    if (decoded[1] !== repo)
+        return null; // cross-repo move — engine rejects; policy ignores dest
+    return decoded.slice(3).join("/");
+}
+//# sourceMappingURL=proxy-policy.js.map

package/dist/shell/proxy-policy.js.map

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

package/dist/shell/proxy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Fronting proxy — auth-shell plan §1 "Serve mode: fronting proxy", WS4.
+ *
+ * For deployments where the engine must run separately (polyglot/containerized
+ * topologies), `mrplex proxy --policy <file> --upstream <unix|url>` sits in
+ * front of a raw engine bound to a unix socket or loopback. Per request it:
+ *   1. authenticates the caller (bearer API key, like the HTTP front),
+ *   2. classifies the REST route and enforces write/destructive policy against
+ *      the entitlement — route-aware, because the URL path is authoritative for
+ *      writes (see proxy-policy.ts),
+ *   3. STRIPS any inbound `X-Mrplex-*` headers (mandatory — the engine trusts
+ *      them unconditionally, so a client must never set its own identity),
+ *   4. INJECTS the entitlement's `X-Mrplex-Author` + `X-Mrplex-Scope`,
+ *   5. forwards to the upstream and streams the response back.
+ *
+ * Embedded serve is preferred (no second process, no header-trust surface);
+ * this exists for topologies that need engine/shell separation. MCP-over-proxy
+ * is read-only here: MCP tool args are opaque to path-level policy (docs_put
+ * carries a version id, not a source path), so writes over `/mcp` are refused
+ * with a pointer to embedded mode. REST writes are fully policed.
+ */
+import { type Server } from "node:http";
+import type { AuditSink } from "./guard.js";
+export type ProxyConfig = {
+    policyPath: string;
+    /** `unix:/path/to.sock` or `http://127.0.0.1:PORT` — the raw engine upstream. */
+    upstream: string;
+    host?: string;
+    port?: number;
+    /**
+     * Audit-sink factory. When set, every authenticated request appends a record
+     * (principal, op derived from method+route, repo/path, outcome). Proxy mode
+     * bypasses the guard, so this is the accountability trail the guard would
+     * otherwise provide (auth-shell plan decision 8).
+     */
+    auditSinkFor?: (principal: string) => AuditSink;
+    log?: (msg: string) => void;
+};
+export type ProxyHandle = {
+    server: Server;
+    port: number;
+    host: string;
+    baseUrl: string;
+    reloadPolicy: () => void;
+    close: () => Promise<void>;
+};
+export declare function startProxyServer(config: ProxyConfig): Promise<ProxyHandle>;

package/dist/shell/proxy.js

@@ -0,0 +1,253 @@
+/**
+ * Fronting proxy — auth-shell plan §1 "Serve mode: fronting proxy", WS4.
+ *
+ * For deployments where the engine must run separately (polyglot/containerized
+ * topologies), `mrplex proxy --policy <file> --upstream <unix|url>` sits in
+ * front of a raw engine bound to a unix socket or loopback. Per request it:
+ *   1. authenticates the caller (bearer API key, like the HTTP front),
+ *   2. classifies the REST route and enforces write/destructive policy against
+ *      the entitlement — route-aware, because the URL path is authoritative for
+ *      writes (see proxy-policy.ts),
+ *   3. STRIPS any inbound `X-Mrplex-*` headers (mandatory — the engine trusts
+ *      them unconditionally, so a client must never set its own identity),
+ *   4. INJECTS the entitlement's `X-Mrplex-Author` + `X-Mrplex-Scope`,
+ *   5. forwards to the upstream and streams the response back.
+ *
+ * Embedded serve is preferred (no second process, no header-trust surface);
+ * this exists for topologies that need engine/shell separation. MCP-over-proxy
+ * is read-only here: MCP tool args are opaque to path-level policy (docs_put
+ * carries a version id, not a source path), so writes over `/mcp` are refused
+ * with a pointer to embedded mode. REST writes are fully policed.
+ */
+import { createServer, request, } from "node:http";
+import { claimsGrantRead, normalizeClaims } from "../kernel/auth/scope.js";
+import { bearerToken, principalForKey } from "./keys.js";
+import { compile, loadPolicyFile } from "./policy.js";
+import { classifyRestRequest } from "./proxy-policy.js";
+/**
+ * Request-body cap, mirroring the REST surface's `MAX_BODY_BYTES` (8 MB). The
+ * proxy is the enforcement point: it fronts an engine on a unix socket/loopback
+ * that can't be independently rate-limited, so a hostile client streaming
+ * unbounded bytes must be cut off here.
+ */
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+function parseUpstream(spec) {
+    if (spec.startsWith("unix:")) {
+        return { kind: "unix", socketPath: spec.slice("unix:".length) };
+    }
+    const url = new URL(spec);
+    if (url.protocol !== "http:") {
+        throw new Error(`proxy upstream must be unix:<path> or http://<loopback> — got ${spec}`);
+    }
+    return { kind: "tcp", host: url.hostname, port: Number(url.port || 80) };
+}
+/** All inbound X-Mrplex-* headers are stripped before forwarding. */
+function stripMrplexHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        if (v === undefined)
+            continue;
+        if (k.toLowerCase().startsWith("x-mrplex-"))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
+export async function startProxyServer(config) {
+    let policy = loadPolicyFile(config.policyPath);
+    const upstream = parseUpstream(config.upstream);
+    const log = config.log ?? ((m) => process.stderr.write(`${m}\n`));
+    let entitlementCache = new Map();
+    function entitlementFor(principalId) {
+        const cached = entitlementCache.get(principalId);
+        if (cached)
+            return cached;
+        const e = compile(policy, principalId);
+        entitlementCache.set(principalId, e);
+        return e;
+    }
+    function authenticate(req) {
+        const key = bearerToken(firstHeader(req.headers.authorization));
+        if (key === null)
+            return null;
+        const principalId = principalForKey(policy, key);
+        if (principalId === null)
+            return null;
+        return { principalId, entitlement: entitlementFor(principalId) };
+    }
+    const auditSinkFor = config.auditSinkFor;
+    const server = createServer((req, res) => {
+        void handle(req, res).catch((err) => writeError(res, 500, "internal_error", String(err)));
+    });
+    async function handle(req, res) {
+        const auth = authenticate(req);
+        if (auth === null) {
+            return writeError(res, 401, "unauthorized", "missing or invalid credential");
+        }
+        const { principalId, entitlement } = auth;
+        const audit = auditSinkFor?.(principalId);
+        const method = req.method ?? "GET";
+        const url = req.url ?? "/";
+        const pathname = new URL(url, "http://x").pathname;
+        // MCP-over-proxy is read-only (tool args are opaque to path policy). We
+        // can't tell a read tool from a write tool without parsing the JSON-RPC
+        // body, so /mcp is refused entirely in proxy mode — embedded serve is the
+        // supported path for authenticated MCP.
+        if (pathname === "/mcp" || pathname.startsWith("/mcp?") || pathname.startsWith("/mcp/")) {
+            audit?.({ op: "mcp", outcome: "forbidden" });
+            return writeError(res, 403, "forbidden", "MCP over the fronting proxy is not supported; use `mrplex serve --policy` (embedded) for authenticated MCP");
+        }
+        // Enforce REST route policy before forwarding.
+        const requirement = classifyRestRequest(method, pathname, firstHeader(req.headers.destination));
+        const op = opName(method, requirement);
+        const meta = auditMeta(requirement);
+        const denial = policyDenial(requirement, entitlement);
+        if (denial !== null) {
+            audit?.({ op, ...meta, outcome: "forbidden" });
+            return writeError(res, denial.status, denial.code, denial.reason);
+        }
+        // Strip inbound identity headers, inject the entitlement's. The engine
+        // trusts these unconditionally, which is exactly why the client's own
+        // X-Mrplex-* were stripped above.
+        const headers = stripMrplexHeaders(req.headers);
+        headers["x-mrplex-author"] = entitlement.author;
+        headers["x-mrplex-scope"] = JSON.stringify(entitlement.read);
+        forward(req, res, headers, (status) => {
+            // The shell allowed the call; the engine's status becomes the outcome's
+            // error tag when it's a 4xx/5xx (mirrors the guard's "ok, engine error").
+            audit?.({
+                op,
+                ...meta,
+                outcome: "ok",
+                ...(status >= 400 ? { error: `http_${status}` } : {}),
+            });
+        });
+    }
+    function forward(req, res, headers, onResponse) {
+        const common = { method: req.method, path: req.url, headers };
+        const upstreamReq = upstream.kind === "unix"
+            ? request({ socketPath: upstream.socketPath, ...common }, (upRes) => {
+                onResponse(upRes.statusCode ?? 502);
+                pipeResponse(upRes, res);
+            })
+            : request({ host: upstream.host, port: upstream.port, ...common }, (upRes) => {
+                onResponse(upRes.statusCode ?? 502);
+                pipeResponse(upRes, res);
+            });
+        upstreamReq.on("error", (err) => writeError(res, 502, "bad_gateway", err.message));
+        // Cap the streamed body — the proxy is the enforcement point in front of an
+        // otherwise-unprotected engine. Past the limit, destroy both ends and 413.
+        let total = 0;
+        req.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > MAX_BODY_BYTES) {
+                req.destroy();
+                upstreamReq.destroy();
+                writeError(res, 413, "payload_too_large", `body exceeded ${MAX_BODY_BYTES} bytes`);
+            }
+        });
+        req.pipe(upstreamReq);
+    }
+    const host = config.host ?? "127.0.0.1";
+    const port = config.port ?? 8321;
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, host, () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const boundPort = server.address().port;
+    const baseUrl = `http://${host.includes(":") ? `[${host}]` : host}:${boundPort}`;
+    log(`mrplex: proxy (authenticated) on ${baseUrl}`);
+    log(`mrplex:   policy   ${config.policyPath}`);
+    log(`mrplex:   upstream ${config.upstream}`);
+    function reloadPolicy() {
+        try {
+            policy = loadPolicyFile(config.policyPath);
+            entitlementCache = new Map();
+            log(`mrplex: policy reloaded from ${config.policyPath}`);
+        }
+        catch (err) {
+            log(`mrplex: policy reload FAILED, keeping previous: ${err.message}`);
+        }
+    }
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        await new Promise((resolve) => server.close(() => resolve()));
+    };
+    return { server, port: boundPort, host, baseUrl, reloadPolicy, close };
+}
+/**
+ * A coarse op label for the audit log, derived from method + route class. The
+ * proxy doesn't parse bodies, so this is method-and-route granularity (e.g.
+ * `write`, `destructive`, `read`) rather than the exact kernel op name the
+ * embedded guard records — enough to answer "who did what where".
+ */
+function opName(method, requirement) {
+    return `${method.toUpperCase()} ${requirement.kind}`;
+}
+/** repo/path fields for the audit record, when the route carries them. */
+function auditMeta(requirement) {
+    if (requirement.kind === "write") {
+        return { repo: requirement.repo, path: requirement.paths.join(" -> ") };
+    }
+    return {};
+}
+/** Null = allowed. Otherwise the HTTP denial to write. */
+function policyDenial(requirement, entitlement) {
+    switch (requirement.kind) {
+        case "read":
+            return null; // read scope is enforced downstream via injected X-Mrplex-Scope
+        case "destructive":
+            return entitlement.destructive
+                ? null
+                : { status: 403, code: "forbidden", reason: "destructive op not permitted" };
+        case "write":
+            return writeAllowed(entitlement, requirement.repo, requirement.paths)
+                ? null
+                : { status: 403, code: "forbidden", reason: "write outside permitted scope" };
+        case "unknown":
+            // A route we don't model must not be forwarded blind — it could be an
+            // unpoliced write. Refuse; add the route to the classifier if it's real.
+            return { status: 403, code: "forbidden", reason: "route not recognized by the proxy" };
+    }
+}
+/**
+ * True iff the entitlement's write scope covers EVERY path (both-endpoints on a
+ * move). Reuses the guard's exact matcher semantics. Sigil paths are the
+ * engine's to police (validatePath), so they pass at the policy layer.
+ */
+function writeAllowed(entitlement, repo, paths) {
+    const matchers = normalizeClaims(entitlement.write);
+    return paths.every((p) => isSystemPath(p) || claimsGrantRead(matchers, repo, p));
+}
+function isSystemPath(path) {
+    return path.split("/").some((seg) => seg.startsWith(":"));
+}
+function firstHeader(v) {
+    if (v === undefined)
+        return undefined;
+    return Array.isArray(v) ? v[0] : v;
+}
+function pipeResponse(upRes, res) {
+    res.statusCode = upRes.statusCode ?? 502;
+    for (const [k, v] of Object.entries(upRes.headers)) {
+        if (v !== undefined)
+            res.setHeader(k, v);
+    }
+    upRes.pipe(res);
+}
+function writeError(res, status, code, reason) {
+    if (res.headersSent) {
+        res.end();
+        return;
+    }
+    res.statusCode = status;
+    res.setHeader("Content-Type", "application/json");
+    res.end(JSON.stringify({ code, data: { reason } }));
+}
+//# sourceMappingURL=proxy.js.map

package/dist/shell/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../src/shell/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAIL,YAAY,EACZ,OAAO,GACR,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE3E,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACzD,OAAO,EAAiC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrF,OAAO,EAAyB,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AA6BvC,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;IAClE,CAAC;IACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAC1B,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,iEAAiE,IAAI,EAAE,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;AAC3E,CAAC;AAED,qEAAqE;AACrE,SAAS,kBAAkB,CACzB,OAAuC;IAEvC,MAAM,GAAG,GAAsC,EAAE,CAAC;IAClD,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7C,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,WAAW,CAAC;YAAE,SAAS;QACtD,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,MAAmB;IACxD,IAAI,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAE1E,IAAI,gBAAgB,GAAG,IAAI,GAAG,EAAuB,CAAC;IACtD,SAAS,cAAc,CAAC,WAAmB;QACzC,MAAM,MAAM,GAAG,gBAAgB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QACjD,IAAI,MAAM;YAAE,OAAO,MAAM,CAAC;QAC1B,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACvC,gBAAgB,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QACrC,OAAO,CAAC,CAAC;IACX,CAAC;IAED,SAAS,YAAY,CACnB,GAAoB;QAEpB,MAAM,GAAG,GAAG,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;QAChE,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QAC9B,MAAM,WAAW,GAAG,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;QACjD,IAAI,WAAW,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACtC,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,cAAc,CAAC,WAAW,CAAC,EAAE,CAAC;IACnE,CAAC;IAED,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAEzC,MAAM,MAAM,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;QACvC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAC3C,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CACpD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,KAAK,UAAU,MAAM,CAAC,GAAoB,EAAE,GAAmB;QAC7D,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,cAAc,EAAE,+BAA+B,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;QAC1C,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC,WAAW,CAAC,CAAC;QAE1C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,KAAK,CAAC;QACnC,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,QAAQ,CAAC;QAEnD,wEAAwE;QACxE,wEAAwE;QACxE,0EAA0E;QAC1E,wCAAwC;QACxC,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACxF,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;YAC7C,OAAO,UAAU,CACf,GAAG,EACH,GAAG,EACH,WAAW,EACX,4GAA4G,CAC7G,CAAC;QACJ,CAAC;QAED,+CAA+C;QAC/C,MAAM,WAAW,GAAG,mBAAmB,CAAC,MAAM,EAAE,QAAQ,EAAE,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC;QAChG,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;QACvC,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,YAAY,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;QACtD,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC;YAC/C,OAAO,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACpE,CAAC;QAED,uEAAuE;QACvE,sEAAsE;QACtE,kCAAkC;QAClC,MAAM,OAAO,GAAG,kBAAkB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAChD,OAAO,CAAC,iBAAiB,CAAC,GAAG,WAAW,CAAC,MAAM,CAAC;QAChD,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAE7D,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE;YACpC,wEAAwE;YACxE,0EAA0E;YAC1E,KAAK,EAAE,CAAC;gBACN,EAAE;gBACF,GAAG,IAAI;gBACP,OAAO,EAAE,IAAI;gBACb,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtD,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,SAAS,OAAO,CACd,GAAoB,EACpB,GAAmB,EACnB,OAA0C,EAC1C,UAAoC;QAEpC,MAAM,MAAM,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,CAAC;QAC9D,MAAM,WAAW,GACf,QAAQ,CAAC,IAAI,KAAK,MAAM;YACtB,CAAC,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,UAAU,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE;gBAChE,UAAU,CAAC,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;gBACpC,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC3B,CAAC,CAAC;YACJ,CAAC,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,GAAG,MAAM,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE;gBACzE,UAAU,CAAC,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC,CAAC;gBACpC,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;QACT,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC;QAEnF,4EAA4E;QAC5E,2EAA2E;QAC3E,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAC/B,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;YACtB,IAAI,KAAK,GAAG,cAAc,EAAE,CAAC;gBAC3B,GAAG,CAAC,OAAO,EAAE,CAAC;gBACd,WAAW,CAAC,OAAO,EAAE,CAAC;gBACtB,UAAU,CAAC,GAAG,EAAE,GAAG,EAAE,mBAAmB,EAAE,iBAAiB,cAAc,QAAQ,CAAC,CAAC;YACrF,CAAC;QACH,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACxB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,WAAW,CAAC;IACxC,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC;IACjC,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE;YAC7B,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,MAAM,SAAS,GAAI,MAAM,CAAC,OAAO,EAAkB,CAAC,IAAI,CAAC;IACzD,MAAM,OAAO,GAAG,UAAU,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,SAAS,EAAE,CAAC;IAEjF,GAAG,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;IACnD,GAAG,CAAC,sBAAsB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IAC/C,GAAG,CAAC,sBAAsB,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE7C,SAAS,YAAY;QACnB,IAAI,CAAC;YACH,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAC3C,gBAAgB,GAAG,IAAI,GAAG,EAAE,CAAC;YAC7B,GAAG,CAAC,gCAAgC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,mDAAoD,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IAED,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,KAAK,GAAG,KAAK,IAAI,EAAE;QACvB,IAAI,MAAM;YAAE,OAAO;QACnB,MAAM,GAAG,IAAI,CAAC;QACd,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IACtE,CAAC,CAAC;IAEF,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;AACzE,CAAC;AAED;;;;;GAKG;AACH,SAAS,MAAM,CAAC,MAAc,EAAE,WAA6B;IAC3D,OAAO,GAAG,MAAM,CAAC,WAAW,EAAE,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC;AACvD,CAAC;AAED,0EAA0E;AAC1E,SAAS,SAAS,CAAC,WAA6B;IAC9C,IAAI,WAAW,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QACjC,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,0DAA0D;AAC1D,SAAS,YAAY,CACnB,WAAmD,EACnD,WAAwB;IAExB,QAAQ,WAAW,CAAC,IAAI,EAAE,CAAC;QACzB,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,CAAC,gEAAgE;QAC/E,KAAK,aAAa;YAChB,OAAO,WAAW,CAAC,WAAW;gBAC5B,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,8BAA8B,EAAE,CAAC;QACjF,KAAK,OAAO;YACV,OAAO,YAAY,CAAC,WAAW,EAAE,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC,KAAK,CAAC;gBACnE,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC;QAClF,KAAK,SAAS;YACZ,sEAAsE;YACtE,yEAAyE;YACzE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,mCAAmC,EAAE,CAAC;IAC3F,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CAAC,WAAwB,EAAE,IAAY,EAAE,KAAe;IAC3E,MAAM,QAAQ,GAAG,eAAe,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACnF,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AAC5D,CAAC;AAED,SAAS,WAAW,CAAC,CAAgC;IACnD,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACtC,OAAO,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACrC,CAAC;AAED,SAAS,YAAY,CAAC,KAAsB,EAAE,GAAmB;IAC/D,GAAG,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,GAAG,CAAC;IACzC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClB,CAAC;AAED,SAAS,UAAU,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAY,EAAE,MAAc;IACnF,IAAI,GAAG,CAAC,WAAW,EAAE,CAAC;QACpB,GAAG,CAAC,GAAG,EAAE,CAAC;QACV,OAAO;IACT,CAAC;IACD,GAAG,CAAC,UAAU,GAAG,MAAM,CAAC;IACxB,GAAG,CAAC,SAAS,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;AACtD,CAAC"}

package/dist/shell/serve.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Embedded serve — the shell's primary mode (auth-shell plan §1 "Serve mode:
+ * embedded", WS3).
+ *
+ * One process: open the database, `createKernel`, and mount mrplex's own REST +
+ * MCP surfaces on top of PER-REQUEST guarded kernels. There is no engine
+ * listener at all — so there is no trusted-header problem and no second
+ * process. Each request:
+ *   1. carries a credential (today: an API key as `Authorization: Bearer`);
+ *   2. the shell resolves it to a principal, `compile()`s the entitlement
+ *      (cached per principal, invalidated on policy reload),
+ *   3. `guardKernel()`s the shared kernel with that entitlement + an audit sink,
+ *   4. and the surface dispatches against the guarded kernel.
+ *
+ * The surfaces accept a `kernelForRequest` factory (WS0's generalization), so
+ * this file is pure composition: no surface code is forked, and all write /
+ * destructive / author policy lives in the guard.
+ *
+ * Policy is reloadable on SIGHUP: the loader swaps the in-memory policy and
+ * clears the entitlement cache, so a running server picks up a key revocation
+ * or grant change without a restart. The credential→principal→entitlement
+ * pipeline is otherwise identical to the stdio and (future) proxy fronts —
+ * they differ only in how the credential arrives.
+ */
+import { type Server } from "node:http";
+import { type EmbedConfig } from "../embed/config.js";
+import type { EmbedHook } from "../embed/hook.js";
+import { type Worker } from "../embed/worker.js";
+import { type Kernel } from "../kernel/kernel.js";
+import { type PathConfig } from "../kernel/path-config.js";
+import type { Storage } from "../storage/types.js";
+import { type AuditSink } from "./guard.js";
+import { type OidcVerifier } from "./oidc.js";
+export type ShellServeConfig = {
+    database: string;
+    /** Path to the YAML policy file. Loaded at startup, reloaded on SIGHUP. */
+    policyPath: string;
+    host?: string;
+    port?: number;
+    serverPathConfig?: PathConfig;
+    embed?: EmbedConfig;
+    /** Audit-log path. When set, every authenticated call appends a JSONL line. */
+    auditPath?: string;
+    /** Factory for the audit sink — injectable for tests; defaults to file JSONL. */
+    auditSinkFor?: (principal: string) => AuditSink;
+    /**
+     * OIDC verifier for the JWT front. When set, a bearer that isn't a known API
+     * key is verified as a JWT and matched to a principal by its oidc binding.
+     */
+    oidc?: OidcVerifier;
+    log?: (msg: string) => void;
+};
+export type ShellServeHandle = {
+    server: Server;
+    storage: Storage;
+    kernel: Kernel;
+    port: number;
+    host: string;
+    baseUrl: string;
+    embed: {
+        hook: EmbedHook;
+        worker: Worker;
+    } | null;
+    /** Re-read the policy file and clear the entitlement cache. Called on SIGHUP. */
+    reloadPolicy: () => void;
+    close: () => Promise<void>;
+};
+/**
+ * Peel an optional `/k/<token>/…` credential prefix off a request URL. Some MCP
+ * clients (ChatGPT connectors among them) can set a URL but not an
+ * `Authorization` header; this lets the bearer ride in the path instead. The
+ * `<token>` segment is the exact same credential the header carries (an API key
+ * or a JWT) — issuance, hashing, and revocation are unchanged.
+ *
+ * Returns the token plus the URL with the prefix removed (`/k/<t>/mcp` →
+ * `/mcp`, `/k/<t>` → `/`), or null when there's no prefix. The caller rewrites
+ * `req.url` to the stripped form BEFORE anything routes or logs on it, so the
+ * token lives only in the TLS bytes and the (secret-treated) Authorization
+ * header — never in a logged URL. NOTE: an upstream reverse proxy may still log
+ * the original path; see docs/archive/security.md.
+ */
+export declare function stripTokenPrefix(url: string): {
+    token: string;
+    url: string;
+} | null;
+export declare function startShellServer(config: ShellServeConfig): Promise<ShellServeHandle>;

package/dist/shell/serve.js.map

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

package/dist/shell/stdio.d.ts

@@ -0,0 +1,55 @@
+/**
+ * stdio launcher — auth-shell plan §1 "Launcher mode: stdio", WS4.
+ *
+ * `mrplex mcp-stdio` runs an in-process stdio MCP session over a GUARDED
+ * kernel. stdio has no HTTP layer, so the credential arrives one of three ways
+ * (the MCP spec's own guidance for stdio is credentials-from-environment):
+ *
+ *   1. `--principal <id>` — trust-by-spawn, no credential: the parent chose to
+ *      spawn us (local dev, or a gateway that already authenticated).
+ *   2. `MRPLEX_SHELL_KEY` env / `--key` — an API key, verified against the
+ *      policy file exactly as the HTTP front does.
+ *   3. `MRPLEX_SHELL_TOKEN` env / `--token` — an OAuth access token (WS5).
+ *
+ * All three converge on the same `credential → principal → compile() →
+ * guardKernel` pipeline; stdio is only special in how the credential arrives.
+ */
+import type { Kernel } from "../kernel/kernel.js";
+import { type StdioMount } from "../mcp/server.js";
+import { type AuditSink } from "./guard.js";
+import { type OidcVerifier } from "./oidc.js";
+import { type Policy } from "./policy.js";
+export type StdioCredential = {
+    kind: "principal";
+    id: string;
+} | {
+    kind: "key";
+    key: string;
+} | {
+    kind: "token";
+    token: string;
+};
+/** A resolved stdio caller: which principal, plus a derived author for tokens. */
+export type StdioResolution = {
+    principalId: string;
+    derivedAuthor?: string;
+};
+/**
+ * Resolve a stdio credential to a principal against the policy, or throw a
+ * clear error. `--principal` is trust-by-spawn (the id must exist, no secret
+ * checked); a key is verified by hash; a token is verified as a JWT (requires
+ * an OIDC verifier) and matched to a principal by its oidc binding.
+ */
+export declare function resolveCredential(policy: Policy, cred: StdioCredential, oidc?: OidcVerifier): Promise<StdioResolution>;
+/**
+ * Start a guarded stdio MCP session. Resolves the credential to a principal,
+ * compiles its entitlement, wraps the kernel in the guard (+ optional audit),
+ * and hands the guarded kernel to the shared stdio transport.
+ */
+export declare function startShellStdio(config: {
+    kernel: Kernel;
+    policy: Policy;
+    credential: StdioCredential;
+    oidc?: OidcVerifier;
+    auditSinkFor?: (principal: string) => AuditSink;
+}): Promise<StdioMount>;