sic/docs/design.md

sic — design

A daemon (sicd) receives an argument vector over a stream and runs it, so the caller does not pass a quoted string through a shell. A client (sic) frames the argv and pipes it over ssh.

Problem

Composing shell → ssh → remote shell → program re-parses arguments at each layer. ssh host touch 'a b' creates two files: ssh concatenates its argv with spaces and hands the string to the remote login shell, which re-splits it. Escaping tricks (base64, heredocs, printf %q, ${var@Q}) all exist to survive that round-trip.

Approach: transmit argv, then execvp

A shell flattens argv into one string and re-parses it. sicd skips that: it receives the argument vector as discrete framed fields and calls execvp(argv) (subprocess.run(argv, shell=False)). No shell touches the arguments, so quotes, $, backticks, newlines, and spaces are ordinary bytes in a field.

This is the mechanism behind find -print0 / xargs -0 / git -z: frame argv unambiguously instead of serialising it as a shell string.

Wire format: netstrings

Each field is a netstring (djb): <length>:<bytes>,.

4:echo,            bytes "echo",        length 4
11:hello world,    bytes "hello world", length 11
0:,                empty netstring, used as a terminator

The length prefix means there is no delimiter to collide with and nothing to escape. Netstrings are chosen over ASCII US/RS separators (0x1F/0x1E) because those bytes can appear inside arbitrary payloads; netstrings are binary-safe and need no escaping. The cost is a few header bytes per field.

Frame grammar

<mode-netstring> <arg-netstring>* <empty-netstring>

• mode-netstring — first field, 4:exec, or 2:sh,.
• arg-netstring* — zero or more argument fields. In exec mode these are the elements of argv (first = program). In sh mode there is one field: the whole shell string.
• empty-netstring — 0:, terminates the frame. The daemon runs it and resets. An empty terminator (not a separator) lets multiple frames pipeline in one connection.

Examples

Intent	Wire bytes
argv = ["echo", "hello world"]	4:exec,4:echo,11:hello world,0:,
argv = ["touch", "a b"]	4:exec,5:touch,3:a b,0:,
shell echo hi | wc -c	2:sh,15:echo hi | wc -c,0:,
two frames	4:exec,2:id,0:,4:exec,7:uptime,0:,

Exec modes

mode	selector	behaviour	when
exec (default)	4:exec,	execvp(argv), shell=False. No pipes/redirects/globs.	Default path.
sh	2:sh,	single field to sh -c. Pipes, redirects, globs work; shell parsing is re-accepted for that one string.	Only when a pipeline/redirect/glob is required.

sh mode is a per-frame opt-in, so shell parsing is never entered by accident.

Transport and security

sicd runs what it is sent. That is remote code execution by design, so:

• Do not listen on an open TCP or message-bus port. An unauthenticated stream-to-exec endpoint is a backdoor.
• Run sicd over ssh: as the remote command on ssh stdin, or pinned to a key with command="sicd" in authorized_keys. This reuses ssh's authentication, encryption, and host identity; sicd adds only the framing.
• For same-host fan-out, a Unix domain socket with 0600 permissions is an option. Still not a TCP port.

The client invokes ssh host sicd with the frame on stdin, so the outer shell sees a plain command with no special characters.

Response framing

sicd inherits the child's stdout, stderr, and exit status. Structured results (for example a netstring triple <exit-code> <stdout> <stderr>) are not implemented; add them the same way if needed.

Prior art

Technique	Used for
find -print0 / xargs -0 / git -z	Framing argv without a shell re-split.
netstrings (djb)	Length-prefixed, escaping-free, binary-safe framing.
execve / subprocess(shell=False)	Bypassing the shell for arguments.
the ssh argv gotcha	The case this removes (ssh host touch 'a b' → two files).

Implementation

• cmd/sic — Go client.
• cmd/sicd — Go daemon (single static binary).
• gateway/sicd — Python reference daemon (~40 lines).

Reading all of stdin is sufficient for the ssh-per-call model. A long-lived socket daemon needs incremental parsing; read_netstring already returns the unconsumed remainder for that.