formist-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.
- formist_cli/__init__.py +1 -0
- formist_cli/__main__.py +3 -0
- formist_cli/airtable.py +238 -0
- formist_cli/alerts.py +207 -0
- formist_cli/api.py +1027 -0
- formist_cli/chat.py +618 -0
- formist_cli/chats.py +517 -0
- formist_cli/cli.py +1367 -0
- formist_cli/cli_support.py +221 -0
- formist_cli/connectors.py +358 -0
- formist_cli/context.py +164 -0
- formist_cli/diff.py +943 -0
- formist_cli/doctor.py +128 -0
- formist_cli/export.py +427 -0
- formist_cli/files.py +670 -0
- formist_cli/importer.py +425 -0
- formist_cli/kb.py +185 -0
- formist_cli/login.py +615 -0
- formist_cli/logs.py +781 -0
- formist_cli/meetings.py +200 -0
- formist_cli/messages.py +414 -0
- formist_cli/participants.py +402 -0
- formist_cli/prefs.py +328 -0
- formist_cli/privileges.py +375 -0
- formist_cli/projects.py +127 -0
- formist_cli/resolve.py +443 -0
- formist_cli/settings.py +199 -0
- formist_cli/skill_library.py +246 -0
- formist_cli/skills.py +308 -0
- formist_cli/space_plan.py +411 -0
- formist_cli/spaces.py +693 -0
- formist_cli/targets.py +153 -0
- formist_cli/textnorm.py +26 -0
- formist_cli/tokens.py +339 -0
- formist_cli/update.py +433 -0
- formist_cli/uploads.py +928 -0
- formist_cli/usage_tokens.py +152 -0
- formist_cli/users.py +384 -0
- formist_cli/whatsapp.py +451 -0
- formist_cli-0.1.0.dist-info/METADATA +176 -0
- formist_cli-0.1.0.dist-info/RECORD +44 -0
- formist_cli-0.1.0.dist-info/WHEEL +4 -0
- formist_cli-0.1.0.dist-info/entry_points.txt +2 -0
- formist_cli-0.1.0.dist-info/licenses/LICENSE +21 -0
formist_cli/targets.py
ADDED
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
"""Which deployment a command talks to.
|
|
2
|
+
|
|
3
|
+
``fm`` talks to ``https://api.formist.ai`` unless ``--host`` names another
|
|
4
|
+
deployment. ``--host`` takes either a name from :data:`HOSTS` or an API origin
|
|
5
|
+
(``https://api.example.com``, ``127.0.0.1:8160``) for a custom deployment.
|
|
6
|
+
|
|
7
|
+
Spaces are addressed by UUID, never by name: names are not unique, so a name can
|
|
8
|
+
silently pick the wrong space.
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
from __future__ import annotations
|
|
12
|
+
|
|
13
|
+
import re
|
|
14
|
+
from dataclasses import dataclass
|
|
15
|
+
from urllib.parse import urlparse
|
|
16
|
+
|
|
17
|
+
#: Deployment kinds. ``env`` on a :class:`Target` is one of these; it decides how
|
|
18
|
+
#: the server is expected to behave (multi-region admin routing, local dev), not
|
|
19
|
+
#: where credentials are stored (that is :attr:`Target.name`).
|
|
20
|
+
REGION_LOCAL = "local"
|
|
21
|
+
REGION_GLOBAL = "global"
|
|
22
|
+
REGION_AE = "ae"
|
|
23
|
+
REGION_FORMIST = "formist"
|
|
24
|
+
REGION_CUSTOM = "custom"
|
|
25
|
+
|
|
26
|
+
VALID_ENVS = (REGION_LOCAL, REGION_AE, REGION_GLOBAL, REGION_FORMIST, REGION_CUSTOM)
|
|
27
|
+
|
|
28
|
+
#: Deployments that serve the whole ``/admin`` surface themselves. A regional
|
|
29
|
+
#: Evane host (``evane-ae``) serves only a region-local subset and answers 410
|
|
30
|
+
#: for the rest.
|
|
31
|
+
ADMIN_ONLY_ENVS = (REGION_GLOBAL, REGION_FORMIST, REGION_CUSTOM)
|
|
32
|
+
|
|
33
|
+
DEFAULT_HOST = "formist"
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
@dataclass(frozen=True)
|
|
37
|
+
class HostSpec:
|
|
38
|
+
"""One named deployment."""
|
|
39
|
+
|
|
40
|
+
name: str
|
|
41
|
+
api_base: str
|
|
42
|
+
env: str
|
|
43
|
+
product: str
|
|
44
|
+
description: str
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
HOSTS: dict[str, HostSpec] = {
|
|
48
|
+
"formist": HostSpec(
|
|
49
|
+
"formist", "https://api.formist.ai", REGION_FORMIST, "Formist", "Formist"
|
|
50
|
+
),
|
|
51
|
+
"evane": HostSpec(
|
|
52
|
+
"evane", "https://api.evane.ai", REGION_GLOBAL, "Evane", "Evane, Global region"
|
|
53
|
+
),
|
|
54
|
+
"evane-ae": HostSpec(
|
|
55
|
+
"evane-ae", "https://ae.api.evane.ai", REGION_AE, "Evane", "Evane, UAE region"
|
|
56
|
+
),
|
|
57
|
+
"formist-cn": HostSpec(
|
|
58
|
+
"formist-cn",
|
|
59
|
+
"https://formist-api.we-carbon.com",
|
|
60
|
+
REGION_FORMIST,
|
|
61
|
+
"Formist",
|
|
62
|
+
"Formist China",
|
|
63
|
+
),
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
_UUID_RE = re.compile(
|
|
67
|
+
r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
|
|
68
|
+
)
|
|
69
|
+
_LOOPBACK = {"127.0.0.1", "localhost", "::1"}
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class TargetError(Exception):
|
|
73
|
+
"""A refusal to point at something. The message is written for the user."""
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
@dataclass(frozen=True)
|
|
77
|
+
class Target:
|
|
78
|
+
"""A resolved destination.
|
|
79
|
+
|
|
80
|
+
``name`` keys the stored credential and is what the user typed (or the
|
|
81
|
+
default); ``env`` is the deployment kind (see :data:`VALID_ENVS`).
|
|
82
|
+
"""
|
|
83
|
+
|
|
84
|
+
env: str
|
|
85
|
+
api_base: str
|
|
86
|
+
name: str = DEFAULT_HOST
|
|
87
|
+
product: str | None = None
|
|
88
|
+
|
|
89
|
+
@property
|
|
90
|
+
def is_prod(self) -> bool:
|
|
91
|
+
return self.env != REGION_LOCAL
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def is_admin_env(env: str) -> bool:
|
|
95
|
+
"""True when a deployment of kind ``env`` serves ``/admin`` itself."""
|
|
96
|
+
return env in ADMIN_ONLY_ENVS
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def host_names() -> tuple[str, ...]:
|
|
100
|
+
return tuple(HOSTS)
|
|
101
|
+
|
|
102
|
+
|
|
103
|
+
def _custom(value: str) -> Target:
|
|
104
|
+
parsed = urlparse(value if "://" in value else f"//{value}", scheme="")
|
|
105
|
+
host = (parsed.hostname or "").lower()
|
|
106
|
+
if not host or parsed.path not in ("", "/") or parsed.query or parsed.fragment:
|
|
107
|
+
raise TargetError(
|
|
108
|
+
f"--host {value!r} is neither a known deployment "
|
|
109
|
+
f"({', '.join(HOSTS)}) nor an API origin such as "
|
|
110
|
+
"https://api.example.com or 127.0.0.1:8160."
|
|
111
|
+
)
|
|
112
|
+
loopback = host in _LOOPBACK
|
|
113
|
+
scheme = parsed.scheme or ("http" if loopback else "https")
|
|
114
|
+
if scheme not in ("http", "https"):
|
|
115
|
+
raise TargetError(f"--host {value!r}: only http and https are supported.")
|
|
116
|
+
netloc = f"{host}:{parsed.port}" if parsed.port else host
|
|
117
|
+
if ":" in host:
|
|
118
|
+
netloc = f"[{host}]:{parsed.port}" if parsed.port else f"[{host}]"
|
|
119
|
+
return Target(
|
|
120
|
+
env=REGION_LOCAL if loopback else REGION_CUSTOM,
|
|
121
|
+
api_base=f"{scheme}://{netloc}",
|
|
122
|
+
name=netloc,
|
|
123
|
+
)
|
|
124
|
+
|
|
125
|
+
|
|
126
|
+
def resolve(host: str | None) -> Target:
|
|
127
|
+
"""Resolve ``--host`` to a :class:`Target`. ``None`` means :data:`DEFAULT_HOST`."""
|
|
128
|
+
value = (host or DEFAULT_HOST).strip()
|
|
129
|
+
if not value:
|
|
130
|
+
value = DEFAULT_HOST
|
|
131
|
+
spec = HOSTS.get(value.lower())
|
|
132
|
+
if spec is None:
|
|
133
|
+
return _custom(value)
|
|
134
|
+
return Target(env=spec.env, api_base=spec.api_base, name=spec.name, product=spec.product)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def check_api_base(url: str) -> None:
|
|
138
|
+
"""Refuse a base URL that has no hostname."""
|
|
139
|
+
parsed = urlparse(url if "://" in url else f"//{url}")
|
|
140
|
+
if not parsed.hostname:
|
|
141
|
+
raise TargetError(f"could not read a hostname out of {url!r}")
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def require_space_id(value: str) -> str:
|
|
145
|
+
"""A space is addressed by its UUID, never by name."""
|
|
146
|
+
value = value.strip()
|
|
147
|
+
if not _UUID_RE.match(value):
|
|
148
|
+
raise TargetError(
|
|
149
|
+
f"--space needs a space id (a UUID), got {value!r}. fm never looks a "
|
|
150
|
+
"space up by name, because names are not unique. Find the id with "
|
|
151
|
+
"`fm spaces`."
|
|
152
|
+
)
|
|
153
|
+
return value
|
formist_cli/textnorm.py
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"""Character tables used to normalise text before comparing it.
|
|
2
|
+
|
|
3
|
+
``fm diff`` and ``fm ai-benchmark`` both decide whether two pieces of
|
|
4
|
+
text are the same, under different rules: ``diff`` matches a source
|
|
5
|
+
row against a database row to decide a write, and is case-sensitive,
|
|
6
|
+
since folding case can match the wrong row. ``ai-benchmark`` looks for
|
|
7
|
+
an expected string inside a model's prose answer, and folds case. The
|
|
8
|
+
two commands keep separate comparison rules but share the same
|
|
9
|
+
Unicode facts: which characters are a space, a quote, or a dash.
|
|
10
|
+
|
|
11
|
+
Stdlib only: this module must not add a runtime dependency.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
#: Unicode spaces mapped to U+0020. A bare ``.strip()`` already removes
|
|
17
|
+
#: most of these; the table is load-bearing for U+200B and U+FEFF,
|
|
18
|
+
#: which are ``isspace()``-false, unmatched by ``\s``, and untouched by
|
|
19
|
+
#: NFKC.
|
|
20
|
+
SPACES = " "
|
|
21
|
+
|
|
22
|
+
#: Curly quotes and the prime, mapped to their straight equivalents.
|
|
23
|
+
QUOTES = {"‘": "'", "’": "'", "“": '"', "”": '"', "′": "'"}
|
|
24
|
+
|
|
25
|
+
#: En/em/figure/non-breaking dashes and the minus sign, mapped to ``-``.
|
|
26
|
+
DASHES = {"‐": "-", "‑": "-", "‒": "-", "–": "-", "—": "-", "−": "-"}
|
formist_cli/tokens.py
ADDED
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
"""Session-token storage for ``fm``: on disk at 0600, never on a terminal.
|
|
2
|
+
|
|
3
|
+
A token that has to be handed around by hand ends up in scrollback, in
|
|
4
|
+
history, and in transcripts. ``fm login`` puts it in a file only this
|
|
5
|
+
user can read; ``fm logout`` removes it. Nothing here ever prints a
|
|
6
|
+
token, and :func:`describe_meta` deliberately returns metadata rather
|
|
7
|
+
than the credential.
|
|
8
|
+
|
|
9
|
+
The file is per-environment, so a local token can never be sent to prod
|
|
10
|
+
by accident: the target picks the file, not the other way round.
|
|
11
|
+
|
|
12
|
+
The access token itself is opaque (``crst_at_...``): since ``fm login``
|
|
13
|
+
is an OAuth client there is nothing in it to decode, which is exactly
|
|
14
|
+
what makes it revocable. Anything worth reporting about a stored
|
|
15
|
+
credential (expiry, scopes, who issued it) was already written to the
|
|
16
|
+
metadata beside it at the moment ``fm login``/refresh minted it
|
|
17
|
+
(:func:`formist_cli.login.store_payload`); see :func:`describe_meta`,
|
|
18
|
+
which reads that instead of the token.
|
|
19
|
+
|
|
20
|
+
The one exception to "on disk, never on a terminal" is ``$EVANE_TOKEN``
|
|
21
|
+
(see :func:`env_token`): one credential environment variable, for CI and
|
|
22
|
+
unattended machines that have no browser to run ``fm login`` in. It is
|
|
23
|
+
read fresh on every invocation, wins over whatever is on disk for that
|
|
24
|
+
call, and is never written to a file and never refreshed; a CI token
|
|
25
|
+
that expires gets re-issued by whoever owns it, the same as the
|
|
26
|
+
file-based one needs a fresh ``fm login`` after 30 days.
|
|
27
|
+
"""
|
|
28
|
+
|
|
29
|
+
from __future__ import annotations
|
|
30
|
+
|
|
31
|
+
import json
|
|
32
|
+
import os
|
|
33
|
+
import re
|
|
34
|
+
import stat
|
|
35
|
+
from dataclasses import dataclass
|
|
36
|
+
from datetime import datetime, timezone
|
|
37
|
+
from pathlib import Path
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class TokenError(Exception):
|
|
41
|
+
"""Something wrong with a stored credential. Never contains the credential."""
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
CONFIG_DIR_VAR = "FORMIST_CONFIG_DIR"
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def config_dir() -> Path:
|
|
48
|
+
"""``$FORMIST_CONFIG_DIR``, else ``$XDG_CONFIG_HOME/formist``, else ``~/.config/formist``.
|
|
49
|
+
|
|
50
|
+
Public, and the only implementation: this resolves where the
|
|
51
|
+
credentials live, and a second copy of this logic elsewhere would risk
|
|
52
|
+
`fm logout` one day clearing a directory that `fm login` did not write
|
|
53
|
+
to, with the symptom being a token that survives a logout.
|
|
54
|
+
"""
|
|
55
|
+
explicit = os.environ.get(CONFIG_DIR_VAR)
|
|
56
|
+
if explicit:
|
|
57
|
+
return Path(explicit).expanduser()
|
|
58
|
+
xdg = os.environ.get("XDG_CONFIG_HOME")
|
|
59
|
+
base = Path(xdg).expanduser() if xdg else Path.home() / ".config"
|
|
60
|
+
return base / "formist"
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _file_key(name: str) -> str:
|
|
64
|
+
"""A host name or ``host:port`` as a safe file-name component."""
|
|
65
|
+
return re.sub(r"[^A-Za-z0-9._-]", "_", name)
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def token_path(env: str) -> Path:
|
|
69
|
+
"""The credential file for one host (``env`` is :attr:`Target.name`)."""
|
|
70
|
+
return config_dir() / f"token-{_file_key(env)}.json"
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
#: The one credential environment variable this CLI reads.
|
|
74
|
+
ENV_TOKEN_VAR = "FORMIST_TOKEN"
|
|
75
|
+
|
|
76
|
+
#: The origin :func:`load_for` reports when the credential came from
|
|
77
|
+
#: :data:`ENV_TOKEN_VAR` rather than any environment's file. Never equal to a real
|
|
78
|
+
#: env name (``local`` / ``global`` / ``ae``), so ``origin == env`` (the
|
|
79
|
+
#: "not borrowed from another region" check callers already do) stays correct
|
|
80
|
+
#: unchanged.
|
|
81
|
+
ENV_TOKEN_ORIGIN = "env"
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def _looks_like_a_session_jwt(value: str) -> bool:
|
|
85
|
+
"""True for a 3-segment dot-separated value, the shape an old pasted-browser
|
|
86
|
+
credential had. An `fm login` token is opaque (``crst_at_...``, no dots at
|
|
87
|
+
all), so this shape is never a legitimate value here.
|
|
88
|
+
|
|
89
|
+
Refusing it is the one guard code can actually run: `fm` cannot tell a stolen
|
|
90
|
+
*opaque* token from a legitimate one (that is what "opaque" means), but it can
|
|
91
|
+
tell that a JWT landed in the wrong variable, which would hand `fm` a 7-day
|
|
92
|
+
whole-account credential instead of the scoped, revocable one the OAuth flow
|
|
93
|
+
exists to provide.
|
|
94
|
+
"""
|
|
95
|
+
parts = value.split(".")
|
|
96
|
+
return len(parts) == 3 and all(parts)
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def env_token() -> str:
|
|
100
|
+
"""``$EVANE_TOKEN``, stripped; ``""`` when unset or blank.
|
|
101
|
+
|
|
102
|
+
Raises :class:`TokenError` rather than silently ignoring a JWT-shaped
|
|
103
|
+
value, so a CI job that exported the wrong secret gets one clear
|
|
104
|
+
message instead of a hard-to-place 401 (or worse, a working-but-wrong
|
|
105
|
+
request against someone else's session).
|
|
106
|
+
"""
|
|
107
|
+
raw = (os.environ.get(ENV_TOKEN_VAR) or "").strip()
|
|
108
|
+
if raw and _looks_like_a_session_jwt(raw):
|
|
109
|
+
raise TokenError(
|
|
110
|
+
f"{ENV_TOKEN_VAR} looks like a browser session token (three "
|
|
111
|
+
"dot-separated segments), not an `fm login` credential. `fm login` "
|
|
112
|
+
"tokens are opaque and never contain a dot. Mint one with `fm login` "
|
|
113
|
+
"and export the 'token' field of the file it writes "
|
|
114
|
+
f"({token_path('<env>')}) instead."
|
|
115
|
+
)
|
|
116
|
+
return raw
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def local_scopes(env: str) -> list | None:
|
|
120
|
+
"""The scopes ``fm`` can claim to know about ``env``'s credential, for
|
|
121
|
+
:func:`formist_cli.privileges.check`'s LOCAL pre-flight ONLY.
|
|
122
|
+
|
|
123
|
+
``None`` whenever :data:`ENV_TOKEN_VAR` is set: an env-sourced token is opaque
|
|
124
|
+
and this process never learns what it was granted, so a FILE's recorded scopes
|
|
125
|
+
(if one happens to exist for the same env) describe a DIFFERENT credential than
|
|
126
|
+
the one actually in use and must not be consulted. ``privileges.check`` already
|
|
127
|
+
treats ``None`` as "not recorded, defer to the server", the correct answer
|
|
128
|
+
here too, and the same answer an operator who never logged in locally at all
|
|
129
|
+
would get.
|
|
130
|
+
"""
|
|
131
|
+
if env_token():
|
|
132
|
+
return None
|
|
133
|
+
return load_meta(env).get("scopes")
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
def store(env: str, token: str, meta: dict | None = None) -> Path:
|
|
137
|
+
"""Write ``token`` for ``env`` at 0600, creating the directory at 0700.
|
|
138
|
+
|
|
139
|
+
The mode is set BEFORE the write where the platform allows it (``os.open``
|
|
140
|
+
with the mode argument), so the secret is never briefly world-readable;
|
|
141
|
+
a chmod after the fact leaves a window.
|
|
142
|
+
|
|
143
|
+
``meta`` holds what `fm login` learned at the same moment: the ``refresh_token``
|
|
144
|
+
(a secret, and the reason this whole file is 0600), the granted ``scopes``, the
|
|
145
|
+
absolute ``expires_at``, and the ``client_id`` / ``grant_id`` `fm logout` needs
|
|
146
|
+
in order to revoke server-side. They live in the same file rather than a second
|
|
147
|
+
one because they describe THIS credential: a metadata file that could outlive
|
|
148
|
+
its token, or be swapped for another environment's, is a way to revoke the wrong
|
|
149
|
+
thing. :func:`load_meta` never returns either secret.
|
|
150
|
+
"""
|
|
151
|
+
directory = config_dir()
|
|
152
|
+
directory.mkdir(parents=True, exist_ok=True)
|
|
153
|
+
os.chmod(directory, stat.S_IRWXU) # 0700
|
|
154
|
+
|
|
155
|
+
path = token_path(env)
|
|
156
|
+
payload = json.dumps(
|
|
157
|
+
{"env": env, "token": token, "stored_at": _now_iso(), **(meta or {})}, indent=2
|
|
158
|
+
)
|
|
159
|
+
fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, stat.S_IRUSR | stat.S_IWUSR)
|
|
160
|
+
try:
|
|
161
|
+
os.write(fd, payload.encode())
|
|
162
|
+
finally:
|
|
163
|
+
os.close(fd)
|
|
164
|
+
os.chmod(path, stat.S_IRUSR | stat.S_IWUSR) # 0600, belt and braces
|
|
165
|
+
return path
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def _refuse_loose_permissions(path: Path, env: str) -> None:
|
|
169
|
+
"""Refuse a credential file anyone else can read.
|
|
170
|
+
|
|
171
|
+
Its own function because the file now holds TWO secrets (the access token and
|
|
172
|
+
the refresh token) read by two callers, and a permission check that guarded one
|
|
173
|
+
of them would be a check that cannot fail for the other.
|
|
174
|
+
"""
|
|
175
|
+
mode = path.stat().st_mode
|
|
176
|
+
if mode & (stat.S_IRWXG | stat.S_IRWXO):
|
|
177
|
+
raise TokenError(
|
|
178
|
+
f"{path} is readable by others (mode {stat.filemode(mode)}). "
|
|
179
|
+
"Refusing to use it. Run `fm logout --env "
|
|
180
|
+
f"{env}` and `fm login --host {env}` to replace it."
|
|
181
|
+
)
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
def load(env: str) -> str | None:
|
|
185
|
+
"""The stored token for ``env``, or None. Refuses a file with loose permissions."""
|
|
186
|
+
path = token_path(env)
|
|
187
|
+
if not path.exists():
|
|
188
|
+
return None
|
|
189
|
+
_refuse_loose_permissions(path, env)
|
|
190
|
+
try:
|
|
191
|
+
return json.loads(path.read_text()).get("token") or None
|
|
192
|
+
except (json.JSONDecodeError, OSError) as exc:
|
|
193
|
+
raise TokenError(f"could not read {path}: {exc}") from exc
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def load_meta(env: str) -> dict:
|
|
197
|
+
"""The non-secret facts stored beside the credential. Never the credential.
|
|
198
|
+
|
|
199
|
+
Returns ``{}`` when there is no file, when it is unreadable, or when it was
|
|
200
|
+
written by a pre-``fm login``-flow version that stored only a token: a missing
|
|
201
|
+
``token_id`` must degrade to "revoke whatever credential this request carries",
|
|
202
|
+
not to a crash.
|
|
203
|
+
"""
|
|
204
|
+
path = token_path(env)
|
|
205
|
+
if not path.exists():
|
|
206
|
+
return {}
|
|
207
|
+
try:
|
|
208
|
+
data = json.loads(path.read_text())
|
|
209
|
+
except (json.JSONDecodeError, OSError):
|
|
210
|
+
return {}
|
|
211
|
+
if not isinstance(data, dict):
|
|
212
|
+
return {}
|
|
213
|
+
return {k: v for k, v in data.items() if k not in ("token", "refresh_token")}
|
|
214
|
+
|
|
215
|
+
|
|
216
|
+
def load_refresh(env: str) -> str | None:
|
|
217
|
+
"""The stored refresh token, or None. Same 0600 refusal as :func:`load`.
|
|
218
|
+
|
|
219
|
+
Separate from :func:`load_meta` on purpose: this is a secret, it buys a fresh
|
|
220
|
+
access token for as long as the grant lives, so it is never in the dict that
|
|
221
|
+
gets printed, logged or handed to `fm whoami`.
|
|
222
|
+
"""
|
|
223
|
+
path = token_path(env)
|
|
224
|
+
if not path.exists():
|
|
225
|
+
return None
|
|
226
|
+
_refuse_loose_permissions(path, env)
|
|
227
|
+
try:
|
|
228
|
+
return json.loads(path.read_text()).get("refresh_token") or None
|
|
229
|
+
except (json.JSONDecodeError, OSError) as exc:
|
|
230
|
+
raise TokenError(f"could not read {path}: {exc}") from exc
|
|
231
|
+
|
|
232
|
+
|
|
233
|
+
def clear(env: str) -> bool:
|
|
234
|
+
"""Remove the stored token for ``env``. True if there was one."""
|
|
235
|
+
path = token_path(env)
|
|
236
|
+
if not path.exists():
|
|
237
|
+
return False
|
|
238
|
+
path.unlink()
|
|
239
|
+
return True
|
|
240
|
+
|
|
241
|
+
|
|
242
|
+
def clear_all() -> list[str]:
|
|
243
|
+
"""Remove every stored token. Returns the environments that had one."""
|
|
244
|
+
directory = config_dir()
|
|
245
|
+
if not directory.exists():
|
|
246
|
+
return []
|
|
247
|
+
removed = []
|
|
248
|
+
for path in sorted(directory.glob("token-*.json")):
|
|
249
|
+
removed.append(path.stem.removeprefix("token-"))
|
|
250
|
+
path.unlink()
|
|
251
|
+
return removed
|
|
252
|
+
|
|
253
|
+
|
|
254
|
+
@dataclass(frozen=True)
|
|
255
|
+
class TokenInfo:
|
|
256
|
+
"""Non-secret facts about a stored token, as recorded in its metadata,
|
|
257
|
+
never decoded from the token (see :func:`describe_meta`)."""
|
|
258
|
+
|
|
259
|
+
expires_at: datetime | None
|
|
260
|
+
issued_at: datetime | None
|
|
261
|
+
|
|
262
|
+
@property
|
|
263
|
+
def expired(self) -> bool:
|
|
264
|
+
return self.expires_at is not None and self.expires_at <= _utcnow()
|
|
265
|
+
|
|
266
|
+
def describe_expiry(self) -> str:
|
|
267
|
+
if self.expires_at is None:
|
|
268
|
+
return "no expiry recorded"
|
|
269
|
+
delta = self.expires_at - _utcnow()
|
|
270
|
+
if delta.total_seconds() <= 0:
|
|
271
|
+
return f"EXPIRED at {self.expires_at.isoformat()}"
|
|
272
|
+
hours = int(delta.total_seconds() // 3600)
|
|
273
|
+
return f"valid for ~{hours}h (until {self.expires_at.isoformat()})"
|
|
274
|
+
|
|
275
|
+
|
|
276
|
+
def describe_meta(meta: dict) -> TokenInfo:
|
|
277
|
+
"""Non-secret facts about a stored credential, read from :func:`load_meta`,
|
|
278
|
+
never by decoding the token itself.
|
|
279
|
+
|
|
280
|
+
An ``fm login`` access token is opaque (``crst_at_...``, no dots at
|
|
281
|
+
all), so there is nothing in it to decode. Everything worth reporting
|
|
282
|
+
was already written beside the token at the moment it was minted or
|
|
283
|
+
refreshed (:func:`formist_cli.login.store_payload`): ``expires_at`` and
|
|
284
|
+
``obtained_at``, so this reads that instead of guessing at the token's
|
|
285
|
+
shape.
|
|
286
|
+
"""
|
|
287
|
+
return TokenInfo(
|
|
288
|
+
expires_at=_parse_iso(meta.get("expires_at")),
|
|
289
|
+
issued_at=_parse_iso(meta.get("obtained_at")),
|
|
290
|
+
)
|
|
291
|
+
|
|
292
|
+
|
|
293
|
+
def _parse_iso(value: object) -> datetime | None:
|
|
294
|
+
if not isinstance(value, str) or not value:
|
|
295
|
+
return None
|
|
296
|
+
try:
|
|
297
|
+
return datetime.fromisoformat(value)
|
|
298
|
+
except ValueError:
|
|
299
|
+
return None
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
def _utcnow() -> datetime:
|
|
303
|
+
return datetime.now(timezone.utc)
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
def _now_iso() -> str:
|
|
307
|
+
return _utcnow().isoformat()
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
#: The Evane regions are one deployment with one sign-in: a token minted on either
|
|
311
|
+
#: host is accepted by both. Every other host keeps its own credential.
|
|
312
|
+
_SHARED_SECRET_ENVS = frozenset({"evane", "evane-ae"})
|
|
313
|
+
|
|
314
|
+
|
|
315
|
+
def load_for(env: str) -> tuple[str | None, str | None]:
|
|
316
|
+
"""The token to use for ``env``, and where it came from.
|
|
317
|
+
|
|
318
|
+
``$EVANE_TOKEN`` (:data:`ENV_TOKEN_VAR`) is checked first and, when set, wins
|
|
319
|
+
over any stored file for THIS call; the origin comes back as
|
|
320
|
+
:data:`ENV_TOKEN_ORIGIN`, never a real env name, so a caller comparing
|
|
321
|
+
``origin == env`` (the cross-region-borrow check) is unaffected.
|
|
322
|
+
|
|
323
|
+
Absent that, falling back between the prod regions saves a second `fm login`
|
|
324
|
+
for one credential. The origin is returned rather than hidden so the caller can
|
|
325
|
+
print it: a credential silently sourced from somewhere else is exactly the
|
|
326
|
+
kind of invisible state this tool is otherwise built to refuse.
|
|
327
|
+
"""
|
|
328
|
+
env_value = env_token()
|
|
329
|
+
if env_value:
|
|
330
|
+
return env_value, ENV_TOKEN_ORIGIN
|
|
331
|
+
direct = load(env)
|
|
332
|
+
if direct:
|
|
333
|
+
return direct, env
|
|
334
|
+
if env in _SHARED_SECRET_ENVS:
|
|
335
|
+
for other in sorted(_SHARED_SECRET_ENVS - {env}):
|
|
336
|
+
borrowed = load(other)
|
|
337
|
+
if borrowed:
|
|
338
|
+
return borrowed, other
|
|
339
|
+
return None, None
|