Add database tunnel, CLI, and Sequel commands via SSM

[rmccue]

Adds three commands for connecting to an application's primary database through its sandbox:

altis-cli app database tunnel example-dev-01 --port 3307
altis-cli app database cli example-dev-01 --port 3307
altis-cli app database sequel example-dev-01 --port 3307

• tunnel opens a loopback TCP listener for an external database client.
• cli launches the local mysql executable with the terminal attached.
• sequel opens Sequel Ace or Sequel Pro on macOS, matching local-server's composer server db sequel command.

All commands accept an optional stack argument (otherwise prompt), and a local port that defaults to 3306. They create sessions using the POST endpoint in humanmade/vantage-backend#1547 and request remote cleanup using its DELETE endpoint after disconnect, interruption, bind failure, or client-launch failure. Transport uses aws_ssm_session_id; cleanup uses the Vantage record id.

The client commands obtain credentials from the existing database-server endpoint and require permission to retrieve its password. Credentials are kept out of process arguments and environment variables, written only to private temporary files (0700 directory / 0600 file), and removed when the command finishes. The MySQL client uses TCP to the loopback listener; Sequel uses an escaped local .spf connection file.

The binary transport bounds buffering, respects SSM pause/resume, negotiates non-multiplexed port forwarding, rejects additional client connections, and handles errors and terminal interrupts. It supports one database client connection per SSM session.

Prerequisites before shipping

• SSM socket support: Add binary socket APIs and controlled handshakes for port forwarding ssm#2 is merged and released as @humanmade/ssm 0.0.4. This PR now depends on ^0.0.4 and locks the published package, including its raw binary and public handshake APIs.
• Vantage API: humanmade/vantage-backend#1547 must be deployed before automatic session creation and cleanup can work.
• Live validation: test real MySQL/TLS and Sequel connections, large results, idle periods, interruptions, and remote cleanup. The historical intermittent SSL/keepalive issue remains to be checked with the integrated SSM library. Local tests use fake sessions and real loopback TCP sockets; no live AWS session or GUI was launched.

Validation

• npm test: 56 passing tests, including transport, Vantage creation/cleanup, bind and constructor failures, malformed connection data, private temporary-file cleanup, credential escaping, MySQL launch, and missing-client errors.
• npm run test:native: 4 passing tests, with discovery/help coverage for all three new commands through both app and stack.
• npm run typecheck, npm run build, npm run smoke, and git diff --check: passed.
• Generated Sequel configuration parsed successfully with Python plistlib.

Keep as draft until the deployed backend endpoint, complete database commands, and Sequel GUI pass end-to-end validation.

Live follow-up validation (2026-10-15)

• With SSM PR Prepare v1 Release #2 loaded process-locally on platform-test, interactive SSH, UTF-8, terminal resizing, 256 KiB output, command failures, a 65-second keepalive check, simultaneous sessions, and three fresh connections passed.
• SCP uploaded and downloaded empty, 513-byte binary, and 1 MiB random files with matching SHA-256/content.
• The database tunnel transport passed read-only live MySQL checks with required TLS, a 256 KiB result, and binary bytes. A test adapter created/terminated the real AWS session; the new backend REST route remains undeployed, so full database commands and Sequel GUI are still untested.
• Fixed pasted UTF-8 corruption (2821fd5) and live-test shell cleanup (135d3d1). Verified zero active test sessions and no remaining test-created sandbox shells. Older sandbox processes and application services were untouched.

Published SSM dependency integration (2026-10-16)

Updated the dependency and lockfile to @humanmade/ssm@^0.0.4, installed the registry package in an isolated checkout, and refreshed the compatibility guard and README. Typecheck, 60 tests, four native-source checks, smoke, and diff checks passed. A 131,075-byte binary round trip over real local TCP/WebSocket sockets passed using the installed npm package, with exactly one remote cleanup request.

Staging authentication

The OAuth browser login now uses the origin configured by VANTAGE_URL, matching token exchange. Failed HTTP responses, invalid JSON, and missing access tokens reject the login instead of leaving the CLI waiting behind a false success screen. Token exchange has a 30-second timeout, and authentication waits for token persistence. Callback and URL regression tests are included; 64 tests, four native checks, and typecheck pass.

[joehoyle]

@rmccue how are you starting the SSM session? I assume you are starting it with a different document perhaps? Currently with the SSM PR too, I am not getting a handshake request

[joehoyle]

Ah I see https://github.com/humanmade/vantage-backend/pull/1547/files

[joehoyle]

I set this up locally, and I was running in to intermittent connection errors, specifically I was seeing an SSL handshake version mismatch error.

I logged all the recieved / sent data and ran a diff between times it worked and times it didn't which showed https://gist.github.com/joehoyle/116f96f917ea382b481b4a40ce52ede9/revisions. It seems the times it doesn't work, there's extra send packets from the ping interval. Once I commented out the setInterval for ping, I did not have connection errors.

Once connected I also haven't experienced any drops with the ping code removed.

@rmccue mentioned that the ping shouldn't interfere with the mysql connection, as presumably that's a different packet type or something long those lines, but it does seem like it is interfering. Could be that we are messing up state with packet etcs etc with a band implementation, or perhaps could be a ssm-server level issue too.