taktcli 0.6.2__tar.gz → 0.7.0__tar.gz

{taktcli-0.6.2 → taktcli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taktcli
-Version: 0.6.2
+Version: 0.7.0
 Summary: Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core
 Author: Takt
 License: MIT
@@ -43,8 +43,8 @@ the supported replacement for the retired `tools/wait_for_task.py`.
 ## Quickstart
 
 ```bash
-taktcli login                          # device-auth, stores ~/.takt/credentials.json
-taktcli whoami                         # nickname + claims + active credential source
+taktcli login                          # browser approval, stores a self-refreshing profile
+taktcli whoami                         # subject, owner, workspace, expiry, credential source
 taktcli board --project takt           # show the board
 taktcli claim takt-42                  # READY → RUNNING, prints leaseId
 taktcli run takt-42                    # heartbeat the lease
@@ -58,33 +58,50 @@ lists a group's verbs.
 
 Token resolution, simplest-wins:
 
-1. **`TAKT_TOKEN` env** → used verbatim. This is what harness containers are
-   stuffed with; env always wins over any stored credential.
-2. Else **`~/.takt/credentials.json`** — plain JSON `{ "token": "<jwt>", "url": "..." }`,
-   mode `0600`, written by `taktcli login`.
+1. **`TAKT_TOKEN` env** → used verbatim and never refreshed. This is what harness
+   containers are stuffed with; env always wins over any stored credential.
+2. Else the selected **profile** in `~/.takt/credentials.json`, written by
+   `taktcli login`. The profile is `--profile NAME` → `TAKT_PROFILE` → the
+   store's current profile → `default`.
 3. Else error: `No Takt credentials found. Run: taktcli login` (exit `3`).
 
-URL resolution mirrors it: `TAKT_URL` env → `url` in the credentials file →
-default `https://api.takt.sh/graphql`. The `watch` WS endpoint is derived by
-swapping the scheme (`https → wss`).
+URL resolution mirrors it: `TAKT_URL` env → the profile's URL → default
+`https://api.takt.sh/graphql`. The `watch` WS endpoint is derived by swapping the
+scheme (`https → wss`).
 
-`taktcli login` runs the OAuth 2.0 **device-authorization grant**: it prints a
-verification URL + user code, polls until you approve in a browser, then persists
-the token. `logout` removes the stored credential; `whoami` prints who you are
-and which credential source is active.
+`taktcli login` runs the OAuth 2.0 **device grant** (RFC 8628). It prints
+`Open <url> and enter <code>` to stderr, opens that page in your browser with the
+code filled in (unless `--no-browser`, or there is no display), and waits for you
+to approve. `--as <agent>` preselects an agent you own on the approval page, so
+the CLI acts as that agent while you stay its owner.
 
 ```bash
-taktcli login                                       # default endpoint
-taktcli login --url http://localhost:8454/graphql   # override the endpoint
-taktcli logout
-taktcli whoami
+taktcli login                                       # you, profile "default"
+taktcli login --as claude-code --profile claude-code
+taktcli login --no-browser                          # headless: just print the URL + code
+taktcli login --url http://localhost:8454/graphql   # another server
+taktcli whoami                                      # subject, owner, client, workspace, expiry, source
+taktcli profile list                                # stored profiles (no secrets)
+taktcli profile use claude-code
+taktcli logout                                      # revoke the grant, then delete the profile
 ```
 
-Auth is the same JWT + claims used by MCP and GraphQL — `taktcli` adds **no**
-privilege surface. There is no claims/permission verb anywhere; admin ops are
-reachable via `gql` only if the caller's token already holds the `admin` claim.
-Long-lived bot tokens stay minted out-of-band (`tools/jwt_cli.py`) and dropped
-into `TAKT_TOKEN`; `login` is for humans and dev machines.
+The stored grant refreshes itself: an access token lasts an hour and is renewed
+60 seconds before it expires (or once after the server rejects it), and the grant
+lives as long as it is used at least once every 90 days. Refreshes take a lock on
+`~/.takt/credentials.lock`, so parallel `taktcli` and `watch` processes share one
+rotation. `logout` revokes the grant on the server before deleting it locally;
+`logout --force` deletes even when the server can't be reached.
+
+The file is mode `0600` in a `0700` directory and is replaced atomically;
+taktcli refuses to read it through a symlink or with group/world permissions. A
+`{ "token", "url" }` file from taktcli ≤ 0.6 keeps working until your next
+`login` rewrites it.
+
+`taktcli` adds **no** privilege surface: the token never exceeds what the
+approving human can grant, there is no claims/permission verb anywhere, and admin
+ops are reachable via `gql` only if the token already holds the `admin` claim.
+Bots and harness images keep using `TAKT_TOKEN`.
 
 ## Passthrough — reaches 100% of GraphQL
 

{taktcli-0.6.2 → taktcli-0.7.0}/README.md

@@ -27,8 +27,8 @@ the supported replacement for the retired `tools/wait_for_task.py`.
 ## Quickstart
 
 ```bash
-taktcli login                          # device-auth, stores ~/.takt/credentials.json
-taktcli whoami                         # nickname + claims + active credential source
+taktcli login                          # browser approval, stores a self-refreshing profile
+taktcli whoami                         # subject, owner, workspace, expiry, credential source
 taktcli board --project takt           # show the board
 taktcli claim takt-42                  # READY → RUNNING, prints leaseId
 taktcli run takt-42                    # heartbeat the lease
@@ -42,33 +42,50 @@ lists a group's verbs.
 
 Token resolution, simplest-wins:
 
-1. **`TAKT_TOKEN` env** → used verbatim. This is what harness containers are
-   stuffed with; env always wins over any stored credential.
-2. Else **`~/.takt/credentials.json`** — plain JSON `{ "token": "<jwt>", "url": "..." }`,
-   mode `0600`, written by `taktcli login`.
+1. **`TAKT_TOKEN` env** → used verbatim and never refreshed. This is what harness
+   containers are stuffed with; env always wins over any stored credential.
+2. Else the selected **profile** in `~/.takt/credentials.json`, written by
+   `taktcli login`. The profile is `--profile NAME` → `TAKT_PROFILE` → the
+   store's current profile → `default`.
 3. Else error: `No Takt credentials found. Run: taktcli login` (exit `3`).
 
-URL resolution mirrors it: `TAKT_URL` env → `url` in the credentials file →
-default `https://api.takt.sh/graphql`. The `watch` WS endpoint is derived by
-swapping the scheme (`https → wss`).
+URL resolution mirrors it: `TAKT_URL` env → the profile's URL → default
+`https://api.takt.sh/graphql`. The `watch` WS endpoint is derived by swapping the
+scheme (`https → wss`).
 
-`taktcli login` runs the OAuth 2.0 **device-authorization grant**: it prints a
-verification URL + user code, polls until you approve in a browser, then persists
-the token. `logout` removes the stored credential; `whoami` prints who you are
-and which credential source is active.
+`taktcli login` runs the OAuth 2.0 **device grant** (RFC 8628). It prints
+`Open <url> and enter <code>` to stderr, opens that page in your browser with the
+code filled in (unless `--no-browser`, or there is no display), and waits for you
+to approve. `--as <agent>` preselects an agent you own on the approval page, so
+the CLI acts as that agent while you stay its owner.
 
 ```bash
-taktcli login                                       # default endpoint
-taktcli login --url http://localhost:8454/graphql   # override the endpoint
-taktcli logout
-taktcli whoami
+taktcli login                                       # you, profile "default"
+taktcli login --as claude-code --profile claude-code
+taktcli login --no-browser                          # headless: just print the URL + code
+taktcli login --url http://localhost:8454/graphql   # another server
+taktcli whoami                                      # subject, owner, client, workspace, expiry, source
+taktcli profile list                                # stored profiles (no secrets)
+taktcli profile use claude-code
+taktcli logout                                      # revoke the grant, then delete the profile
 ```
 
-Auth is the same JWT + claims used by MCP and GraphQL — `taktcli` adds **no**
-privilege surface. There is no claims/permission verb anywhere; admin ops are
-reachable via `gql` only if the caller's token already holds the `admin` claim.
-Long-lived bot tokens stay minted out-of-band (`tools/jwt_cli.py`) and dropped
-into `TAKT_TOKEN`; `login` is for humans and dev machines.
+The stored grant refreshes itself: an access token lasts an hour and is renewed
+60 seconds before it expires (or once after the server rejects it), and the grant
+lives as long as it is used at least once every 90 days. Refreshes take a lock on
+`~/.takt/credentials.lock`, so parallel `taktcli` and `watch` processes share one
+rotation. `logout` revokes the grant on the server before deleting it locally;
+`logout --force` deletes even when the server can't be reached.
+
+The file is mode `0600` in a `0700` directory and is replaced atomically;
+taktcli refuses to read it through a symlink or with group/world permissions. A
+`{ "token", "url" }` file from taktcli ≤ 0.6 keeps working until your next
+`login` rewrites it.
+
+`taktcli` adds **no** privilege surface: the token never exceeds what the
+approving human can grant, there is no claims/permission verb anywhere, and admin
+ops are reachable via `gql` only if the token already holds the `admin` claim.
+Bots and harness images keep using `TAKT_TOKEN`.
 
 ## Passthrough — reaches 100% of GraphQL
 

{taktcli-0.6.2 → taktcli-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taktcli"
-version = "0.6.2"
+version = "0.7.0"
 description = "Authorized GraphQL CLI for Takt — full GraphQL surface from the shell, stdlib-only core"
 readme = "README.md"
 requires-python = ">=3.12"

{taktcli-0.6.2 → taktcli-0.7.0}/taktcli/__main__.py

@@ -8,7 +8,7 @@ default 2 (which the contract reserves for transport failures).
 import argparse
 import sys
 
-from . import __version__, commands
+from . import __version__, auth, commands
 from .errors import TaktCliError
 
 DOCS_HINT = (
@@ -34,6 +34,12 @@ def build_parser() -> TaktArgumentParser:
         epilog=DOCS_HINT,
     )
     parser.add_argument("--version", action="version", version=f"taktcli {__version__}")
+    parser.add_argument(
+        "--profile",
+        metavar="NAME",
+        default=None,
+        help="credential profile from ~/.takt/credentials.json (default: TAKT_PROFILE, else the current one)",
+    )
     subparsers = parser.add_subparsers(dest="command", metavar="<command>", required=True)
     commands.register(subparsers)
     help_parser = subparsers.add_parser("help", help="show this help message and exit")
@@ -49,6 +55,7 @@ def main(argv=None) -> int:
     if handler is None:
         parser.print_help(sys.stderr)
         return 3
+    auth.set_profile_override(getattr(args, "profile", None))
     try:
         result = handler(args)
     except TaktCliError as exc:

taktcli-0.7.0/taktcli/auth.py

@@ -0,0 +1,188 @@
+"""Credential + URL resolution and silent refresh (PRD 002 §6, PRD-004 §9, [[takt-468]]).
+
+Token:   ``TAKT_TOKEN`` env (verbatim, never refreshed)  ->  the selected profile  ->  exit 3
+Profile: ``--profile``  ->  ``TAKT_PROFILE``  ->  the store's ``current_profile``  ->  ``default``
+URL:     ``TAKT_URL`` env  ->  the profile's ``url``  ->  default
+
+An explicit token never changes which URL is chosen. A profile that carries a refresh token is
+refreshed 60s before its expiry and once more after a rejected request, under a cross-process
+lock with a re-read: when another process already rotated, its tokens are used as they are.
+"""
+
+import os
+from dataclasses import dataclass
+
+from . import oauth
+from .credentials import DEFAULT_PROFILE, CredentialStore, expires_at_from, expiring
+from .errors import ConfigError
+
+DEFAULT_URL = "https://api.takt.sh/graphql"
+LOGIN_HINT = "No Takt credentials found. Run: taktcli login"
+REFRESH_LEEWAY_SECONDS = 60
+
+_profile_override: str | None = None
+_resolved_profiles: dict[str, str] = {}
+
+
+def set_profile_override(name: str | None) -> None:
+    """Pin the profile for this process (the ``--profile`` flag); ``None`` clears it."""
+    global _profile_override
+    _profile_override = name or None
+
+
+def profile_name(payload: dict | None = None) -> str:
+    """The selected profile: ``--profile`` -> ``TAKT_PROFILE`` -> current -> ``default``."""
+    explicit = _profile_override or os.environ.get("TAKT_PROFILE")
+    if explicit:
+        return explicit
+    if payload is not None and payload.get("current_profile"):
+        return payload["current_profile"]
+    return DEFAULT_PROFILE
+
+
+def _profile_explicit() -> bool:
+    return bool(_profile_override or os.environ.get("TAKT_PROFILE"))
+
+
+@dataclass
+class Credential:
+    """The credential a command will use, and where it came from."""
+
+    url: str
+    token: str
+    source: str
+    profile_name: str | None = None
+    profile: dict | None = None
+
+    @property
+    def refreshable(self) -> bool:
+        return bool(self.profile and self.profile.get("refresh_token") and self.profile.get("origin"))
+
+
+def _check_origin(url: str, name: str, profile: dict) -> None:
+    """Refuse to send an OAuth profile's tokens to a ``TAKT_URL`` on another origin."""
+    origin = profile.get("origin")
+    if origin and oauth.origin_from_url(url) != origin.rstrip("/"):
+        raise ConfigError(
+            f"Profile {name!r} was issued by {origin}, but TAKT_URL points at {url}. "
+            f"Unset TAKT_URL, pick another profile with --profile, or run: taktcli login --profile {name} --url {url}"
+        )
+
+
+def select(store: CredentialStore | None = None) -> Credential:
+    """Resolve the active credential without refreshing it."""
+    env_url = os.environ.get("TAKT_URL")
+    env_token = os.environ.get("TAKT_TOKEN")
+    if env_token:
+        if env_url:
+            return Credential(env_url, env_token, "TAKT_TOKEN env")
+        store = store or CredentialStore()
+        payload = store.read(strict=False)
+        profile = payload["profiles"].get(profile_name(payload)) or {}
+        return Credential(profile.get("url") or DEFAULT_URL, env_token, "TAKT_TOKEN env")
+    store = store or CredentialStore()
+    payload = store.read()
+    name = profile_name(payload)
+    profile = payload["profiles"].get(name)
+    if not profile or not profile.get("access_token"):
+        if payload["profiles"] and (_profile_explicit() or name not in payload["profiles"]):
+            raise ConfigError(f"No Takt credentials for profile {name!r}. Run: taktcli login --profile {name}")
+        raise ConfigError(LOGIN_HINT)
+    url = env_url or profile.get("url") or DEFAULT_URL
+    if env_url:
+        _check_origin(env_url, name, profile)
+    return Credential(url, profile["access_token"], f"profile {name!r} ({store.path})", name, profile)
+
+
+def refresh_profile(name: str, expected_token: str, *, store: CredentialStore | None = None, opener=None) -> dict:
+    """Rotate profile ``name``'s tokens under the cross-process lock; return the fresh profile.
+
+    Inside the lock the store is re-read: if another process already replaced
+    ``expected_token`` with a still-valid one, that is returned untouched. An ``invalid_grant``
+    (a replayed or revoked refresh token, PRD-004 D10) re-reads the store once more before
+    giving up with "run taktcli login" (exit 3).
+    """
+    store = store or CredentialStore()
+    with store.lock():
+        profile = store.read()["profiles"].get(name)
+        if not profile or not profile.get("access_token"):
+            raise ConfigError(f"Profile {name!r} was logged out. Run: taktcli login --profile {name}")
+        if profile["access_token"] != expected_token and not expiring(profile, REFRESH_LEEWAY_SECONDS):
+            return profile
+        if not profile.get("refresh_token") or not profile.get("origin"):
+            raise ConfigError(f"Profile {name!r} cannot be refreshed. Run: taktcli login --profile {name}")
+        try:
+            body = oauth.refresh(
+                profile["origin"], profile["refresh_token"], profile.get("client_id") or oauth.CLIENT_ID, opener=opener
+            )
+        except oauth.OAuthError as exc:
+            if exc.error == "invalid_grant":
+                current = store.read()["profiles"].get(name) or {}
+                if current.get("refresh_token") not in (None, profile["refresh_token"]) and not expiring(current, 0):
+                    return current
+                raise ConfigError(
+                    f"The session for profile {name!r} expired or was revoked. Run: taktcli login --profile {name}"
+                ) from exc
+            raise ConfigError(f"Token refresh failed: {exc}") from exc
+        fresh = apply_token_response(profile, body)
+        store.save_profile(name, fresh, make_current=False)
+        return fresh
+
+
+def apply_token_response(profile: dict, body: dict) -> dict:
+    """``profile`` updated from an RFC 6749 §5.1 token response (rotated refresh token included)."""
+    try:
+        access_token = body["access_token"]
+    except KeyError as exc:
+        raise ConfigError("The token endpoint returned no access_token") from exc
+    fresh = dict(profile)
+    fresh["access_token"] = access_token
+    fresh["refresh_token"] = body.get("refresh_token") or profile.get("refresh_token")
+    fresh["expires_at"] = expires_at_from(body.get("expires_in"))
+    if body.get("scope") is not None:
+        fresh["scope"] = body["scope"]
+    return fresh
+
+
+def resolve_credential(store: CredentialStore | None = None, opener=None) -> Credential:
+    """The active credential, refreshed first when it expires within 60s."""
+    store = store or CredentialStore()
+    cred = select(store)
+    if cred.refreshable and expiring(cred.profile, REFRESH_LEEWAY_SECONDS):
+        fresh = refresh_profile(cred.profile_name, cred.token, store=store, opener=opener)
+        cred = Credential(cred.url, fresh["access_token"], cred.source, cred.profile_name, fresh)
+    if cred.profile_name is not None:
+        _resolved_profiles[cred.token] = cred.profile_name
+    return cred
+
+
+def resolve_auth() -> tuple[str, str]:
+    """``(url, token)`` for a GraphQL call, refreshing a stored OAuth profile when due."""
+    cred = resolve_credential()
+    return cred.url, cred.token
+
+
+def reauthorize(rejected_token: str, *, store: CredentialStore | None = None, opener=None) -> str | None:
+    """A replacement for ``rejected_token`` after the server refused it, or ``None``.
+
+    Only a token this process resolved from a stored profile is replaced, and only from that
+    same profile, so a retry can never switch identity (``TAKT_TOKEN`` and anything not
+    resolved here get ``None``). When the profile already holds a newer token (another
+    process rotated) that one is returned; otherwise the profile is refreshed once.
+    """
+    name = _resolved_profiles.get(rejected_token)
+    if name is None or os.environ.get("TAKT_TOKEN"):
+        return None
+    store = store or CredentialStore()
+    profile = store.read()["profiles"].get(name) or {}
+    current = profile.get("access_token")
+    if not current:
+        return None
+    if current != rejected_token:
+        _resolved_profiles[current] = name
+        return current
+    if not (profile.get("refresh_token") and profile.get("origin")):
+        return None
+    fresh = refresh_profile(name, rejected_token, store=store, opener=opener)["access_token"]
+    _resolved_profiles[fresh] = name
+    return fresh

{taktcli-0.6.2 → taktcli-0.7.0}/taktcli/commands/_exec.py

@@ -10,7 +10,7 @@ import argparse
 import os
 import sys
 
-from ..auth import resolve_auth
+from ..auth import reauthorize, resolve_auth
 from ..errors import ConfigError
 from ..io import format_output, read_path
 from ..transport import execute
@@ -34,7 +34,7 @@ def add_output_args(parser: argparse.ArgumentParser) -> None:
 def fetch(document: str, variables: dict) -> dict:
     """Resolve auth, run the operation, and return the full GraphQL envelope."""
     url, token = resolve_auth()
-    return execute(document, variables, url=url, token=token)
+    return execute(document, variables, url=url, token=token, reauthorize=reauthorize)
 
 
 def run_operation(args, document: str, variables: dict) -> int:

{taktcli-0.6.2 → taktcli-0.7.0}/taktcli/commands/_run.py

@@ -8,7 +8,7 @@ resolving an inline-or-file (``-`` = stdin) text argument.
 
 import sys
 
-from ..auth import resolve_auth
+from ..auth import reauthorize, resolve_auth
 from ..errors import ConfigError
 from ..io import format_output, read_path
 from ..transport import execute
@@ -30,7 +30,7 @@ def run_op(args, document: str, variables: dict, *, hint=None, unwrap=None) -> i
     which still sees the full ``.data``.
     """
     url, token = resolve_auth()
-    envelope = execute(document, variables, url=url, token=token)
+    envelope = execute(document, variables, url=url, token=token, reauthorize=reauthorize)
     print(format_output(
         envelope,
         raw=getattr(args, "raw", False),
@@ -52,7 +52,7 @@ def fetch_data(document: str, variables: dict) -> dict:
     resolving a label name to its id) without printing the intermediate result.
     """
     url, token = resolve_auth()
-    envelope = execute(document, variables, url=url, token=token)
+    envelope = execute(document, variables, url=url, token=token, reauthorize=reauthorize)
     return (envelope or {}).get("data") or {}