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

{gea_program-0.53.0 → gea_program-0.55.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gea-program
-Version: 0.53.0
+Version: 0.55.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`
@@ -648,6 +648,17 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Decline curves
+
+Each well's monthly production fitted by Arps's curves - the modified
+hyperbolic, turned exponential at a terminal decline - forecast month by
+month to its economic limit and valued: the estimated ultimate recovery,
+and the net cash flow discounted at the declared rate, at the SEC 12-month
+average of the first-of-month WTI and Henry Hub prices (shipped from the
+EIA) or a declared price, with the net revenue interest, severance tax and
+operating cost declared. A forecast is not a reserves report, and the page
+says so. The **Decline curves** tab, `gea decline`, `gea help decline`.
+
 ### Torque and drag
 
 The hook load and torque the drill string should take at each bit depth, by
@@ -1238,11 +1249,35 @@ 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`.
+
 ### 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.53.0 → gea_program-0.55.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`
@@ -609,6 +609,17 @@ against it; `gea seedlink --config ... --hello` prints what a server says of
 itself; `gea help seedlink`. A TexNet station is served by EarthScope at
 `rtserve.iris.washington.edu:18000`, network `TX`.
 
+### Decline curves
+
+Each well's monthly production fitted by Arps's curves - the modified
+hyperbolic, turned exponential at a terminal decline - forecast month by
+month to its economic limit and valued: the estimated ultimate recovery,
+and the net cash flow discounted at the declared rate, at the SEC 12-month
+average of the first-of-month WTI and Henry Hub prices (shipped from the
+EIA) or a declared price, with the net revenue interest, severance tax and
+operating cost declared. A forecast is not a reserves report, and the page
+says so. The **Decline curves** tab, `gea decline`, `gea help decline`.
+
 ### Torque and drag
 
 The hook load and torque the drill string should take at each bit depth, by
@@ -1199,11 +1210,35 @@ 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`.
+
 ### 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.53.0 → gea_program-0.55.0}/gea/__init__.py

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

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

@@ -622,6 +622,21 @@ def main(argv=None) -> int:
     p_pl.add_argument("--actor", type=str, default="cli")
     p_pl.add_argument("--json", action="store_true")
 
+    p_dc = sub.add_parser("decline", help="each well's monthly production fitted by Arps's curves, forecast to its economic limit and valued at the SEC 12-month price or a declared one")
+    p_dc.add_argument("--workspace", type=str, required=True)
+    p_dc.add_argument("--well", type=str, default=None)
+    p_dc.add_argument("--attach", type=str, default=None, help="attach FILE as the well's monthly production (CSV or Excel)")
+    p_dc.add_argument("--remove", action="store_true")
+    for k_, h_ in (("terminal-decline", "the terminal decline, effective annual (0.08 = 8 %%)"), ("b-max", "the largest b fitted"), ("oil-price", "USD/bbl"),
+                   ("gas-price", "USD/MMBtu"), ("price-basis", "sec or flat"), ("nri", "the net revenue interest"), ("severance", "the severance tax (0.046 = 4.6 %%)"),
+                   ("opex", "the operating cost, USD a month"), ("discount", "the discount rate (0.10)"), ("start", "fit from this month (YYYY-MM)"),
+                   ("as-of", "value as of this date (YYYY-MM-DD)")):
+        p_dc.add_argument("--" + k_, type=str, default=None, help=h_)
+    p_dc.add_argument("--source", type=str, default="", help="where the production or the terms came from")
+    p_dc.add_argument("--write", action="store_true")
+    p_dc.add_argument("--actor", type=str, default="cli")
+    p_dc.add_argument("--json", action="store_true")
+
     p_td = sub.add_parser("torque-drag", help="the hook load and torque the string should take at each bit depth (soft-string model), the broomstick, and the friction factors that fit the rig's own trips")
     p_td.add_argument("--workspace", type=str, default=None)
     p_td.add_argument("--well", type=str, default=None)
@@ -741,13 +756,26 @@ 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_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")
@@ -2486,6 +2514,42 @@ def main(argv=None) -> int:
             raise SystemExit(f"collision: {e.args[0] if e.args else e}")
         print(_json.dumps({k: v for k, v in r.items()}, default=str) if a.json else _CO.text(r))
         return 0
+    elif a.cmd == "decline":
+        import json as _json
+        from . import decline as _DCA
+        from .cli import _safe_stdout
+        from .workspace import Workspace, WorkspaceError
+        _safe_stdout()
+        try:
+            ws = Workspace(a.workspace)
+            terms = {"terminal_decline": a.terminal_decline, "b_max": a.b_max, "oil_price": a.oil_price, "gas_price": a.gas_price, "price_basis": a.price_basis,
+                     "nri": a.nri, "severance": a.severance, "opex_month": a.opex, "discount": a.discount, "start": a.start}
+            if (a.attach or a.remove or any(v is not None for v in terms.values()) or a.write) and not a.well:
+                raise ValueError("--well is needed")
+            if a.attach:
+                with open(a.attach, "rb") as f_:
+                    r_ = _DCA.attach(ws, a.well, os.path.basename(a.attach), f_.read(), a.actor, a.source)
+                print(f"production attached to {a.well}: {r_['months']} months, {r_['first']} to {r_['last']}")
+                return 0
+            if a.remove:
+                _DCA.remove(ws, a.well, a.actor)
+                print(f"production removed from {a.well}")
+                return 0
+            if any(v is not None for v in terms.values()):
+                c_ = _DCA.set_config(ws, a.actor, a.well, a.source, **{k: v for k, v in terms.items() if v is not None})
+                print(f"{a.well}: terminal {c_['terminal_decline']:g}, price {c_['price_basis']}, NRI {c_['nri']:g}, severance {c_['severance']:g}, opex {c_['opex_month']:,.0f}/month, discount {c_['discount']:g}")
+                return 0
+            if a.write:
+                r_ = _DCA.write_report(ws, __version__, a.well, a.actor)
+                print(f"wrote {r_['report_id']}: {r_['paths']['html']}")
+                if r_['paths'].get('pdf'):
+                    print(f"  printable: {r_['paths']['pdf']}")
+                return 0
+            r = _DCA.page(ws, a.well, a.as_of)
+        except (KeyError, ValueError, OSError, WorkspaceError) as e:
+            raise SystemExit(f"decline: {e.args[0] if e.args else e}")
+        print(_json.dumps(r, default=str) if a.json else _DCA.text(r))
+        return 0
     elif a.cmd == "torque-drag":
         import json as _json
         from . import torque_drag as _TND
@@ -2552,6 +2616,41 @@ 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 == "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
@@ -2895,18 +2994,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")