lorebase-cli 0.2.3__py3-none-any.whl

lorebase_cli/commands/admin.py

@@ -0,0 +1,254 @@
+"""`apikey create|list|revoke`: API keys of a Domain; `admin erase`: erasure of personal data;
+`admin vault status|rotate`: vault key rotation."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import JsonValue
+
+from lorebase_cli.context import app_of
+from lorebase_cli.failures import CliError
+from lorebase_cli.options import AllOpt, DomainOpt, JsonOpt, LimitOpt
+from lorebase_cli.output import Column
+
+apikey_app = typer.Typer(help="Manage the API keys of a Domain.", no_args_is_help=True)
+admin_app = typer.Typer(help="Administer the personal data of a Domain.", no_args_is_help=True)
+vault_app = typer.Typer(
+    help="Rotate the vault keys (installation administrators).", no_args_is_help=True
+)
+admin_app.add_typer(vault_app, name="vault")
+
+KEY_COLUMNS = [
+    Column("id", "id"),
+    Column("prefix", "prefix"),
+    Column("principal", "principal_id"),
+    Column("expires", "expires_at"),
+    Column("last used", "last_used_at"),
+    Column("revoked", "revoked_at"),
+    Column("networks", "allowed_networks"),
+]
+
+
+@apikey_app.command("create")
+def apikey_create(
+    ctx: typer.Context,
+    name: Annotated[
+        str,
+        typer.Argument(help="Name of the service principal the key belongs to.", metavar="NAME"),
+    ],
+    domain: DomainOpt = None,
+    role: Annotated[
+        str | None,
+        typer.Option("--role", help="Role the principal gets in the Domain (server default)."),
+    ] = None,
+    ttl_days: Annotated[
+        int | None, typer.Option("--ttl-days", min=1, help="Lifetime in days (server default).")
+    ] = None,
+    principal_id: Annotated[
+        str | None,
+        typer.Option("--principal-id", help="Add a key to an existing service principal."),
+    ] = None,
+    allow_network: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--allow-network",
+            metavar="CIDR",
+            help="Client network the key may be used from, e.g. 203.0.113.0/24; repeatable. "
+            "Without it the key works from any address.",
+        ),
+    ] = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Create an API key. The secret is shown once; store it right away."""
+    app = app_of(ctx, json_out)
+    created = app.client().api_keys.create(
+        app.domain(domain),
+        name,
+        role=role,
+        ttl_days=ttl_days,
+        principal_id=principal_id,
+        allowed_networks=allow_network,
+    )
+
+    def human() -> None:
+        app.out.pairs(
+            [
+                ("key", created.key),
+                ("id", created.id),
+                ("principal", created.principal_id),
+                ("role", created.role),
+                ("expires", created.expires_at),
+                ("networks", ", ".join(created.allowed_networks) or "any"),
+            ]
+        )
+        app.out.info("This is the only time the key is shown: store it now.")
+
+    app.out.emit(created, human)
+
+
+@apikey_app.command("list")
+def apikey_list(
+    ctx: typer.Context,
+    domain: DomainOpt = None,
+    limit: LimitOpt = None,
+    everything: AllOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """List the API keys of a Domain, including revoked and expired ones."""
+    app = app_of(ctx, json_out)
+    items, more = app.take(app.client().api_keys.iterate(app.domain(domain)), limit, everything)
+    app.out.emit(items, lambda: app.out.table([k.model_dump() for k in items], KEY_COLUMNS))
+    if more:
+        app.note_truncated(len(items))
+
+
+@apikey_app.command("revoke")
+def apikey_revoke(
+    ctx: typer.Context,
+    key_id: Annotated[
+        str, typer.Argument(help="Id of the key (see `apikey list`).", metavar="KEY_ID")
+    ],
+    domain: DomainOpt = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Revoke an API key; it stops working at once."""
+    app = app_of(ctx, json_out)
+    app.client().api_keys.revoke(app.domain(domain), key_id)
+    app.out.emit({"revoked": key_id}, lambda: app.out.info(f"revoked key {key_id}"))
+
+
+@admin_app.command("erase")
+def admin_erase(
+    ctx: typer.Context,
+    kind: Annotated[str, typer.Argument(help="Kind api name.", metavar="KIND")],
+    key: Annotated[
+        str | None, typer.Option("--key", help="Erase the values of the Record with this key.")
+    ] = None,
+    attribute: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--attribute",
+            help="Vault Attribute (api name). With --key: limit to it (repeatable); with "
+            "--value: the Attribute whose value is erased in every Record.",
+        ),
+    ] = None,
+    value: Annotated[
+        str | None,
+        typer.Option(
+            "--value",
+            metavar="- | @FILE",
+            help="Where the value to erase is read from (JSON, or plain text when it is not "
+            "valid JSON): - for standard input (asked without echo on a terminal), @FILE for a "
+            "file. A value given on the command line is refused: it would stay in the shell "
+            "history and the process list.",
+        ),
+    ] = None,
+    branch: Annotated[
+        str | None, typer.Option("--branch", help="Branch whose schema names the Kind.")
+    ] = None,
+    domain: DomainOpt = None,
+    yes: Annotated[bool, typer.Option("--yes", "-y", help="Do not ask for confirmation.")] = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """Erase personal data from the vault, on every branch and Revision. This cannot be undone.
+
+    `--key K` erases what the Record ever held in its vault Attributes; `--attribute A --value
+    V` erases V of A in every Record of the Kind. History keeps its shape: reads show the
+    values as erased.
+    """
+    app = app_of(ctx, json_out)
+    if (key is None) == (value is None):
+        raise CliError("give --key, or --attribute and --value")
+    attributes = attribute or []
+    if value is not None and len(attributes) != 1:
+        raise CliError("erasure by --value takes exactly one --attribute")
+    text = None if value is None else _value_text(value)
+    target = f"{kind}/{key}" if key is not None else f"a value of {kind}.{attributes[0]}"
+    if not yes:
+        if not sys.stdin.isatty():
+            raise CliError("erasure is irreversible: pass --yes to confirm")
+        typer.confirm(f"Erase {target} from the vault for good?", abort=True)
+    vault = app.client().vault
+    if key is not None:
+        result = vault.erase_record(
+            app.domain(domain), kind, key, attributes=attributes or None, branch=branch
+        )
+    else:
+        result = vault.erase_value(
+            app.domain(domain),
+            kind,
+            attributes[0],
+            _parsed(text or ""),
+            branch=branch,
+        )
+    app.out.emit(result, lambda: app.out.info(f"erased {result.erased} vault value(s)"))
+
+
+def _value_text(source: str) -> str:
+    """The value read from standard input (`-`) or a file (`@FILE`)."""
+    if source == "-":
+        if sys.stdin.isatty():
+            return str(typer.prompt("Value to erase", hide_input=True))
+        return sys.stdin.read().rstrip("\n")
+    if source.startswith("@") and len(source) > 1:
+        try:
+            return Path(source[1:]).read_text(encoding="utf-8").rstrip("\n")
+        except OSError as error:
+            raise CliError(f"cannot read {source[1:]}: {error.strerror}") from None
+    raise CliError(
+        "give the value as --value - (standard input) or --value @FILE: a value on the "
+        "command line stays in the shell history and the process list"
+    )
+
+
+def _parsed(text: str) -> JsonValue:
+    try:
+        parsed: JsonValue = json.loads(text)
+    except ValueError:
+        return text
+    return parsed
+
+
+@vault_app.command("status")
+def vault_status(ctx: typer.Context, json_out: JsonOpt = False) -> None:
+    """Show which keys the vault rows use and which earlier keys can be removed."""
+    app = app_of(ctx, json_out)
+    keys = app.client().vault.keys()
+
+    def human() -> None:
+        app.out.pairs(
+            [
+                ("encryption key", keys.key_id),
+                ("token key", keys.token_key_id),
+                ("rows by encryption key", _counts(keys.encryption_keys)),
+                ("rows by fingerprint key", _counts(keys.fingerprint_keys)),
+                ("tombstones by fingerprint key", _counts(keys.tombstone_keys)),
+                ("rows to rotate", keys.outdated),
+                ("removable previous_keys", ", ".join(keys.removable_keys) or "none"),
+                (
+                    "removable previous_token_keys",
+                    ", ".join(keys.removable_token_keys) or "none",
+                ),
+                ("digest key", keys.digests),
+            ]
+        )
+
+    app.out.emit(keys, human)
+
+
+@vault_app.command("rotate")
+def vault_rotate(ctx: typer.Context, json_out: JsonOpt = False) -> None:
+    """Queue the job that seals and fingerprints the vault rows of every Domain again under the
+    current keys, in batches. Follow it with `admin vault status`."""
+    app = app_of(ctx, json_out)
+    queued = app.client().vault.rotate()
+    app.out.emit(queued, lambda: app.out.info(f"queued vault rotation job {queued.job_id}"))
+
+
+def _counts(counts: dict[str, int]) -> str:
+    return ", ".join(f"{key}: {count}" for key, count in counts.items()) or "none"

lorebase_cli/commands/agents.py

@@ -0,0 +1,244 @@
+"""`context`, `explain` and `health`: what an agent reads about Records, where their values came
+from, and how sound the data is."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+
+from lorebase_cli.commands.data import json_argument
+from lorebase_cli.context import app_of
+from lorebase_cli.failures import CliError
+from lorebase_cli.options import AtOpt, BranchOpt, DomainOpt, JsonOpt
+from lorebase_cli.output import Column, short_id
+from lorebase_client import models as m
+
+MarkdownOpt = Annotated[
+    bool, typer.Option("--markdown", help="Print the Markdown rendering instead of a summary.")
+]
+
+SEED_COLUMNS = [Column("record", "ref"), Column("title", "title"), Column("values", "values")]
+NEIGHBOR_COLUMNS = [
+    Column("record", "ref"),
+    Column("title", "title"),
+    Column("depth", "depth"),
+]
+ATTRIBUTE_COLUMNS = [
+    Column("attribute", "name"),
+    Column("value", "value"),
+    Column("actor", "actor"),
+    Column("origin", "origin_type"),
+    Column("revision", "revision", short_id),
+    Column("at", "at"),
+]
+
+
+def context_command(
+    ctx: typer.Context,
+    ref: Annotated[
+        list[str] | None,
+        typer.Option("--ref", help="Seed Record as KIND/KEY. Repeatable."),
+    ] = None,
+    search: Annotated[
+        str | None, typer.Option("--search", help="Seed Records found by this text.")
+    ] = None,
+    query: Annotated[
+        str | None,
+        typer.Option("--query", help="Seed Records of a DSL query: inline JSON, @file or -."),
+    ] = None,
+    budget: Annotated[
+        int | None, typer.Option("--budget", min=1, help="Token budget of the pack.")
+    ] = None,
+    depth: Annotated[
+        int | None, typer.Option("--depth", min=0, help="Hops to expand around the seeds.")
+    ] = None,
+    relation: Annotated[
+        list[str] | None,
+        typer.Option("--relation", help="Follow only this Relation. Repeatable."),
+    ] = None,
+    domain: DomainOpt = None,
+    branch: BranchOpt = None,
+    at: AtOpt = None,
+    markdown: MarkdownOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """Build a context pack: seed Records, their neighbors, schema and recent changes.
+
+    Name the seeds with exactly one of --ref, --search or --query.
+    """
+    app = app_of(ctx, json_out)
+    parsed = None if query is None else json_argument(query)
+    if parsed is not None and not isinstance(parsed, dict):
+        raise CliError("a query is a JSON object")
+    request = m.ContextRequest(
+        branch=app.branch(branch),
+        at=at,
+        refs=ref or None,
+        query=parsed,
+        search=search,
+        budget_tokens=budget,
+        depth=depth,
+        relations=relation or None,
+    )
+    agents = app.client().agents
+    name = app.domain(domain)
+    if markdown:
+        app.out.text(agents.context_markdown(name, request))
+        return
+    pack = agents.context(name, request)
+
+    def human() -> None:
+        used = pack.budget.get("used_tokens")
+        limit = pack.budget.get("limit_tokens")
+        app.out.pairs(
+            [
+                ("domain", pack.domain),
+                ("branch", pack.branch),
+                ("revision", short_id(pack.revision)),
+                ("seeds", len(pack.seeds)),
+                ("neighbors", len(pack.neighbors)),
+                ("tokens", f"{used}/{limit}"),
+            ]
+        )
+        app.out.table(pack.seeds, SEED_COLUMNS)
+        if pack.neighbors:
+            app.out.table(pack.neighbors, NEIGHBOR_COLUMNS)
+
+    app.out.emit(pack, human)
+
+
+def explain_command(
+    ctx: typer.Context,
+    kind: Annotated[str, typer.Argument(help="Kind api name.", metavar="KIND")],
+    key: Annotated[str, typer.Argument(help="Record key.", metavar="KEY")],
+    domain: DomainOpt = None,
+    branch: BranchOpt = None,
+    at: AtOpt = None,
+    markdown: MarkdownOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """Explain a Record: where each value and Link came from, and the Proposals behind it."""
+    app = app_of(ctx, json_out)
+    agents = app.client().agents
+    name = app.domain(domain)
+    chosen = app.branch(branch)
+    if markdown:
+        app.out.text(agents.explain_markdown(name, kind, key, branch=chosen, at=at))
+        return
+    found = agents.explain(name, kind, key, branch=chosen, at=at)
+
+    def human() -> None:
+        record = found.record
+        app.out.pairs(
+            [
+                ("record", record.get("ref")),
+                ("title", record.get("title")),
+                ("branch", found.branch),
+                ("revision", short_id(found.revision)),
+                ("created by", (found.created or {}).get("actor")),
+                ("links", len(found.links)),
+                ("changes", found.history.get("changes")),
+                ("proposals", [f"{p.get('id')} ({p.get('status')})" for p in found.proposals]),
+            ]
+        )
+        app.out.table(found.attributes, ATTRIBUTE_COLUMNS)
+
+    app.out.emit(found, human)
+
+
+KIND_HEALTH_COLUMNS = [
+    Column("kind", "kind"),
+    Column("records", "records"),
+    Column("invalid", "invalid"),
+    Column("duplicate groups", "duplicates"),
+    Column("derived", "derived"),
+    Column("last change", "last_change", short_id),
+]
+RELATION_HEALTH_COLUMNS = [
+    Column("relation", "relation"),
+    Column("from", "from_kind"),
+    Column("to", "to_kind"),
+    Column("links", "links"),
+    Column("orphans", "orphans"),
+    Column("gaps", "gaps"),
+]
+
+
+def _kind_rows(kinds: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        {
+            "kind": k["kind"],
+            "records": k["records"],
+            "invalid": k["violations"]["invalid_records"],
+            "duplicates": k["duplicates"]["total_groups"],
+            "derived": "stale" if (k.get("derived") or {}).get("stale") else "",
+            "last_change": (k.get("last_change") or {}).get("revision"),
+        }
+        for k in kinds
+    ]
+
+
+def _relation_rows(relations: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [
+        {
+            **r,
+            "orphans": r["orphan_links"]["count"],
+            "gaps": None if r.get("required_gaps") is None else r["required_gaps"]["missing"],
+        }
+        for r in relations
+    ]
+
+
+def health_command(
+    ctx: typer.Context,
+    kind: Annotated[
+        str | None,
+        typer.Argument(help="Report on this Kind only.", metavar="[KIND]"),
+    ] = None,
+    domain: DomainOpt = None,
+    branch: BranchOpt = None,
+    at: AtOpt = None,
+    markdown: MarkdownOpt = False,
+    json_out: JsonOpt = False,
+) -> None:
+    """Check the data: constraint violations, orphan Links, required-Link gaps, duplicates."""
+    app = app_of(ctx, json_out)
+    agents = app.client().agents
+    name = app.domain(domain)
+    chosen = app.branch(branch)
+    if markdown:
+        app.out.text(
+            agents.kind_health_markdown(name, kind, branch=chosen, at=at)
+            if kind
+            else agents.health_markdown(name, branch=chosen, at=at)
+        )
+        return
+    found = (
+        agents.kind_health(name, kind, branch=chosen, at=at)
+        if kind
+        else agents.health(name, branch=chosen, at=at)
+    )
+    kinds = [found.health] if isinstance(found, m.KindHealthReport) else found.kinds
+
+    def human() -> None:
+        summary = found.summary
+        app.out.pairs(
+            [
+                ("domain", found.domain),
+                ("branch", found.branch),
+                ("revision", short_id(found.revision)),
+                ("status", "ok" if summary.ok else "needs attention"),
+                ("records", summary.records),
+                ("invalid records", summary.invalid_records),
+                ("orphan links", summary.orphan_links),
+                ("required-link gaps", summary.required_relation_gaps),
+                ("duplicate groups", summary.duplicate_groups),
+                ("kinds with stale derived values", summary.stale_kinds),
+            ]
+        )
+        app.out.table(_kind_rows(kinds), KIND_HEALTH_COLUMNS)
+        if found.relations:
+            app.out.table(_relation_rows(found.relations), RELATION_HEALTH_COLUMNS)
+
+    app.out.emit(found, human)

lorebase_cli/commands/audit.py

@@ -0,0 +1,51 @@
+"""`audit verify`: check the hash chain of a Domain's audit log."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from lorebase_cli.context import app_of
+from lorebase_cli.failures import EXIT_INVALID
+from lorebase_cli.options import DomainOpt, JsonOpt
+
+audit_app = typer.Typer(help="Check the audit log of a Domain.", no_args_is_help=True)
+
+
+@audit_app.command("verify")
+def audit_verify(
+    ctx: typer.Context,
+    domain: DomainOpt = None,
+    after_seq: Annotated[
+        int | None,
+        typer.Option(
+            "--after-seq",
+            min=0,
+            help="Start after this entry, trusting it (the last seq of an earlier run).",
+        ),
+    ] = None,
+    json_out: JsonOpt = False,
+) -> None:
+    """Recompute the audit hash chain of a Domain and report the first broken entry.
+
+    Needs the audit.read permission (the admin role). Exits with 2 when an entry does not
+    verify.
+    """
+    app = app_of(ctx, json_out)
+    result = app.client().audit.verify(app.domain(domain), after_seq=after_seq)
+
+    def human() -> None:
+        if result.first_broken is None:
+            app.out.text(f"intact: {result.checked} entries verified")
+        else:
+            broken = result.first_broken
+            app.out.text(
+                f"broken at seq {broken.seq}: {broken.reason}; "
+                f"{result.checked} entries verified before it"
+            )
+        app.out.pairs([("domain", result.domain_id), ("last seq", result.last_seq)])
+
+    app.out.emit(result, human)
+    if not result.intact:
+        raise typer.Exit(EXIT_INVALID)