sayfirst-cli 0.2.0__py3-none-any.whl

sayfirst_cli/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The product command-line interface of the `sayfirst` control plane."""

sayfirst_cli/approvals.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Read a suspended request, approve it, reject it — one person, nothing more.
+
+Article 12's simple form: no signatures, no designation, one person's act. This
+module reads the same way `trace` and `explain` do — through `reads.read` and
+`reads.finish` — because `show` is exactly that shape, and `approve`/`reject`
+answer the same document a `show` would: the record the act left behind, so a
+caller renders one writer whichever of the three it asked for.
+
+Unlike `read_decision`, the daemon does NOT close the connection after
+`read_approval` or `resolve_approval` (the transport's own docstrings say so):
+it writes both answers through its own handler and leaves the connection for
+the next request. That is what lets a person read a wait and then end it
+without reconnecting — and it is the daemon's behaviour to rely on, not a
+promise the daemon owes across every future release. One command here ever
+does one thing, so nothing in this module reads twice on the same connection
+and rule C4's explicit reconnect never comes up.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Mapping, Sequence
+from typing import Final, TextIO
+
+from sayfirst_contract.approvals import ApprovalResolution, Resolution
+
+from . import reads, render
+
+
+def _stated(value: object) -> str:
+    """A member as a person reads it, with absence said rather than shown.
+
+    The same rule `render._stated` applies, spelled here rather than imported:
+    that helper is render's own, and a second module reaching into it is a
+    second module that breaks when its name does.
+    """
+    return render.NOT_STATED if value is None else str(value)
+
+
+def _write_approval(document: Mapping[str, object], stream: TextIO) -> None:
+    """The seven members a person reads about one wait — read or resolved alike."""
+    stream.write(f"approval: {document['approval_ref']}\n")
+    stream.write(f"decision: {document['decision_ref']}\n")
+    stream.write(f"state: {document['state']}\n")
+    stream.write(f"requested_at: {document['requested_at']}\n")
+    stream.write(f"deadline: {document['deadline']}\n")
+    stream.write(f"resolved_at: {_stated(document.get('resolved_at'))}\n")
+    stream.write(f"reason: {_stated(document.get('resolution_reason'))}\n")
+
+
+def _connection_parser(prog: str) -> argparse.ArgumentParser:
+    """Every `approvals` subcommand shares the connection options and `--approval`."""
+    parser = argparse.ArgumentParser(prog=prog)
+    reads.add_connection_arguments(parser)
+    parser.add_argument("--approval", required=True, help="the reference of the suspended approval")
+    return parser
+
+
+def _show(argv: Sequence[str], *, out: TextIO, err: TextIO) -> int:
+    parser = _connection_parser("sayfirst approvals show")
+    arguments = parser.parse_args(argv)
+    connection = reads.open_connection(arguments, err)
+    if isinstance(connection, int):
+        return connection
+    try:
+        result = reads.read(lambda: connection.read_approval(arguments.scope, arguments.approval))
+        return reads.finish(result, arguments, connection, out, err, _write_approval)
+    finally:
+        connection.close()
+
+
+def _resolve(argv: Sequence[str], *, out: TextIO, err: TextIO, resolution: Resolution) -> int:
+    parser = _connection_parser(f"sayfirst approvals {resolution.value}")
+    parser.add_argument("--reason", default=None, help="why this decision was made")
+    arguments = parser.parse_args(argv)
+    connection = reads.open_connection(arguments, err)
+    if isinstance(connection, int):
+        return connection
+    try:
+        act = ApprovalResolution(arguments.scope, arguments.approval, resolution, arguments.reason)
+        # Put exactly once (the transport's own rule): a failure here is
+        # reported as what the transport classified it, never retried by this
+        # command on the caller's behalf.
+        result = reads.read(lambda: connection.resolve_approval(act))
+        return reads.finish(result, arguments, connection, out, err, _write_approval)
+    finally:
+        connection.close()
+
+
+def _approve(argv: Sequence[str], *, out: TextIO, err: TextIO) -> int:
+    return _resolve(argv, out=out, err=err, resolution=Resolution.APPROVE)
+
+
+def _reject(argv: Sequence[str], *, out: TextIO, err: TextIO) -> int:
+    return _resolve(argv, out=out, err=err, resolution=Resolution.REJECT)
+
+
+#: The three acts this distribution answers, each with the entry point that
+#: owns its parser and its exit codes.
+COMMANDS: Final[dict[str, Callable[..., int]]] = {
+    "show": _show,
+    "approve": _approve,
+    "reject": _reject,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sayfirst approvals",
+        description="Read a suspended request, approve it, or reject it.",
+    )
+    commands = parser.add_subparsers(dest="command", required=True)
+    for name in COMMANDS:
+        commands.add_parser(name, add_help=False)
+    return parser
+
+
+def main(
+    argv: Sequence[str] | None = None, *, out: TextIO | None = None, err: TextIO | None = None
+) -> int:
+    forwarded = list(sys.argv[1:] if argv is None else argv)
+    if forwarded and (command := COMMANDS.get(forwarded[0])) is not None:
+        return command(forwarded[1:], out=out or sys.stdout, err=err or sys.stderr)
+    build_parser().parse_args(forwarded)
+    raise AssertionError("argparse accepted an approvals command that has no entry point")

sayfirst_cli/ask.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: Apache-2.0
+"""`sayfirst ask`: put one question to the control plane and render its answer.
+
+This is the product act. A person names a capability and a scope, this client
+opens the daemon's socket, verifies the far end is the daemon's principal before
+it writes anything, sends the question the contract defines, and renders the
+answer the control plane gave — `allow`, `deny` or `suspend` — with an exit code
+per outcome.
+
+What this command does **not** do is the point of it. It holds no policy, it
+caches no decision, and when the daemon cannot be reached it says so; it never
+turns "could not ask" into "deny" and never turns it into "allow" (articles 1
+and 2). There is no `--url` and nothing that takes a token: the boundary says
+who the caller is, and it says so from the socket (article 6).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+from typing import Final, TextIO
+
+from sayfirst_contract.client import Answered, Refused
+from sayfirst_contract.decisions import DecisionAsk, Outcome
+from sayfirst_contract.generation import CONTRACT_GENERATION
+from sayfirst_contract.transport.socket_client import (
+    PER_USER,
+    SYSTEM,
+    ProfileMisuse,
+    SocketClientProblem,
+    SocketProfile,
+    connect,
+    declared_delegation,
+)
+
+from . import exit_codes, reads, render
+
+#: One exit code per outcome the contract defines. `tests/test_exit_codes.py`
+#: holds this map against `Outcome`, so the fallback below is unreachable in a
+#: build whose contract and client agree.
+EXIT_BY_OUTCOME: Final[dict[Outcome, int]] = {
+    Outcome.ALLOW: exit_codes.EXIT_ALLOW,
+    Outcome.DENY: exit_codes.EXIT_DENY,
+    Outcome.SUSPEND: exit_codes.EXIT_SUSPEND,
+}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Every option this command accepts. None of them names a network."""
+    parser = argparse.ArgumentParser(
+        prog="sayfirst ask",
+        description="Ask the control plane whether one capability may be exercised.",
+    )
+    parser.add_argument("--capability", required=True, help="the kind of effect, and nothing more")
+    parser.add_argument("--scope", default="local", help="the scope the question is asked in")
+    parser.add_argument("--socket", required=True, help="the path of the daemon's socket")
+    parser.add_argument("--mode", choices=(PER_USER, SYSTEM), default=PER_USER)
+    parser.add_argument(
+        "--daemon-user",
+        default=None,
+        help="the account the daemon runs as; a system profile names it",
+    )
+    parser.add_argument("--arguments-digest", default=None)
+    parser.add_argument("--correlation", default=None)
+    parser.add_argument("--json", action="store_true", help="write the envelope instead of prose")
+    return parser
+
+
+def _exit_for_answer(outcome: Outcome) -> int:
+    """The code for an outcome, failing closed on one this client cannot render.
+
+    An outcome the contract defines and this map has forgotten is a defect of
+    this file, not an answer: it is reported the way an unreadable answer is,
+    because the one thing it must never do is exit zero (articles 1 and 3).
+    """
+    return EXIT_BY_OUTCOME.get(outcome, exit_codes.EXIT_COULD_NOT_ASK)
+
+
+def main(
+    argv: Sequence[str] | None = None, *, out: TextIO | None = None, err: TextIO | None = None
+) -> int:
+    """Run the command and return the code the calling shell should see."""
+    stdout = out or sys.stdout
+    stderr = err or sys.stderr
+    arguments = build_parser().parse_args(argv)
+
+    try:
+        profile = SocketProfile(
+            arguments.socket,
+            mode=arguments.mode,
+            daemon_user=arguments.daemon_user,
+            scope=arguments.scope,
+        )
+    except ProfileMisuse as misuse:
+        stderr.write(f"{misuse}\n")
+        return exit_codes.EXIT_MISUSE
+
+    # Declared by a privilege tool, never proven by it: article 6 keeps a
+    # delegation visible instead of collapsing it into the human's identity.
+    declared = declared_delegation()
+
+    try:
+        connection = connect(profile)
+    except SocketClientProblem as failure:
+        could_not_ask = failure.classification != "refused"
+        document = render.envelope(
+            CONTRACT_GENERATION,
+            render.verification_document(None, None, False),
+            problem=failure.problem.to_document(CONTRACT_GENERATION),
+        )
+        _write(document, arguments.json, stderr, could_not_ask=could_not_ask)
+        return exit_codes.EXIT_COULD_NOT_ASK if could_not_ask else exit_codes.EXIT_REFUSED
+
+    try:
+        ask = DecisionAsk(
+            capability=arguments.capability,
+            scope=arguments.scope,
+            arguments_digest=arguments.arguments_digest,
+            correlation=arguments.correlation,
+        )
+        # Read before the question is put, because it is already true: the far
+        # end was verified before a byte was written, and it stays what was
+        # verified whether or not an answer ever comes back.
+        verification = render.verification_document(
+            connection.server_credential.uid, connection.expected_uid, connection.verified
+        )
+        # A transport failure with the question already on the wire (a daemon
+        # restarted, stopped or killed between the accept and the answer) and
+        # an answer that arrived but is not a decision document are both
+        # non-answers: nothing is reported as an answer, and neither reaches
+        # the shell as a traceback — exit 1 is this client's published code
+        # for `deny` (articles 1 and 2). The one rule lives beside the reads.
+        result = reads.read(lambda: connection.ask_decision(ask, declared))
+        if isinstance(result, Answered):
+            document = render.envelope(
+                result.contract_generation, verification, result=result.value.to_document()
+            )
+            _write(document, arguments.json, stdout)
+            return _exit_for_answer(result.value.outcome)
+        could_not_ask = not isinstance(result, Refused)
+        document = render.envelope(
+            CONTRACT_GENERATION,
+            verification,
+            problem=result.problem.to_document(CONTRACT_GENERATION),
+        )
+        _write(document, arguments.json, stderr, could_not_ask=could_not_ask)
+        return exit_codes.EXIT_COULD_NOT_ASK if could_not_ask else exit_codes.EXIT_REFUSED
+    finally:
+        connection.close()
+
+
+def _write(
+    document: dict[str, object], as_json: bool, stream: TextIO, *, could_not_ask: bool = False
+) -> None:
+    if as_json:
+        render.write_json(document, stream)
+        return
+    verification = document["verification"]
+    assert isinstance(verification, dict)
+    render.write_verification(verification, stream)
+    result = document.get("result")
+    if isinstance(result, dict):
+        render.write_decision(result, stream)
+    problem = document.get("problem")
+    if isinstance(problem, dict):
+        render.write_problem(problem, stream, could_not_ask=could_not_ask)