psst-secret-cli 1.0.0__tar.gz

psst_secret_cli-1.0.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.3
+Name: psst-secret-cli
+Version: 1.0.0
+Summary: Command-line client for psst-secret
+Requires-Dist: cryptography>=50.0.2
+Requires-Dist: pydantic>=2.14.3
+Requires-Dist: requests>=2.34.2
+Requires-Dist: typer>=0.28.0
+Requires-Python: >=3.15
+Description-Content-Type: text/markdown
+
+# psst-secret-cli
+
+Command-line client for [psst-secret](https://github.com/ch0wm3in/psst-secret). Encryption happens locally; the link fragment, keys, and passwords are never sent to the server.
+
+Implements format version 1 as specified in psst-secret `v1.5.2` (`docs/format.md`).
+
+## Usage
+
+```sh
+psst config set-server https://psst.example.com   # or --server / PSST_SERVER
+psst info                                          # compatibility check
+
+# Send mode: secret text is read from stdin or a hidden prompt, never from arguments
+psst send < secret.txt
+psst send --file id_ed25519 --password --max-views 1 --expiry 1h
+
+# Reveal: the link is read from stdin or a hidden prompt
+psst reveal -o ./downloads
+
+# Receive mode
+psst request --password              # prints a submit link and a view link
+psst request --notify-email me@example.com --reader alice@example.com
+psst status                          # has the request been submitted? (view link from stdin/prompt)
+psst submit '<submit link>' --file creds.env
+
+# Saved receive requests (opt-in, kept in a private file on this machine)
+psst config save-requests on         # or `psst request --save` for a single request
+psst request --label "deploy key"
+psst requests list                   # pending / submitted / gone, without using a view
+psst requests reveal "deploy key"
+psst requests prune                  # forget expired or revealed requests
+psst config save-requests off        # offers to delete everything saved
+
+# Sign in (servers that require it): browser sign-in with PKCE, token saved per server
+psst login                      # --port 53682 --no-browser for SSH forwarding, --manual if enabled
+psst logout                     # revokes the token
+```
+
+`PSST_TOKEN` overrides the saved token, e.g. in automation.
+
+## Development
+
+```sh
+uv sync
+uv run pytest                                      # unit tests and spec vectors
+
+docker compose -f tests/integration/docker-compose.yml up -d
+PSST_TEST_SERVER=http://127.0.0.1:18000 uv run pytest -m integration
+```
+
+The test vectors in `tests/vectors/v1/` are copied from `spec/vectors/v1/` at psst-secret `v1.5.2`.

psst_secret_cli-1.0.0/README.md

@@ -0,0 +1,51 @@
+# psst-secret-cli
+
+Command-line client for [psst-secret](https://github.com/ch0wm3in/psst-secret). Encryption happens locally; the link fragment, keys, and passwords are never sent to the server.
+
+Implements format version 1 as specified in psst-secret `v1.5.2` (`docs/format.md`).
+
+## Usage
+
+```sh
+psst config set-server https://psst.example.com   # or --server / PSST_SERVER
+psst info                                          # compatibility check
+
+# Send mode: secret text is read from stdin or a hidden prompt, never from arguments
+psst send < secret.txt
+psst send --file id_ed25519 --password --max-views 1 --expiry 1h
+
+# Reveal: the link is read from stdin or a hidden prompt
+psst reveal -o ./downloads
+
+# Receive mode
+psst request --password              # prints a submit link and a view link
+psst request --notify-email me@example.com --reader alice@example.com
+psst status                          # has the request been submitted? (view link from stdin/prompt)
+psst submit '<submit link>' --file creds.env
+
+# Saved receive requests (opt-in, kept in a private file on this machine)
+psst config save-requests on         # or `psst request --save` for a single request
+psst request --label "deploy key"
+psst requests list                   # pending / submitted / gone, without using a view
+psst requests reveal "deploy key"
+psst requests prune                  # forget expired or revealed requests
+psst config save-requests off        # offers to delete everything saved
+
+# Sign in (servers that require it): browser sign-in with PKCE, token saved per server
+psst login                      # --port 53682 --no-browser for SSH forwarding, --manual if enabled
+psst logout                     # revokes the token
+```
+
+`PSST_TOKEN` overrides the saved token, e.g. in automation.
+
+## Development
+
+```sh
+uv sync
+uv run pytest                                      # unit tests and spec vectors
+
+docker compose -f tests/integration/docker-compose.yml up -d
+PSST_TEST_SERVER=http://127.0.0.1:18000 uv run pytest -m integration
+```
+
+The test vectors in `tests/vectors/v1/` are copied from `spec/vectors/v1/` at psst-secret `v1.5.2`.

psst_secret_cli-1.0.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "psst-secret-cli"
+version = "1.0.0"
+description = "Command-line client for psst-secret"
+readme = "README.md"
+requires-python = ">=3.15"
+dependencies = [
+    "cryptography>=50.0.2",
+    "pydantic>=2.14.3",
+    "requests>=2.34.2",
+    "typer>=0.28.0",
+]
+
+[project.scripts]
+psst = "psst_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "psst_cli"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["integration: needs a running psst-secret server (set PSST_TEST_SERVER)"]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.7.0",
+    "pytest>=9.2.0",
+]

psst_secret_cli-1.0.0/pyproject.toml.orig

@@ -0,0 +1,32 @@
+[project]
+name = "psst-secret-cli"
+version = "1.0.0"
+description = "Command-line client for psst-secret"
+readme = "README.md"
+requires-python = ">=3.15"
+dependencies = [
+    "cryptography>=50.0.2",
+    "pydantic>=2.14.3",
+    "requests>=2.34.2",
+    "typer>=0.28.0",
+]
+
+[project.scripts]
+psst = "psst_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.17,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "psst_cli"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["integration: needs a running psst-secret server (set PSST_TEST_SERVER)"]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.7.0",
+    "pytest>=9.2.0",
+]

psst_secret_cli-1.0.0/src/psst_cli/__init__.py

@@ -0,0 +1,19 @@
+"""Command-line client for psst-secret."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("psst-secret-cli")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+# psst-secret release whose docs/format.md and spec/vectors/ this client implements.
+SPEC_VERSION = "v1.5.2"
+API_VERSION = 1
+FORMAT_VERSION = 1
+# Versions this client can read; it only writes FORMAT_VERSION.
+READABLE_FORMAT_VERSIONS = frozenset({0, 1})
+
+
+class PsstError(Exception):
+    """Base class for errors shown to the user."""

psst_secret_cli-1.0.0/src/psst_cli/api.py

@@ -0,0 +1,285 @@
+"""HTTP client for the psst-secret /api/v1/ endpoints."""
+
+from datetime import datetime
+from enum import StrEnum
+from typing import Literal
+
+import requests
+from pydantic import BaseModel, Field, ValidationError
+
+from . import API_VERSION, FORMAT_VERSION, PsstError
+
+DEFAULT_TIMEOUT = 30
+
+
+class Expiry(StrEnum):
+    FIVE_MINUTES = "5m"
+    ONE_HOUR = "1h"
+    ONE_DAY = "1d"
+    ONE_WEEK = "1w"
+    ONE_MONTH = "1M"
+
+
+class ApiError(PsstError):
+    def __init__(self, status: int, message: str):
+        super().__init__(f"Server returned {status}: {message}")
+        self.status = status
+
+
+class IncompatibleServerError(PsstError):
+    pass
+
+
+class ApiInfoAuth(BaseModel):
+    login_required: bool
+    loopback_pkce: bool
+    manual_code: bool
+    scopes: list[str]
+
+
+class ApiInfoReceiveAccess(BaseModel):
+    enabled: bool
+    default: bool
+    required: bool
+
+
+class ApiInfoFeatures(BaseModel):
+    email_notifications: bool
+    receive_access: ApiInfoReceiveAccess
+    receive_history: bool
+    rich_text: bool
+
+
+class ApiInfoPolicies(BaseModel):
+    view_requires_auth: bool
+    submit_requires_auth: bool
+
+
+class ApiInfoLimits(BaseModel):
+    max_upload_bytes: int
+    max_views: int
+    expiry_options: list[str]
+
+
+class ApiInfo(BaseModel):
+    server_version: str
+    api_version: int
+    format_versions: list[int]
+    auth: ApiInfoAuth
+    # Added in psst-secret v1.5.2; None on older servers.
+    features: ApiInfoFeatures | None = None
+    policies: ApiInfoPolicies | None = None
+    limits: ApiInfoLimits | None = None
+
+
+class CreateWhisper(BaseModel):
+    v: Literal[1] = FORMAT_VERSION
+    reveal_token_hash: str
+    ciphertext: str
+    iv: str
+    salt: str = ""
+    max_views: int = Field(default=1, ge=0, le=100)
+    expiry: Expiry = Expiry.ONE_DAY
+    require_auth_view: bool = False
+    notify_email: str = ""
+
+
+class CreateWhisperResponse(BaseModel):
+    id: str
+    url: str
+
+
+class CreateRequest(BaseModel):
+    v: Literal[1] = FORMAT_VERSION
+    reveal_token_hash: str
+    public_key: str
+    salt: str = ""
+    wrapped_key: str = ""
+    wrapped_key_iv: str = ""
+    max_views: int = Field(default=1, ge=0, le=100)
+    expiry: Expiry = Expiry.ONE_DAY
+    require_auth_view: bool = False
+    require_auth_submit: bool = False
+    notify_email: str = ""
+    # None lets the server apply its default.
+    creator_only: bool | None = None
+    allowed_reader_emails: list[str] | None = Field(default=None, max_length=20)
+
+
+class CreateRequestResponse(BaseModel):
+    id: str
+    submit_url: str
+    view_url: str
+    expires_at: datetime
+
+
+class SubmitRequestKey(BaseModel):
+    public_key: str
+    v: int = 0
+
+
+class SubmitWhisper(BaseModel):
+    v: Literal[1] = FORMAT_VERSION
+    ciphertext: str
+    iv: str
+    encapsulated_key: str
+
+
+class SubmitWhisperResponse(BaseModel):
+    success: bool
+
+
+class _RevealBody(BaseModel):
+    reveal_token: str
+
+
+class RevealWhisperResponse(BaseModel):
+    v: int = 0
+    ciphertext: str
+    iv: str
+    salt: str = ""
+    encapsulated_key: str = ""
+    wrapped_key: str = ""
+    wrapped_key_iv: str = ""
+    view_count: int
+    max_views: int
+    remaining_views: int
+
+
+class WhisperStatus(BaseModel):
+    status: Literal["pending", "submitted", "gone"]
+    expires_at: datetime | None = None
+    view_count: int | None = None
+    max_views: int | None = None
+    remaining_views: int | None = None
+
+
+class TokenExchange(BaseModel):
+    code: str
+    code_verifier: str
+    redirect_uri: str
+
+
+class TokenResponse(BaseModel):
+    access_token: str
+    token_type: str
+    expires_in: int
+    expires_at: datetime
+    scope: str
+
+
+def normalize_server_url(url: str) -> str:
+    url = url.strip().rstrip("/")
+    if not url.startswith(("http://", "https://")):
+        raise PsstError("Server URL must start with http:// or https://")
+    if "#" in url or "?" in url:
+        raise PsstError("Server URL must not contain a query or fragment")
+    return url
+
+
+class Client:
+    def __init__(
+        self, server: str, token: str | None = None, timeout: float = DEFAULT_TIMEOUT
+    ):
+        self.server = normalize_server_url(server)
+        self.timeout = timeout
+        self._info: ApiInfo | None = None
+        self.session = requests.Session()
+        self.session.headers["Accept"] = "application/json"
+        if token:
+            self.session.headers["Authorization"] = f"Bearer {token}"
+
+    @property
+    def has_token(self) -> bool:
+        return "Authorization" in self.session.headers
+
+    def _send(
+        self, method: str, path: str, body: BaseModel | None = None
+    ) -> requests.Response:
+        url = f"{self.server}/api/v1/{path}"
+        try:
+            resp = self.session.request(
+                method,
+                url,
+                json=(
+                    body.model_dump(mode="json", exclude_none=True)
+                    if body is not None
+                    else None
+                ),
+                timeout=self.timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as exc:
+            raise PsstError(
+                f"Could not reach {self.server}: {exc.__class__.__name__}"
+            ) from exc
+        if not resp.ok:
+            try:
+                message = resp.json().get("error") or resp.reason
+            except ValueError, AttributeError:
+                message = resp.reason
+            raise ApiError(resp.status_code, str(message))
+        return resp
+
+    def _request[T: BaseModel](
+        self,
+        method: str,
+        path: str,
+        response_model: type[T],
+        body: BaseModel | None = None,
+    ) -> T:
+        resp = self._send(method, path, body)
+        try:
+            return response_model.model_validate_json(resp.content)
+        except ValidationError as exc:
+            raise PsstError(
+                f"Unexpected response from {self.server}/api/v1/{path}"
+            ) from exc
+
+    def info(self) -> ApiInfo:
+        if self._info is None:
+            self._info = self._request("GET", "info", ApiInfo)
+        return self._info
+
+    def check_compatible(self, *, creating: bool) -> ApiInfo:
+        """Verify the server speaks API v1 and, when creating, accepts our format version."""
+        info = self.info()
+        if info.api_version != API_VERSION:
+            raise IncompatibleServerError(
+                f"Server API version {info.api_version} is not supported (expected {API_VERSION})"
+            )
+        if creating and FORMAT_VERSION not in info.format_versions:
+            raise IncompatibleServerError(
+                f"Server does not accept format version {FORMAT_VERSION} "
+                f"(accepts {info.format_versions})"
+            )
+        return info
+
+    def create_whisper(self, body: CreateWhisper) -> CreateWhisperResponse:
+        return self._request("POST", "whisper", CreateWhisperResponse, body)
+
+    def create_request(self, body: CreateRequest) -> CreateRequestResponse:
+        return self._request("POST", "whisper/request", CreateRequestResponse, body)
+
+    def get_submit_key(self, request_id: str) -> SubmitRequestKey:
+        return self._request("GET", f"whisper/submit/{request_id}", SubmitRequestKey)
+
+    def submit(self, request_id: str, body: SubmitWhisper) -> SubmitWhisperResponse:
+        return self._request(
+            "POST", f"whisper/submit/{request_id}", SubmitWhisperResponse, body
+        )
+
+    def reveal(self, view_id: str, reveal_token: str | None) -> RevealWhisperResponse:
+        body = _RevealBody(reveal_token=reveal_token or "")
+        return self._request(
+            "POST", f"whisper/{view_id}/reveal", RevealWhisperResponse, body
+        )
+
+    def status(self, view_id: str) -> WhisperStatus:
+        return self._request("GET", f"whisper/{view_id}/status", WhisperStatus)
+
+    def exchange_token(self, body: TokenExchange) -> TokenResponse:
+        return self._request("POST", "cli/token", TokenResponse, body)
+
+    def revoke_token(self) -> None:
+        self._send("POST", "cli/revoke")

psst_secret_cli-1.0.0/src/psst_cli/auth.py

@@ -0,0 +1,148 @@
+"""API token sign-in: loopback redirect with PKCE (RFC 8252, RFC 7636)."""
+
+import base64
+import hashlib
+import hmac
+import secrets
+import time
+import webbrowser
+from collections.abc import Callable
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from urllib.parse import parse_qs, urlencode, urlsplit
+
+from . import PsstError
+from .api import Client, TokenExchange, TokenResponse
+
+CLIENT_NAME = "psst CLI"
+CALLBACK_PATH = "/callback"
+MANUAL_REDIRECT_URI = "urn:ietf:wg:oauth:2.0:oob"
+LOGIN_TIMEOUT = 300
+
+_CALLBACK_PAGE = (
+    "<!doctype html><meta charset=utf-8><title>psst CLI</title>"
+    "<p>{message} You can close this window and return to the terminal.</p>"
+)
+
+
+class LoginError(PsstError):
+    pass
+
+
+def new_pkce_pair() -> tuple[str, str]:
+    verifier = secrets.token_urlsafe(64)
+    challenge = base64.urlsafe_b64encode(
+        hashlib.sha256(verifier.encode("ascii")).digest()
+    )
+    return verifier, challenge.rstrip(b"=").decode("ascii")
+
+
+def authorize_url(
+    server: str, redirect_uri: str, challenge: str, state: str, scope: str | None
+) -> str:
+    params = {
+        "redirect_uri": redirect_uri,
+        "code_challenge": challenge,
+        "code_challenge_method": "S256",
+        "state": state,
+        "client_name": CLIENT_NAME,
+    }
+    if scope:
+        params["scope"] = scope
+    return f"{server}/cli/authorize?{urlencode(params)}"
+
+
+class _CallbackServer(HTTPServer):
+    result: dict[str, str] | None = None
+
+
+class _CallbackHandler(BaseHTTPRequestHandler):
+    server: _CallbackServer
+
+    def do_GET(self) -> None:
+        parts = urlsplit(self.path)
+        if parts.path != CALLBACK_PATH:
+            self.send_error(404)
+            return
+        self.server.result = {k: v[0] for k, v in parse_qs(parts.query).items()}
+        ok = "code" in self.server.result
+        body = _CALLBACK_PAGE.format(
+            message="Signed in." if ok else "Sign-in was not completed."
+        )
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Cache-Control", "no-store")
+        self.end_headers()
+        self.wfile.write(body.encode("utf-8"))
+
+    def log_message(self, format: str, *args: object) -> None:
+        # The default logger would print the authorization code to stderr.
+        pass
+
+
+def _wait_for_callback(httpd: _CallbackServer, timeout: float) -> dict[str, str]:
+    deadline = time.monotonic() + timeout
+    while httpd.result is None:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise LoginError("Timed out waiting for the browser sign-in")
+        httpd.timeout = remaining
+        httpd.handle_request()
+    return httpd.result
+
+
+def login_loopback(
+    client: Client,
+    *,
+    port: int = 0,
+    scope: str | None = None,
+    open_browser: bool = True,
+    show_url: Callable[[str], None] = print,
+    timeout: float = LOGIN_TIMEOUT,
+) -> TokenResponse:
+    verifier, challenge = new_pkce_pair()
+    state = secrets.token_urlsafe(32)
+    try:
+        httpd = _CallbackServer(("127.0.0.1", port), _CallbackHandler)
+    except OSError as exc:
+        raise LoginError(
+            f"Could not listen on 127.0.0.1:{port}: {exc.strerror}"
+        ) from exc
+    with httpd:
+        redirect_uri = f"http://127.0.0.1:{httpd.server_address[1]}{CALLBACK_PATH}"
+        url = authorize_url(client.server, redirect_uri, challenge, state, scope)
+        show_url(url)
+        if open_browser:
+            webbrowser.open(url)
+        result = _wait_for_callback(httpd, timeout)
+
+    if not hmac.compare_digest(result.get("state", ""), state):
+        raise LoginError("Sign-in response had an invalid state; aborting")
+    if "error" in result:
+        raise LoginError(f"Sign-in failed: {result['error']}")
+    if "code" not in result:
+        raise LoginError("Sign-in response did not contain a code")
+    return client.exchange_token(
+        TokenExchange(
+            code=result["code"], code_verifier=verifier, redirect_uri=redirect_uri
+        )
+    )
+
+
+def login_manual(
+    client: Client,
+    *,
+    read_code: Callable[[], str],
+    scope: str | None = None,
+    show_url: Callable[[str], None] = print,
+) -> TokenResponse:
+    verifier, challenge = new_pkce_pair()
+    state = secrets.token_urlsafe(32)
+    show_url(authorize_url(client.server, MANUAL_REDIRECT_URI, challenge, state, scope))
+    code = read_code().strip()
+    if not code:
+        raise LoginError("No code entered")
+    return client.exchange_token(
+        TokenExchange(
+            code=code, code_verifier=verifier, redirect_uri=MANUAL_REDIRECT_URI
+        )
+    )