gea-program 0.54.0__tar.gz → 0.56.0__tar.gz

{gea_program-0.54.0/gea_program.egg-info → gea_program-0.56.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.54.0
+Version: 0.56.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
@@ -243,7 +243,7 @@ disappearing. Every action is written to `records/audit.jsonl` with the
 actor's name and the SHA-256 of the inputs it used. The service is written on
 the standard library only (no new dependency, the standalone check still
 passes), listens on the loopback interface by default (`--host 0.0.0.0` for a
-site network, behind the site's TLS proxy), keeps sessions in HttpOnly
+site network, over HTTPS - its own, below, or the site's TLS proxy), keeps sessions in HttpOnly
 SameSite cookies, and requires the page's own header on every action so a
 foreign form cannot act. Accounts live in `users.json` as salted PBKDF2-SHA256
 hashes; `gea users --workspace C:\site --action add --name ... --role admin`
@@ -1249,11 +1249,54 @@ is recomputed in the index. On the Reports page: the packets on record,
 Assemble as a job, and Schedule monthly (day and hour, the previous month).
 `gea help month-end`.
 
+### HTTPS
+
+The service speaks TLS itself when the workspace names a certificate: the
+site's own (from the company's certificate authority, which managed
+computers already trust; read where the site keeps it, at every start) or a
+self-signed one it makes with the standard library alone (an RSA key and an
+X.509 v3 server certificate for every name and address it is reached by).
+TLS 1.2 is the floor; the cookie is marked Secure; every answer carries
+Strict-Transport-Security; a plain `http://` request on the same port is
+sent to HTTPS; a certificate in its last 30 days raises the `tls.expiring`
+alert; a workspace whose certificate files are broken does not start rather
+than fall back to plain HTTP.
+
+```
+gea tls --workspace C:\site --site-cert C:\certs\gea-pad3.crt --site-key C:\certs\gea-pad3.key
+gea tls --workspace C:\site --self-signed --name gea-pad3 --name 10.20.0.15 --export-cert C:\certs\gea-site.crt
+gea serve --workspace C:\site --host 0.0.0.0                       # https://gea-pad3:8765/
+```
+
+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.
+
 ### Before a site goes live
 
-`deploy/README.md` is the checklist: keep the service on the loopback
-address and put a TLS proxy in front (`deploy/Caddyfile`,
-`deploy/nginx-gea.conf`), start with `--behind-proxy`. The service itself
+`deploy/README.md` is the checklist: HTTPS from the service itself (above),
+or keep the service on the loopback address and put the site's TLS proxy in
+front (`deploy/Caddyfile`, `deploy/nginx-gea.conf`), start with
+`--behind-proxy`. The service itself
 rate-limits sign-ins (five failures lock the name and the address for 15
 minutes, audited), lists and revokes live sessions, sends the security
 headers on every response, and `gea housekeeping --workspace C:\site --apply`

{gea_program-0.54.0 → gea_program-0.56.0}/README.md

@@ -204,7 +204,7 @@ disappearing. Every action is written to `records/audit.jsonl` with the
 actor's name and the SHA-256 of the inputs it used. The service is written on
 the standard library only (no new dependency, the standalone check still
 passes), listens on the loopback interface by default (`--host 0.0.0.0` for a
-site network, behind the site's TLS proxy), keeps sessions in HttpOnly
+site network, over HTTPS - its own, below, or the site's TLS proxy), keeps sessions in HttpOnly
 SameSite cookies, and requires the page's own header on every action so a
 foreign form cannot act. Accounts live in `users.json` as salted PBKDF2-SHA256
 hashes; `gea users --workspace C:\site --action add --name ... --role admin`
@@ -1210,11 +1210,54 @@ is recomputed in the index. On the Reports page: the packets on record,
 Assemble as a job, and Schedule monthly (day and hour, the previous month).
 `gea help month-end`.
 
+### HTTPS
+
+The service speaks TLS itself when the workspace names a certificate: the
+site's own (from the company's certificate authority, which managed
+computers already trust; read where the site keeps it, at every start) or a
+self-signed one it makes with the standard library alone (an RSA key and an
+X.509 v3 server certificate for every name and address it is reached by).
+TLS 1.2 is the floor; the cookie is marked Secure; every answer carries
+Strict-Transport-Security; a plain `http://` request on the same port is
+sent to HTTPS; a certificate in its last 30 days raises the `tls.expiring`
+alert; a workspace whose certificate files are broken does not start rather
+than fall back to plain HTTP.
+
+```
+gea tls --workspace C:\site --site-cert C:\certs\gea-pad3.crt --site-key C:\certs\gea-pad3.key
+gea tls --workspace C:\site --self-signed --name gea-pad3 --name 10.20.0.15 --export-cert C:\certs\gea-site.crt
+gea serve --workspace C:\site --host 0.0.0.0                       # https://gea-pad3:8765/
+```
+
+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.
+
 ### Before a site goes live
 
-`deploy/README.md` is the checklist: keep the service on the loopback
-address and put a TLS proxy in front (`deploy/Caddyfile`,
-`deploy/nginx-gea.conf`), start with `--behind-proxy`. The service itself
+`deploy/README.md` is the checklist: HTTPS from the service itself (above),
+or keep the service on the loopback address and put the site's TLS proxy in
+front (`deploy/Caddyfile`, `deploy/nginx-gea.conf`), start with
+`--behind-proxy`. The service itself
 rate-limits sign-ins (five failures lock the name and the address for 15
 minutes, audited), lists and revokes live sessions, sends the security
 headers on every response, and `gea housekeeping --workspace C:\site --apply`

{gea_program-0.54.0 → gea_program-0.56.0}/gea/__init__.py

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

{gea_program-0.54.0 → gea_program-0.56.0}/gea/__main__.py

@@ -756,13 +756,44 @@ def main(argv=None) -> int:
 
     p_sv = sub.add_parser("serve", help="serve the dashboard over a workspace: the page, the reports and the JSON API (standard library HTTP)")
     p_sv.add_argument("--workspace", type=str, required=True, help="the workspace folder (gea workspace --action init)")
-    p_sv.add_argument("--host", type=str, default="127.0.0.1", help="bind address; 0.0.0.0 exposes it on the site network (put TLS in front)")
+    p_sv.add_argument("--host", type=str, default="127.0.0.1", help="bind address; 0.0.0.0 exposes it on the site network (turn HTTPS on first: gea tls)")
     p_sv.add_argument("--port", type=int, default=8765)
     p_sv.add_argument("--workers", type=int, default=1, help="jobs run at once")
     p_sv.add_argument("--no-scheduler", action="store_true", help="do not run scheduled jobs from this process")
     p_sv.add_argument("--behind-proxy", action="store_true", help="a reverse proxy terminates TLS in front: trust X-Forwarded-For/-Proto, mark the cookie Secure (deploy/ has nginx and Caddy examples)")
     p_sv.add_argument("--no-browser", action="store_true", help="do not open the control panel in a browser once the service is listening (a scheduled start, a restart, a server with no desktop)")
 
+    p_tl = sub.add_parser("tls", help="HTTPS for the dashboard: the site's own certificate, a self-signed one made here, or off; with no option, how it stands")
+    p_tl.add_argument("--workspace", type=str, required=True)
+    p_tl.add_argument("--site-cert", type=str, default=None, help="the site's certificate (PEM, the server's first, then any chain) - read from where it is at every start")
+    p_tl.add_argument("--site-key", type=str, default=None, help="its private key (PEM, without a passphrase)")
+    p_tl.add_argument("--self-signed", action="store_true", help="make a self-signed certificate and key in the workspace's keys\\tls folder")
+    p_tl.add_argument("--name", action="append", default=[], help="--self-signed: a host name or address the dashboard is reached by (repeat; default: this machine's names, localhost, 127.0.0.1)")
+    p_tl.add_argument("--days", type=int, default=825, help="--self-signed: days valid (at most 825)")
+    p_tl.add_argument("--bits", type=int, default=2048, choices=[2048, 3072])
+    p_tl.add_argument("--off", action="store_true", help="plain HTTP from the next start (the files are left where they are)")
+    p_tl.add_argument("--export-cert", type=str, default=None, help="write the certificate (public, never the key) to this file, for the site's computers to trust")
+    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")
@@ -2603,6 +2634,88 @@ 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
+        from .workspace import Workspace, WorkspaceError
+        try:
+            ws = Workspace(a.workspace)
+            if sum(bool(x) for x in (a.self_signed, a.site_cert or a.site_key, a.off)) > 1:
+                raise ValueError("one of --self-signed, --site-cert/--site-key or --off")
+            if a.site_cert or a.site_key:
+                if not (a.site_cert and a.site_key):
+                    raise ValueError("--site-cert and --site-key go together")
+                r = _TLS.use_site_certificate(ws, a.actor, a.site_cert, a.site_key)
+            elif a.self_signed:
+                r = _TLS.make_self_signed(ws, a.actor, a.name or None, a.days, a.bits)
+            elif a.off:
+                r = _TLS.turn_off(ws, a.actor)
+            else:
+                r = _TLS.status(ws)
+            if a.export_cert:
+                pem = _TLS.certificate_pem(ws)
+                if not pem:
+                    raise ValueError("HTTPS is off: there is no certificate to export")
+                with open(a.export_cert, "wb") as f_:
+                    f_.write(pem)
+        except (KeyError, ValueError, OSError, WorkspaceError) as e:
+            raise SystemExit(f"tls: {e.args[0] if e.args else e}")
+        if a.json:
+            print(_json.dumps(r, default=str))
+        else:
+            print(_TLS.text(r))
+            if a.self_signed or a.site_cert or a.off:
+                print("   takes effect at the next start of the control panel (gea serve, or Restart on the Administration page)")
+            if a.export_cert:
+                print(f"   certificate written to {a.export_cert} - hand this out, never the key")
+        return 0
     elif a.cmd == "frac-hits":
         import json as _json
         from . import frac_hits as _FH
@@ -2946,18 +3059,29 @@ def main(argv=None) -> int:
             print(f"serve: BLOCK {mism}")
         if pre or mism:
             raise SystemExit("serve: not starting - fix the above (gea doctor --workspace ... shows the full picture)")
+        from .tls import TlsError
         try:
             svc = Service(a.workspace, host=a.host, port=a.port, workers=a.workers, scheduler=not a.no_scheduler, behind_proxy=a.behind_proxy)
         except WorkspaceError as e:
             raise SystemExit(f"serve: {e}")
+        except TlsError as e:
+            raise SystemExit(f"serve: HTTPS is on for this workspace but {e}. Put the files right, or: gea tls --workspace \"{a.workspace}\" --off")
         n_users = svc.app.users.count()
         print(f"gea {__version__}: serving workspace '{svc.ws.manifest['name']}' at {svc.url}")
         print(f"   code: {os.path.dirname(os.path.abspath(__file__))}   (an installed copy serves the files it was installed from; pip install -e <clone> follows the clone)")
         print(f"   patches: {len(svc.app.patches.store.list())} defined, {len([s for s in svc.app.patches.states() if s['status'] != 'STOPPED'])} running")
         if n_users == 0:
             print("   no accounts yet: the page will ask for the first administrator's name and password (one time), or run: gea users --workspace ... --action add --role admin --name ...")
-        if a.host not in ("127.0.0.1", "localhost", "::1") and not a.behind_proxy:
-            print("   NOTE: bound to a network address without --behind-proxy: traffic is plain HTTP. Put TLS in front (deploy/README.md) for anything beyond a trusted LAN.")
+        if svc.tls_status:
+            ts_ = svc.tls_status
+            f_ = ts_.get("facts") or {}
+            print(f"   HTTPS ({ts_['state']}): {ts_['detail']}")
+            print(f"   names {', '.join(f_.get('names') or [])}; SHA-256 {f_.get('sha256_fingerprint')}")
+            if f_.get("self_signed"):
+                print(f"   the certificate to hand out (never the key): {ts_['cert']}  - or download it from the Administration page")
+        elif a.host not in ("127.0.0.1", "localhost", "::1") and not a.behind_proxy:
+            print("   NOTE: bound to a network address in plain HTTP. Turn HTTPS on (gea tls --workspace ... --site-cert/--site-key, or --self-signed),")
+            print("   or put the site's TLS proxy in front (--behind-proxy; deploy/README.md), for anything beyond a trusted LAN.")
         print("   Ctrl+C stops it; every action is in records/audit.jsonl, every start and stop in records/runlog.jsonl")
         print("   the control panel's Stop and Restart end this run with a stated code: 0 stop, 86 start me again -")
         print("   the launcher reads it, and on anything but 86 it hands the window to a PowerShell prompt, never a Python one")