qso-graph-auth 0.1.0__py3-none-any.whl

qso_graph_auth/__init__.py

@@ -0,0 +1,3 @@
+"""QSO-Graph Auth — persona and credential management for MCP servers."""
+
+__version__ = "0.1.0"

qso_graph_auth/cli/__init__.py

@@ -0,0 +1,7 @@
+"""CLI package for qso-graph-auth."""
+
+from __future__ import annotations
+
+from .root import main
+
+__all__ = ["main"]

qso_graph_auth/cli/creds.py

@@ -0,0 +1,234 @@
+"""Credentials subcommands (OS keyring)."""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+from typing import Optional
+
+from qso_graph_auth.cli.provider import auth_type, list_supported
+from qso_graph_auth.credentials import (
+    SERVICE,
+    Credentials,
+    delete_creds,
+    get_creds,
+    set_creds,
+)
+from qso_graph_auth.identity.store import PersonaStore
+
+try:
+    import keyring
+except Exception:
+    keyring = None  # type: ignore[assignment]
+
+
+def _redacted(c: Credentials) -> dict[str, str]:
+    def mask(v: str) -> str:
+        return (v[:2] + "…") if len(v) > 4 else "•••"
+
+    out: dict[str, str] = {}
+    if c.username:
+        out["username"] = c.username
+    if c.password:
+        out["password"] = mask(c.password)
+    if c.api_key:
+        out["api_key"] = mask(c.api_key)
+    return out
+
+
+def cmd_set(args: argparse.Namespace) -> int:
+    if keyring is None:
+        print("Install keyring: pip install keyring")
+        return 2
+
+    prov = args.provider.lower()
+    a = auth_type(prov)
+
+    username: str | None = args.username
+    password: str | None = args.password
+    api_key: str | None = args.api_key
+
+    def _norm(s: str | None) -> str | None:
+        if s is None:
+            return None
+        s = s.strip()
+        return s if s else None
+
+    if a == "username_password":
+        username = _norm(username) or input(f"{prov} username/callsign: ").strip() or None
+        if password is None:
+            pw = getpass.getpass(f"{prov} password: ").strip()
+            password = pw or None
+        api_key = None
+    elif a == "api_key":
+        username = _norm(username) or input(f"{prov} username/callsign: ").strip() or None
+        api_key = _norm(api_key) or input(f"{prov} API key: ").strip() or None
+        password = None
+    else:
+        username = _norm(username) or input("Username (blank to skip): ").strip() or None
+        api_key = _norm(api_key) or input("API key (blank to skip): ").strip() or None
+        if password is None:
+            pw = getpass.getpass("Password (hidden, blank to skip): ").strip()
+            password = pw or None
+
+    creds = Credentials(
+        username=_norm(username), password=_norm(password), api_key=_norm(api_key)
+    )
+    set_creds(args.persona, prov, creds)
+    print(f"Saved credentials for {args.persona}:{prov} in {SERVICE}.")
+    return 0
+
+
+def cmd_get(args: argparse.Namespace) -> int:
+    if keyring is None:
+        print("Install keyring: pip install keyring")
+        return 2
+    c = get_creds(args.persona, args.provider)
+    if not c:
+        print("No credentials stored.")
+        return 1
+    if getattr(args, "raw", False):
+        print(c.to_json())
+    else:
+        print(json.dumps(_redacted(c), indent=2))
+    return 0
+
+
+def cmd_delete(args: argparse.Namespace) -> int:
+    if keyring is None:
+        print("Install keyring: pip install keyring")
+        return 2
+    ok = delete_creds(args.persona, args.provider)
+    print("Deleted." if ok else "Nothing to delete.")
+    return 0
+
+
+def cmd_reset(args: argparse.Namespace) -> int:
+    if not args.yes:
+        print("Refusing to reset without --yes (this deletes ALL personas and credentials)")
+        return 2
+    if keyring is None:
+        print("Install keyring: pip install keyring")
+        return 2
+
+    store = PersonaStore()
+    personas = store.list()
+    cred_count = 0
+
+    for p in personas:
+        for prov in list(p.providers.keys()):
+            if delete_creds(p.name, prov):
+                cred_count += 1
+
+    persona_count = 0
+    for p in personas:
+        store.remove(p.name)
+        persona_count += 1
+
+    print(f"Reset complete: {persona_count} persona(s), {cred_count} credential(s) deleted.")
+    return 0
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    if keyring is None:
+        print("Install keyring: pip install keyring")
+        return 2
+    print(
+        "Keyring entries are stored under service "
+        f"'{SERVICE}' with username 'persona:provider'.\n"
+        "Use your OS keychain UI to enumerate entries."
+    )
+    return 0
+
+
+def _has_required_fields(c: Optional[Credentials], a: str) -> bool:
+    a = a.lower()
+    if a == "username_password":
+        return bool(c and c.username and c.password)
+    if a == "api_key":
+        return bool(c and c.username and c.api_key)
+    return bool(c and (c.username or c.password or c.api_key))
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    store = PersonaStore()
+    personas = store.list()
+    if not personas:
+        print("(no personas) — create one with: qso-auth persona add --name NAME …")
+        return 0
+
+    target = (args.persona or "").lower() if hasattr(args, "persona") else ""
+    ok = missing = 0
+
+    for p in personas:
+        if not p.name or (target and p.name.lower() != target):
+            continue
+
+        for prov in list_supported():
+            if prov not in p.providers:
+                continue
+            a = auth_type(prov)
+            c = get_creds(p.name, prov)
+            if _has_required_fields(c, a):
+                print(f"  {p.name}:{prov} — stored ({a})")
+                ok += 1
+            else:
+                need = (
+                    "username+password"
+                    if a == "username_password"
+                    else (
+                        "username+api_key" if a == "api_key" else "some secret"
+                    )
+                )
+                print(
+                    f"  {p.name}:{prov} — missing {need} "
+                    f"(run: qso-auth creds set {p.name} {prov})"
+                )
+                missing += 1
+
+    print(f"\nSummary: stored={ok}, missing={missing}")
+    return 0
+
+
+def register_cli(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    p = subparsers.add_parser(
+        "creds",
+        help="Manage credentials in the OS keyring.",
+        description="Set/get/delete credentials per persona/provider.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+
+    sp: argparse._SubParsersAction[argparse.ArgumentParser] = p.add_subparsers(
+        dest="creds_cmd", required=True
+    )
+
+    s = sp.add_parser("set", help="Save credentials.")
+    s.add_argument("persona", help="Persona name")
+    s.add_argument("provider", help="Provider (eqsl, lotw, qrz, qrz_logbook, hamqth)")
+    s.add_argument("--username", default=None, help="Username/login")
+    s.add_argument("--password", default=None, help="Password (unsafe on CLI)")
+    s.add_argument("--api-key", default=None, help="API key/token")
+    s.set_defaults(func=cmd_set)
+
+    g = sp.add_parser("get", help="Show redacted credentials.")
+    g.add_argument("persona", help="Persona name")
+    g.add_argument("provider", help="Provider")
+    g.add_argument("--raw", action="store_true", help="Print raw JSON (Use with Caution)")
+    g.set_defaults(func=cmd_get)
+
+    d = sp.add_parser("delete", help="Delete stored credentials.")
+    d.add_argument("persona", help="Persona name")
+    d.add_argument("provider", help="Provider")
+    d.set_defaults(func=cmd_delete)
+
+    list_parser = sp.add_parser("list", help="Explain where entries live.")
+    list_parser.set_defaults(func=cmd_list)
+
+    r = sp.add_parser("reset", help="Delete ALL personas and credentials (factory reset).")
+    r.add_argument("--yes", action="store_true", help="Confirm destructive op")
+    r.set_defaults(func=cmd_reset)
+
+    doc = sp.add_parser("doctor", help="Check creds across personas/providers.")
+    doc.add_argument("--persona", default=None, help="Only check this persona")
+    doc.set_defaults(func=cmd_doctor)

qso_graph_auth/cli/persona.py

@@ -0,0 +1,204 @@
+"""Persona subcommands backed by PersonaStore (JSON index)."""
+
+from __future__ import annotations
+
+import argparse
+from datetime import date
+
+from qso_graph_auth.credentials import Credentials, set_creds
+from qso_graph_auth.identity.store import PersonaStore
+from qso_graph_auth.paths import config_dir
+
+
+def _validate_dates(
+    start: str | None, end: str | None,
+) -> tuple[date | None, date | None]:
+    if not start:
+        raise SystemExit("--start YYYY-MM-DD is required")
+    s = start.strip()
+    try:
+        ds = date.fromisoformat(s)
+    except Exception as exc:
+        raise SystemExit(f"invalid --start '{start}'") from exc
+    de: date | None = None
+    if end:
+        e = end.strip()
+        try:
+            de = date.fromisoformat(e)
+        except Exception as exc:
+            raise SystemExit(f"invalid --end '{end}'") from exc
+        if de < ds:
+            raise SystemExit("end date must be >= start date")
+    return ds, de
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    store = PersonaStore()
+    personas = store.list()
+    if not personas:
+        print("(no personas) — create with: qso-auth persona add --name NAME …")
+        return 0
+
+    verbose = bool(getattr(args, "verbose", False))
+    for p in personas:
+        providers = ", ".join(sorted(p.providers.keys())) or "(none)"
+        if verbose:
+            print(
+                f"{p.name:15s}  {p.callsign:10s}  "
+                f"{p.active_span():23s}  providers: {providers}"
+            )
+        else:
+            print(f"{p.name:15s}  providers: {providers}")
+    return 0
+
+
+def cmd_add(args: argparse.Namespace) -> int:
+    name = args.name.strip().lower()
+    if not name:
+        print("persona --name is required")
+        return 1
+
+    callsign = (args.callsign or "").strip().upper()
+    if not callsign:
+        raise SystemExit("callsign is required")
+
+    ds, de = _validate_dates(args.start, args.end)
+
+    store = PersonaStore()
+    existing = store.get(name)
+    if existing and not args.force:
+        print(f"Persona {name} already exists. Use --force to overwrite.")
+        return 1
+
+    store.upsert(name=name, callsign=callsign, start=ds, end=de)
+
+    providers = [str(p).lower() for p in (args.providers or [])]
+    for prov in providers:
+        store.set_provider_ref(persona=name, provider=prov, username="")
+
+    print(f"Created persona {name}")
+    return 0
+
+
+def cmd_remove(args: argparse.Namespace) -> int:
+    store = PersonaStore()
+    if not store.remove(args.name):
+        print(f"No persona {args.name}")
+        return 1
+    print(f"Removed persona {args.name}")
+    return 0
+
+
+def cmd_remove_all(args: argparse.Namespace) -> int:
+    if not args.yes:
+        print("Refusing to remove all personas without --yes")
+        return 2
+    store = PersonaStore()
+    personas = store.list()
+    if not personas:
+        print("(no personas)")
+        return 0
+    count = 0
+    for p in personas:
+        store.remove(p.name)
+        count += 1
+    print(f"Removed {count} persona(s)")
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    store = PersonaStore()
+    p = store.get(args.name)
+    if not p:
+        print(f"No persona {args.name} found.")
+        return 1
+    print(f"name:      {p.name}")
+    print(f"callsign:  {p.callsign}")
+    print(f"start:     {p.start.isoformat() if p.start else '—'}")
+    print(f"end:       {p.end.isoformat() if p.end else '—'}")
+    if p.providers:
+        print(f"providers: {', '.join(sorted(p.providers.keys()))}")
+    else:
+        print("providers: (none)")
+    return 0
+
+
+def cmd_set_active(args: argparse.Namespace) -> int:
+    cfg = config_dir()
+    marker = cfg / "current.txt"
+    marker.write_text(args.name, encoding="utf-8")
+    print(f"Set active persona to {args.name}")
+    return 0
+
+
+def cmd_set_credential(args: argparse.Namespace) -> int:
+    name = args.persona
+    provider = args.provider.lower()
+
+    def _norm(s: str | None) -> str | None:
+        if s is None:
+            return None
+        s = s.strip()
+        return s if s else None
+
+    creds = Credentials(
+        username=_norm(args.username),
+        password=_norm(args.password),
+        api_key=_norm(args.api_key),
+    )
+    set_creds(name, provider, creds)
+    print(f"Saved credentials for {name}:{provider}.")
+    return 0
+
+
+def register_cli(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    p = subparsers.add_parser(
+        "persona",
+        help="Manage personas",
+        description="Manage persona profiles with callsign date ranges.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp = p.add_subparsers(dest="persona_cmd", required=True)
+
+    s_list = sp.add_parser("list", help="List personas")
+    s_list.add_argument("--verbose", action="store_true", help="Show callsign and date range")
+    s_list.set_defaults(func=cmd_list)
+
+    s_add = sp.add_parser("add", help="Add a new persona")
+    s_add.add_argument("--name", required=True, help="Persona name")
+    s_add.add_argument("--callsign", required=True, help="Primary callsign")
+    s_add.add_argument("--start", required=True, help="Start date YYYY-MM-DD (inclusive)")
+    s_add.add_argument("--end", help="End date YYYY-MM-DD (inclusive)")
+    s_add.add_argument("--providers", nargs="*", help="Initial providers (e.g. eqsl lotw qrz)")
+    s_add.add_argument("--force", action="store_true", help="Overwrite if exists")
+    s_add.set_defaults(func=cmd_add)
+
+    s_rm = sp.add_parser("remove", help="Remove a persona")
+    s_rm.add_argument("name", help="Persona name")
+    s_rm.set_defaults(func=cmd_remove)
+
+    s_rmall = sp.add_parser("remove-all", help="Remove ALL personas")
+    s_rmall.add_argument("--yes", action="store_true", help="Confirm destructive op")
+    s_rmall.set_defaults(func=cmd_remove_all)
+
+    s_show = sp.add_parser("show", help="Show persona config")
+    s_show.add_argument("name", help="Persona name")
+    s_show.set_defaults(func=cmd_show)
+
+    s_set = sp.add_parser("set-active", help="Mark persona as active")
+    s_set.add_argument("name", help="Persona name")
+    s_set.set_defaults(func=cmd_set_active)
+
+    s_sc = sp.add_parser("set-credential", help="Set credentials for a persona/provider")
+    s_sc.add_argument("--persona", required=True, help="Persona name")
+    s_sc.add_argument(
+        "--provider", required=True,
+        choices=["eqsl", "lotw", "qrz", "qrz_logbook", "hamqth"],
+        help="Provider slug",
+    )
+    s_sc.add_argument("--username", help="Username/callsign", default=None)
+    s_sc.add_argument("--password", help="Password", default=None)
+    s_sc.add_argument("--api-key", help="API key/token", default=None)
+    s_sc.set_defaults(func=cmd_set_credential)

qso_graph_auth/cli/provider.py

@@ -0,0 +1,159 @@
+"""Provider subcommands and metadata access (dynamic discovery)."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from functools import cache
+from importlib.resources import files
+from pathlib import Path
+from typing import Any, Dict, List, cast
+
+from qso_graph_auth.credentials import get_creds
+from qso_graph_auth.identity.store import PersonaStore
+
+# ---------- Provider metadata (resources/providers/*.json) ----------
+
+PROVIDERS_DIR: Path = Path(files("qso_graph_auth.resources") / "providers")  # type: ignore[arg-type]
+
+
+def _provider_path(slug: str) -> Path:
+    return Path(PROVIDERS_DIR) / f"{slug}.json"
+
+
+def list_supported() -> List[str]:
+    p = Path(PROVIDERS_DIR)
+    if not p.exists():
+        return []
+    return sorted(f.stem for f in p.glob("*.json"))
+
+
+@cache
+def get_provider(slug: str) -> Dict[str, Any]:
+    path = _provider_path(slug)
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+            return cast(Dict[str, Any], data or {})
+    except FileNotFoundError:
+        return {"name": slug, "slug": slug, "auth": "none"}
+    except json.JSONDecodeError:
+        return {"name": slug, "slug": slug, "auth": "none"}
+
+
+def auth_type(slug: str) -> str:
+    meta = get_provider(slug)
+    return str(meta.get("auth", "none")).lower()
+
+
+def _require_supported(provider: str) -> str:
+    p = provider.lower()
+    supported = set(list_supported())
+    if p not in supported:
+        raise SystemExit(
+            f"Unknown provider '{provider}'. Supported: {', '.join(sorted(supported))}"
+        )
+    return p
+
+
+def cmd_list(args: argparse.Namespace) -> int:
+    providers = list_supported()
+    print("Supported providers: " + ", ".join(providers or ["(none found)"]))
+
+    store = PersonaStore()
+    personas = store.list()
+    if not personas:
+        print("(no personas discovered)")
+        return 0
+
+    print("\nEnabled per persona:")
+    for p in personas:
+        enabled = [k for k in sorted(p.providers.keys()) if k in providers]
+        print(f"  {p.name:15s} -> {', '.join(enabled) or '(none)'}")
+    return 0
+
+
+def cmd_enable(args: argparse.Namespace) -> int:
+    persona = args.persona
+    provider = _require_supported(args.provider)
+
+    store = PersonaStore()
+    p = store.get(persona)
+    if not p:
+        print(f"Persona '{persona}' not found")
+        return 1
+
+    if provider in p.providers:
+        print(f"{provider} already enabled for {persona}")
+    else:
+        store.set_provider_ref(persona=persona, provider=provider, username="")
+        print(f"Enabled {provider} for {persona}")
+
+    c = get_creds(persona, provider)
+    a = auth_type(provider)
+    need = (
+        "username+password"
+        if a == "username_password"
+        else ("username+api_key" if a == "api_key" else "some secret")
+    )
+    missing = (
+        not c
+        or (a == "username_password" and not (c.username and c.password))
+        or (a == "api_key" and not (c.username and c.api_key))
+    )
+    if missing:
+        print(
+            f"note: no credentials for {persona}:{provider} ({a}). "
+            f"Run: qso-auth creds set {persona} {provider}  # need {need}"
+        )
+    return 0
+
+
+def cmd_disable(args: argparse.Namespace) -> int:
+    persona = args.persona
+    provider = _require_supported(args.provider)
+
+    store = PersonaStore()
+    p = store.get(persona)
+    if not p:
+        print(f"Persona '{persona}' not found")
+        return 1
+
+    try:
+        removed = store.remove_provider_ref(persona=persona, provider=provider)
+    except KeyError:
+        print(f"Persona '{persona}' not found")
+        return 1
+
+    if not removed:
+        print(f"{provider} already disabled for {persona}")
+    else:
+        print(f"Disabled {provider} for {persona}")
+    return 0
+
+
+def register_cli(
+    subparsers: argparse._SubParsersAction[argparse.ArgumentParser],
+) -> None:
+    p = subparsers.add_parser(
+        "provider",
+        help="Provider operations",
+        description="Enable/disable providers on persona profiles.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    sp: argparse._SubParsersAction[argparse.ArgumentParser] = p.add_subparsers(
+        dest="provider_cmd", required=True
+    )
+
+    s_list = sp.add_parser("list", help="List supported and enabled providers.")
+    s_list.set_defaults(func=cmd_list)
+
+    s_en = sp.add_parser("enable", help="Enable a provider for a persona.")
+    s_en.add_argument("persona", help="Persona name")
+    s_en.add_argument("provider", help="Provider to enable")
+    s_en.set_defaults(func=cmd_enable)
+
+    s_dis = sp.add_parser("disable", help="Disable a provider for a persona.")
+    s_dis.add_argument("persona", help="Persona name")
+    s_dis.add_argument("provider", help="Provider to disable")
+    s_dis.set_defaults(func=cmd_disable)

qso_graph_auth/cli/root.py

@@ -0,0 +1,52 @@
+"""Root CLI wiring for qso-auth."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Callable, Protocol, cast
+
+from . import creds, persona, provider
+
+
+class _RegisterCLI(Protocol):
+    def __call__(self, sp: argparse._SubParsersAction[argparse.ArgumentParser]) -> None: ...
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="qso-auth",
+        description="Persona and credential management for qso-graph MCP servers",
+    )
+    parser.add_argument(
+        "--version", action="version",
+        version=f"%(prog)s {__import__('qso_graph_auth').__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    if hasattr(persona, "register_cli"):
+        cast(_RegisterCLI, getattr(persona, "register_cli"))(subparsers)
+    if hasattr(provider, "register_cli"):
+        cast(_RegisterCLI, getattr(provider, "register_cli"))(subparsers)
+    if hasattr(creds, "register_cli"):
+        cast(_RegisterCLI, getattr(creds, "register_cli"))(subparsers)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_in = sys.argv[1:] if argv is None else argv
+    parser = build_parser()
+
+    if not args_in:
+        parser.print_help()
+        return 0
+
+    args = parser.parse_args(args_in)
+    func = cast(Callable[[argparse.Namespace], int] | None, getattr(args, "func", None))
+    if func is not None:
+        return func(args)
+
+    parser.print_help()
+    return 2

qso_graph_auth/credentials/__init__.py

@@ -0,0 +1,19 @@
+"""Credentials package for qso-graph-auth."""
+
+from .credentials import (
+    SERVICE,
+    Credentials,
+    delete_creds,
+    ensure_keyring,
+    get_creds,
+    set_creds,
+)
+
+__all__ = [
+    "SERVICE",
+    "Credentials",
+    "delete_creds",
+    "ensure_keyring",
+    "get_creds",
+    "set_creds",
+]