gea-program 0.55.0__tar.gz → 0.57.0__tar.gz

{gea_program-0.55.0/gea_program.egg-info → gea_program-0.57.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.55.0
+Version: 0.57.0
 Summary: GEA-Program: downhole gauge monitoring - canonical measurement records, quality rules, drift evaluation with a re-fit change log, well-test validation, alarm management, model cards, store-and-forward, monthly SLA measurement, FAT/SAT protocols and a dashboard, generated from live objects in the client's reporting outline.
 Author: Daniel T. Murphy
 License: MPL-2.0
@@ -1272,6 +1272,38 @@ Or Administration -> **HTTPS** in the page (download the certificate, not
 the key, for the site's computers to trust; compare the SHA-256 shown).
 `gea help https`.
 
+### Company sign-in
+
+People sign in with the account the company already manages - Microsoft
+Entra ID, Okta, Google Workspace, Ping, Keycloak, AD FS - by OpenID Connect
+(the authorization code flow with PKCE), so the company's multi-factor,
+conditional access and leavers apply. The ID token is checked with the
+standard library alone (its RS256 signature against the provider's
+published keys, the issuer, the audience, the times, the nonce); the role in
+GEA is the highest any of the person's app roles or groups maps to. Local
+accounts stay, for the first administrator and for when the provider cannot
+be reached. HTTPS comes first (above).
+
+```
+gea oidc --workspace C:\site --issuer https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0 --client-id a41c7e92-0d3b-4f6a-9e85-2b6d1c4f7a30 --redirect-uri https://gea-pad3.example.local:8765/api/oidc/callback --secret-from-env GEA_OIDC_SECRET --map GEA.Operator=operator --map GEA.Admin=admin --test
+```
+
+Or Administration -> **Company sign-in**. `gea help company-sign-in` has the
+Entra ID app registration step by step.
+
+### For an IT department
+
+`docs/IT_SECURITY.md` (`gea security` prints it from any installation)
+answers what a reviewer asks before installing: where the data is and every
+connection the program can make, the one port, HTTPS, company sign-in and
+roles, the audit log, the bill of materials (`gea sbom`), and how a kit is
+checked - the build's attestation
+(`gea-program-0.57.0-win64.zip` checked with
+`gh attestation verify gea-program-0.57.0-win64.zip -R Daniel8Murphy0007/GEA-Program`)
+and the file catalog beside the kit's folder, Authenticode-signed once the
+publisher's certificate is in place. `SECURITY.md` says how to report a
+vulnerability.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: HTTPS from the service itself (above),
@@ -1403,4 +1435,5 @@ https://pypi.org/project/gea-program/ after the first successful run.
 ## Licence
 
 Mozilla Public License 2.0 (MPL-2.0); see `LICENSE`. Every source file carries the MPL-2.0
-header (Exhibit A). Copyright (c) 2026 Daniel T. Murphy.
+header (Exhibit A). Copyright (c) 2026 Daniel T. Murphy. The signed kit, its updates and
+support are a subscription from ENRGYONE (`docs/commercial/COMMERCIAL.md`).

{gea_program-0.55.0 → gea_program-0.57.0}/README.md

@@ -1233,6 +1233,38 @@ Or Administration -> **HTTPS** in the page (download the certificate, not
 the key, for the site's computers to trust; compare the SHA-256 shown).
 `gea help https`.
 
+### Company sign-in
+
+People sign in with the account the company already manages - Microsoft
+Entra ID, Okta, Google Workspace, Ping, Keycloak, AD FS - by OpenID Connect
+(the authorization code flow with PKCE), so the company's multi-factor,
+conditional access and leavers apply. The ID token is checked with the
+standard library alone (its RS256 signature against the provider's
+published keys, the issuer, the audience, the times, the nonce); the role in
+GEA is the highest any of the person's app roles or groups maps to. Local
+accounts stay, for the first administrator and for when the provider cannot
+be reached. HTTPS comes first (above).
+
+```
+gea oidc --workspace C:\site --issuer https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0 --client-id a41c7e92-0d3b-4f6a-9e85-2b6d1c4f7a30 --redirect-uri https://gea-pad3.example.local:8765/api/oidc/callback --secret-from-env GEA_OIDC_SECRET --map GEA.Operator=operator --map GEA.Admin=admin --test
+```
+
+Or Administration -> **Company sign-in**. `gea help company-sign-in` has the
+Entra ID app registration step by step.
+
+### For an IT department
+
+`docs/IT_SECURITY.md` (`gea security` prints it from any installation)
+answers what a reviewer asks before installing: where the data is and every
+connection the program can make, the one port, HTTPS, company sign-in and
+roles, the audit log, the bill of materials (`gea sbom`), and how a kit is
+checked - the build's attestation
+(`gea-program-0.57.0-win64.zip` checked with
+`gh attestation verify gea-program-0.57.0-win64.zip -R Daniel8Murphy0007/GEA-Program`)
+and the file catalog beside the kit's folder, Authenticode-signed once the
+publisher's certificate is in place. `SECURITY.md` says how to report a
+vulnerability.
+
 ### Before a site goes live
 
 `deploy/README.md` is the checklist: HTTPS from the service itself (above),
@@ -1364,4 +1396,5 @@ https://pypi.org/project/gea-program/ after the first successful run.
 ## Licence
 
 Mozilla Public License 2.0 (MPL-2.0); see `LICENSE`. Every source file carries the MPL-2.0
-header (Exhibit A). Copyright (c) 2026 Daniel T. Murphy.
+header (Exhibit A). Copyright (c) 2026 Daniel T. Murphy. The signed kit, its updates and
+support are a subscription from ENRGYONE (`docs/commercial/COMMERCIAL.md`).

{gea_program-0.55.0 → gea_program-0.57.0}/gea/__init__.py

@@ -123,7 +123,7 @@ from .profile_catalog import (
     read_pangaea_txt,
 )
 
-__version__ = "0.55.0"
+__version__ = "0.57.0"
 __all__ = [
     "aging_rate", "rate_psi_yr", "accuracy_psi",
     "Sensor", "SimulatorConfig", "DownholeEngine",

{gea_program-0.55.0 → gea_program-0.57.0}/gea/__main__.py

@@ -67,7 +67,16 @@ def _build_config(a):
     return SimulatorConfig(**kw)
 
 
+# the front door's own commands (gea.cli), reached the same way through `python -m gea` - the kit's gea.cmd and
+# gea wrapper run `python -m gea`, and before v0.57 `gea guide`, `gea help` and the rest answered "invalid choice"
+FRONT_ONLY = ('quickstart', 'guide', 'security', 'docs', 'gui', 'help')
+
+
 def main(argv=None) -> int:
+    _argv = list(sys.argv[1:] if argv is None else argv)
+    if _argv and _argv[0] in FRONT_ONLY:
+        from .cli import main as _front
+        return _front(_argv)
     ap = argparse.ArgumentParser(prog="gea",
                                  description="GEA Downhole Simulator - headless CLI")
     sub = ap.add_subparsers(dest="cmd", required=True)
@@ -776,6 +785,24 @@ def main(argv=None) -> int:
     p_tl.add_argument("--actor", type=str, default="cli")
     p_tl.add_argument("--json", action="store_true")
 
+    p_oc = sub.add_parser("oidc", help="company sign-in (OpenID Connect: Entra ID, Okta, Google, Ping, Keycloak, AD FS): set it, test the provider, remove it; with no option, how it stands")
+    p_oc.add_argument("--workspace", type=str, required=True)
+    p_oc.add_argument("--issuer", type=str, default=None, help="Entra ID: https://login.microsoftonline.com/3f8b2c1d-6a4e-4d9b-8c2f-1e7a5b9d0c64/v2.0")
+    p_oc.add_argument("--client-id", type=str, default=None)
+    p_oc.add_argument("--redirect-uri", type=str, default=None, help="https://gea-pad3.example.local:8765/api/oidc/callback, registered with the provider exactly")
+    p_oc.add_argument("--secret-from-env", type=str, default=None, help="read the client secret from this environment variable now and keep it in keys\\oidc_client_secret.txt")
+    p_oc.add_argument("--secret-env", type=str, default=None, help="or: the service reads the client secret from this environment variable at each sign-in (nothing kept)")
+    p_oc.add_argument("--role-claim", type=str, default=None, help="roles (Entra ID app roles, the default) or groups, or any claim")
+    p_oc.add_argument("--map", action="append", default=[], help="VALUE=ROLE, e.g. GEA.Admin=admin (repeat)")
+    p_oc.add_argument("--default-role", type=str, default=None, help="the role of a person with no mapped value; 'none' (the default) means no sign-in")
+    p_oc.add_argument("--name-claim", type=str, default=None, help="the claim that names the person (preferred_username by default)")
+    p_oc.add_argument("--label", type=str, default=None, help="the sign-in button's words")
+    p_oc.add_argument("--pause", action="store_true", help="keep the settings, stop company sign-in")
+    p_oc.add_argument("--test", action="store_true", help="read the provider's discovery document and keys now")
+    p_oc.add_argument("--off", action="store_true", help="remove company sign-in (local accounts are unchanged)")
+    p_oc.add_argument("--actor", type=str, default="cli")
+    p_oc.add_argument("--json", action="store_true")
+
     p_hk = sub.add_parser("housekeeping", help="rotate the append-only logs, prune finished job folders and old live recordings (dry run unless --apply)")
     p_hk.add_argument("--workspace", type=str, required=True)
     p_hk.add_argument("--apply", action="store_true")
@@ -2616,6 +2643,53 @@ def main(argv=None) -> int:
             raise SystemExit(f"pore-pressure: {e.args[0] if e.args else e}")
         print(_json.dumps(r, default=str) if a.json else _PPF.text(r))
         return 0
+    elif a.cmd == "oidc":
+        import json as _json
+        from . import oidc as _OI
+        from .workspace import Workspace, WorkspaceError
+        try:
+            ws = Workspace(a.workspace)
+            changing = any(x is not None for x in (a.issuer, a.client_id, a.redirect_uri, a.secret_from_env, a.secret_env, a.role_claim,
+                                                   a.default_role, a.name_claim, a.label)) or a.map or a.pause
+            if a.off:
+                r = _OI.turn_off(ws, a.actor)
+            elif changing:
+                cur = _OI.settings(ws) or {}
+                s = {k: cur.get(k, v) for k, v in _OI.DEFAULTS.items()}
+                for k, v in (("issuer", a.issuer), ("client_id", a.client_id), ("redirect_uri", a.redirect_uri), ("role_claim", a.role_claim),
+                             ("name_claim", a.name_claim), ("label", a.label), ("client_secret_env", a.secret_env)):
+                    if v is not None:
+                        s[k] = v
+                if a.default_role is not None:
+                    s["default_role"] = None if a.default_role.lower() in ("", "none") else a.default_role
+                if a.map:
+                    m = {}
+                    for x in a.map:
+                        v_, _, r_ = x.rpartition("=")
+                        if not v_:
+                            raise ValueError(f"--map takes VALUE=ROLE, not {x!r}")
+                        m[v_.strip()] = r_.strip()
+                    s["role_map"] = m
+                if a.secret_from_env:
+                    s["client_secret_env"] = ""
+                s["enabled"] = not a.pause
+                sec = None
+                if a.secret_from_env:
+                    sec = os.environ.get(a.secret_from_env, "")
+                    if not sec:
+                        raise ValueError(f"the environment variable {a.secret_from_env} is empty")
+                r = _OI.configure(ws, a.actor, s, sec)
+            else:
+                r = _OI.status(ws)
+            if a.test:
+                r = {**r, "test": _OI.test(ws)}
+        except (KeyError, ValueError, OSError, WorkspaceError) as e:
+            raise SystemExit(f"oidc: {e.args[0] if e.args else e}")
+        if a.json:
+            print(_json.dumps(r, default=str))
+        else:
+            print(_OI.text(r))
+        return 0
     elif a.cmd == "tls":
         import json as _json
         from . import tls as _TLS

{gea_program-0.55.0 → gea_program-0.57.0}/gea/acceptance_tests.py

@@ -12461,6 +12461,366 @@ def section_cx_https(tmp: str) -> None:
        "no dossier carries the key; the help page" + (f" - failed: {failed4}" if failed4 else ""))
 
 
+def section_cy_company_sign_in(tmp: str) -> None:
+    """Section CY - company sign-in (OpenID Connect): against a stand-in provider over HTTPS, the whole browser round
+    trip - the start, the provider, the code exchanged with PKCE and the secret, the ID token checked, the role from the
+    claims, a session - and every way an ID token or a return can be wrong turned away; the company account beside the
+    local ones; the settings, the secret kept out of sight; the CLI, the page and the help."""
+    import http.client
+    import ssl as _ssl
+    import subprocess as _sp
+    import urllib.parse as _up
+    import zipfile as _zf
+    from . import __version__ as _ver
+    from . import dossier as DZ
+    from . import helplib as H
+    from . import oidc as OI
+    from . import tls as TLS
+    from .oidc_mock import MockIdP
+    from .service import Service, Users
+    from .workspace import Workspace
+    pkg = Path(__file__).parent
+    idp = MockIdP()
+    wsp = str(Path(tmp, "ws_cy")); ws = Workspace.create(wsp, "Company Site", actor="tester")
+    users = Users(str(Path(wsp, "users.json")))
+    users.add("adm", "admin-pass-123", "admin"); users.add("v", "viewer-pass-1", "viewer"); users.add("olga.local", "local-pass-12", "operator")
+    TLS.make_self_signed(ws, "tester", ["localhost", "127.0.0.1"], days=60)
+    svc = Service(wsp, host="127.0.0.1", port=0, scheduler=False)
+    svc.app.oidc_ssl_context = idp.client_ctx
+    svc.start()
+    base = svc.url.rstrip("/")
+    trust = _ssl.create_default_context(cafile=str(Path(wsp, TLS.SELF_CERT)))
+
+    def get(url, cookie=None, ctx=trust):
+        u = _up.urlsplit(url)
+        c = http.client.HTTPSConnection(u.hostname, u.port, context=ctx, timeout=30)
+        c.request("GET", u.path + ("?" + u.query if u.query else ""), headers=({"Cookie": cookie} if cookie else {}))
+        r = c.getresponse()
+        b = r.read()
+        c.close()
+        return r.status, r.getheader("Location"), r.headers.get_all("Set-Cookie") or [], b
+
+    def api(method, path, body=None, cookie=None):
+        c = http.client.HTTPSConnection("127.0.0.1", svc.port, context=trust, timeout=30)
+        h = {"Content-Type": "application/json", "X-GEA-Action": "1"} if method == "POST" else {}
+        if cookie:
+            h["Cookie"] = cookie
+        c.request(method, path, body=(json.dumps(body) if body is not None else None), headers=h)
+        r = c.getresponse()
+        b = r.read()
+        c.close()
+        return r.status, json.loads(b or b"{}"), r.headers.get_all("Set-Cookie") or []
+
+    def local(name, pw):
+        return [x for x in api("POST", "/api/login", {"name": name, "password": pw})[2] if x.startswith("gea_session")][0].split(";")[0]
+
+    def round_trip(user=None, fault=None, keep_cookie=True):
+        """The browser's path: start -> the provider -> back. (status, the page, the session cookie or None, the callback URL, the flow cookie)"""
+        idp.fault = fault
+        if user:
+            idp.user = user
+        s1, loc1, ck1, _ = get(base + "/api/oidc/start")
+        flow = ck1[0].split(";")[0] if ck1 else None
+        s2, loc2, _, _ = get(loc1, ctx=idp.client_ctx)
+        s3, _, ck3, b3 = get(loc2, cookie=(flow if keep_cookie else None))
+        sess = next((x.split(";")[0] for x in ck3 if x.startswith("gea_session=") and not x.startswith("gea_session=;")), None)
+        return s3, b3.decode("utf-8", "replace"), sess, loc2, flow, (s1, s2, ck1)
+    olga = {"sub": "sub-olga", "preferred_username": "olga@example.com", "roles": ["GEA.Operator"]}
+    try:
+        adm = local("adm", "admin-pass-123"); vw = local("v", "viewer-pass-1")
+        # -- CY1 the settings --------------------------------------------------------------------------------------------
+        redir = base + "/api/oidc/callback"
+        good = {"issuer": idp.issuer, "client_id": idp.client_id, "redirect_uri": redir,
+                "role_map": {"GEA.Viewer": "viewer", "GEA.Operator": "operator", "GEA.Approver": "approver", "GEA.Admin": "admin"}}
+        bad = [{**good, "redirect_uri": "http://gea-pad3.example.local:8765/api/oidc/callback"}, {**good, "redirect_uri": base + "/somewhere"},
+               {**good, "issuer": "https://login.microsoftonline.com/common/v2.0"}, {**good, "issuer": "http://idp.example"},
+               {**good, "role_map": {}}, {**good, "role_map": {"x": "superuser"}}, {**good, "client_id": ""}]
+        bad_codes = [api("POST", "/api/oidc", {"action": "set", **b, "client_secret": "s"}, adm)[0] for b in bad]
+        s_vset = api("POST", "/api/oidc", {"action": "set", **good, "client_secret": idp.client_secret}, vw)[0]
+        s_set, st_set, _ = api("POST", "/api/oidc", {"action": "set", **good, "client_secret": idp.client_secret}, adm)
+        s_get, st_get, _ = api("GET", "/api/oidc", cookie=adm)
+        s_vget = api("GET", "/api/oidc", cookie=vw)[0]
+        s_test, tst, _ = api("POST", "/api/oidc", {"action": "test"}, adm)
+        sess_pub = api("GET", "/api/session")[1]
+        secret_file = Path(wsp, OI.SECRET_FILE)
+        c1 = {
+            "refused": all(c == 400 for c in bad_codes) and s_vset == 403 and s_vget == 403,
+            "kept": s_set == 200 and st_set["configured"] and st_set["secret"] == "kept" and s_get == 200 and st_get["issuer"] == idp.issuer
+                    and idp.client_secret not in json.dumps(st_get) and secret_file.read_text(encoding="utf-8") == idp.client_secret
+                    and (os.name == "nt" or (secret_file.stat().st_mode & 0o077) == 0),
+            "test": s_test == 200 and tst["ok"] and tst["signing_keys"] == 1 and tst["token_endpoint"].endswith("/token"),
+            "public": sess_pub.get("company_sign_in") == {"label": "Sign in with your company account"} and sess_pub.get("user") is None,
+        }
+        failed1 = [k for k, v in c1.items() if not v]
+        ok(not failed1,
+           "CY1 company sign-in is set by an administrator only: an http:// or wrong redirect URI, a multi-tenant issuer, an issuer not on https, no role map "
+           "and no default, a role that does not exist, no client id - each refused; the secret is kept in keys\\ readable by its owner only and never sent "
+           "back; Test reads the provider's discovery and keys; the sign-in page learns only that the button exists" + (f" - failed: {failed1}" if failed1 else ""))
+        # -- CY2 the round trip --------------------------------------------------------------------------------------------
+        s3, page, sess, cb_url, flow, (s1, s2, ck1) = round_trip(olga)
+        me = api("GET", "/api/session", cookie=sess)[1]["user"] if sess else {}
+        call = idp.token_calls[-1] if idp.token_calls else {}
+        r_replay = get(cb_url, cookie=flow)
+        s_replay, replay_body = r_replay[0], r_replay[3].decode()
+        idp.user = dict(olga, roles=["GEA.Operator", "GEA.Admin"])
+        s_up, _, sess_up, _, _, _ = round_trip()
+        me_up = api("GET", "/api/session", cookie=sess_up)[1]["user"] if sess_up else {}
+        listed = {u["name"]: u for u in api("GET", "/api/users", cookie=adm)[1]["users"]}
+        live = [x for x in api("GET", "/api/sessions", cookie=adm)[1]["sessions"] if x["name"] == "olga@example.com"]
+        c2 = {
+            "start": s1 == 302 and "SameSite=Lax" in ck1[0] and "Secure" in ck1[0] and "Path=/api/oidc" in ck1[0] and s2 == 302,
+            "back": s3 == 200 and 'http-equiv="refresh"' in page and sess is not None and me.get("name") == "olga@example.com" and me.get("role") == "operator"
+                    and me.get("via") == "company",
+            "pkce": call.get("code_verifier") and call.get("client_secret") == idp.client_secret and call.get("redirect_uri") == redir,
+            "once": s_replay == 401 and "unknown or has expired" in replay_body,
+            "role_follows": me_up.get("role") == "admin" and listed["olga@example.com"]["kind"] == "company" and listed["olga@example.com"]["role"] == "admin"
+                            and live and all(x["via"] == "company" for x in live),
+        }
+        failed2 = [k for k, v in c2.items() if not v]
+        ok(not failed2,
+           "CY2 the round trip: the start sends the browser to the provider with a flow cookie (SameSite=Lax, Secure, this path only); back with a code, the "
+           "service exchanges it with the client secret and the PKCE verifier, checks the ID token, and the person is signed in as a company account with the "
+           "role their claims map to - the highest, taken again at every sign-in - by a page that moves on by itself (the session cookie stays Strict); "
+           "a return is accepted once" + (f" - failed: {failed2}" if failed2 else ""))
+        # -- CY3 every way it can be wrong ----------------------------------------------------------------------------------
+        outcomes = {}
+        for f in ("aud", "expired", "sig", "alg_none", "hs256", "nonce", "iss"):
+            st_, pg_, se_, _, _, _ = round_trip(olga, fault=f)
+            outcomes[f] = (st_, se_ is None, pg_)
+        st_rot, _, se_rot, _, _, _ = round_trip(olga, fault="rotate")
+        st_nb, pg_nb, se_nb, _, _, _ = round_trip(olga, keep_cookie=False)
+        st_nr, pg_nr, se_nr, _, _, _ = round_trip({"sub": "sub-x", "preferred_username": "x@example.com", "roles": ["Other"]})
+        st_lc, pg_lc, se_lc, _, _, _ = round_trip({"sub": "sub-l", "preferred_username": "olga.local", "roles": ["GEA.Admin"]})
+        st_os, pg_os, se_os, _, _, _ = round_trip({"sub": "someone-else", "preferred_username": "olga@example.com", "roles": ["GEA.Admin"]})
+        pg_ov = ""
+        try:
+            OI.role_of({"_claim_names": {"groups": "src1"}}, {**OI.DEFAULTS, "role_claim": "groups", "role_map": {"g": "viewer"}})
+        except OI.OidcError as e:
+            pg_ov = str(e)
+        s_dis = api("POST", "/api/users/disable", {"name": "olga@example.com", "disabled": True}, adm)[0]
+        st_dis, pg_dis, se_dis, _, _, _ = round_trip(olga)
+        api("POST", "/api/users/disable", {"name": "olga@example.com", "disabled": False}, adm)
+        s_pw = api("POST", "/api/users/password", {"name": "olga@example.com", "password": "whatever-123"}, adm)[0]
+        s_role = api("POST", "/api/users/role", {"name": "olga@example.com", "role": "viewer"}, adm)[0]
+        s_pwlogin = api("POST", "/api/login", {"name": "olga@example.com", "password": ""})[0]
+        s_local = api("POST", "/api/login", {"name": "olga.local", "password": "local-pass-12"})[0]
+        audit = Path(ws.audit_path).read_text(encoding="utf-8")
+        why = {"aud": "audience", "expired": "expired", "sig": "signature", "alg_none": "only RS256", "hs256": "only RS256", "nonce": "nonce", "iss": "issued by"}
+        c3 = {
+            "tokens": all(outcomes[f][0] == 401 and outcomes[f][1] and why[f] in outcomes[f][2] for f in why),
+            "rotation": st_rot == 200 and se_rot is not None,
+            "binding": st_nb == 401 and se_nb is None and "another browser" in pg_nb,
+            "no_role": st_nr == 401 and se_nr is None and "no role in GEA" in pg_nr and "Other" in pg_nr,
+            "no_takeover": st_lc == 401 and se_lc is None and "local account" in pg_lc and st_os == 401 and se_os is None and "another company identity" in pg_os,
+            "overage": "more groups than a token carries" in pg_ov,
+            "disabled": s_dis == 200 and st_dis == 401 and se_dis is None and "disabled" in pg_dis,
+            "no_password": s_pw == 400 and s_role == 400 and s_pwlogin in (400, 401) and s_local == 200,
+            "audited": audit.count('"via": "company"') >= 3 and '"login.failed"' in audit and "audience" in audit,
+        }
+        failed3 = [k for k, v in c3.items() if not v]
+        ok(not failed3,
+           "CY3 turned away, each saying why, with no session: an ID token for another application, expired, with a bad signature, signed 'none' or HS256, "
+           "with another sign-in's nonce, from another issuer; a return to a browser that did not start the sign-in; a person with no mapped role; a name "
+           "a local account has, or a company account bound to another subject; a person in more groups than a token carries; a company account disabled "
+           "in GEA. A rotated signing key is fetched and accepted. A company account has no password here and its role is not set by hand; local accounts "
+           "sign in as before; every sign-in and failure is audited" + (f" - failed: {failed3}" if failed3 else ""))
+    finally:
+        svc.stop()
+    # -- CY4 the CLI, the dossier, the page, the help -------------------------------------------------------------------
+    env = {**os.environ, "GEA_OIDC_TEST_SECRET": "cli-secret-456", "SSL_CERT_FILE": idp.cafile}
+    w2 = str(Path(tmp, "ws_cy2")); Workspace.create(w2, "CLI Site", actor="tester")
+    cli_set = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--issuer", idp.issuer, "--client-id", idp.client_id,
+                       "--redirect-uri", "https://gea-pad3.example.local:8765/api/oidc/callback", "--secret-from-env", "GEA_OIDC_TEST_SECRET",
+                       "--map", "GEA.Admin=admin", "--map", "GEA.Viewer=viewer", "--default-role", "none", "--test"],
+                      capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    cli_st = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--json"], capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    cli_bad = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--map", "nonsense"], capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    cli_off = _sp.run([sys.executable, "-m", "gea", "oidc", "--workspace", w2, "--off"], capture_output=True, text=True, cwd=str(pkg.parent), env=env)
+    idp.stop()
+    __import__("gea.frac_hits", fromlist=["write_report"]).write_report(ws, _ver, "tester")
+    dz = DZ.build(ws, "tester", _ver, None, include_sources=True)
+    with _zf.ZipFile(Path(ws.reports_dir, dz["path"])) as z:
+        leaked = [n for n in z.namelist() if idp.client_secret.encode() in z.read(n)]
+    page_src = (pkg / "web" / "app.html").read_text(encoding="utf-8")
+    st_cli = json.loads(cli_st.stdout) if cli_st.returncode == 0 else {}
+    c4 = {
+        "cli": cli_set.returncode == 0 and "provider: GOOD" in cli_set.stdout and "GEA.Admin -> admin" in cli_set.stdout
+               and st_cli.get("secret") == "kept" and Path(w2, OI.SECRET_FILE).read_text(encoding="utf-8") == "cli-secret-456"
+               and "cli-secret-456" not in cli_st.stdout and cli_bad.returncode != 0 and "VALUE=ROLE" in (cli_bad.stderr + cli_bad.stdout)
+               and cli_off.returncode == 0 and "local accounts only" in cli_off.stdout,
+        "dossier": not leaked and idp.client_secret not in Path(ws.audit_path).read_text(encoding="utf-8"),
+        "page": all(x in page_src for x in ("/api/oidc/start", "aCompany", "s.company_sign_in", "ocSave", "ocTest", "ocMap", "company account: role from its claims"))
+                and "[hidden] { display: none !important; }" in page_src,
+        "help": not H.check("company-sign-in") and "Entra" in (H.page("company-sign-in") or "") and "App roles" in (H.page("company-sign-in") or ""),
+    }
+    failed4 = [k for k, v in c4.items() if not v]
+    ok(not failed4,
+       "CY4 `gea oidc` sets company sign-in from a terminal (the secret read from an environment variable once and kept, never printed), tests the "
+       "provider, refuses a malformed map and removes it; no dossier carries the client secret; the sign-in page's button and the Company sign-in card; "
+       "the help page with the Entra ID steps" + (f" - failed: {failed4}" if failed4 else ""))
+
+
+def section_cz_it_review(tmp: str) -> None:
+    """Section CZ - what an IT department asks: the security overview ships with the program and agrees with the
+    code it describes (the rounds, the sessions, the lock, the port, TLS, every host the program can reach); `gea
+    security`, `gea guide` and `gea help` answer through `python -m gea` as the kit's launcher runs it; in a checkout,
+    the kit tools zip the kit again with its catalog beside it and tell the site how to check it, and the build
+    workflow attests both kits and signs the catalog only when a certificate is configured."""
+    import importlib.util
+    import json as _json
+    import subprocess as _sp
+    import urllib.parse as _up
+    import zipfile as _zf
+    from . import doctor as DR
+    from . import elevation as EL
+    from . import helplib as H
+    from . import seismic_watch as SW
+    from . import service as SVC
+    from . import tls as TLS
+    pkg = Path(__file__).parent
+    checkout = (pkg.parent / "pyproject.toml").exists() and (pkg.parent / "tools" / "build_installer.py").exists()
+
+    # -- CZ1 the overview, and the code it describes -------------------------------------------------------------------
+    text = H.security_text() or ""
+    docs_copy = pkg.parent / "docs" / "IT_SECURITY.md"
+    same = (not docs_copy.exists()) or docs_copy.read_text(encoding="utf-8") == text
+    flat = " ".join(text.split())
+    with open(Path(pkg, "reference", "eia_prices.provenance.json"), encoding="utf-8") as f:
+        eia_hosts = {_up.urlsplit(s["refresh_url"]).hostname for s in _json.load(f)["series"].values() if s.get("refresh_url")}
+    doctor_src = Path(DR.__file__).read_text(encoding="utf-8")
+    hosts = {_up.urlsplit(EL.EPQS_URL).hostname, _up.urlsplit(SW.QUERY_URL).hostname, _up.urlsplit(SW.FEED_URL).hostname, *eia_hosts}
+    hosts |= {"pypi.org"} if "https://pypi.org/pypi/gea-program/json" in doctor_src else {"(the update check moved)"}
+    facts = {
+        "rounds": f"{SVC.PBKDF2_ROUNDS:,}" in flat,
+        "sessions": f"{SVC.SESSION_HOURS} hours" in flat and "256-bit" in flat,
+        "lock": SVC.LOGIN_MAX_FAILURES == 5 and "five failures" in flat and f"{SVC.LOGIN_LOCK_S // 60} minutes" in flat,
+        "port": "TCP 8765" in flat and "8765" in Path(DR.__file__).read_text(encoding="utf-8"),
+        "tls": "TLS 1.2 minimum" in flat and f"last {TLS.EXPIRING_DAYS} days" in flat,
+        "hosts": all(f"`{h}`" in flat for h in hosts),
+        "no_telemetry": "No telemetry" in flat,
+    }
+    # Python 3.14's argparse formats every help string as the parser is built (help % params) and stops on a bare
+    # "%": v0.54.0's first ship stopped at its gate that way while 3.13 passed. The same check, on any Python.
+    import argparse as _ap
+    import contextlib as _cl
+    import io as _io
+    from . import __main__ as _M
+    bad_help = []
+    _orig_add, _orig_sub = _ap.ArgumentParser.add_argument, _ap._SubParsersAction.add_parser
+    _params = {k_: "x" for k_ in ("prog", "default", "dest", "type", "choices", "metavar", "required", "nargs", "const", "option_strings")}
+
+    def _fmt_ok(h):
+        try:
+            h % _params
+            return True
+        except (ValueError, TypeError, KeyError):
+            return False
+
+    def _add(self, *a_, **k_):
+        h_ = k_.get("help")
+        if isinstance(h_, str) and h_ != _ap.SUPPRESS and not _fmt_ok(h_):
+            bad_help.append(f"{self.prog} {'/'.join(a_)}")
+        return _orig_add(self, *a_, **k_)
+
+    def _sub(self, name, **k_):
+        h_ = k_.get("help")
+        if isinstance(h_, str) and not _fmt_ok(h_):
+            bad_help.append(f"gea {name}")
+        return _orig_sub(self, name, **k_)
+    _ap.ArgumentParser.add_argument, _ap._SubParsersAction.add_parser = _add, _sub
+    try:
+        with _cl.redirect_stdout(_io.StringIO()), _cl.redirect_stderr(_io.StringIO()):
+            try:
+                _M.main(["wells"])
+            except SystemExit:
+                pass
+    finally:
+        _ap.ArgumentParser.add_argument, _ap._SubParsersAction.add_parser = _orig_add, _orig_sub
+    facts["help_strings"] = not bad_help
+    r_sec = _sp.run([sys.executable, "-m", "gea", "security"], capture_output=True, text=True, encoding="utf-8", errors="replace")
+    r_guide = _sp.run([sys.executable, "-m", "gea", "guide"], capture_output=True, text=True, encoding="utf-8", errors="replace")
+    r_help = _sp.run([sys.executable, "-m", "gea", "help", "https"], capture_output=True, text=True, encoding="utf-8", errors="replace")
+    bad = [k for k, v in facts.items() if not v]
+    ok(text.startswith("# GEA-Program for an IT department") and same and not bad
+       and r_sec.returncode == 0 and "GEA-Program for an IT department" in r_sec.stdout
+       and r_guide.returncode == 0 and "HOW TO TEST GEA" in r_guide.stdout and r_help.returncode == 0 and "**The command**" in r_help.stdout,
+       "CZ1 the security overview ships in the package (identical to docs/IT_SECURITY.md) and agrees with the code: the password hashing rounds, the "
+       "session length and token size, the sign-in lock, the one port, the TLS floor and the expiry warning, every host the program can reach "
+       "(ComCat, the elevation service, the price series, PyPI); `python -m gea security`, `guide` and `help` answer as the kit's own launcher "
+       "runs them; every option's help text formats the way Python 3.14 checks it as the parser is built"
+       + (f" - disagrees: {bad}" if bad else "") + (f" - help texts: {bad_help}" if bad_help else ""))
+
+    # -- CZ2 the kit is zipped again with its catalog, and says how to check it ----------------------------------------------
+    if checkout:
+        spec = importlib.util.spec_from_file_location("cz_installer", str(pkg.parent / "tools" / "build_installer.py"))
+        bi = importlib.util.module_from_spec(spec); spec.loader.exec_module(bi)
+        kit = Path(tmp, "cz_kit", "gea-program-9.9.9-win64"); (kit / "python").mkdir(parents=True)
+        (kit / "MANIFEST.json").write_text("{}", encoding="utf-8"); (kit / "python" / "python.exe").write_bytes(b"MZ stand-in")
+        (kit / "SHA256SUMS.txt").write_text("x  MANIFEST.json\n", encoding="utf-8")
+        cat = Path(tmp, "cz_kit", "gea-program-9.9.9-win64.cat"); cat.write_bytes(b"0\x82 a catalog stand-in")
+        zp = bi.rezip(kit, [cat])
+        with _zf.ZipFile(zp) as z:
+            names = sorted(z.namelist())
+            cat_back = z.read("gea-program-9.9.9-win64.cat")
+        try:
+            bi.rezip(Path(tmp, "cz_kit"), [])
+            not_kit = "accepted"
+        except SystemExit as e:
+            not_kit = str(e)
+        readme = bi.README.format(version="9.9.9", target="Windows x64", pyline="p", install="i", start="s", verify="v", port="8765",
+                                  service="sv", stop="st", uninstall="u", workspace="w", check=bi.WIN_CHECK.format(version="9.9.9"))
+        build_src = (pkg.parent / "tools" / "build_installer.py").read_text(encoding="utf-8")
+        c2 = {
+            "rezip": names == ["gea-program-9.9.9-win64.cat", "gea-program-9.9.9-win64/MANIFEST.json", "gea-program-9.9.9-win64/SHA256SUMS.txt",
+                               "gea-program-9.9.9-win64/python/python.exe"] and cat_back == cat.read_bytes() and "not a kit folder" in not_kit,
+            "readme": all(x in readme for x in ("gh attestation verify gea-program-9.9.9-win64.zip -R Daniel8Murphy0007/GEA-Program",
+                                                "Test-FileCatalog -CatalogFilePath .\\gea-program-9.9.9-win64.cat -Path .\\gea-program-9.9.9-win64",
+                                                "Get-AuthenticodeSignature", "IT_SECURITY.md", "gea help https"))
+                      and "368 checks" not in readme and "behind the site's TLS proxy" not in readme,
+            "ships_overview": "docs' / 'IT_SECURITY.md'" in build_src and "kit / 'IT_SECURITY.md'" in build_src,
+        }
+        where = "the checkout's kit tools"
+    else:
+        c2 = {"installed": bool(H.security_text())}
+        where = "an installed copy: the kit tools are checked in the checkout"
+    failed2 = [k for k, v in c2.items() if not v]
+    ok(not failed2,
+       f"CZ2 ({where}) the kit is zipped again from its folder with its file catalog beside the folder, every file kept; a folder that is not a kit "
+       "is refused; the kit's README tells the site how to check the build's attestation and every file against the catalog and its signature, "
+       "and carries the IT overview" + (f" - failed: {failed2}" if failed2 else ""))
+
+    # -- CZ3 the build workflow: attested, signed only with a certificate, never signed in name only ----------------------------
+    wf = pkg.parent / ".github" / "workflows" / "build-installer.yml"
+    if wf.exists():
+        y = wf.read_text(encoding="utf-8")
+        win = y[y.index("windows-kit:"):y.index("linux-kit:")]
+        lin = y[y.index("linux-kit:"):]
+        order = [win.index(s) for s in ("New-FileCatalog", "azure/artifact-signing-action", "signtool", "Test-FileCatalog", "--rezip", "call install.cmd",
+                                        "attest-build-provenance", "attach-kit.sh")]
+        c3 = {
+            "permissions": "id-token: write" in y and "attestations: write" in y and "contents: write" in y,
+            "attested": "actions/attest-build-provenance" in win and "actions/attest-build-provenance" in lin
+                        and "subject-path: dist/gea-program-*-win64.zip" in win and "subject-path: dist/gea-program-*-linux-*.zip" in lin,
+            "conditional": "if: env.ARTIFACT_SIGNING_ACCOUNT != ''" in win and "if: env.ARTIFACT_SIGNING_ACCOUNT == '' && env.SIGNING_PFX_BASE64 != ''" in win
+                           and "secrets.ARTIFACT_SIGNING_ACCOUNT" in win and "secrets.SIGNING_PFX_BASE64" in win,
+            "checked": "-CatalogVersion 2.0" in win and "throw 'the catalog does not match the kit'" in win
+                       and "throw 'a certificate is configured but the catalog is not validly signed'" in win and "ships unsigned" in win
+                       and "Remove-Item $pfx" in win and "/tr http://timestamp" in win and "timestamp-rfc3161" in win,
+            "order": order == sorted(order),
+            "policy": (pkg.parent / "SECURITY.md").exists() and "Report a vulnerability" in " ".join((pkg.parent / "SECURITY.md").read_text(encoding="utf-8").split()),
+        }
+        where3 = "the checkout's workflow"
+    else:
+        c3 = {"installed": True}
+        where3 = "an installed copy: the workflow is checked in the checkout"
+    failed3 = [k for k, v in c3.items() if not v]
+    ok(not failed3,
+       f"CZ3 ({where3}) both kits are attested by the build that made them; the Windows kit's file catalog is made, signed by Azure Artifact "
+       "Signing or a PFX only when its secrets are configured (timestamped; the PFX removed), checked against the kit - a mismatch, or a "
+       "configured certificate that did not sign, stops the build - then zipped beside the kit before the kit is installed and its gate run; "
+       "SECURITY.md says how to report a vulnerability" + (f" - failed: {failed3}" if failed3 else ""))
+
+
 def PR_read_ok(path) -> bool:
     from . import pdf_report as PR
     try:
@@ -12574,6 +12934,8 @@ def main() -> int:
         section_cv_torque_drag(tmp)
         section_cw_decline(tmp)
         section_cx_https(tmp)
+        section_cy_company_sign_in(tmp)
+        section_cz_it_review(tmp)
     if _FAILS:
         print(f"[ACCEPTANCE] {len(_FAILS)} FAILURES ({_PASS} passed):")
         for f in _FAILS:

{gea_program-0.55.0 → gea_program-0.57.0}/gea/cli.py

@@ -10,6 +10,7 @@
     gea model-cards ...    gea store-forward ...  gea sla-report ...  gea fat-sat ...
     gea help [topic]                    the help library, by the job (gea help drift); same text as the dashboard's panels
     gea guide                           the click-by-click tester guide
+    gea security                        what an IT department asks before installing, answered (docs/IT_SECURITY.md)
     gea docs                            where the catalogue and the reports live on this machine
     gea gui                             the desktop window (desktop extra)
     gea accept                          the product gate
@@ -23,7 +24,7 @@ import os
 import sys
 from pathlib import Path
 
-FRONT = {'quickstart', 'survey', 'guide', 'docs', 'gui', 'help', '-h', '--help'}
+FRONT = {'quickstart', 'survey', 'guide', 'security', 'docs', 'gui', 'help', '-h', '--help'}
 
 
 def _pkg_root() -> Path:
@@ -62,6 +63,16 @@ def cmd_guide(_argv) -> int:
     return 0
 
 
+def cmd_security(_argv) -> int:
+    from .helplib import security_text
+    text = security_text()                                # ships inside the package (gea/help/IT_SECURITY.md)
+    if text is None:
+        print('the security overview is missing from this installation; reinstall: python -m pip install --upgrade --force-reinstall "gea-program[live]"')
+        return 2
+    print(text)
+    return 0
+
+
 def cmd_help(argv) -> int:
     from .helplib import page, index_text, topics
     if not argv:
@@ -141,6 +152,8 @@ def main(argv=None) -> int:
             return cmd_survey(rest)
         if cmd == 'guide':
             return cmd_guide(rest)
+        if cmd == 'security':
+            return cmd_security(rest)
         if cmd == 'docs':
             return cmd_docs(rest)
         if cmd == 'gui':