@solarisdk/core 0.4.2 → 0.4.3

package/dist/desktop.js

@@ -46,11 +46,19 @@ export class Desktop extends SessionHandle {
             stream: opts.stream,
         });
     }
-    execStream(cmd, onChunk, opts = {}) {
-        return this.rpcStream("exec", { cmd, args: opts.args ?? [], cwd: opts.cwd, timeoutMs: opts.timeoutMs, stream: true }, (c) => {
+    async execStream(cmd, onChunk, opts = {}) {
+        const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+        const result = await this.rpcStream("exec", { cmd, args: opts.args ?? [], cwd: opts.cwd, timeoutMs: opts.timeoutMs, stream: true }, (c) => {
             const bytes = c.data ? base64ToBytes(c.data) : new Uint8Array();
-            onChunk({ stream: c.stream, text: new TextDecoder().decode(bytes), bytes });
+            const dec = decoders[c.stream] ?? decoders.stdout;
+            onChunk({ stream: c.stream, text: dec.decode(bytes, { stream: true }), bytes });
         });
+        for (const stream of ["stdout", "stderr"]) {
+            const rest = decoders[stream].decode();
+            if (rest)
+                onChunk({ stream, text: rest, bytes: new Uint8Array() });
+        }
+        return result;
     }
     fs = {
         read: (path) => this.files.read(path),
@@ -126,7 +134,18 @@ export class Desktop extends SessionHandle {
     process = {
         list: async () => {
             const r = await this.guiCall("process.list", {});
-            return r.processes;
+            return (r.processes ?? []).map((p) => {
+                const info = {
+                    pid: Number(p.pid),
+                    name: String(p.name ?? p.comm ?? ""),
+                };
+                const cmd = p.cmd ?? p.cmdline;
+                if (typeof cmd === "string")
+                    info.cmd = cmd;
+                if (typeof p.state === "string")
+                    info.state = p.state;
+                return info;
+            });
         },
         kill: (pid) => this.guiCall("process.kill", { pid }).then(() => undefined),
         start: async (cmd, opts = {}) => {

package/dist/handle.d.ts

@@ -58,12 +58,18 @@ export interface SessionConfig extends ControlChannelConfig {
 export declare const DEFAULT_COMMAND_TIMEOUT_MS = 600000;
 /** Cap on PTY output held before the first onData() subscriber (bytes, total). */
 export declare const PTY_EARLY_BUFFER_MAX: number;
+export interface SessionHandle {
+    /** `await using sbx = await client.create(...)` releases the machine (`kill()`) when the scope ends. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
 export declare class SessionHandle {
     /** The session id (sandboxId / sessionId). */
     readonly id: string;
     readonly controlUrl: string;
     readonly expiresAt: string;
     protected readonly channel: ControlChannel;
+    /** Set once the gateway has refused a command stream because this sandbox is `shared`. */
+    private sharedContext;
     protected readonly hooks: SessionHooks;
     /** Set by {@link kill} so {@link close} doesn't warn about a machine we
      *  have just released. */
@@ -198,10 +204,19 @@ export declare class SessionHandle {
     };
     /** Run `git <args>` in the guest via the command RPC (no shell). */
     private runGit;
-    /** Run `git <args>`; throw with the stderr on a non-zero exit. */
+    /** Run `git <args>`; throw with the stderr on a non-zero exit. A password passed in `secret` is masked in the message. */
     private mustGit;
-    /** Splice basic-auth creds into an https remote URL (for private remotes). */
-    private authUrl;
+    /**
+     * Credentials for ONE git command, for a private http(s) remote at `remoteUrl`. They go to the guest as environment
+     * variables of that command and git reads them back through an inline credential helper, so they are never in the
+     * clone URL (and so not in `.git/config`, a snapshot or a template), never in argv (`/proc/<pid>/cmdline`), and never
+     * in a config file: the `-c` options last for this command only and the helper script holds no secret.
+     *
+     * The helper is bound to the remote's origin (`credential.<scheme>://<host>.helper`), so git never hands the password
+     * to another host: a redirect to a different host, or a downgrade to http, gets nothing. Returns undefined when
+     * there are no credentials, or the remote is not http(s) (ssh remotes do not use them).
+     */
+    private gitAuth;
     private gitClone;
     private gitStatus;
     private gitAdd;

package/dist/handle.js

@@ -23,11 +23,23 @@ function trackUnreleased(token, id) {
 }
 const MIN_REST_TIMEOUT_MS = 1000;
 export const PTY_EARLY_BUFFER_MAX = 1024 * 1024;
+const GIT_CREDENTIAL_HELPER = '!f() { test "$1" = get && printf "username=%s\\npassword=%s\\n" "$SOLARI_GIT_USERNAME" "$SOLARI_GIT_PASSWORD"; }; f';
+function gitSubcommand(args) {
+    let i = 0;
+    while (args[i] === "-c")
+        i += 2;
+    return args[i] ?? "";
+}
+function rejectOptionLike(what, v) {
+    if (v.startsWith("-"))
+        throw new Error(`git ${what} must not start with "-": ${JSON.stringify(v)}`);
+}
 export class SessionHandle {
     id;
     controlUrl;
     expiresAt;
     channel;
+    sharedContext = false;
     hooks;
     killed = false;
     releaseToken = {};
@@ -120,17 +132,26 @@ export class SessionHandle {
                     opts.onStderr?.(c.data);
             });
         }
-        this.channel.onFrame("cmd.data", cmdId, (f) => {
-            const stream = f.stream ?? "stdout";
-            const data = f.base64 ? new TextDecoder().decode(base64ToBytes(f.base64)) : "";
-            const chunk = { stream, data };
+        const decoders = { stdout: new TextDecoder(), stderr: new TextDecoder() };
+        const emit = (chunk) => {
             if (dataCbs.length === 0)
                 buffered.push(chunk);
             else
                 for (const cb of dataCbs)
                     cb(chunk);
+        };
+        this.channel.onFrame("cmd.data", cmdId, (f) => {
+            const stream = f.stream ?? "stdout";
+            const dec = decoders[stream] ?? decoders.stdout;
+            const data = f.base64 ? dec.decode(base64ToBytes(f.base64), { stream: true }) : "";
+            emit({ stream, data });
         });
         this.channel.onFrame("cmd.exit", cmdId, (f) => {
+            for (const stream of ["stdout", "stderr"]) {
+                const rest = decoders[stream].decode();
+                if (rest)
+                    emit({ stream, data: rest });
+            }
             this.channel.offFrame("cmd.data", cmdId);
             this.channel.offFrame("cmd.exit", cmdId);
             this.channel.offStreamClose(cmdId);
@@ -172,23 +193,21 @@ export class SessionHandle {
         if (typeof timeoutMs !== "number" || !Number.isFinite(timeoutMs) || timeoutMs < 0) {
             throw new SolariError(`Solari: timeoutMs must be a non-negative number of milliseconds, got ${String(timeoutMs)}`);
         }
-        if (this.hooks.exec &&
+        const restEligible = !!this.hooks.exec &&
             !opts.background &&
             !opts.onStdout &&
             !opts.onStderr &&
             !opts.env &&
             !opts.user &&
             timeoutMs >= MIN_REST_TIMEOUT_MS &&
-            timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS &&
-            !this.channel.connected) {
+            timeoutMs <= DEFAULT_COMMAND_TIMEOUT_MS;
+        const viaRest = async () => {
+            const r = await this.hooks.exec(this.id, { cmd, args: opts.args, cwd: opts.cwd, timeoutMs });
+            return { ...r, timedOut: r.timedOut === true };
+        };
+        if (restEligible && (!this.channel.connected || this.sharedContext)) {
             try {
-                const r = await this.hooks.exec(this.id, {
-                    cmd,
-                    args: opts.args,
-                    cwd: opts.cwd,
-                    timeoutMs,
-                });
-                return { ...r, timedOut: r.timedOut === true };
+                return await viaRest();
             }
             catch (err) {
                 if (!isRouteUnavailable(err))
@@ -196,7 +215,24 @@ export class SessionHandle {
             }
         }
         const acc = { stdout: "", stderr: "" };
-        const handle = await this.startCommand(cmd, { ...opts, timeoutMs: undefined }, acc);
+        let handle;
+        try {
+            handle = await this.startCommand(cmd, { ...opts, timeoutMs: undefined }, acc);
+        }
+        catch (err) {
+            if (!isSharedRefusal(err))
+                throw err;
+            this.sharedContext = true;
+            if (restEligible) {
+                try {
+                    return await viaRest();
+                }
+                catch (e) {
+                    throw normalizeExecError(e, timeoutMs);
+                }
+            }
+            throw err;
+        }
         if (opts.background) {
             return { exitCode: 0, stdout: "", stderr: "", timedOut: false };
         }
@@ -378,42 +414,61 @@ export class SessionHandle {
         branches: (cwd) => this.gitBranches(cwd),
         log: (opts = {}) => this.gitLog(opts),
     };
-    async runGit(args, cwd) {
-        return this.runCommand("git", { args, ...(cwd ? { cwd } : {}) });
+    async runGit(args, cwd, env) {
+        return this.runCommand("git", { args, ...(cwd ? { cwd } : {}), ...(env ? { env } : {}) });
     }
-    async mustGit(args, cwd) {
-        const r = await this.runGit(args, cwd);
+    async mustGit(args, cwd, env, secret) {
+        const r = await this.runGit(args, cwd, env);
         if (r.exitCode !== 0) {
-            const detail = (r.stderr || r.stdout || "").trim();
-            throw new Error(`git ${args[0]} failed (exit ${r.exitCode}): ${detail}`);
+            let detail = (r.stderr || r.stdout || "").trim();
+            if (secret)
+                detail = detail.split(secret).join("***");
+            throw new Error(`git ${gitSubcommand(args)} failed (exit ${r.exitCode}): ${detail}`);
         }
         return r.stdout;
     }
-    authUrl(url, username, password) {
+    gitAuth(remoteUrl, username, password) {
         if (!username && !password)
-            return url;
+            return undefined;
+        for (const v of [username, password]) {
+            if (v !== undefined && /[\r\n\0]/.test(v))
+                throw new Error("git credentials must not contain line breaks or NUL");
+        }
+        let origin;
         try {
-            const u = new URL(url);
-            if (username)
-                u.username = encodeURIComponent(username);
-            if (password)
-                u.password = encodeURIComponent(password);
-            return u.toString();
+            const u = new URL(remoteUrl);
+            if (u.protocol !== "https:" && u.protocol !== "http:")
+                return undefined;
+            origin = `${u.protocol}//${u.host}`;
         }
         catch {
-            return url;
+            return undefined;
         }
+        if (/[=\s]/.test(origin))
+            return undefined;
+        return {
+            cfg: [
+                "-c", "credential.helper=",
+                "-c", `credential.${origin}.helper=${GIT_CREDENTIAL_HELPER}`,
+            ],
+            env: {
+                GIT_TERMINAL_PROMPT: "0",
+                SOLARI_GIT_USERNAME: username ?? "",
+                SOLARI_GIT_PASSWORD: password ?? "",
+            },
+        };
     }
     async gitClone(url, opts) {
-        const args = ["clone"];
+        const auth = this.gitAuth(url, opts.username, opts.password);
+        const args = [...(auth?.cfg ?? []), "clone"];
         if (opts.depth && opts.depth > 0)
             args.push("--depth", String(opts.depth));
         if (opts.branch)
             args.push("--branch", opts.branch);
-        args.push(this.authUrl(url, opts.username, opts.password));
+        args.push("--", url);
         if (opts.path)
             args.push(opts.path);
-        await this.mustGit(args, opts.cwd);
+        await this.mustGit(args, opts.cwd, auth?.env, opts.password);
     }
     async gitStatus(cwd) {
         const out = await this.mustGit(["status", "--porcelain=v1", "--branch"], cwd);
@@ -488,25 +543,25 @@ export class SessionHandle {
     }
     async gitPushPull(op, opts) {
         const remote = opts.remote || "origin";
-        const cfg = [];
+        rejectOptionLike("remote", remote);
+        if (opts.branch)
+            rejectOptionLike("branch", opts.branch);
+        let auth;
         if (opts.username || opts.password) {
-            const plain = (await this.runGit(["remote", "get-url", remote], opts.cwd)).stdout.trim();
-            if (plain) {
-                const authed = this.authUrl(plain, opts.username, opts.password);
-                if (authed !== plain)
-                    cfg.push("-c", `url.${authed}.insteadOf=${plain}`);
-            }
+            const plain = (await this.mustGit(["remote", "get-url", "--", remote], opts.cwd)).trim();
+            auth = this.gitAuth(plain, opts.username, opts.password);
         }
-        const args = [...cfg, op, remote];
+        const args = [...(auth?.cfg ?? []), op, "--", remote];
         if (opts.branch)
             args.push(opts.branch);
-        await this.mustGit(args, opts.cwd);
+        await this.mustGit(args, opts.cwd, auth?.env, opts.password);
     }
     async gitCheckout(ref, opts) {
+        rejectOptionLike("ref", ref);
         const args = ["checkout"];
         if (opts.create)
             args.push("-b");
-        args.push(ref);
+        args.push(ref, "--");
         await this.mustGit(args, opts.cwd);
     }
     async gitBranches(cwd) {
@@ -652,6 +707,11 @@ function explainShellCommandFailure(cmd, err) {
     }
     return new Error(msg + hint);
 }
+function isSharedRefusal(err) {
+    if (err instanceof ActionError && err.code === "NotAvailableOnSharedIsolation")
+        return true;
+    return err instanceof Error && /NotAvailableOnSharedIsolation|not available on a shared/.test(err.message);
+}
 function isRouteUnavailable(err) {
     return (err instanceof GatewayError &&
         (err.status === 404 || err.status === 405 || err.status === 501));

package/dist/types.d.ts

@@ -686,8 +686,12 @@ export interface ProcessListParams {
 }
 export interface ProcessInfo {
     pid: number;
+    /** The process name (the guest agent's `comm`). */
     name: string;
+    /** The full command line (the guest agent's `cmdline`). */
     cmd?: string;
+    /** Process state letter as the kernel reports it (`R`, `S`, `Z`, ...). */
+    state?: string;
 }
 export interface ProcessListResult {
     processes: ProcessInfo[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solarisdk/core",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Shared runtime for the Solari SDK \u2014 transport, session handles, images, templates, and types used by @solarisdk/desktop and @solarisdk/sandbox.",
   "type": "module",
   "main": "./dist/index.js",