tickwire-cli 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,74 @@
1
+ """``tickwire sandbox create``: a free sandbox with one simulated account, no sign-in.
2
+
3
+ Calls ``POST /v1/sandbox/signup`` (anonymous, rate limited per IP) and stores
4
+ the new ``twsk_`` key in the ``sandbox`` profile, so ``tickwire --sandbox …``
5
+ works at once. The key is shown once by the server and is not printed unless
6
+ you ask (``--show-key``). It is a **restricted** key: accounts, trading,
7
+ streaming and reads. For webhooks (``listen``, ``trigger``), sign in and create
8
+ a sandbox key with ``POST /v1/sandbox/keys``, then ``tickwire login --sandbox``.
9
+
10
+ A lost reply is reported as ``unknown`` and never retried: a retry could create
11
+ a second sandbox.
12
+ """
13
+ from __future__ import annotations
14
+
15
+ from tickwire import OutcomeUnknown, sandbox_signup
16
+
17
+ from ..credentials import SANDBOX_PROFILE
18
+ from ..errors import UsageError
19
+
20
+
21
+ def register(sub, common) -> None:
22
+ p = sub.add_parser("sandbox", parents=[common], help="the free sandbox")
23
+ ss = p.add_subparsers(dest="sandbox_command", metavar="<subcommand>")
24
+ ss.required = True
25
+ c = ss.add_parser("create", parents=[common], help="create a sandbox and store its key",
26
+ description=__doc__.split("\n\n")[1] if __doc__ else None)
27
+ c.add_argument("--platform", choices=["mt5", "mt4"], default="mt5")
28
+ c.add_argument("--no-save", action="store_true", help="do not store the key (needs --show-key)")
29
+ c.add_argument("--show-key", action="store_true", help="print the key (shown once by the server)")
30
+ c.add_argument("--force", action="store_true", help="replace the key already stored in the profile")
31
+ c.set_defaults(func=create)
32
+
33
+
34
+ def create(ctx) -> int:
35
+ args = ctx.args
36
+ if args.no_save and not args.show_key:
37
+ raise UsageError("--no-save would lose the key (the server shows it once): add --show-key")
38
+ name = args.profile or SANDBOX_PROFILE
39
+ existing = ctx.store.profile(name)
40
+ if not args.no_save and existing is not None and existing.storage and not args.force:
41
+ raise UsageError(f"profile {name!r} already holds a key ({existing.key_hint}); pass --force to "
42
+ f"replace it, or --profile <new name>")
43
+ if existing is not None and not existing.sandbox:
44
+ raise UsageError(f"profile {name!r} is a live profile; use another --profile")
45
+ url = ctx.api_url(sandbox=True)
46
+ try:
47
+ body = sandbox_signup(url, platform=args.platform, transport=ctx.transport)
48
+ except OutcomeUnknown as e:
49
+ ctx.out.error("unknown", f"{e.message}. Not retried; run `tickwire sandbox create` again only "
50
+ f"if you want another sandbox")
51
+ return 5
52
+ key = body.get("apiKey", "")
53
+ stored = None
54
+ if not args.no_save:
55
+ stored = ctx.store.save(name, key, api_url=url, sandbox=True)
56
+ account = body.get("account") or {}
57
+ data = {"sandbox": True, "restricted": bool(body.get("restricted")), "tenantId": body.get("tenantId"),
58
+ "account": account, "profile": name if stored else None,
59
+ "storage": stored.storage if stored else None,
60
+ "key": stored.key_hint if stored else None}
61
+ if args.show_key:
62
+ data["apiKey"] = key
63
+ lines = [f"Sandbox created at {url}.",
64
+ f"Account {account.get('id')} ({account.get('platform')}, login {account.get('login')}, "
65
+ f"server {account.get('server')}): {account.get('state')}, {account.get('connectionStatus')}."]
66
+ if stored:
67
+ lines.append(f"Key {stored.key_hint} stored in profile {name!r}: use `tickwire --sandbox …`.")
68
+ if args.show_key:
69
+ lines.append(f"API key (shown once): {key}")
70
+ if body.get("restricted"):
71
+ lines.append("This key is restricted (accounts, trading, reads). For webhooks, create a sandbox key "
72
+ "from your live key: POST /v1/sandbox/keys.")
73
+ ctx.out.result(data, "\n".join(lines))
74
+ return 0
@@ -0,0 +1,153 @@
1
+ """``tickwire trade open|close``: guarded, idempotent trades with a truthful outcome.
2
+
3
+ Every trade goes through ``POST /v1/execution/accounts/{id}/trade`` (the
4
+ account's pre-trade hooks apply), needs ``--reason`` (kept in the audit log)
5
+ and carries an ``Idempotency-Key``: generated when you do not pass one, and
6
+ always printed so you can repeat the *same* request safely.
7
+
8
+ The answer is one of:
9
+
10
+ ``applied`` the terminal confirmed it (exit 0)
11
+ ``no_change`` nothing needed doing, e.g. already closed (exit 0)
12
+ ``rejected`` not executed (exit 3)
13
+ ``held`` a pre-trade hook holds it for approval; nothing executed yet (exit 4)
14
+ ``unknown`` it MAY have executed (exit 5)
15
+
16
+ ``unknown`` is never retried, by the SDK or by this command. Check the account
17
+ first; to try again, pass the printed key with ``--idempotency-key`` so the
18
+ server can refuse a second execution. A server error (5xx) without an outcome
19
+ is reported as ``unknown`` too, never as a failure that is safe to repeat.
20
+ """
21
+ from __future__ import annotations
22
+
23
+ import math
24
+
25
+ from tickwire import OutcomeUnknown, TickwireError, TradeResult, new_idempotency_key
26
+
27
+ from ..errors import UsageError
28
+
29
+ EXIT = {"applied": 0, "no_change": 0, "rejected": 3, "held": 4, "unknown": 5}
30
+
31
+
32
+ def register(sub, common) -> None:
33
+ p = sub.add_parser("trade", parents=[common], help="open or close a position (needs --reason)",
34
+ description=__doc__.split("\n\n")[1] if __doc__ else None)
35
+ ss = p.add_subparsers(dest="trade_command", metavar="<subcommand>")
36
+ ss.required = True
37
+
38
+ o = ss.add_parser("open", parents=[common], help="market order")
39
+ o.add_argument("account_id")
40
+ o.add_argument("--side", choices=["buy", "sell"], required=True)
41
+ o.add_argument("--symbol", required=True)
42
+ o.add_argument("--volume", type=float, required=True, help="lots, e.g. 0.01")
43
+ o.add_argument("--sl", type=float, help="stop loss price")
44
+ o.add_argument("--tp", type=float, help="take profit price")
45
+ o.add_argument("--comment")
46
+ o.add_argument("--client-id", help="your own order tag")
47
+ _mutation_args(o)
48
+ o.set_defaults(func=trade_open)
49
+
50
+ c = ss.add_parser("close", parents=[common], help="close a position (all of it, or --volume)")
51
+ c.add_argument("account_id")
52
+ c.add_argument("position_id")
53
+ c.add_argument("--volume", type=float, help="close only this many lots")
54
+ _mutation_args(c)
55
+ c.set_defaults(func=trade_close)
56
+
57
+
58
+ def _mutation_args(p) -> None:
59
+ p.add_argument("--reason", required=True, help="why (recorded in the audit log)")
60
+ p.add_argument("--idempotency-key", help="repeat an earlier request safely (reuse its key)")
61
+
62
+
63
+ def _volume(v: float | None) -> float | None:
64
+ if v is not None and (not math.isfinite(v) or v <= 0):
65
+ raise UsageError("--volume must be a positive number of lots")
66
+ return v
67
+
68
+
69
+ def trade_open(ctx) -> int:
70
+ a = ctx.args
71
+ body = {"actionType": "ORDER_TYPE_BUY" if a.side == "buy" else "ORDER_TYPE_SELL",
72
+ "symbol": a.symbol, "volume": _volume(a.volume)}
73
+ for field, value in (("stopLoss", a.sl), ("takeProfit", a.tp), ("comment", a.comment),
74
+ ("clientId", a.client_id)):
75
+ if value is not None:
76
+ body[field] = value
77
+ return _execute(ctx, body)
78
+
79
+
80
+ def trade_close(ctx) -> int:
81
+ a = ctx.args
82
+ if a.volume is None:
83
+ body = {"actionType": "POSITION_CLOSE_ID", "positionId": str(a.position_id)}
84
+ else:
85
+ body = {"actionType": "POSITION_PARTIAL", "positionId": str(a.position_id), "volume": _volume(a.volume)}
86
+ return _execute(ctx, body)
87
+
88
+
89
+ def _execute(ctx, body: dict) -> int:
90
+ a = ctx.args
91
+ reason = (a.reason or "").strip()
92
+ if not reason:
93
+ raise UsageError("--reason must say why (it is recorded in the audit log)")
94
+ key = (a.idempotency_key or "").strip() or new_idempotency_key()
95
+ tw = ctx.client()
96
+ try:
97
+ # One call. The CLI never retries on its own; the SDK repeats it (same key)
98
+ # only when nothing ran: the connection never opened, a 409
99
+ # idempotency_in_flight, or a 429/5xx whose body says ``sent: false``.
100
+ # A bare status code never counts, and a lost reply is never retried.
101
+ result = tw.execute_trade(a.account_id, body, reason=reason, idempotency_key=key)
102
+ except OutcomeUnknown as e:
103
+ result = TradeResult.unknown(key, e.message, e.status)
104
+ except TickwireError as e:
105
+ b = e.body if isinstance(e.body, dict) else {}
106
+ if e.status is not None and _says_not_sent(b):
107
+ # The server said explicitly that nothing was sent (retries used up).
108
+ result = TradeResult(outcome="rejected", sent=False, idempotency_key=key, status=e.status,
109
+ body={**b, "error": e.code or b.get("error"), "message": e.message})
110
+ elif e.status is not None and e.status >= 500:
111
+ result = TradeResult.unknown(key, f"HTTP {e.status} with no outcome: {e.message}", e.status)
112
+ elif e.status is not None and 400 <= e.status < 500:
113
+ result = TradeResult(outcome="rejected", sent=False, idempotency_key=key, status=e.status,
114
+ body={**b, "error": e.code or b.get("error"), "message": e.message})
115
+ else:
116
+ raise # not sent (no connection): exit 1 with the SDK's message
117
+ _report(ctx, a.account_id, body, result)
118
+ return EXIT[result.outcome]
119
+
120
+
121
+ def _says_not_sent(body: dict) -> bool:
122
+ """The SDK's rule: ``sent: false`` or ``outcome: "not_sent"`` (top level or metadata)."""
123
+ meta = body.get("metadata") if isinstance(body.get("metadata"), dict) else {}
124
+ sent = body.get("sent", meta.get("sent"))
125
+ if sent is not None:
126
+ return sent is False
127
+ return body.get("outcome", meta.get("outcome")) == "not_sent"
128
+
129
+
130
+ def _report(ctx, account_id: str, request: dict, r: TradeResult) -> None:
131
+ data = {"accountId": account_id, "request": request, "outcome": r.outcome, "sent": r.sent,
132
+ "idempotencyKey": r.idempotency_key, "status": r.status, "error": r.error, "message": r.message,
133
+ "evidence": r.evidence, "holdId": r.hold_id, "replayed": r.replayed, "body": r.body}
134
+
135
+ def human() -> str:
136
+ lines = [f"outcome: {r.outcome.upper()} (sent: {str(r.sent).lower()})",
137
+ f"idempotency key: {r.idempotency_key}"]
138
+ if r.replayed:
139
+ lines.append("replayed: the server returned the answer to the first request with this key")
140
+ if r.error or r.message:
141
+ lines.append(f"{r.error or 'message'}: {r.message or ''}".rstrip(": "))
142
+ if r.evidence:
143
+ lines.append(f"evidence: {r.evidence}")
144
+ if r.outcome == "held":
145
+ lines.append(f"hold: {r.hold_id}. A pre-trade hook holds this order for approval; nothing has "
146
+ f"executed yet.")
147
+ if r.outcome == "unknown":
148
+ lines.append("The order MAY have executed. It was NOT re-sent. Check the account's positions "
149
+ "before doing anything else. To try again safely, repeat this exact command with "
150
+ f"--idempotency-key {r.idempotency_key} (the server will not execute it twice).")
151
+ return "\n".join(lines)
152
+
153
+ ctx.out.result(data, human)
@@ -0,0 +1,44 @@
1
+ """``tickwire trigger <event>``: publish one test event (``POST /v1/webhook-events/trigger``).
2
+
3
+ The event carries the catalog's example data plus ``"test": true`` and goes to
4
+ your real webhook endpoints and to running ``tickwire listen`` sessions. With a
5
+ sandbox key any catalog type works; with a live key only ``webhook.test``, so a
6
+ test trade never reaches a production handler. ``tickwire trigger --list``
7
+ shows the types.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ from ..errors import UsageError
12
+ from ..output import clean, table
13
+
14
+
15
+ def register(sub, common) -> None:
16
+ p = sub.add_parser("trigger", parents=[common], help="send a test webhook event",
17
+ description=__doc__.split("\n\n")[1] if __doc__ else None)
18
+ p.add_argument("event", nargs="?", help="event type, e.g. trade.outcome (see --list)")
19
+ p.add_argument("--account", help="put this account id in the event (must be yours)")
20
+ p.add_argument("--list", action="store_true", help="list the event types")
21
+ p.add_argument("--idempotency-key", help="repeat an earlier trigger without sending it twice")
22
+ p.set_defaults(func=trigger)
23
+
24
+
25
+ def trigger(ctx) -> int:
26
+ a = ctx.args
27
+ tw = ctx.client()
28
+ if a.list:
29
+ types = tw.webhook_event_types()
30
+ rows = types.get("data", types) if isinstance(types, dict) else types
31
+ ctx.out.result(rows, lambda: table([[t.get("type"), t.get("description")] for t in rows],
32
+ ["TYPE", "DESCRIPTION"]))
33
+ return 0
34
+ if not a.event:
35
+ raise UsageError("name an event type (tickwire trigger --list shows them)")
36
+ body = {"type": a.event}
37
+ if a.account:
38
+ body["accountId"] = a.account
39
+ out = tw.request("POST", "/webhook-events/trigger", control=True, json=body,
40
+ idempotency_key=a.idempotency_key, reason="tickwire trigger")
41
+ ctx.out.result(out, f"Triggered test event {clean(out.get('type'))} (seq {clean(out.get('seq'))}, "
42
+ f"{'sandbox' if out.get('sandbox') else 'live'}). It goes to your webhook endpoints "
43
+ f"and to running `tickwire listen` sessions.")
44
+ return 0
@@ -0,0 +1,112 @@
1
+ """``tickwire listen --forward-to <url>``: receive your webhook events on localhost.
2
+
3
+ How it works (``docs/public/cli.md`` has the full story):
4
+
5
+ 1. ``POST /v1/webhook-listeners`` creates a listener and returns its signing
6
+ secret (printed on start: configure your local handler with it).
7
+ 2. The CLI polls ``GET /v1/webhook-listeners/{id}/events``. The control plane
8
+ signs each event with the listener secret, exactly as it signs real
9
+ deliveries (``X-Tickwire-Signature`` and the Standard Webhooks headers).
10
+ 3. The CLI verifies both signatures and the timestamp before forwarding. An
11
+ event that fails verification is never forwarded: the command stops.
12
+ 4. It POSTs the exact signed bytes and headers to ``--forward-to`` and prints
13
+ the status. A failed forward is reported and not retried.
14
+
15
+ Events published while nothing was listening are not replayed, and a listener
16
+ that falls behind the server's event buffer is told so (``truncated``).
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import time
21
+ from urllib.parse import quote, urlsplit
22
+
23
+ import httpx
24
+ from tickwire import WebhookVerificationError, verify_standard_webhook, verify_webhook
25
+
26
+ from ..errors import UsageError
27
+
28
+
29
+ def register(sub, common) -> None:
30
+ p = sub.add_parser("listen", parents=[common], help="forward your webhook events to a local URL",
31
+ description=__doc__.split("\n\n")[1] if __doc__ else None)
32
+ p.add_argument("--forward-to", required=True, metavar="URL", help="e.g. http://localhost:3000/webhooks")
33
+ p.add_argument("--events", default="", help="comma-separated types or families (trade.*); default all")
34
+ p.add_argument("--interval", type=float, default=2.0, help="seconds between polls when idle (default 2)")
35
+ p.add_argument("--timeout", type=float, default=10.0, help="seconds to wait for your handler (default 10)")
36
+ p.add_argument("--once", action="store_true", help="poll once, forward what is there, and exit")
37
+ p.set_defaults(func=listen)
38
+
39
+
40
+ def _check_url(url: str) -> str:
41
+ parts = urlsplit(url)
42
+ if parts.scheme not in ("http", "https") or not parts.netloc:
43
+ raise UsageError(f"--forward-to must be an http(s) URL, e.g. http://localhost:3000/webhooks (got {url!r})")
44
+ return url
45
+
46
+
47
+ def verify_event(secret: str, headers: dict, body: bytes) -> None:
48
+ """Both signature schemes must match the listener secret; raises on any mismatch."""
49
+ verify_webhook(secret, headers, body)
50
+ verify_standard_webhook(secret, headers, body)
51
+
52
+
53
+ def listen(ctx) -> int:
54
+ a = ctx.args
55
+ target = _check_url(a.forward_to)
56
+ if a.interval <= 0 or a.timeout <= 0:
57
+ raise UsageError("--interval and --timeout must be positive")
58
+ types = [t.strip() for t in a.events.split(",") if t.strip()]
59
+ tw = ctx.client()
60
+ lst = tw.request("POST", "/webhook-listeners", control=True, reason="tickwire listen")
61
+ lid, secret, cursor = lst["id"], lst["secret"], str(lst.get("cursor") or "") # opaque "<boot>:<seq>"
62
+ ctx.out.line({"ready": True, "listener": lid, "secret": secret, "forwardTo": target, "events": types or ["*"]},
63
+ [f"Ready. Forwarding {'events ' + ','.join(types) if types else 'all events'} to {target}.",
64
+ f"Listener signing secret: {secret}",
65
+ "(verify deliveries with it locally; it is not your API key). Ctrl-C to stop."])
66
+ params: dict = {"limit": 100}
67
+ if types:
68
+ params["types"] = ",".join(types)
69
+ with httpx.Client(transport=ctx.forward_transport, timeout=a.timeout) as http:
70
+ while True:
71
+ page = tw.request("GET", f"/webhook-listeners/{quote(lid, safe='')}/events", control=True,
72
+ params={**params, "after": cursor})
73
+ if page.get("reset"):
74
+ ctx.out.note("warning: the control plane restarted; showing its event buffer from the "
75
+ "start (events from before the restart, or that already left the buffer, "
76
+ "are missing)")
77
+ elif page.get("truncated"):
78
+ ctx.out.note("warning: this listener fell behind the server's event buffer; some events "
79
+ "were skipped")
80
+ for ev in page.get("events") or []:
81
+ code = _forward(ctx, http, target, secret, ev)
82
+ if code is not None:
83
+ return code
84
+ cursor = str(page.get("cursor") or cursor)
85
+ if a.once:
86
+ return 0
87
+ if not page.get("events"):
88
+ ctx.sleep(a.interval)
89
+
90
+
91
+ def _forward(ctx, http: httpx.Client, target: str, secret: str, ev: dict) -> int | None:
92
+ body = str(ev.get("body", "")).encode()
93
+ headers = {str(k): str(v) for k, v in (ev.get("headers") or {}).items()}
94
+ base = {"seq": ev.get("seq"), "id": ev.get("id"), "type": ev.get("type")}
95
+ try:
96
+ verify_event(secret, headers, body)
97
+ except WebhookVerificationError as e:
98
+ ctx.out.error("signature_invalid", f"event {ev.get('id')} failed signature verification ({e}); "
99
+ f"nothing was forwarded. Stopping.", **base)
100
+ return 1
101
+ started = time.monotonic()
102
+ try:
103
+ resp = http.post(target, content=body, headers=headers)
104
+ except httpx.HTTPError as e:
105
+ ms = int((time.monotonic() - started) * 1000)
106
+ ctx.out.line({**base, "forwarded": False, "error": f"{type(e).__name__}: {e}", "latencyMs": ms},
107
+ f"{ev.get('type')} {ev.get('id')} -> not delivered ({type(e).__name__}); not retried")
108
+ return None
109
+ ms = int((time.monotonic() - started) * 1000)
110
+ ctx.out.line({**base, "forwarded": True, "status": resp.status_code, "latencyMs": ms},
111
+ f"{ev.get('type')} {ev.get('id')} -> [{resp.status_code}] {ms} ms")
112
+ return None
@@ -0,0 +1,259 @@
1
+ """Where the CLI keeps profiles and API keys.
2
+
3
+ * ``config.json`` (in the config directory): one entry per profile, the API URL,
4
+ whether it is the sandbox, where its key is stored and a short hint of the key
5
+ (``twsk_…a1b2``). Never the key itself.
6
+ * The key: the OS keychain (``keyring``, service ``tickwire-cli``, user = the
7
+ profile) when the ``keyring`` package is installed and has a working backend;
8
+ otherwise ``credentials.json``, created with mode ``0600`` in a ``0700``
9
+ directory. A credentials file other users can read is refused, as ``ssh``
10
+ does, instead of used.
11
+
12
+ The config directory is ``$TICKWIRE_CONFIG_DIR``, else
13
+ ``$XDG_CONFIG_HOME/tickwire``, else ``~/.config/tickwire``.
14
+
15
+ ``TICKWIRE_API_KEY`` in the environment always wins over a stored key, so CI
16
+ jobs need no login.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import json
21
+ import os
22
+ import secrets
23
+ import stat
24
+ from collections.abc import Mapping
25
+ from dataclasses import dataclass
26
+ from pathlib import Path
27
+ from typing import Any
28
+
29
+ KEYRING_SERVICE = "tickwire-cli"
30
+ CONFIG_FILE = "config.json"
31
+ CREDENTIALS_FILE = "credentials.json"
32
+ DEFAULT_PROFILE = "default"
33
+ SANDBOX_PROFILE = "sandbox"
34
+
35
+
36
+ class CredentialError(Exception):
37
+ """No usable credential, or an unsafe credentials file."""
38
+
39
+
40
+ def config_dir(env: Mapping[str, str] | None = None) -> Path:
41
+ env = os.environ if env is None else env
42
+ if env.get("TICKWIRE_CONFIG_DIR"):
43
+ return Path(env["TICKWIRE_CONFIG_DIR"]).expanduser()
44
+ base = env.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
45
+ return Path(base).expanduser() / "tickwire"
46
+
47
+
48
+ def key_hint(key: str) -> str:
49
+ """Enough to recognise a key, never enough to use it."""
50
+ prefix = key.split("_", 1)[0] + "_" if "_" in key[:12] else ""
51
+ return f"{prefix}…{key[-4:]}" if len(key) >= 12 else "…"
52
+
53
+
54
+ def load_keyring(module: Any = "auto") -> Any | None:
55
+ """The ``keyring`` module when it has a working backend, else ``None``."""
56
+ if module is None:
57
+ return None
58
+ if module != "auto":
59
+ return module
60
+ try:
61
+ import keyring # type: ignore[import-not-found]
62
+ from keyring.backends import fail # type: ignore[import-not-found]
63
+ except Exception: # noqa: BLE001 - not installed or broken: use the file
64
+ return None
65
+ try:
66
+ backend = keyring.get_keyring()
67
+ if isinstance(backend, fail.Keyring) or getattr(backend, "priority", 1) <= 0:
68
+ return None
69
+ except Exception: # noqa: BLE001
70
+ return None
71
+ return keyring
72
+
73
+
74
+ @dataclass
75
+ class Profile:
76
+ name: str
77
+ api_url: str = ""
78
+ sandbox: bool = False
79
+ storage: str = "" # "keyring" | "file" | "" (no key stored)
80
+ key_hint: str = ""
81
+
82
+ def public(self) -> dict:
83
+ return {"profile": self.name, "apiUrl": self.api_url, "sandbox": self.sandbox,
84
+ "storage": self.storage or None, "key": self.key_hint or None}
85
+
86
+
87
+ class CredentialStore:
88
+ def __init__(self, directory: Path | None = None, *, keyring_module: Any = "auto",
89
+ env: Mapping[str, str] | None = None) -> None:
90
+ self.env = os.environ if env is None else env
91
+ self.dir = directory or config_dir(self.env)
92
+ self._keyring_arg = keyring_module
93
+ self._keyring: Any = "unset"
94
+
95
+ # ---- keyring
96
+ @property
97
+ def keyring(self) -> Any | None:
98
+ if self._keyring == "unset":
99
+ self._keyring = load_keyring(self._keyring_arg)
100
+ return self._keyring
101
+
102
+ # ---- files
103
+ def _ensure_dir(self) -> None:
104
+ """Create the config directory 0700. A directory that already exists is never
105
+ chmod-ed (it may be one the user chose, e.g. ``$HOME``); it must not be a
106
+ symlink and must belong to us."""
107
+ if not self.dir.exists():
108
+ self.dir.parent.mkdir(parents=True, exist_ok=True)
109
+ try:
110
+ self.dir.mkdir(mode=0o700)
111
+ except FileExistsError:
112
+ pass
113
+ else:
114
+ if os.name != "nt":
115
+ os.chmod(self.dir, 0o700) # umask-proof, on the directory we just made
116
+ self._check_dir()
117
+
118
+ def _check_dir(self) -> None:
119
+ st = os.lstat(self.dir)
120
+ if stat.S_ISLNK(st.st_mode) or not stat.S_ISDIR(st.st_mode):
121
+ raise CredentialError(f"{self.dir} is not a plain directory (a symlink?); refusing to use it")
122
+ if os.name != "nt" and st.st_uid != os.getuid():
123
+ raise CredentialError(f"{self.dir} belongs to another user; refusing to use it")
124
+
125
+ def _read_json(self, name: str, *, private: bool) -> dict:
126
+ path = self.dir / name
127
+ try:
128
+ st = os.lstat(path)
129
+ except FileNotFoundError:
130
+ return {}
131
+ if stat.S_ISLNK(st.st_mode) or not stat.S_ISREG(st.st_mode):
132
+ raise CredentialError(f"{path} is not a regular file (a symlink?); refusing to use it")
133
+ if private and os.name != "nt":
134
+ self._check_dir()
135
+ if st.st_uid != os.getuid():
136
+ raise CredentialError(f"{path} belongs to another user; refusing to use it")
137
+ mode = stat.S_IMODE(st.st_mode)
138
+ if mode & 0o077:
139
+ raise CredentialError(
140
+ f"{path} can be read by other users (mode {mode:o}); refusing to use it. "
141
+ f"Run: chmod 600 {path}")
142
+ flags = os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)
143
+ fd = os.open(path, flags)
144
+ try:
145
+ with os.fdopen(fd, "r", encoding="utf-8") as fh:
146
+ text = fh.read()
147
+ except OSError:
148
+ raise CredentialError(f"cannot read {path}") from None
149
+ try:
150
+ data = json.loads(text or "{}")
151
+ except ValueError:
152
+ raise CredentialError(f"{path} is not valid JSON; fix or delete it") from None
153
+ return data if isinstance(data, dict) else {}
154
+
155
+ def _write_json(self, name: str, data: dict, *, private: bool) -> None:
156
+ """Write a fresh, exclusively created temp file (never following a symlink),
157
+ then rename it over the target atomically."""
158
+ self._ensure_dir()
159
+ path = self.dir / name
160
+ mode = 0o600 if private else 0o644
161
+ flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0)
162
+ for _ in range(10):
163
+ tmp = path.with_name(f".{path.name}.{secrets.token_hex(6)}.tmp")
164
+ try:
165
+ fd = os.open(tmp, flags, mode)
166
+ break
167
+ except FileExistsError:
168
+ continue
169
+ else:
170
+ raise CredentialError(f"cannot create a temporary file in {self.dir}")
171
+ try:
172
+ try:
173
+ if os.name != "nt":
174
+ os.fchmod(fd, mode) # umask-proof
175
+ os.write(fd, (json.dumps(data, indent=2, sort_keys=True) + "\n").encode())
176
+ os.fsync(fd)
177
+ finally:
178
+ os.close(fd)
179
+ os.replace(tmp, path)
180
+ except BaseException:
181
+ try:
182
+ os.unlink(tmp)
183
+ except OSError:
184
+ pass
185
+ raise
186
+
187
+ # ---- profiles
188
+ def profiles(self) -> dict[str, Profile]:
189
+ raw = self._read_json(CONFIG_FILE, private=False).get("profiles", {})
190
+ out = {}
191
+ for name, p in raw.items():
192
+ if isinstance(p, dict):
193
+ out[name] = Profile(name=name, api_url=p.get("api_url", ""), sandbox=bool(p.get("sandbox")),
194
+ storage=p.get("storage", ""), key_hint=p.get("key_hint", ""))
195
+ return out
196
+
197
+ def profile(self, name: str) -> Profile | None:
198
+ return self.profiles().get(name)
199
+
200
+ def _save_profiles(self, profiles: dict[str, Profile]) -> None:
201
+ self._write_json(CONFIG_FILE, {"profiles": {
202
+ n: {"api_url": p.api_url, "sandbox": p.sandbox, "storage": p.storage, "key_hint": p.key_hint}
203
+ for n, p in profiles.items()}}, private=False)
204
+
205
+ # ---- keys
206
+ def save(self, name: str, key: str, *, api_url: str, sandbox: bool, use_keyring: bool = True) -> Profile:
207
+ """Store ``key`` for profile ``name``; returns the profile (with where it went)."""
208
+ key = key.strip()
209
+ if not key:
210
+ raise CredentialError("empty key")
211
+ storage = "file"
212
+ kr = self.keyring if use_keyring else None
213
+ if kr is not None:
214
+ try:
215
+ kr.set_password(KEYRING_SERVICE, name, key)
216
+ storage = "keyring"
217
+ except Exception: # noqa: BLE001 - locked or unavailable keychain: fall back to the file
218
+ storage = "file"
219
+ creds = self._read_json(CREDENTIALS_FILE, private=True)
220
+ if storage == "file":
221
+ creds[name] = key
222
+ else:
223
+ creds.pop(name, None)
224
+ if creds or (self.dir / CREDENTIALS_FILE).exists():
225
+ self._write_json(CREDENTIALS_FILE, creds, private=True)
226
+ profiles = self.profiles()
227
+ profiles[name] = Profile(name=name, api_url=api_url, sandbox=sandbox, storage=storage,
228
+ key_hint=key_hint(key))
229
+ self._save_profiles(profiles)
230
+ return profiles[name]
231
+
232
+ def key(self, name: str) -> str | None:
233
+ p = self.profile(name)
234
+ if p is None:
235
+ return None
236
+ if p.storage == "keyring":
237
+ kr = self.keyring
238
+ if kr is None:
239
+ raise CredentialError(f"profile {name!r} keeps its key in the OS keychain, but no keychain "
240
+ f"is available now (install the keyring package, or log in again)")
241
+ return kr.get_password(KEYRING_SERVICE, name)
242
+ return self._read_json(CREDENTIALS_FILE, private=True).get(name)
243
+
244
+ def delete(self, name: str) -> bool:
245
+ profiles = self.profiles()
246
+ p = profiles.pop(name, None)
247
+ if p is None:
248
+ return False
249
+ if p.storage == "keyring" and self.keyring is not None:
250
+ try:
251
+ self.keyring.delete_password(KEYRING_SERVICE, name)
252
+ except Exception: # noqa: BLE001 - already gone
253
+ pass
254
+ creds = self._read_json(CREDENTIALS_FILE, private=True)
255
+ if name in creds:
256
+ creds.pop(name)
257
+ self._write_json(CREDENTIALS_FILE, creds, private=True)
258
+ self._save_profiles(profiles)
259
+ return True
tickwire_cli/errors.py ADDED
@@ -0,0 +1,6 @@
1
+ """CLI-side errors (API errors are the SDK's ``TickwireError``)."""
2
+ from __future__ import annotations
3
+
4
+
5
+ class UsageError(Exception):
6
+ """A problem the user fixes by changing the command or logging in (exit 2)."""