solwyn-cli 0.1.0__py3-none-any.whl

solwyn_cli/commands/keys.py

@@ -0,0 +1,386 @@
+"""Project key recovery commands."""
+
+from typing import Annotated
+from urllib.parse import quote
+
+import typer
+from pydantic import (
+    AwareDatetime,
+    BaseModel,
+    ConfigDict,
+    Field,
+    SecretStr,
+    ValidationError,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
+
+from solwyn_cli._vendor.validation import validate_project_key_format
+from solwyn_cli._vendor.wire import ProjectKeyRotateRequest
+from solwyn_cli.auth import (
+    AuthError,
+    JwtCredential,
+    ProjectKeyCredential,
+    resolve_credential,
+)
+from solwyn_cli.client import SolwynClient
+from solwyn_cli.commands._shared import exit_with_error, required_credential
+from solwyn_cli.errors import ApiError
+from solwyn_cli.exit_codes import ErrorSemantic
+from solwyn_cli.help import help_contract
+from solwyn_cli.output import OneTimeSecretPanel, OutputError, TableData
+from solwyn_cli.runtime import command_context, output_engine
+
+
+app = typer.Typer(
+    help="Recover from leaked or expired project keys.",
+    epilog=help_contract(
+        endpoint="composite router for project-key subcommands",
+        auth="JWT",
+        exits="0 success; 2 usage",
+        schema="varies by subcommand",
+        guidance=("Metadata help never reveals existing key material.",),
+    ),
+)
+
+
+class _ProjectKeyMetadata(BaseModel):
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+
+    id: str = Field(min_length=1)
+    key_prefix: str = Field(pattern=r"^sk_proj_[a-f0-9]{16}$")
+    name: str = Field(min_length=1)
+    last_used_at: AwareDatetime | None
+    expires_at: AwareDatetime | None
+    rotation_grace_until: AwareDatetime | None
+    created_at: AwareDatetime
+
+
+class _ProjectKeyRotateResponse(BaseModel):
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+
+    id: str = Field(min_length=1)
+    key: SecretStr
+    key_prefix: str = Field(pattern=r"^sk_proj_[a-f0-9]{16}$")
+    rotation_grace_until: AwareDatetime
+
+    @field_validator("key")
+    @classmethod
+    def validate_key(cls, value: SecretStr) -> SecretStr:
+        validate_project_key_format(value.get_secret_value())
+        return value
+
+    @model_validator(mode="after")
+    def validate_key_prefix(self) -> "_ProjectKeyRotateResponse":
+        if self.key_prefix != self.key.get_secret_value()[:24]:
+            raise ValueError("Invalid project key prefix")
+        return self
+
+    @field_serializer("key")
+    def serialize_key(self, value: SecretStr) -> str:
+        return value.get_secret_value()
+
+
+class _ProjectKeyRevokeData(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    project_id: str
+    key_id: str
+    revoked: bool = True
+
+
+def _date_time(value: AwareDatetime | None) -> str:
+    if value is None:
+        return "-"
+    return value.isoformat().replace("+00:00", "Z")
+
+
+def _metadata_table(data: _ProjectKeyMetadata) -> TableData:
+    return TableData(
+        columns=("Field", "Value"),
+        rows=(
+            ("ID", data.id),
+            ("Key prefix", data.key_prefix),
+            ("Name", data.name),
+            ("Last used", _date_time(data.last_used_at)),
+            ("Expires", _date_time(data.expires_at)),
+            ("Rotation grace until", _date_time(data.rotation_grace_until)),
+            ("Created", _date_time(data.created_at)),
+        ),
+        right_align=("Value",),
+    )
+
+
+def _rotate_table(data: _ProjectKeyRotateResponse) -> TableData:
+    return TableData(
+        columns=("Field", "Value"),
+        rows=(
+            ("ID", data.id),
+            ("Key prefix", data.key_prefix),
+            ("Rotation grace until", _date_time(data.rotation_grace_until)),
+        ),
+        right_align=("Value",),
+    )
+
+
+def _revoke_table(data: _ProjectKeyRevokeData) -> TableData:
+    return TableData(
+        columns=("Field", "Value"),
+        rows=(
+            ("Project", data.project_id),
+            ("Key ID", data.key_id),
+            ("Revoked", "true"),
+        ),
+        right_align=("Value",),
+    )
+
+
+def _validated_identifier(
+    context: typer.Context,
+    value: str | None,
+    *,
+    label: str,
+) -> str:
+    if value is None or not value.strip():
+        hint = (
+            "Choose a project with --project, SOLWYN_PROJECT_ID, or "
+            "config default_project."
+            if label == "project"
+            else "Provide a nonblank key identifier with --key-id."
+        )
+        exit_with_error(
+            context,
+            OutputError(
+                code=f"{label}_required",
+                message=f"A {label} is required.",
+                hint=hint,
+            ),
+            semantic=ErrorSemantic.USAGE,
+        )
+    return value.strip()
+
+
+def _jwt_credential(context: typer.Context, *, operation: str) -> JwtCredential:
+    credential = required_credential(context, resolve=resolve_credential)
+    if isinstance(credential, ProjectKeyCredential):
+        hint = (
+            f"Unset SOLWYN_API_KEY, run solwyn login, then retry keys {operation}."
+            if credential.source == "environment"
+            else (f"Run solwyn logout, then solwyn login, and retry keys {operation}.")
+        )
+        exit_with_error(
+            context,
+            OutputError(
+                code="authentication_required",
+                message="User login is required to manage project keys.",
+                hint=hint,
+            ),
+            semantic=ErrorSemantic.AUTH,
+        )
+    return credential
+
+
+def _actionable_api_error(error: ApiError) -> ApiError:
+    hints = {
+        404: "Verify the project or key identifier and retry.",
+        409: "A key rotation may already be in progress; inspect the active key before retrying.",
+        410: "The project key is inactive; inspect current key metadata before retrying.",
+        429: "Retry later after the project-key rate limit resets.",
+    }
+    hint = error.hint or hints.get(error.status_code)
+    if hint == error.hint:
+        return error
+    return ApiError(
+        status_code=error.status_code,
+        code=error.code,
+        message=error.message,
+        hint=hint,
+        detail=error.detail,
+    )
+
+
+def _invalid_response(context: typer.Context) -> None:
+    exit_with_error(
+        context,
+        OutputError(
+            code="invalid_keys_response",
+            message="The project key response was invalid.",
+        ),
+    )
+
+
+def _validate_metadata_response(payload: object) -> _ProjectKeyMetadata:
+    """Reject raw key material before metadata validation can inspect it."""
+    if not isinstance(payload, dict) or "key" in payload:
+        raise ValueError("Invalid project key metadata")
+    return _ProjectKeyMetadata.model_validate(payload)
+
+
+@app.command(
+    "show",
+    epilog=help_contract(
+        endpoint="GET /api/v1/projects/{project}/key",
+        auth="JWT",
+        exits="0 success; 1 generic/API; 2 usage; 3 auth; 5 not found",
+        schema="solwyn.keys-show.v1",
+        guidance=("Shows metadata only and never reveals existing key material.",),
+    ),
+)
+def show_key(context: typer.Context) -> None:
+    """Show active project-key metadata without revealing key material."""
+    runtime = command_context(context)
+    project_id = _validated_identifier(context, runtime.project, label="project")
+    credential = _jwt_credential(context, operation="show")
+    path = quote(project_id, safe="")
+    try:
+        with SolwynClient(api_url=runtime.api_url, credential=credential) as client:
+            response = client.request("GET", f"/api/v1/projects/{path}/key")
+        if response.status_code != 200:
+            raise ValueError("Key metadata did not return 200")
+        data = _validate_metadata_response(response.json())
+    except ApiError as error:
+        exit_with_error(context, _actionable_api_error(error))
+    except AuthError as error:
+        exit_with_error(
+            context,
+            OutputError(code="authentication_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    except (ValidationError, ValueError, TypeError):
+        _invalid_response(context)
+
+    output_engine(context).write_success(
+        schema="solwyn.keys-show.v1",
+        data=data,
+        table=_metadata_table(data),
+    )
+
+
+@app.command(
+    "rotate",
+    epilog=help_contract(
+        endpoint="POST /api/v1/projects/{project}/key/rotate",
+        auth="JWT",
+        exits="0 success; 1 generic/API; 2 usage; 3 auth; 5 not found",
+        schema="solwyn.keys-rotate.v1",
+        guidance=(
+            "The replacement key is shown exactly once; store it in the OS keychain.",
+        ),
+    ),
+)
+def rotate_key(
+    context: typer.Context,
+    grace_seconds: Annotated[
+        int | None,
+        typer.Option(
+            "--grace-seconds",
+            help="Seconds the old key remains valid (0 through 604800).",
+        ),
+    ] = None,
+) -> None:
+    """Rotate the active key and reveal its replacement exactly once."""
+    runtime = command_context(context)
+    project_id = _validated_identifier(context, runtime.project, label="project")
+    try:
+        request = ProjectKeyRotateRequest(grace_seconds=grace_seconds)
+    except ValidationError:
+        exit_with_error(
+            context,
+            OutputError(
+                code="invalid_key_rotation_request",
+                message="The key rotation request is invalid.",
+                hint="Use --grace-seconds with a value from 0 through 604800.",
+            ),
+            semantic=ErrorSemantic.USAGE,
+        )
+    credential = _jwt_credential(context, operation="rotate")
+    path = quote(project_id, safe="")
+    try:
+        with SolwynClient(api_url=runtime.api_url, credential=credential) as client:
+            response = client.request(
+                "POST",
+                f"/api/v1/projects/{path}/key/rotate",
+                json=request.model_dump(mode="json"),
+                retry_rate_limit=False,
+                retry_auth=False,
+            )
+        if response.status_code != 200:
+            raise ValueError("Key rotation did not return 200")
+        data = _ProjectKeyRotateResponse.model_validate(response.json())
+    except ApiError as error:
+        exit_with_error(context, _actionable_api_error(error))
+    except AuthError as error:
+        exit_with_error(
+            context,
+            OutputError(code="authentication_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    except (ValidationError, ValueError, TypeError):
+        _invalid_response(context)
+
+    output_engine(context).write_success(
+        schema="solwyn.keys-rotate.v1",
+        data=data,
+        table=_rotate_table(data),
+        one_time_secret=OneTimeSecretPanel(
+            title="One-time replacement project key",
+            value=data.key,
+        ),
+    )
+
+
+@app.command(
+    "revoke",
+    epilog=help_contract(
+        endpoint="DELETE /api/v1/projects/{project}/key/{key_id}",
+        auth="JWT",
+        exits="0 success; 1 generic/API; 2 usage; 3 auth; 5 not found",
+        schema="solwyn.keys-revoke.v1 (CLI output after bodyless 204)",
+        guidance=("Accepts only a key identifier; never pass key material.",),
+    ),
+)
+def revoke_key(
+    context: typer.Context,
+    key_id: Annotated[
+        str,
+        typer.Option("--key-id", help="Identifier of the key to hard-revoke."),
+    ],
+) -> None:
+    """Hard-revoke a project key without minting a replacement."""
+    runtime = command_context(context)
+    project_id = _validated_identifier(context, runtime.project, label="project")
+    validated_key_id = _validated_identifier(context, key_id, label="key_id")
+    credential = _jwt_credential(context, operation="revoke")
+    project_path = quote(project_id, safe="")
+    key_path = quote(validated_key_id, safe="")
+    try:
+        with SolwynClient(api_url=runtime.api_url, credential=credential) as client:
+            response = client.request(
+                "DELETE",
+                f"/api/v1/projects/{project_path}/key/{key_path}",
+                retry_rate_limit=False,
+                retry_auth=False,
+            )
+        if response.status_code != 204 or response.content:
+            raise ValueError("Key revocation did not return a bodyless 204")
+    except ApiError as error:
+        exit_with_error(context, _actionable_api_error(error))
+    except AuthError as error:
+        exit_with_error(
+            context,
+            OutputError(code="authentication_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    except (ValidationError, ValueError, TypeError):
+        _invalid_response(context)
+
+    data = _ProjectKeyRevokeData(
+        project_id=project_id,
+        key_id=validated_key_id,
+    )
+    output_engine(context).write_success(
+        schema="solwyn.keys-revoke.v1",
+        data=data,
+        table=_revoke_table(data),
+    )

solwyn_cli/commands/login.py

@@ -0,0 +1,205 @@
+"""Login and logout commands."""
+
+import sys
+from typing import Annotated, Literal
+
+import typer
+from pydantic import BaseModel, ConfigDict, Field, SecretStr, ValidationError
+
+from solwyn_cli._vendor.wire import LoginRequest
+from solwyn_cli.auth import (
+    AuthError,
+    CredentialStorageError,
+    JwtCredential,
+    ProjectKeyCredential,
+    clear_credentials,
+    store_jwt_pair,
+    store_project_key,
+)
+from solwyn_cli.client import SolwynClient
+from solwyn_cli.commands._shared import exit_with_error
+from solwyn_cli.errors import ApiError
+from solwyn_cli.exit_codes import ErrorSemantic
+from solwyn_cli.help import help_contract
+from solwyn_cli.output import OutputError, TableData
+from solwyn_cli.runtime import command_context, output_engine
+
+
+LOGIN_HELP = help_contract(
+    endpoint="POST /api/v1/auth/login or local keychain write with --with-key",
+    auth="none",
+    exits="0 success; 1 generic/API; 2 usage; 3 auth or credential storage",
+    schema="solwyn.login.v1",
+    guidance=(
+        "Keys and passwords are never accepted as command-line arguments or echoed.",
+        "Read project keys only from a hidden prompt or stdin; passwords use a hidden prompt.",
+    ),
+)
+
+LOGOUT_HELP = help_contract(
+    endpoint="local keychain clear",
+    auth="local (none)",
+    exits="0 success; 2 usage; 3 credential storage",
+    schema="solwyn.logout.v1",
+)
+
+
+class _LoginTokenResponse(BaseModel):
+    """Validated login response whose tokens remain redacted in memory."""
+
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+
+    access_token: SecretStr = Field(min_length=1)
+    refresh_token: SecretStr = Field(min_length=1)
+    token_type: Literal["bearer"] = "bearer"
+
+
+def authenticate_with_project_key(project_key: str) -> ProjectKeyCredential:
+    """Validate and store one project key through the shared auth boundary."""
+    return store_project_key(project_key)
+
+
+def authenticate_with_password(
+    *, api_url: str, email: str, password: str
+) -> JwtCredential:
+    """Authenticate, validate the token response, and store the JWT pair."""
+    request = LoginRequest(email=email, password=password)
+    with SolwynClient(api_url=api_url, credential=None) as client:
+        response = client.request_unauthenticated(
+            "POST",
+            "/api/v1/auth/login",
+            json=request.model_dump(),
+        )
+    tokens = _LoginTokenResponse.model_validate(response.json())
+    return store_jwt_pair(
+        tokens.access_token.get_secret_value(),
+        tokens.refresh_token.get_secret_value(),
+    )
+
+
+def _stdin_is_tty() -> bool:
+    return sys.stdin.isatty()
+
+
+def _login_success(context: typer.Context, auth_type: str) -> None:
+    output_engine(context).write_success(
+        schema="solwyn.login.v1",
+        data={"auth_type": auth_type},
+        table=TableData(
+            columns=("Authentication", "Status"),
+            rows=((auth_type, "authenticated"),),
+            right_align=("Status",),
+        ),
+    )
+
+
+def _login_with_key(context: typer.Context) -> None:
+    project_key = (
+        typer.prompt("Project key", hide_input=True, err=True)
+        if _stdin_is_tty()
+        else sys.stdin.read().strip()
+    )
+    try:
+        authenticate_with_project_key(project_key)
+    except CredentialStorageError as error:
+        exit_with_error(
+            context,
+            OutputError(code="credential_storage_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    except AuthError:
+        exit_with_error(
+            context,
+            OutputError(
+                code="invalid_project_key",
+                message="The project key is empty or malformed.",
+            ),
+            semantic=ErrorSemantic.AUTH,
+        )
+    _login_success(context, "project_key")
+
+
+def _login_with_password(context: typer.Context) -> None:
+    if not _stdin_is_tty():
+        exit_with_error(
+            context,
+            OutputError(
+                code="interactive_auth_required",
+                message="Email and password login requires an interactive terminal.",
+                hint="Set SOLWYN_API_KEY or pipe a project key to login --with-key.",
+            ),
+            semantic=ErrorSemantic.AUTH,
+        )
+    email = typer.prompt("Email", err=True)
+    password = typer.prompt("Password", hide_input=True, err=True)
+    try:
+        runtime = command_context(context)
+        authenticate_with_password(
+            api_url=runtime.api_url,
+            email=email,
+            password=password,
+        )
+    except ApiError as error:
+        if error.status_code == 403 and error.code == "email_not_verified":
+            error = ApiError(
+                status_code=error.status_code,
+                code=error.code,
+                message=error.message,
+                hint="Verify your email in the dashboard, then try logging in again.",
+                detail=error.detail,
+            )
+        exit_with_error(context, error, semantic=ErrorSemantic.AUTH)
+    except CredentialStorageError as error:
+        exit_with_error(
+            context,
+            OutputError(code="credential_storage_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    except (ValidationError, ValueError, TypeError):
+        exit_with_error(
+            context,
+            OutputError(
+                code="invalid_auth_response",
+                message="The authentication response was invalid.",
+            ),
+            semantic=ErrorSemantic.AUTH,
+        )
+    _login_success(context, "jwt")
+
+
+def login(
+    context: typer.Context,
+    with_key: Annotated[
+        bool,
+        typer.Option(
+            "--with-key",
+            help="Read and store a project API key from a hidden prompt or stdin.",
+        ),
+    ] = False,
+) -> None:
+    """Authenticate with Solwyn."""
+    if with_key:
+        _login_with_key(context)
+    else:
+        _login_with_password(context)
+
+
+def logout(context: typer.Context) -> None:
+    """Clear all stored Solwyn credentials."""
+    try:
+        clear_credentials()
+    except CredentialStorageError as error:
+        exit_with_error(
+            context,
+            OutputError(code="credential_storage_failed", message=str(error)),
+            semantic=ErrorSemantic.AUTH,
+        )
+    output_engine(context).write_success(
+        schema="solwyn.logout.v1",
+        data={"cleared": True},
+        table=TableData(
+            columns=("Credentials", "Status"),
+            rows=(("all", "cleared"),),
+            right_align=("Status",),
+        ),
+    )

solwyn_cli/commands/mcp.py

@@ -0,0 +1,28 @@
+"""Run the local Solwyn MCP server over stdio."""
+
+import typer
+
+from solwyn_cli.help import help_contract
+from solwyn_cli.mcp.server import McpLaunchOptions, TOOL_NAMES, create_server
+
+
+MCP_HELP = help_contract(
+    endpoint="local stdio MCP server",
+    auth="resolved per tool call",
+    exits="0 clean shutdown; 1 startup or protocol failure; 2 usage",
+    schema="MCP protocol (stdio JSON-RPC)",
+    guidance=(
+        "Protocol: stdio only; stdout is reserved for MCP JSON-RPC framing.",
+        "Runtime configuration and credentials are resolved anew for every tool call.",
+        f"Tools: {', '.join(TOOL_NAMES)}.",
+        "No telemetry, update checks, provider keys, prompts, or responses are collected.",
+    ),
+)
+
+
+def mcp(context: typer.Context) -> None:
+    """Serve Solwyn tools over local MCP stdio."""
+    launch_options = (
+        context.obj if isinstance(context.obj, McpLaunchOptions) else McpLaunchOptions()
+    )
+    create_server(launch_options=launch_options).run(transport="stdio")