#4386 Docs: what serve instances must not share, flat AWS Secrets Manager names, and where OAuth values are stored

Manual changes for swamp-club#4265, whose reporter runs several swamp serve instances in one AWS account and region and asked where OAuth values are stored per vault type and whether they can be namespaced. Conclusion there: one datastore per independent instance, and no namespacing option in serve.

Findings come from swamp at dd6591148 and @swamp/aws-sm in swamp-extensions. They were not run against real AWS or S3: the resolve and migrate functions were run over a simulated flat vault, and the rest is from reading code. Check the v3 claim below before stating it.

how-to/swamp-serve/run-multi-instance-deployment.md: what independent instances must not share

• Give each independent instance its own datastore (bucket and prefix). Instances on the same datastore and namespace are one deployment: same OAuth client, tokens and grants.
• A namespace separates key names but is not a trust boundary (explanation/giga-swamp.md: provenance, not isolation). On v2, a namespaced instance first start copies root token-secrets/, including a co-located encryption key, into its namespace (ROOT_CONTROL_PLANE_IMPORT_PREFIXES in src/cli/commands/serve.ts).
• On v3, the comment above that constant says the writer lease is per datastore, so do not promise independent instances through namespaces. This comes from the comment and has not been tested.
• token-secrets block: if instances use different keys, each needs its own key name. Overwriting the secret makes the other instance refuse to start. The example name swamp-token-secrets-key would collide if copied as is in a shared account.
• For a stable client per instance, link the runbook from swamp-club#4366: /manual/how-to/swamp-serve/deploy-headless-oauth#recreate-an-instance-without-registering-a-new-client

how-to/vaults/use-aws-sm.md: flat secret names

• @swamp/aws-sm uses the swamp key as the secret name, and its list covers the whole account and region. Its config is only region and profile. Two swamp vaults in one account and region are the same store.
• Serve does not store OAuth values in Secrets Manager on current builds.
• If oauth-* secrets exist there, from an older serve or from seeding, a new instance on an empty datastore adopts that client, copies it into its datastore and deletes it from Secrets Manager. The next instance registers a new client. With --keep-oauth-client-in-vault, both share the one client. Deleted names cannot be reused until the 30-day recovery window ends.
• Advice: check for oauth-* secrets before starting new instances, and do not seed flat names in a shared account.
• An instance that started with a supplied client id and secret, then later starts without one on the same datastore, moves only the keys its datastore lacks. A flat oauth-resolved-admins stays in the vault because that instance already cached its own map, and serve does not delete a key it did not copy. Another instance with no supplied pair on an empty datastore can still adopt it, so tell operators sharing the vault to delete it by hand.
• Do not say a prefix option exists. swamp-club#4384 tracks adding secret_prefix to aws-sm and is not scheduled.

Storage reference (reference/swamp-serve/serve-flags.md or the best-fitting page)

• The values are in the reserved _token-secrets vault, encrypted, whatever the user vault type.
• Local: .swamp/_control/token-secrets/values/. S3: _control/token-secrets/values/ under the bucket prefix, or /_control/token-secrets/values/ when namespaced.
• Key names: oauth-client-id, oauth-client-secret, oauth-bootstrap-access-token, oauth-resolved-admins, oauth-resolved-grant-usernames, oauth-access-token-. Markers holding no secret value: oauth-secrets-migrated, oauth-access-tokens-recovered.
• swamp vault list-keys does not show them, and _token-secrets refuses vault commands. That is by design.

Sequencing

• swamp-club#4366 has merged and is live. deploy-headless-oauth says the credentials are in the control-plane store, without paths or per-vault-type detail, so those belong here. Link to its runbook rather than repeating it.
• Its section Keep a seeded client in the user vault covers --keep-oauth-client-in-vault and names only oauth-client-id and oauth-client-secret. It does not say whether a supplied pair skips the migration. Add that once the swamp-club#4265 guard has merged: with a supplied pair the flag has no effect.
• Its runbook says one client per deployment, with replicas sharing it, because the club keeps one instance record per client. Keep this page consistent with that.
• swamp-club#4265 is changing one behaviour: today a supplied client id and secret does not protect flat oauth-* secrets, because the instance still copies and deletes them. The planned guard makes such an instance skip the OAuth migration. Check whether that has merged before describing it.