langchain-atomicmail 0.3.14__py3-none-any.whl

atomicmail/__init__.py

@@ -0,0 +1,32 @@
+"""Atomic Mail Python shared foundation package."""
+
+from .config import ResolvedAgentConfig, resolve_agent_config_from_env
+from .credentials import (
+    CredentialStore,
+    Credentials,
+    SkillFiles,
+    default_files_from_out_dir,
+)
+from .help import help
+from .jmap_request import JmapAttachmentInput, JmapRequestResult, jmap_request, run_jmap_request
+from .mcp_server import handle_tool_call
+from .session import AgentSession, RegisterResult, create_agent_session, register
+
+__all__ = [
+    "AgentSession",
+    "Credentials",
+    "CredentialStore",
+    "JmapRequestResult",
+    "JmapAttachmentInput",
+    "RegisterResult",
+    "ResolvedAgentConfig",
+    "SkillFiles",
+    "default_files_from_out_dir",
+    "help",
+    "handle_tool_call",
+    "jmap_request",
+    "run_jmap_request",
+    "register",
+    "create_agent_session",
+    "resolve_agent_config_from_env",
+]

atomicmail/auth_http.py

@@ -0,0 +1,177 @@
+"""Auth-service HTTP helpers: challenge -> session -> capability."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Callable, Mapping
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+from .jwt_utils import decode_jwt_payload
+from .pow import solve_pow
+
+
+@dataclass
+class ChallengeResponse:
+    challengeJWT: str
+    challenge: str
+    difficulty: int
+
+
+@dataclass
+class SessionResponse:
+    sessionJWT: str
+    apiKey: str | None = None
+
+
+def fetch_challenge(auth_url: str) -> ChallengeResponse:
+    base = auth_url.rstrip("/")
+    status, text, headers = _http_post(f"{base}/api/v1/challenge")
+    if status < 200 or status >= 300:
+        raise ValueError(
+            f"auth-service /api/v1/challenge returned {status}: {text}"
+        )
+
+    challenge_jwt = _read_bearer_token(
+        headers.get("Authorization"),
+        "Challenge response missing Authorization bearer token.",
+    )
+    payload = decode_jwt_payload(challenge_jwt)
+    challenge = payload.get("jti")
+    difficulty = payload.get("difficulty")
+    if not isinstance(challenge, str) or not isinstance(difficulty, (int, float)):
+        raise ValueError("Challenge JWT payload malformed (missing jti or difficulty).")
+
+    return ChallengeResponse(
+        challengeJWT=challenge_jwt,
+        challenge=challenge,
+        difficulty=int(difficulty),
+    )
+
+
+def exchange_session(
+    auth_url: str,
+    *,
+    challenge_jwt: str,
+    pow_hex: str,
+    nonce: str,
+    api_key: str | None = None,
+    username: str | None = None,
+) -> SessionResponse:
+    base = auth_url.rstrip("/")
+    payload: dict[str, str] = {"powHex": pow_hex, "nonce": nonce}
+    if api_key:
+        payload["apiKey"] = api_key
+    if username:
+        payload["username"] = username
+
+    status, text, headers = _http_post(
+        f"{base}/api/v1/session",
+        headers={"Authorization": f"Bearer {challenge_jwt}"},
+        json_body=payload,
+    )
+    if status < 200 or status >= 300:
+        raise ValueError(f"auth-service /api/v1/session returned {status}: {text}")
+
+    session_jwt = _read_bearer_token(
+        headers.get("Authorization"),
+        "Session response missing Authorization bearer token.",
+    )
+
+    data: dict[str, object] = {}
+    if text.strip():
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError as err:
+            raise ValueError(
+                "auth-service /api/v1/session returned non-JSON body."
+            ) from err
+        if not isinstance(parsed, dict):
+            raise ValueError("auth-service /api/v1/session returned non-JSON body.")
+        data = parsed
+
+    api_key_out = data.get("apiKey")
+    return SessionResponse(
+        sessionJWT=session_jwt,
+        apiKey=api_key_out if isinstance(api_key_out, str) else None,
+    )
+
+
+def fetch_capability(auth_url: str, session_jwt: str) -> str:
+    base = auth_url.rstrip("/")
+    status, text, headers = _http_post(
+        f"{base}/api/v1/capability",
+        headers={"Authorization": f"Bearer {session_jwt}"},
+    )
+    if status < 200 or status >= 300:
+        raise ValueError(f"auth-service /api/v1/capability returned {status}: {text}")
+
+    return _read_bearer_token(
+        headers.get("Authorization"),
+        "Capability response missing Authorization bearer token.",
+    )
+
+
+def perform_pow_and_session(
+    *,
+    auth_url: str,
+    scrypt_salt: str,
+    api_key: str | None = None,
+    username: str | None = None,
+    on_pow_progress: Callable[[int], None] | None = None,
+) -> SessionResponse:
+    challenge = fetch_challenge(auth_url)
+    solved = solve_pow(
+        challenge=challenge.challenge,
+        difficulty=challenge.difficulty,
+        salt=scrypt_salt,
+        on_progress=on_pow_progress,
+    )
+    return exchange_session(
+        auth_url,
+        challenge_jwt=challenge.challengeJWT,
+        pow_hex=solved.powHex,
+        nonce=solved.nonce,
+        api_key=api_key,
+        username=username,
+    )
+
+
+def _read_bearer_token(header_value: str | None, missing_error: str) -> str:
+    if not header_value:
+        raise ValueError(missing_error)
+
+    raw = header_value.strip()
+    prefix = "bearer "
+    if not raw.lower().startswith(prefix):
+        raise ValueError("Authorization header must use Bearer scheme.")
+
+    token = raw[len(prefix) :].strip()
+    if not token:
+        raise ValueError("Authorization header must use Bearer scheme.")
+    return token
+
+
+def _http_post(
+    url: str,
+    *,
+    headers: Mapping[str, str] | None = None,
+    json_body: object | None = None,
+) -> tuple[int, str, Mapping[str, str]]:
+    req_headers = dict(headers or {})
+    body_bytes: bytes | None = None
+    if json_body is not None:
+        body_bytes = json.dumps(json_body).encode("utf-8")
+        req_headers.setdefault("Content-Type", "application/json")
+
+    req = Request(url, data=body_bytes, headers=req_headers, method="POST")
+    try:
+        with urlopen(req) as response:
+            return (
+                int(response.getcode()),
+                response.read().decode("utf-8"),
+                response.headers,
+            )
+    except HTTPError as err:
+        return err.code, err.read().decode("utf-8", errors="replace"), err.headers

atomicmail/cli.py

@@ -0,0 +1,236 @@
+"""Atomic Mail CLI adapter for Python library."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Mapping, Sequence
+
+from .help import HELP_TOPIC_LIST, help as get_help, normalize_help_topic
+from .jmap_request import DEFAULT_JMAP_USING, JmapAttachmentInput, jmap_request
+from .shared_assets import try_read_shared_json
+from .session import register
+
+
+def _shared_errors() -> dict[str, str]:
+    loaded = try_read_shared_json("messages/errors.json")
+    if isinstance(loaded, dict):
+        return {k: v for k, v in loaded.items() if isinstance(k, str) and isinstance(v, str)}
+    return {}
+
+
+_ERRORS = _shared_errors()
+
+
+def _error(key: str, fallback: str) -> str:
+    return _ERRORS.get(key, fallback)
+
+
+def _error_template(key: str, fallback: str, values: Mapping[str, str | int]) -> str:
+    out = _ERRORS.get(key, fallback)
+    for name, value in values.items():
+        out = out.replace(f"{{{name}}}", str(value))
+    return out
+
+
+def _parse_user_vars_json(raw: str) -> dict[str, str]:
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as err:
+        raise ValueError(
+            _error_template(
+                "vars_invalid_json_template",
+                "--vars is not valid JSON: {details}",
+                {"details": str(err)},
+            )
+        ) from err
+    if not isinstance(value, dict):
+        raise ValueError(_error("vars_not_object", "--vars must be a JSON object of { VAR_NAME: string }."))
+    out: dict[str, str] = {}
+    for key, item in value.items():
+        if not isinstance(key, str) or not key:
+            raise ValueError(
+                _error_template(
+                    "vars_key_invalid_template",
+                    "--vars key '{key}' must match /^[A-Z][A-Z0-9_]*$/.",
+                    {"key": str(key)},
+                )
+            )
+        if not key[0].isalpha() or not key[0].isupper():
+            raise ValueError(
+                _error_template(
+                    "vars_key_invalid_template",
+                    "--vars key '{key}' must match /^[A-Z][A-Z0-9_]*$/.",
+                    {"key": key},
+                )
+            )
+        if any((not ch.isdigit()) and (not ch.isupper()) and ch != "_" for ch in key[1:]):
+            raise ValueError(
+                _error_template(
+                    "vars_key_invalid_template",
+                    "--vars key '{key}' must match /^[A-Z][A-Z0-9_]*$/.",
+                    {"key": key},
+                )
+            )
+        if not isinstance(item, str):
+            raise ValueError(
+                _error_template(
+                    "vars_value_not_string_template",
+                    "--vars value for '{key}' must be a string.",
+                    {"key": key},
+                )
+            )
+        out[key] = item
+    return out
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="atomicmail", description="Atomic Mail Python CLI")
+    subparsers = parser.add_subparsers(dest="command")
+
+    register_cmd = subparsers.add_parser(
+        "register", help="PoW signup or API-key login and persist credentials"
+    )
+    register_mode = register_cmd.add_mutually_exclusive_group(required=True)
+    register_mode.add_argument("--username", help="Desired username (5-21 characters).")
+    register_mode.add_argument("--api-key", help="Existing API key for login.")
+    register_cmd.add_argument("--credentials-dir", help="Credential directory for this command.")
+    register_cmd.add_argument(
+        "--forced",
+        action="store_true",
+        help="Allow replacing existing credentials for a different username (username mode only).",
+    )
+
+    jmap_cmd = subparsers.add_parser("jmap_request", help="Send a JMAP request")
+    jmap_cmd.add_argument("--credentials-dir", help="Credential directory for this command.")
+    jmap_ops = jmap_cmd.add_mutually_exclusive_group(required=True)
+    jmap_ops.add_argument("--ops", help="Inline JMAP JSON.")
+    jmap_ops.add_argument("--ops-file", help="JMAP ops file path or bundled preset name.")
+    jmap_cmd.add_argument(
+        "--using",
+        help="Comma-separated capability URNs used when ops does not provide using.",
+    )
+    jmap_cmd.add_argument("--vars", help="JSON object with VAR_NAME -> string placeholder values.")
+    jmap_cmd.add_argument(
+        "--attachment",
+        action="append",
+        dest="attachments",
+        help="Attachment path; repeat for multiple files.",
+    )
+    jmap_cmd.add_argument(
+        "--attachment-path-base",
+        help="Base directory for resolving relative attachment paths.",
+    )
+    jmap_cmd.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Resolve envelope and print request without sending it.",
+    )
+
+    help_cmd = subparsers.add_parser("help", help="Print Atomic Mail help topic")
+    help_cmd.add_argument("--topic", help="Help topic; omit for overview.")
+
+    return parser
+
+
+def _cmd_register(args: argparse.Namespace) -> int:
+    if args.api_key and args.forced:
+        raise ValueError("--forced can only be used with --username.")
+
+    result = register(
+        username=args.username,
+        api_key=args.api_key,
+        credentials_dir=args.credentials_dir,
+        forced=bool(args.forced),
+    )
+    sys.stdout.write(json.dumps(result.__dict__, indent=2) + "\n")
+    return 0
+
+
+def _cmd_jmap_request(args: argparse.Namespace) -> int:
+    attachments: list[JmapAttachmentInput] | None = None
+    if args.attachments:
+        attachments = [JmapAttachmentInput(path=item) for item in args.attachments]
+    if args.dry_run and attachments:
+        raise ValueError(
+            _error(
+                "cli_dry_run_with_attachment",
+                "--dry-run cannot be combined with --attachment.",
+            )
+        )
+
+    using = list(DEFAULT_JMAP_USING)
+    if args.using:
+        using = [item.strip() for item in args.using.split(",") if item.strip()]
+
+    vars_map: dict[str, str] | None = None
+    if args.vars is not None:
+        vars_map = _parse_user_vars_json(args.vars)
+
+    result = jmap_request(
+        ops=args.ops,
+        ops_file=args.ops_file,
+        vars=vars_map,
+        dry_run=bool(args.dry_run),
+        attachments=attachments,
+        attachment_path_base=args.attachment_path_base,
+        using=using,
+        credentials_dir=args.credentials_dir,
+    )
+    sys.stdout.write(result.bodyText if result.bodyText.endswith("\n") else f"{result.bodyText}\n")
+    if result.ok:
+        return 0
+    sys.stderr.write(f"Error: JMAP request failed (HTTP {result.status}): {result.bodyText}\n")
+    return 1
+
+
+def _cmd_help(args: argparse.Namespace) -> int:
+    topic = args.topic
+    if topic is not None and normalize_help_topic(topic) == "readme":
+        # Python package does not bundle npm README lookup;
+        # we intentionally return the same shared stub text as get_help("readme").
+        sys.stdout.write(get_help("readme") + "\n")
+        return 0
+
+    sys.stdout.write(get_help(topic) + "\n")
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(list(argv) if argv is not None else None)
+
+    if not args.command:
+        parser.print_help(sys.stderr)
+        return 2
+
+    try:
+        if args.command == "register":
+            return _cmd_register(args)
+        if args.command == "jmap_request":
+            return _cmd_jmap_request(args)
+        if args.command == "help":
+            return _cmd_help(args)
+        message = _error_template(
+            "cli_unknown_command_template",
+            "Unknown command: {cmd}",
+            {"cmd": str(args.command)},
+        )
+        sys.stderr.write(f"Error: {message}\n")
+        return 2
+    except ValueError as err:
+        sys.stderr.write(f"Error: {err}\n")
+        return 2
+    except Exception as err:  # pragma: no cover - defensive CLI adapter guard
+        sys.stderr.write(f"Error: {err}\n")
+        return 1
+
+
+def console_main() -> None:
+    raise SystemExit(main())
+
+
+def help_topics_for_cli() -> str:
+    """Expose topics for tests/help text parity checks."""
+    return ", ".join(HELP_TOPIC_LIST)

atomicmail/config.py

@@ -0,0 +1,112 @@
+"""Configuration resolution for auth/api/credential defaults."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Mapping
+
+from .constants import (
+    DEFAULT_API_URL,
+    DEFAULT_AUTH_URL,
+    DEFAULT_POW_SCRYPT_SALT_HEX,
+)
+from .credentials import SkillFiles, default_files_from_out_dir, try_read_credentials
+
+ConfigSource = Literal["credentials-file", "env", "mixed", "defaults"]
+
+
+@dataclass
+class ResolvedAgentConfig:
+    authUrl: str
+    apiUrl: str
+    scryptSalt: str
+    apiKey: str | None
+    inboxId: str | None
+    credentialDir: str
+    files: SkillFiles
+    source: ConfigSource
+
+
+def resolve_credential_dir() -> str:
+    from_env = os.getenv("ATOMIC_MAIL_CREDENTIALS_DIR")
+    if from_env:
+        return from_env
+
+    home = os.getenv("HOME") or os.getenv("USERPROFILE")
+    if not home:
+        raise ValueError(
+            "Cannot determine default credential directory: HOME and USERPROFILE "
+            "are both unset. Set ATOMIC_MAIL_CREDENTIALS_DIR explicitly."
+        )
+    home_base = home.rstrip("/\\")
+    return f"{home_base}/.atomicmail"
+
+
+def expand_credential_dir_input(dir_value: str | None = None) -> str:
+    raw = dir_value or os.getenv("ATOMIC_MAIL_CREDENTIALS_DIR") or "~/.atomicmail"
+    if raw == "~":
+        return str(Path.home())
+    return str(Path(raw).expanduser().resolve())
+
+
+def _normalize_url(url: str) -> str:
+    return url.rstrip("/")
+
+
+def _pick_env(env: Mapping[str, str], key: str) -> str | None:
+    value = env.get(key)
+    return value if value else None
+
+
+def resolve_agent_config_from_env(
+    env: Mapping[str, str] | None = None,
+    credential_dir: str | None = None,
+) -> ResolvedAgentConfig:
+    current_env = env or os.environ
+    resolved_credential_dir = (
+        expand_credential_dir_input(credential_dir)
+        if credential_dir is not None
+        else resolve_credential_dir()
+    )
+    files = default_files_from_out_dir(resolved_credential_dir)
+    file_creds = try_read_credentials(files.credentialsFile)
+
+    env_auth_url = _pick_env(current_env, "ATOMIC_MAIL_AUTH_URL")
+    env_api_url = _pick_env(current_env, "ATOMIC_MAIL_API_URL")
+    env_salt = _pick_env(current_env, "ATOMIC_MAIL_SCRYPT_SALT")
+    env_api_key = _pick_env(current_env, "ATOMIC_MAIL_API_KEY")
+
+    auth_url = env_auth_url or (file_creds.authUrl if file_creds else None) or DEFAULT_AUTH_URL
+    api_url = env_api_url or (file_creds.apiUrl if file_creds else None) or DEFAULT_API_URL
+    scrypt_salt = (
+        env_salt
+        or (file_creds.scryptSalt if file_creds else None)
+        or DEFAULT_POW_SCRYPT_SALT_HEX
+    )
+    api_key = env_api_key or (file_creds.apiKey if file_creds else None)
+    inbox_id = file_creds.inboxId if file_creds else None
+
+    using_file = file_creds is not None
+    using_env = any((env_auth_url, env_api_url, env_salt, env_api_key))
+
+    if using_file and using_env:
+        source: ConfigSource = "mixed"
+    elif using_file:
+        source = "credentials-file"
+    elif using_env:
+        source = "env"
+    else:
+        source = "defaults"
+
+    return ResolvedAgentConfig(
+        authUrl=_normalize_url(auth_url),
+        apiUrl=_normalize_url(api_url),
+        scryptSalt=scrypt_salt,
+        apiKey=api_key,
+        inboxId=inbox_id,
+        credentialDir=resolved_credential_dir,
+        files=files,
+        source=source,
+    )

atomicmail/constants.py

@@ -0,0 +1,32 @@
+"""Cross-language constants loaded from shared assets."""
+
+from __future__ import annotations
+
+from .shared_assets import try_read_shared_json
+
+_DEFAULTS = {
+    "DEFAULT_POW_SCRYPT_SALT_HEX": "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083",
+    "DEFAULT_AUTH_URL": "https://auth.atomicmail.ai",
+    "DEFAULT_API_URL": "https://api.atomicmail.ai",
+    "ONE_SEC_MS": 1_000,
+    "ONE_MIN_MS": 60_000,
+    "ONE_HOUR_MS": 3_600_000,
+    "ONE_DAY_MS": 86_400_000,
+    "ONE_MONTH_MS": 2_592_000_000,
+    "ONE_YEAR_MS": 31_536_000_000,
+}
+
+_SHARED = try_read_shared_json("consts.json") or {}
+
+DEFAULT_POW_SCRYPT_SALT_HEX = _SHARED.get(
+    "DEFAULT_POW_SCRYPT_SALT_HEX", _DEFAULTS["DEFAULT_POW_SCRYPT_SALT_HEX"]
+)
+DEFAULT_AUTH_URL = _SHARED.get("DEFAULT_AUTH_URL", _DEFAULTS["DEFAULT_AUTH_URL"])
+DEFAULT_API_URL = _SHARED.get("DEFAULT_API_URL", _DEFAULTS["DEFAULT_API_URL"])
+
+ONE_SEC_MS = int(_SHARED.get("ONE_SEC_MS", _DEFAULTS["ONE_SEC_MS"]))
+ONE_MIN_MS = int(_SHARED.get("ONE_MIN_MS", _DEFAULTS["ONE_MIN_MS"]))
+ONE_HOUR_MS = int(_SHARED.get("ONE_HOUR_MS", _DEFAULTS["ONE_HOUR_MS"]))
+ONE_DAY_MS = int(_SHARED.get("ONE_DAY_MS", _DEFAULTS["ONE_DAY_MS"]))
+ONE_MONTH_MS = int(_SHARED.get("ONE_MONTH_MS", _DEFAULTS["ONE_MONTH_MS"]))
+ONE_YEAR_MS = int(_SHARED.get("ONE_YEAR_MS", _DEFAULTS["ONE_YEAR_MS"]))