Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c
SHA-256: 31ab809d3c407e0214f6b952e4e24cc5289f3d4ee305f6fe0b9b1520f4af9d7d
-module(tmux_identity). -moduledoc """ Observe a Linux process incarnation using its PID, boot ID and start ticks. ```erlang 1> Pid = list_to_integer(os:getpid()), ok. ok 2> {ok, Identity} = tmux_identity:observe(Pid), ok. ok 3> tmux_identity:check(Identity, Pid). ok ``` A successful check is an observation. It neither reserves a PID nor pins a tmux connection, and it never authorizes signalling a process. Endpoint owners in `m:tmux_server` compare the PID returned by the current connection as well. A server can still change between this check and a later one-shot command. Use `fingerprint/1` to compare captured incarnations across endpoint handles or persist that comparison in a plan. It performs no process observation; the key grants neither liveness nor permission to act. """. -export([observe/1, check/2, fingerprint/1]). -export_type([t/0, fingerprint/0]). -doc """ Observed Linux PID, boot identity and process-start token. It does not pin a connection. """. -opaque t() :: {process_identity, pos_integer(), binary(), non_neg_integer()}. -doc """ Versioned SHA-256 comparison key for a captured Linux process incarnation. The linux-v1 prefix identifies the canonical encoding, independent of Erlang term serialization. Keys compare identity observations, not endpoint ownership or current liveness. They are identifiers, not authentication tokens. """. -type fingerprint() :: binary(). -doc """ Derive a portable `t:fingerprint/0` from a captured identity without I/O. The key includes PID, boot ID and process-start ticks. Reconnecting to the same process preserves it; changing any component changes it. The encoding is versioned for persisted plans. Use `check/2` for a fresh process observation. Malformed identity terms return invalid_identity before hashing. ```erlang 1> {ok, I} = tmux_identity:observe(list_to_integer(os:getpid())), ok. ok 2> {ok, Key} = tmux_identity:fingerprint(I), ok. ok 3> byte_size(Key). 73 ``` """. -spec fingerprint(t()) -> {ok, fingerprint()} | {error, #{code := invalid_identity}}. fingerprint({process_identity, Pid, Boot, Started}) when is_integer(Pid, 1, 2147483647), is_binary(Boot), is_integer(Started, 0, 18446744073709551615) -> case valid_boot_id(Boot) of true -> Digest = crypto:hash(sha256, [<<"libtmux-erlang-incarnation", 0, "1", 0>>, integer_to_binary(Pid), <<0>>, Boot, <<0>>, integer_to_binary(Started)]), {ok, <<"linux-v1:", (binary:encode_hex(Digest, lowercase))/binary>>}; false -> {error, #{code => invalid_identity}} end; fingerprint(_) -> {error, #{code => invalid_identity}}. -doc """ Observe a Linux PID incarnation without signalling it. Returns a tagged error if the process cannot be identified; this performs local operating-system I/O. """. -spec observe(pos_integer()) -> {ok, t()} | {error, map()}. observe(Pid) when is_integer(Pid, 1, 2147483647) -> case os:type() of {unix, linux} -> observe_linux(Pid); _ -> {error, #{code => unsupported_platform}} end; observe(_) -> {error, #{code => invalid_pid}}. -doc """ Re-observe the PID and compare its incarnation token. A successful result is a momentary observation, not ownership, permission to signal, or a same-connection guarantee. """. -spec check(t(), pos_integer()) -> ok | {error, map()}. check({process_identity, Pid, Boot, Started} = Identity, ObservedPid) when is_integer(Pid, 1, 2147483647), is_integer(ObservedPid, 1, 2147483647), is_binary(Boot), is_integer(Started, 0, 18446744073709551615) -> case valid_boot_id(Boot) of false -> {error, #{code => invalid_identity}}; true when Pid =/= ObservedPid -> {error, #{code => stale_server}}; true -> case observe(Pid) of {ok, Identity} -> ok; {ok, _} -> {error, #{code => stale_server}}; {error, #{code := target_gone}} -> {error, #{code => stale_server}}; Error -> Error end end; check(_, _) -> {error, #{code => invalid_identity}}. observe_linux(Pid) -> maybe {ok, Stat} ?= read_bounded("/proc/" ++ integer_to_list(Pid) ++ "/stat", 4096), {ok, Started} ?= start_ticks(Pid, Stat), {ok, RawBoot} ?= boot_file(), Boot = string:trim(RawBoot), case valid_boot_id(Boot) of true -> {ok, {process_identity, Pid, Boot, Started}}; false -> {error, #{code => identity_unavailable, reason => malformed_boot_id}} end end. boot_file() -> case read_bounded("/proc/sys/kernel/random/boot_id", 64) of {ok, Bytes} -> {ok, Bytes}; {error, Detail} -> {error, Detail#{code => identity_unavailable, resource => boot_id}} end. read_bounded(Path, Limit) -> case file:open(Path, [read, binary, raw]) of {ok, File} -> try case file:read(File, Limit + 1) of {ok, Data} when byte_size(Data) =< Limit -> {ok, Data}; {ok, _} -> {error, #{code => identity_unavailable, reason => oversized_proc_file}}; eof -> {error, #{code => target_gone}}; {error, Reason} -> file_error(Reason) end after ok = file:close(File) end; {error, Reason} -> file_error(Reason) end. file_error(enoent) -> {error, #{code => target_gone}}; file_error(esrch) -> {error, #{code => target_gone}}; file_error(Reason) -> {error, #{code => identity_unavailable, reason => Reason}}. start_ticks(Pid, Stat) -> Prefix = <<(integer_to_binary(Pid))/binary, " (">>, Size = byte_size(Prefix), case Stat of <<Prefix:Size/binary, Rest/binary>> -> parse_stat_tail(Rest); _ -> {error, #{code => identity_unavailable, reason => malformed_proc_stat}} end. parse_stat_tail(Rest) -> case binary:matches(Rest, <<") ">>) of [] -> {error, #{code => identity_unavailable, reason => malformed_proc_stat}}; Matches -> %% comm may itself contain spaces, newlines and closing parentheses. {Position, 2} = lists:last(Matches), Tail = binary:part(Rest, Position + 2, byte_size(Rest) - Position - 2), Fields = binary:split(Tail, <<" ">>, [global]), parse_fields(Fields) end. parse_fields([State | _]) when State =:= <<"Z">>; State =:= <<"X">>; State =:= <<"x">> -> {error, #{code => target_gone}}; parse_fields(Fields) when length(Fields) >= 20 -> Start = lists:nth(20, Fields), case decimal(Start) of true -> Ticks = binary_to_integer(Start), case Ticks =< 18446744073709551615 of true -> {ok, Ticks}; false -> {error, #{code => identity_unavailable, reason => malformed_proc_stat}} end; false -> {error, #{code => identity_unavailable, reason => malformed_proc_stat}} end; parse_fields(_) -> {error, #{code => identity_unavailable, reason => malformed_proc_stat}}. decimal(<<>>) -> false; decimal(Bytes) -> decimal_tail(Bytes). decimal_tail(<<>>) -> true; decimal_tail(<<C, Rest/binary>>) when C >= $0, C =< $9 -> decimal_tail(Rest); decimal_tail(_) -> false. valid_boot_id(<<A:8/binary, $-, B:4/binary, $-, C:4/binary, $-, D:4/binary, $-, E:12/binary>>) -> hex(<<A/binary, B/binary, C/binary, D/binary, E/binary>>); valid_boot_id(_) -> false. hex(<<>>) -> true; hex(<<C, Rest/binary>>) when (C >= $0 andalso C =< $9) orelse (C >= $a andalso C =< $f) -> hex(Rest); hex(_) -> false.