Restrict Cloud Pod identity reuse to local emulators

[gtsiolis]

Summary

lstk start passes LOCALSTACK_AUTH_TOKEN to the emulator without persisting an environment-provided secret. A later command against that same locally managed emulator can therefore have no caller token even though the emulator already has a valid startup identity.

This change lets emulator-backed Cloud Pod operations reuse that identity only for an lstk-managed local emulator. When the caller supplies a token, lstk continues to send it as the Authorization header, overriding the startup identity.

External endpoints do not get this fallback. snapshot load, save, remove, and load --dry-run require a token from the environment or keychain before lstk calls a protected pod endpoint. Network access to an external emulator is therefore not treated as permission to use its startup identity.

Platform-direct snapshot list, show, and versions continue to require caller authentication. S3 remotes are unchanged because they use the caller's AWS credentials instead of a LocalStack platform token.

Error handling

When a locally managed emulator cannot use either the caller token or its startup identity, 401/403 responses are mapped to snapshot.ErrAuthRequired and rendered as an actionable authentication error. Pod/version not-found and unavailable-feature classifications keep precedence over the generic auth mapping.

This change limits lstk's client behavior; it does not add request authentication to the emulator itself. Per-request protection of privileged emulator endpoints remains a separate server-side hardening concern.

Verification

• go test ./cmd ./internal/emulator/aws ./internal/snapshot
• make test-integration RUN=TestExternalPodOperationsRequireCallerAuthentication
• make test-integration RUN=TestSnapshotLoadPodVersion
• go vet ./... in the root and integration-test modules

The full unit run passed 1,516 of 1,517 tests. The remaining port-sensitive test could not bind because an existing localstack-snowflake container already owned port 4510.

Review: advisable — this changes the authentication boundary for emulator-backed Cloud Pod operations.

Co-Authored-By: Claude noreply@anthropic.com

Closes DEVX-1022

[peter-smith-phd]

I'm a little bit concerned about the security aspects of this PR. Are we saying that an lstk start command requires a valid LOCALSTACK_AUTH_TOKEN, but any other lstk commands after that are just accepted without any authentication?

We now get into a situation with a valid user starts the emulator, but then any other user can assume that user's credentials, without supplying their own. This makes sense when the emulator is locked down to only run on a single (network-confined) host, but as soon as we start running emulators in cloud-based environments, this becomes an issue.

I know that are a lot of other security gaps (especially with our test / test ) credentials, but this PR feels like it's creating a new problem, rather than making it better.

I'd be in favour of either enforcing LOCALSTACK_AUTH_TOKEN is provided, or enforcing a login session. In either case, lstk should always be sending an auth token to the emulator, and the emulator should always be validating it.

[gtsiolis]

Good callout.

The intent is to remove repeated authentication friction for a locally managed, single-user emulator, not to make network access equivalent to authorization. ✔️

I’ve narrowed the PR so startup-identity reuse now applies only to an lstk-managed local emulator. External targets require caller authentication from the environment or keychain before any Cloud Pod load, save, remove, or dry-run operation. S3 remotes remain separate because they use the caller’s AWS credentials.

I think that’s the right boundary for this PR. Separately, we could harden the emulator so privileged endpoints authenticate every request, ideally with a scoped instance credential rather than the container’s platform token.

Could you take another look at this new approach?