Skip to content

feat(cli): Add the vew command-line client - #187

Merged
raphaho merged 9 commits into
mainfrom
feat/vew-cli
Nov 13, 2026
Merged

raphaho merged 9 commits into
mainfrom
feat/vew-cli

Conversation

@raphaho

@raphaho raphaho commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What does this change do?

Adds vew, a Rust command-line client for the workbench, for scripting and CI use where
the web app is not practical, plus the single API endpoint it talks to.

The CLI.

  • vew auth login runs an authorization-code flow with PKCE against the configured OIDC
    provider, receives the callback on a loopback port, and stores tokens per profile.
    vew auth logout revokes the refresh token where the provider has a revocation endpoint.
  • Commands are derived at runtime from each bounded context's OpenAPI document, so the CLI
    tracks the APIs without being regenerated.
  • Configuration is a per-profile file holding the issuer, the OIDC client id and the API
    endpoint. The CLI needs no AWS credentials.
  • Install scripts for Unix shells and PowerShell, and .github/workflows/cli.yml running
    fmt, clippy with warnings as errors, the tests and a dependency audit (cargo-audit
    pinned to 0.22.2), on Rust 1.95.0.

The endpoint it points at. A deploy has one API Gateway per bounded context, so there
was no single host for api_endpoint. VewApiRouterStack provides it: an HTTP API that
path-routes /{bounded-context}/* to each backend gateway. It is built only when the
vew-cli app client is configured and the frontend and backend share a region, because its
authorizer reads that client's id from SSM. With a custom API domain, ApiIntegrationStack
already fronts the gateways and no router is built.

deploy.sh phase 7b writes /<app-name>-ui-<env>/vew-api-endpoint and deletes a router
stack left over once it is no longer configured. --diff stops before this phase, so a
diff writes and deletes nothing.

Type of change

  • Bug fix
  • New feature
  • Refactor / tech debt
  • Documentation
  • Infrastructure / CI

How was this tested?

  • cargo fmt --check, and cargo clippy --all-targets -D warnings with and without the
    log-capture feature: clean.
  • cargo test --features log-capture: 185 passed. Plain cargo test: 177.
  • cargo audit: no vulnerabilities. Two advisories are ignored with written reasons in
    cli/.cargo/audit.toml.
  • pytest infra/backend/tests/test_vew_api_router_stack.py: 16 passed. Synth with and
    without vew-cli configured, and with a custom domain.
  • bash -n deploy.sh and the shell tests under tests/ pass.
  • Deployed to a fresh hub and spoke pair:
    • deploy.sh wrote the endpoint parameter, and every CLI call in the test went through
      the router.
    • vew auth login --verbose and a token refresh logged no code, state, token or claim
      value.

Checklist

  • Follows the guidance in CONTRIBUTING.md
  • Tests added/updated and passing locally
  • Lint / type checks pass locally
  • No secrets, credentials, or account IDs committed
  • Docs updated if behavior or usage changed (cli/README.md, cli/CHANGELOG.md)
  • Linked the related issue (if any): closes #

Notes for reviewers

Where to focus. src/identity/, which holds the OIDC flow, PKCE, the loopback callback
server, token storage and JWT validation, and src/vew_api/domain/service.rs, which
decides which operations become commands.

Nothing secret reaches the log or an error message, --verbose included.

  • Token, refresh and revocation errors report the HTTP status and a standard RFC 6749/7009
    error code only. Provider text such as error_description is dropped, and so are
    non-standard codes.
  • Malformed token responses are reported without quoting the rejected value.
  • Callback errors never include the request line or query.
  • A state mismatch carries neither state value.
  • Rejected ID tokens are reported by error kind only, never with jsonwebtoken's message,
    the kid or a claim.
  • Tests built with the log-capture feature assert that planted markers appear in neither
    the log nor the error. They fail against the earlier logging.

Token file and callback. The token file's temporary copy is created with mode 0600, not
narrowed after writing, and a stale or planted .tmp is removed first. The callback read is
capped at 64 KiB across the request line and headers.

The two ignored advisories sit on the signing paths of jsonwebtoken's dependencies.
The CLI only verifies JWTs against the provider's public keys, with RS256 only.

Setting it up.

  1. Add a vew-cli entry to ADDITIONAL_APP_CLIENTS with
    http://localhost:17823/callback as its callback URL. It must be a public client with no
    secret, since the CLI uses PKCE.
  2. Deploy. Phase 7b writes /<app-name>-ui-<env>/vew-api-endpoint.
  3. Put that endpoint, the issuer URL and the client id into ~/.vew/config.

Acknowledgment

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

raphaho added 3 commits November 8, 2026 22:42
A Rust CLI that logs in against the workbench's OIDC provider and calls
the workbench APIs from a terminal, for scripting and CI use where the
web app is not practical.

- `vew login` runs an authorization-code flow with PKCE against the
  configured provider, receiving the callback on a loopback port, and
  stores the tokens per profile. `vew logout` revokes the refresh token
  where the provider exposes a revocation endpoint.
- Commands are derived at runtime from each bounded context's OpenAPI
  document, so the CLI follows the APIs without being regenerated.
  Internal and documentation paths are skipped.
- Configuration is a per-profile file holding the issuer, the OIDC client
  id and the API endpoints. Nothing is discovered from AWS, so the CLI
  needs no AWS credentials.
- Install scripts for Unix shells and PowerShell, and a GitHub Actions
  workflow running fmt, clippy with warnings as errors, the test suite
  and a dependency audit, all pinned to Rust 1.95.

Diagnostics are off unless --verbose is passed. The token-endpoint
response body and the OAuth callback query string are never logged,
since they carry tokens and the authorization code; only their sizes and
the request path are. OAuth error bodies and JWKS documents are logged,
as neither contains a credential.

To use it, register an additional Cognito app client through the
deployment's ADDITIONAL_APP_CLIENTS setting and put that client id in the
CLI's config file.
The CLI's config holds one `api_endpoint`, but a deploy provisions one API
Gateway per bounded context. Without a custom API domain there is no host
in front of them, so the CLI has nothing to point at.

VewApiRouterStack supplies that host: an HTTP API that path-routes
/{bounded-context}/* to each backend gateway, resolving each target from
the SSM parameter that context's own stack publishes. It is registered as
the `else` of the ApiIntegrationStack branch in backend_app.py, because
with a custom API domain that stack already fronts the gateways under one
host and a second hop would be redundant.

Every route is behind a JWT authorizer. The CLI sends a Cognito access
token, which carries client_id and no aud claim, so the audience is the
CLI's app client id, read from the per-client SSM parameter the frontend
stack publishes for each AdditionalAppClients entry. Registering the
client is therefore a config change, not a code change: add a "vew-cli"
entry naming http://localhost:17823/callback as its callback URL.

deploy.sh gains phase 7b, the single writer of
/<app>-<env>/vew-api-endpoint in both deploy modes — the router's output
when there is no custom domain, the custom domain itself when there is.
Keeping it out of the stacks means an environment that drops its custom
domain does not fail on a parameter that already exists.
Running the CLI's own CI checks locally surfaced work the import needed.

- rustls 0.23.45 -> 0.23.46 clears four advisories, the most serious being
  Debug impls on client session values exposing TLS secrets
  (RUSTSEC-2026-0346), plus buffered data after ECH rejection, unbounded
  Brotli certificate decompression, and a ServerHello downgrade.
- rustls-webpki 0.103.15 -> 0.103.16 clears RUSTSEC-2026-0382, where
  certificate verification could accept distrusted intermediates.
- RUSTSEC-2026-0387, timing variability in crypto-bigint, is exempted with
  its reasoning in .cargo/audit.toml. It arrives through jsonwebtoken ->
  p256/p384 -> elliptic-curve, and the fix needs an upstream chain this
  repo cannot pull forward. It does not apply: the validator only verifies
  against public JWKS keys and holds no signing key, and it configures
  RS256 only, so the ECDSA path is linked but never executed.
- cargo fmt reformats the multi-line debug_log! call.
- cli/.gitignore no longer points at a CI config this repo does not have.

cargo fmt --check, cargo clippy --all-targets --release --locked
-- -D warnings, cargo test --release --locked and cargo audit all pass.
@raphaho
raphaho requested a review from a team November 9, 2026 16:13
@raphaho raphaho closed this Nov 9, 2026
@raphaho raphaho reopened this Nov 9, 2026
Raphael Hofer added 4 commits November 11, 2026 16:17
Make the "no secret is logged" property assertable, then fix every place
a probe with planted markers found one.

debug_log! writes to stderr, which a test cannot read back, so the
property was unassertable and any regression invisible. It now also
records into an in-memory buffer, compiled only under cfg(test) or the
new log-capture feature so a release binary has no buffer at all. The
adapter tests live in cli/tests/, which does not get cfg(test) for this
crate, so CI runs cargo test --features log-capture; without the feature
the new test file compiles to nothing.

New oauth_error module renders a failed OAuth call from its status and
an RFC 6749 / 7009 error code only. A token-endpoint error body can
contain a refresh token, a revocation error body echoes the submitted
token, and error_description is free text chosen by whoever drove the
redirect, so none of it reaches the user or the log. A code outside the
RFC list collapses to a placeholder rather than being echoed.

A serde error quotes the value it rejected, for example
`invalid type: string "<access token>"`. The exchange path now reports
the position only, and the refresh and discovery paths report nothing
from the message.

The callback server no longer puts the request target in the
unexpected-path error, since the query carries code and state, and no
longer forwards error_description or a non-standard error code. Its
request read is capped at 64 KiB: this port takes unauthenticated input,
and read_line on a client that never sends a newline grew without bound.

StateMismatch carried both state values; printing the expected one lets
anyone reading the output replay it, and the mismatch alone is what the
user needs. The JWT validator no longer logs the kid or the sub, and
reports the jsonwebtoken error kind rather than its Display text, which
can quote the token.

The token file's .tmp was created at the umask default and chmod'd to
0600 afterwards, so the secret was briefly readable by others. It is now
created with mode 0600 via create_new, which also refuses to follow a
symlink planted at that path, and a stale .tmp is removed first.

Also: pin cargo-audit to 0.22.2; correct the RUSTSEC-2023-0071 reason,
which claimed upstream has no fix — the advisory records "Patched
>= 0.10.0" and cargo tree shows rsa 0.9.10 is pinned by jsonwebtoken's
rust_crypto backend, which is the real reason we cannot take it;
replace the no-op test_discovery_success, which had neither an act nor
an assert step; and correct cli/README.md, which named a
vew-cli-client-id parameter and a VewCliClientId output that do not
exist and said deploy.sh creates the CLI app client, which it does not.

Each redaction test was confirmed to fail against the unfixed adapter:
5 of 6 fail with the fix stashed. 182 tests pass with the feature,
plain cargo test stays green, clippy --all-targets -D warnings clean.
The router exists only to give the vew CLI one api_endpoint when there
is no custom API domain, but it was built on every domainless deploy.
Its authorizer resolves /<app>-ui-<env>/app-client-id/vew-cli at synth,
and that parameter exists only when the frontend deployment's
ADDITIONAL_APP_CLIENTS contains a vew-cli entry, so a deploy without
that client stood up a stack nothing used and failed on the lookup.

deploy.sh now decides and passes it as context. Two conditions, not
one: the client has to be configured, and the frontend and backend have
to be in the same region. The parameter is written by the frontend
stacks in FE_REGION while the router reads it in AWS_REGION, and a
public deployment puts the frontend in us-east-1 wherever the backend
runs, so that read would miss. A mismatch now warns and skips rather
than failing later.

When the router is no longer configured, Phase 7b deletes a stack left
behind by an earlier deploy that did have the client. Without that it
keeps serving an endpoint nothing maintains, and no later deploy ever
touches it again. A delete that a CloudFormation export blocks warns
instead of aborting, since the leftover is inert once the stack is out
of the CDK app.

Phase 7b also no longer runs under --diff. Its put-parameter is a real
write, and the router-output read fails outright when the router stack
does not exist, so a diff on a fresh account stopped with an error
about a stack a deploy had not yet created. The diff now exits before
it, and the closing summary names the two extra things it skips.

Verified by synthesising the backend app with vew-cli-enabled both true
and false: the router template is present in the first and absent in
the second, with no synth error either way. The jq client test was
checked against an empty list, a list without the entry, and lists with
it. shellcheck and bash -n are clean.
Remove the remaining OAuth callback log leaks and handle API router lifecycle transitions across custom-domain and regional deployments. Correct the documented SSM endpoint path.
A rejected ID token was reported as "token rejected: {kind:?}". The
kind is not a fixed enum: ErrorKind::Json wraps the serde error, which
quotes the rejected claim value, and other variants carry text. With
--verbose the value reached the debug log as well as the error.

Map each kind to a fixed name and drop its payload. The new redaction
test signs a token whose sub is a number and fails against the
previous commit.
andreameroni
andreameroni previously approved these changes Nov 13, 2026
Raphael Hofer added 2 commits November 13, 2026 15:23
Since #199 the backend builds ApiIntegrationStack, not the vew CLI
router, when the API custom domain's certificate comes from
PRIVATE_CA_ARN as well as from CERT_ARN. deploy.sh still decided by
CERT_ARN alone, so a private deployment using a private CA with the
vew-cli client configured would look for the router in phase 7b and
fail. Use the same condition as backend_app.py.
@raphaho
raphaho merged commit 23a7a1d into main Nov 13, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants