Source code for plone_client.credentials
"""Where the password or token of a profile is kept.
``keyring`` (default)
The operating system's secret store, through the :mod:`keyring` package:
macOS Keychain, Windows Credential Locker, or the Secret Service on Linux.
Entries are stored under the service ``plone-client:<profile>``.
``env``
An environment variable, named by the profile's ``secret_env``
(``PLONE_CLIENT_PASSWORD`` by default). Handy in CI.
``command``
The output of a command, named by the profile's ``secret_command``, such
as ``op read op://Private/site/password`` or ``pass show plone/site``.
The command runs without a shell.
``none``
No secret: the profile is anonymous.
The token that MCP clients send to ``plone-client mcp --http`` is kept in the
keyring too, under the service ``plone-client`` (no profile has that
service), or in ``$PLONE_CLIENT_MCP_TOKEN``, which wins.
"""
from .exceptions import PloneConfigurationError
from typing import Any
from typing import TYPE_CHECKING
import os
import secrets
import shlex
import subprocess
if TYPE_CHECKING:
from .profiles import Profile
SERVICE_PREFIX = "plone-client"
[docs]
def keyring_service(profile: "Profile") -> str:
"""Keyring service name of a profile.
:param profile: The profile.
:returns: ``plone-client:<profile name>``.
"""
return f"{SERVICE_PREFIX}:{profile.name}"
[docs]
def keyring_account(profile: "Profile") -> str:
"""Keyring account name of a profile.
:param profile: The profile.
:returns: The username, or ``token`` for token profiles without one.
"""
return profile.username or "token"
def _keyring() -> Any:
"""Import :mod:`keyring`.
:returns: The module.
:raises PloneConfigurationError: If it is not installed.
"""
try:
import keyring
except ImportError: # no cov
raise PloneConfigurationError(
"The keyring needs the 'cli' extra: pip install 'plone-client[cli]'"
) from None
return keyring
[docs]
def get_secret(profile: "Profile") -> str:
"""Look up the secret of a profile.
:param profile: The profile.
:returns: The password or token.
:raises PloneConfigurationError: If the secret is missing.
"""
if profile.secret == "none":
return ""
if profile.secret == "env":
value = os.environ.get(profile.secret_env, "")
if not value:
raise PloneConfigurationError(
f"Profile {profile.name!r}: set ${profile.secret_env}"
)
return value
if profile.secret == "command":
return _run_command(profile)
value = _keyring().get_password(keyring_service(profile), keyring_account(profile))
if not value:
raise PloneConfigurationError(
f"Profile {profile.name!r}: no secret in the keyring; "
f"run 'plone-client profile set-secret {profile.name}'"
)
return str(value)
def _run_command(profile: "Profile") -> str:
"""Run the secret command of a profile.
:param profile: The profile.
:returns: The first line of the command's output.
:raises PloneConfigurationError: If the command fails or prints nothing.
"""
try:
result = subprocess.run( # noqa: S603
shlex.split(profile.secret_command),
capture_output=True,
text=True,
check=False,
timeout=60,
)
except (OSError, subprocess.TimeoutExpired) as exc:
raise PloneConfigurationError(
f"Profile {profile.name!r}: secret command failed: {exc}"
) from exc
value = result.stdout.splitlines()[0].strip() if result.stdout else ""
if result.returncode or not value:
raise PloneConfigurationError(
f"Profile {profile.name!r}: secret command exited with "
f"{result.returncode} and printed no secret"
)
return value
[docs]
def set_secret(profile: "Profile", value: str) -> None:
"""Store the secret of a profile in the keyring.
:param profile: The profile.
:param value: The password or token.
:raises PloneConfigurationError: If the profile keeps its secret elsewhere.
"""
if profile.secret != "keyring":
raise PloneConfigurationError(
f"Profile {profile.name!r} reads its secret from {profile.secret!r}, "
"not from the keyring"
)
_keyring().set_password(keyring_service(profile), keyring_account(profile), value)
[docs]
def delete_secret(profile: "Profile") -> bool:
"""Remove the secret of a profile from the keyring.
:param profile: The profile.
:returns: ``True`` if there was a secret to remove.
"""
if profile.secret != "keyring":
return False
keyring = _keyring()
try:
keyring.delete_password(keyring_service(profile), keyring_account(profile))
except keyring.errors.PasswordDeleteError:
return False
return True
#: Environment variable with the token of the MCP server; wins over the keyring.
MCP_TOKEN_ENV = "PLONE_CLIENT_MCP_TOKEN"
#: Keyring account of the MCP server's token, under the service ``plone-client``.
MCP_TOKEN_ACCOUNT = "mcp-token"
#: Shortest token the MCP server accepts.
MCP_TOKEN_MIN_LENGTH = 32
def _check_mcp_token(value: str, origin: str) -> str:
"""Refuse a token too short to resist guessing.
:param value: The token.
:param origin: Where it came from, for the message.
:returns: The token.
:raises PloneConfigurationError: If it is shorter than
:data:`MCP_TOKEN_MIN_LENGTH`.
"""
if len(value) < MCP_TOKEN_MIN_LENGTH:
raise PloneConfigurationError(
f"The MCP token {origin} has {len(value)} characters; it needs at "
f"least {MCP_TOKEN_MIN_LENGTH}. Run 'plone-client mcp-token generate'"
)
return value
[docs]
def get_mcp_token() -> str:
"""The token that MCP clients must send to the HTTP server.
:returns: ``$PLONE_CLIENT_MCP_TOKEN`` when set, or the token in the keyring.
:raises PloneConfigurationError: If there is none, or it is too short.
"""
value = os.environ.get(MCP_TOKEN_ENV, "")
if value:
return _check_mcp_token(value, f"in ${MCP_TOKEN_ENV}")
value = _keyring().get_password(SERVICE_PREFIX, MCP_TOKEN_ACCOUNT) or ""
if not value:
raise PloneConfigurationError(
"The MCP server over HTTP needs a token: run "
f"'plone-client mcp-token generate', or set ${MCP_TOKEN_ENV}"
)
return _check_mcp_token(str(value), "in the keyring")
[docs]
def set_mcp_token(value: str) -> None:
"""Store the token of the MCP server in the keyring.
:param value: The token.
:raises PloneConfigurationError: If it is too short.
"""
_check_mcp_token(value, "given")
_keyring().set_password(SERVICE_PREFIX, MCP_TOKEN_ACCOUNT, value)
[docs]
def generate_mcp_token() -> str:
"""Make a new random token for the MCP server and store it in the keyring.
:returns: The token, for the MCP clients' configuration.
"""
value = secrets.token_urlsafe(32)
set_mcp_token(value)
return value
[docs]
def delete_mcp_token() -> bool:
"""Remove the token of the MCP server from the keyring.
:returns: ``True`` if there was a token to remove.
"""
keyring = _keyring()
try:
keyring.delete_password(SERVICE_PREFIX, MCP_TOKEN_ACCOUNT)
except keyring.errors.PasswordDeleteError:
return False
return True