sayfirst-cli 0.2.0__py3-none-any.whl

sayfirst_cli/reads.py

@@ -0,0 +1,254 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The shared path for scoped reads: verify the connection and render its result.
+
+A read acts for nobody and carries no delegation. Its success says a record
+was read, never that the effect recorded there may be exercised (article 1).
+"""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Callable, Mapping
+from typing import Final, Protocol, TextIO
+
+from sayfirst_contract.client import Answered, CouldNotAsk, Refused, Result
+from sayfirst_contract.generation import CONTRACT_GENERATION
+from sayfirst_contract.problems import Problem, ProblemCode, problem_retryable
+from sayfirst_contract.transport.socket_client import (
+    PER_USER,
+    SYSTEM,
+    ProfileMisuse,
+    SocketClientProblem,
+    SocketProfile,
+    VerifiedConnection,
+    connect,
+)
+
+from . import exit_codes, render
+
+INPUT_ERRORS: Final = (
+    AttributeError,
+    KeyError,
+    TypeError,
+    ValueError,
+    OverflowError,
+    RecursionError,
+)
+"""The exceptions an answer from the daemon can raise on its way into this client.
+
+The contract's readers classify what they can and let the rest through: a `200`
+whose body is JSON but not an object raises `AttributeError` inside
+`read_decision`, a reply nested past the interpreter's limit raises
+`RecursionError` inside `json.loads`, a timestamp outside the calendar raises
+`OverflowError`. Every one of them is an answer this client could not read —
+« could not ask », never « denied » (articles 1 and 2) — and an escape from here
+ends the process with a traceback, exit 1, which is this client's code for deny.
+One tuple, because five copies of it is how a sixth caller comes to spell none.
+"""
+
+DOCUMENT_DEPTH_LIMIT: Final = 64
+"""How deeply nested a daemon document may be before this client declines to read it.
+
+A real record, page or bundle nests a handful of levels (entries, bodies,
+attached policies). A document nested thousands deep still parses, and then the
+step that renders it back into an envelope exhausts the interpreter and ends the
+process with a traceback — exit 1, deny again. A bound stated here is honest; an
+escape is not.
+
+**The bound is measured where the render happens**, which is `finish` below: it
+is the whole answer a command composes, not one page of it, that the envelope is
+built from. `PAGE_DEPTH_LIMIT` is the same rule read one step earlier, so that a
+page a walk accepts is a page the command that walks it can render.
+"""
+
+PAGE_DEPTH_LIMIT: Final = DOCUMENT_DEPTH_LIMIT - 2
+"""How deeply nested ONE page may be, which is two levels shallower, and why.
+
+A paging read hands `finish` the pages it collected under a member of its own —
+`{"pages": [page, …]}` — so every page sits three levels down in the answer that
+is actually rendered, and its own deepest member two levels deeper than it
+measured alone. A page validator that used the full bound therefore accepted
+pages the render then refused, after the prose for the pages before it had
+already reached the caller: half an answer and then « could not ask » is worse
+than either answer alone.
+
+**One rule, one number, subtracted once, and measured rather than argued.** The
+`2` is not a margin: it is the exact difference between the two documents, and
+`tests/test_evidence_history_and_audit.py`'s bound pair is what pins it — a page
+at the full bound renders as an answer, and one level past it is refused before
+a byte reaches stdout. A subtraction that drifted in either direction turns one
+of those two red. A caller composing a different answer around a page passes its
+own limit to `too_deep`, which is why that argument exists; nothing else is
+bounded twice.
+"""
+
+
+class DocumentValue(Protocol):
+    """A typed contract value that supplies its own document."""
+
+    def to_document(self) -> Mapping[str, object]: ...
+
+
+def positive(value: str) -> int:
+    """A bound a caller supplies: zero and below are misuse, not a small read.
+
+    One rule across the slice, because `--pages 0` claiming « not found within 0
+    page(s) » with exit 0 is a mistyped bound rendered as an established absence.
+    """
+    number = int(value)
+    if number < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return number
+
+
+def too_deep(value: object, limit: int = DOCUMENT_DEPTH_LIMIT) -> bool:
+    """Whether a document nests beyond `limit` — iteratively, so the check itself
+    can never be the recursion it guards against.
+
+    The default is the bound on a whole answer; a caller bounding one piece of
+    one passes `PAGE_DEPTH_LIMIT` and says which piece in its own refusal.
+    """
+    pending: list[tuple[object, int]] = [(value, 1)]
+    while pending:
+        item, depth = pending.pop()
+        if depth > limit:
+            return True
+        if isinstance(item, Mapping):
+            pending.extend((child, depth + 1) for child in item.values())
+        elif isinstance(item, list):
+            pending.extend((child, depth + 1) for child in item)
+    return False
+
+
+def unreadable(failure: Exception) -> CouldNotAsk:
+    """An answer this client could not read, said as that and never as a refusal."""
+    return CouldNotAsk(
+        # Retryability is the registry's to state, never this client's: the
+        # contract's table says « not stated » for an unreadable answer, and the
+        # transport says the same when it is the one that classifies (article 2).
+        Problem(
+            ProblemCode.ANSWER_UNREADABLE,
+            str(failure),
+            problem_retryable(ProblemCode.ANSWER_UNREADABLE),
+            CONTRACT_GENERATION,
+        )
+    )
+
+
+def read[T](operation: Callable[[], Result[T]]) -> Result[T]:
+    """Run one read of the daemon: the two ways an answer fails to be one, in one place.
+
+    A transport failure carries the contract's own classification — refused, or
+    could not ask. An answer that arrives and cannot be read is
+    `answer_unreadable`. Neither is a decision, and neither may reach the shell
+    as exit 1, the code for « deny ». Every read of this client goes through
+    here, a page walk included, so that a command cannot be the one that forgot.
+    """
+    try:
+        return operation()
+    except SocketClientProblem as failure:
+        return connection_problem(failure)
+    except INPUT_ERRORS as failure:
+        return unreadable(failure)
+
+
+def add_connection_arguments(parser: argparse.ArgumentParser) -> None:
+    """Every read names its scope explicitly, with the writer's connection options."""
+    parser.add_argument("--scope", required=True, 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("--json", action="store_true", help="write the envelope instead of prose")
+
+
+def connection_problem(failure: SocketClientProblem) -> Refused | CouldNotAsk:
+    """A transport exception is a non-answer, with the contract's classification."""
+    if failure.classification == "refused":
+        return Refused(failure.problem)
+    return CouldNotAsk(failure.problem)
+
+
+def open_connection(arguments: argparse.Namespace, stderr: TextIO) -> VerifiedConnection | int:
+    """Verify the daemon, or report why this invocation could not open a connection."""
+    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
+    try:
+        return connect(profile)
+    except SocketClientProblem as failure:
+        return _write_problem(
+            connection_problem(failure),
+            arguments,
+            render.verification_document(None, None, False),
+            stderr,
+        )
+
+
+def finish(
+    result: Result[DocumentValue | Mapping[str, object]],
+    arguments: argparse.Namespace,
+    connection: VerifiedConnection,
+    stdout: TextIO,
+    stderr: TextIO,
+    render_answer: Callable[[Mapping[str, object], TextIO], None],
+) -> int:
+    """Render the supplied record or problem; a record's outcome is only data."""
+    verification = render.verification_document(
+        connection.server_credential.uid, connection.expected_uid, connection.verified
+    )
+    # The document is materialised and bounded through the same helper the read
+    # used: `to_document` is itself a step an unreadable answer raises inside,
+    # and the render below is the step a document nested past the bound would
+    # overflow. Either way the answer is one this client could not read.
+    answer = read(lambda: _bounded(result)) if isinstance(result, Answered) else result
+    if isinstance(answer, Answered):
+        document = answer.value
+        if arguments.json:
+            render.write_json(
+                render.envelope(CONTRACT_GENERATION, verification, result=document), stdout
+            )
+        else:
+            render_answer(document, stdout)
+        return 0
+    return _write_problem(answer, arguments, verification, stderr)
+
+
+def _bounded(
+    result: Answered[DocumentValue | Mapping[str, object]],
+) -> Answered[Mapping[str, object]]:
+    """The answer as the document about to be rendered, refused if it nests too deep."""
+    value = result.value
+    document = value if isinstance(value, Mapping) else value.to_document()
+    if too_deep(document):
+        raise ValueError(
+            f"nested deeper than {DOCUMENT_DEPTH_LIMIT} levels; not a document this client reads"
+        )
+    return Answered(document, result.contract_generation)
+
+
+def _write_problem(
+    result: Refused | CouldNotAsk,
+    arguments: argparse.Namespace,
+    verification: Mapping[str, object],
+    stderr: TextIO,
+) -> int:
+    could_not_ask = not isinstance(result, Refused)
+    problem = result.problem.to_document(CONTRACT_GENERATION)
+    document = render.envelope(CONTRACT_GENERATION, verification, problem=problem)
+    if arguments.json:
+        render.write_json(document, stderr)
+    else:
+        render.write_verification(verification, stderr)
+        render.write_problem(problem, stderr, could_not_ask=could_not_ask)
+    return exit_codes.EXIT_COULD_NOT_ASK if could_not_ask else exit_codes.EXIT_REFUSED

sayfirst_cli/render.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: Apache-2.0
+"""How an answer reaches a person, and what this client is not allowed to add.
+
+Article 1: a client explains and invokes control semantics; it never derives an
+answer the control plane did not give. So every member of the envelope below is
+either something the control plane said, something the operating system said, or
+something this process did — and each is labelled as which. Nothing is computed
+from an answer and presented beside it as though it were part of it.
+
+Article 2: an absence is never rendered as a negative fact, a zero or a healthy
+state. Where the answer carries no policy version, no approval reference and no
+reason this generation knows, the rendering says so in words rather than leaving
+a blank the reader completes with a guess.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import TextIO
+
+#: What is written where the control plane said nothing. It is a sentence and
+#: not an empty string, because a blank field reads as a value (article 2).
+NOT_STATED = "not stated"
+
+
+def verification_document(
+    server_uid: int | None, expected_uid: int | None, verified: bool
+) -> dict[str, object]:
+    """What this process verified about the far end before it wrote a byte.
+
+    This is the one part of the envelope the control plane did not say: the
+    client read the server's peer credential and compared it (article 6). It is
+    kept in a member of its own so that no reader can mistake it for something
+    the daemon claimed about itself.
+    """
+    return {"server_uid": server_uid, "expected": expected_uid, "verified": verified}
+
+
+def envelope(
+    contract_generation: int,
+    verification: Mapping[str, object],
+    *,
+    result: Mapping[str, object] | None = None,
+    problem: Mapping[str, object] | None = None,
+) -> dict[str, object]:
+    """The machine-readable form: the answer, or the problem, and never both."""
+    document: dict[str, object] = {
+        "contract_generation": contract_generation,
+        "verification": dict(verification),
+    }
+    if result is not None:
+        document["result"] = dict(result)
+    if problem is not None:
+        document["problem"] = dict(problem)
+    return document
+
+
+def write_json(document: Mapping[str, object], stream: TextIO) -> None:
+    """The whole envelope, stable under sorting so a diff of two runs is readable."""
+    stream.write(json.dumps(document, indent=2, sort_keys=True))
+    stream.write("\n")
+
+
+def _stated(value: object) -> str:
+    """A member as a person reads it, with absence said rather than shown."""
+    return NOT_STATED if value is None else str(value)
+
+
+def write_decision(document: Mapping[str, object], stream: TextIO) -> None:
+    """A decision, in the words the control plane used for it.
+
+    The outcome is written as the control plane spelled it. This client holds no
+    table from `allow` to "approved" or from `deny` to "blocked": a second
+    vocabulary for the same three outcomes is a second control plane, without
+    the evidence (articles 1 and 4).
+    """
+    stream.write(f"outcome: {document['outcome']}\n")
+    stream.write(f"reason: {_stated(document.get('reason'))}\n")
+    stream.write(f"capability: {document['capability']} in scope {document['scope']}\n")
+    stream.write(f"decision: {document['decision_ref']} at {document['decided_at']}\n")
+    stream.write(f"policy version: {_stated(document.get('policy_version'))}\n")
+    if document.get("approval_ref") is not None:
+        stream.write(f"approval: {document['approval_ref']}\n")
+
+
+def write_verification(document: Mapping[str, object], stream: TextIO) -> None:
+    """What was verified about the far end, in the same words `whoami` uses."""
+    stream.write(
+        f"verified: {str(document['verified']).lower()} "
+        f"(server_uid {_stated(document['server_uid'])}, "
+        f"expected {_stated(document['expected'])})\n"
+    )
+
+
+def write_record(document: Mapping[str, object], stream: TextIO) -> None:
+    """Every supplied record member, with its reason and rule on their own lines."""
+    order = (
+        "decision_ref",
+        "scope",
+        "capability",
+        "outcome",
+        "reason",
+        "rule_id",
+        "policy_version",
+        "decided_at",
+        "correlation",
+        "grant_id",
+        "approval_ref",
+    )
+    for key in (*order, *sorted(document.keys() - set(order))):
+        if key in document:
+            stream.write(f"{key}: {_stated(document[key])}\n")
+
+
+def write_chain_position(position: Mapping[str, object], stream: TextIO) -> None:
+    """The position and grade the plane supplied, or the bound actually read."""
+    if position.get("found") is False:
+        stream.write(f"chain: not found within {position['pages']} page(s)\n")
+    else:
+        stream.write(
+            f"chain: sequence {position['sequence']}, entry_hash {position['entry_hash']}, "
+            f"grade {position['grade']}\n"
+        )
+
+
+def write_problem(document: Mapping[str, object], stream: TextIO, *, could_not_ask: bool) -> None:
+    """A refusal or an unanswerable question, each said as what it is.
+
+    Article 1: "could not ask" is never written as "denied" or as "allowed", and
+    article 2 adds that it is not a negative fact either. The line therefore
+    names which of the two happened before it names the code, because the code
+    alone does not tell a reader whether an answer exists somewhere.
+    """
+    kind = "could not ask" if could_not_ask else "refused"
+    stream.write(f"{kind}: {document['code']}: {document['message']}\n")
+    retryable = document.get("retryable")
+    stream.write(f"retryable: {NOT_STATED if retryable is None else str(retryable).lower()}\n")

sayfirst_cli/trace.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Read a decision and locate its first effect entry within a bounded evidence read."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Mapping, Sequence
+from typing import TextIO
+
+from sayfirst_contract.client import Answered, Result
+from sayfirst_contract.generation import CONTRACT_GENERATION
+
+from . import pages, reads, render
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="sayfirst trace", description="Read a decision and its position in scoped evidence."
+    )
+    reads.add_connection_arguments(parser)
+    parser.add_argument("--decision", required=True, help="the reference of the recorded decision")
+    parser.add_argument(
+        "--pages", type=reads.positive, default=10, help="the maximum number of evidence pages"
+    )
+    return parser
+
+
+def _write_trace(document: Mapping[str, object], stream: TextIO) -> None:
+    render.write_record({key: value for key, value in document.items() if key != "chain"}, stream)
+    render.write_chain_position(document["chain"], stream)
+
+
+def main(
+    argv: Sequence[str] | None = None, *, out: TextIO | None = None, err: TextIO | None = None
+) -> int:
+    stdout, stderr = out or sys.stdout, err or sys.stderr
+    arguments = build_parser().parse_args(argv)
+    connection = reads.open_connection(arguments, stderr)
+    if isinstance(connection, int):
+        return connection
+
+    def walk() -> Result[Mapping[str, object]]:
+        """The record, then the pages, then where in the chain the decision sits."""
+        result = connection.read_decision(arguments.scope, arguments.decision)
+        if not isinstance(result, Answered):
+            return result
+        record = result.value.to_document()
+        from_sequence, read_pages, position = 1, 0, None
+        for _ in range(arguments.pages):
+            # The daemon closes the connection after a decision read (an adapter
+            # wrote that answer), and an evidence read may close its own. The
+            # transport never re-opens an address on a caller's behalf (rule
+            # C4), so every page is read on a connection reopened — and the far
+            # end verified again — here, exactly as `history` walks its pages.
+            connection.reconnect()
+            page = connection.read_evidence(arguments.scope, from_sequence, 100)
+            if not isinstance(page, Answered):
+                return page
+            read_pages += 1
+            entries, verification, next_from = pages.members(page.value, from_sequence)
+            for entry in entries:
+                if entry["kind"] == "effect" and entry["body"]["decision_id"] == arguments.decision:
+                    grade = next(
+                        (
+                            item["grade"]
+                            for item in verification["grades"]
+                            if item["connection_id"] == entry["connection_id"]
+                        ),
+                        "unknown",
+                    )
+                    position = {
+                        "sequence": entry["sequence"],
+                        "entry_hash": entry["entry_hash"],
+                        "grade": grade,
+                    }
+                    break
+            if position is not None or next_from is None:
+                break
+            from_sequence = next_from
+        if position is None:
+            position = {"found": False, "pages": read_pages}
+        return Answered({**record, "chain": position}, CONTRACT_GENERATION)
+
+    try:
+        return reads.finish(reads.read(walk), arguments, connection, stdout, stderr, _write_trace)
+    finally:
+        connection.close()