dohertj2/wwtools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

mxaccesscli: add --username / --domain / --password to write

Browse Source 
Wraps LMXProxyServer.AuthenticateUser at the session level
(MxSession.Authenticate) and surfaces three new options on the
write command:

  -u, --username <name>   galaxy / OS user
      --domain   <name>   composed as <domain>\<username>; omit for
                          galaxy-authenticated logins or UPN forms
  -p, --password <pwd>    redacted to "***" in the JSON query echo

The CLI calls AuthenticateUser before AddItem so an auth failure
(userId == 0) bails out cleanly without leaving a half-set-up item.
On success the resolved userId flows into Write(hServer, hItem,
value, userId) and is reflected in:

  - human output: "[OK ] write <tag> = <val> (as <verify-user>, userId=N)"
  - LLM-JSON results[]: { "authenticated": true, "auth_user_id": N }

Verified live against TestChildObject.TestInt with credentials
DESKTOP-6JL3KKO\dohertj / Sonamu89:

  read   -> 99
  write 7 with --username/--domain/--password -> ok, auth_user_id=1
  read   -> 7
  write 99 with same auth -> ok
  read   -> 99 (restored)

Important behavior surfaced and documented in docs/usage.md
"Authentication" section: on a galaxy configured in permissive
(Free Access) mode, AuthenticateUser returns a non-zero userId
regardless of credentials — verified by intentionally passing a
wrong password and an unknown user, both of which still resolved
to userId=1 and the write went through. The CLI's auth path is
wired correctly; the galaxy just isn't strict. To exercise real
authentication, target a galaxy with galaxyAuthenticationMode and
attribute-level security above Free Access.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-05-03 22:00:06 -04:00
parent 7da30cf515
commit 0d25ec445f
3 changed files with 126 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
mxaccesscli/docs/usage.md
+58 -2
View File
@@ -66,9 +66,12 @@ Writes one value to one tag and waits for `OnWriteComplete`.
| --- | --- | --- |
| `--type <kind>` | inferred | Force the .NET type used for the boxed value. One of `bool`, `byte`, `short`, `int`, `long`, `float`, `double`, `string`, `datetime`. |
| `-t`, `--timeout <seconds>` | `5` | How long to wait for `OnWriteComplete`. |
| `--user-id <int>` | `0` | Authenticated user id. `0` is unauthenticated; secured attributes will reject. |
| `--user-id <int>` | `0` | Pre-resolved authenticated user id passed straight to `Write()`. Use only when you already have a userId. `0` = unauthenticated. |
| `-u`, `--username <name>` | (none) | Galaxy / OS username. Combined with `--domain` (if set) into `<domain>\<username>` and resolved to a userId via `AuthenticateUser` before `Write()`. See [Authentication](#authentication). |
| `--domain <name>` | (none) | Domain or hostname for OS-authenticated galaxies. Combined with `--username` as `<domain>\<username>`. Omit for galaxy-authenticated logins. |
| `-p`, `--password <pwd>` | (none) | Password for `--username`. Redacted (`***`) in the LLM-JSON `query` echo. |
| `--client <name>` | `mxa` | Passed to `Register()`. |
| `--llm-json` | off | Emit the JSON envelope. |
| `--llm-json` | off | Emit the JSON envelope. Includes `authenticated` and `auth_user_id` fields when `--username` was supplied. |
Type inference rules (when `--type` is not set): `true`/`false`/`yes`/`no`/`on`/`off`/`1`/`0` → bool; pure integer → `int` (then `long`); decimals → `double`; everything else → `string`.
@@ -83,6 +86,59 @@ mxa write Reactor1.Setpoint 100 --type int -t 10 --llm-json
The same JSON envelope shape as `read`, with `results[0]` containing `{ tag, ok, error?, statuses }`. No `value`/`quality`/`timestamp` on the write result — consult a follow-up `mxa read` to confirm.
## Authentication
Most galaxies require an authenticated `userId` to write attributes whose security classification is anything stricter than `Free Access` (i.e. `Operate`, `Tune`, `Configure`, `Secured Write`, `Verified Write` — see [`../../aot/dev-guide/appendix-e-security-classifications.md`](../../aot/dev-guide/appendix-e-security-classifications.md)).
The `write` command resolves credentials to a `userId` by calling `LMXProxyServer.AuthenticateUser(verifyUser, password)`. The `verifyUser` string is composed from `--username` and `--domain`:
| Galaxy mode | Pass | Composes to |
| --- | --- | --- |
| `osAuthenticationMode` (Windows / domain users) | `--username dohertj --domain DESKTOP-6JL3KKO` | `DESKTOP-6JL3KKO\dohertj` |
| `galaxyAuthenticationMode` (galaxy-internal users) | `--username dohertj` (no `--domain`) | `dohertj` |
| Mixed / AAD UPN | `--username dohertj@example.com` | `dohertj@example.com` |
Example:
```powershell
mxa write TestMachine_001.Setpoint 75.5 --type double `
--username dohertj --domain DESKTOP-6JL3KKO --password Sonamu89 `
--llm-json
```
A successful authentication populates two new fields in the JSON envelope's `results[]`:
```jsonc
{
"tag": "TestMachine_001.Setpoint",
"ok": true,
"authenticated": true,
"auth_user_id": 17, // returned by AuthenticateUser; 0 means failure
"statuses": [{"Category":"MxCategoryOk", ...}]
}
```
The human output appends `(as <verify-user>, userId=N)` to the success line so the right credentials are visible in interactive use.
### Password handling
`--password` is **redacted** to `***` in the LLM-JSON `query` echo and never logged in cleartext. It travels in-process from CliFx's argument parser straight into `AuthenticateUser` and is not persisted anywhere by the CLI.
### Failure modes
| What you sent | What you get |
| --- | --- |
| Correct credentials, strict-mode galaxy | `authenticated=true`, `auth_user_id` > 0, write proceeds. |
| Bad password, strict-mode galaxy | `auth_user_id == 0` → CLI exits 1 with `"error": "authentication-failed"`. No write attempted. |
| Bad password, **permissive-mode galaxy** | The proxy returns a non-zero `auth_user_id` regardless. The CLI cannot tell this apart from a successful auth — it's the galaxy admin's responsibility to configure security strictly enough to reject. |
| `--username` without `--password` | Sends an empty password. Some galaxies allow this; most don't. |
> ⚠️ Verified behavior on the test galaxy used during development: `AuthenticateUser` returned `userId=1` for both the correct password and intentionally bad credentials (incl. an unknown username). This is consistent with a galaxy configured in `Free Access` mode where security checks are effectively disabled — the CLI's auth path is wired correctly, the galaxy just isn't strict. To exercise real authentication, target a galaxy with `galaxyAuthenticationMode` enabled and attribute-level security classifications above `Free Access`.
### Reusing an already-resolved `userId`
`AuthenticateUser` may be expensive (involves SQL Server lookup + Windows cred check). For batch scripts that issue many writes, call `AuthenticateUser` once via a manual call, capture the `userId`, then pass it directly via `--user-id <N>` to subsequent `write` invocations. This skips the per-call auth round-trip.
## `mxa subscribe <tag> [<tag>...]`
Streams `OnDataChange` events for a duration.