fix(wallet): authenticate wallet data and remove simulated production balances

[Joaco2603]

Pre-flight checks

• I searched Backend issues for wallet identity, simulated balances, credits, and payment adapters.
• This is a production-safety bug, not a request to add more payment providers.

Priority

P0 — the current API exposes user-selected identity and simulated money-like state.

Problem

/api/wallet/balance, /transactions, and /purchase accept the wallet identity through a user query parameter or fall back to anon-placeholder. Package purchase mutates database credits using a simulated XLM balance, while Stripe and PayPal adapters return fabricated success responses when configured. This must not be reachable in a market deployment.

Proposed solution

1. Require JWT authentication and derive the wallet from the authenticated principal for all private wallet data/mutations.
2. Remove the user query parameter and anonymous fallback.
3. Put simulated credits, balances, and payment adapters behind an explicit development/test-only boundary that fails closed in staging/production.
4. Until the Market V1 economy ADR is approved, either expose verified on-chain/indexed balances or disable the unsupported credit-package flow with an explicit capability response.
5. Record auditable, idempotent ledger references for any future balance mutation.

Acceptance criteria

• One user cannot read or mutate another wallet by changing request parameters.
• Unauthenticated wallet balance, history, and purchase requests return 401.
• Staging/production cannot boot with simulated payment success enabled.
• No fabricated XLM/USD value or transaction ID is presented as real money activity.
• UI can detect that credit packages are unsupported and hide the action safely.
• Authorization and environment fail-closed behavior have integration tests.

Non-goals

• Selecting the final settlement asset or payout policy; that belongs to the economy ADR.
• Adding another mock provider.

[dostertags]

Secure all wallet endpoints by requiring JWT authentication tied directly to the principal, eliminating query-parameter manipulation and anonymous fallbacks. Lock simulated balances, credits, and mock payment adapters behind strict dev-only flags that fail closed in staging and production. Enforce explicit capability responses for unsupported credit flows while logging auditable, idempotent ledger entries for every mutation.

[grantfox-oss]

🦊 GrantFox — @dostertags has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #16)
2. Your PR will be reviewed by the Stellar-AgentVerse maintainers

Good luck! Track your progress on GrantFox.

[dostertags]

Opened #19 for this (Refs #16, not Closes — reasoning in the criteria table below).

Posting everything I noticed while working through the code, including the parts I deliberately did not change, so you can tell me where you disagree rather than discovering it in review.

---

1. The root cause is wider than the wallet module

The issue describes the wallet symptoms accurately, but the reason staging is unsafe is one line repeated across the codebase: every environment gate compared NODE_ENV against the literal 'production' — a denylist of exactly one string.

NODE_ENV=staging therefore received the full development posture, not just simulated payments:

Gate	Location	What staging got
JWT signing key	env.validation.ts / auth.module.ts:20 / jwt.strategy.ts:13	the published dev-secret fallback — anyone can mint a token for any publicKey, which defeats criterion 1 on its own
DB_SYNCHRONIZE	env.validation.ts	defaulted true — TypeORM auto-alters the schema
CORS_ORIGINS	env.validation.ts + setup.ts	wildcard accepted, with credentials: true
DB_SEED_ON_STARTUP	env.validation.ts	defaulted true — seeds demo assets and a 450-credit wallet
Swagger	swagger.ts:9	/api/docs published
Payment adapters	MOCK_PAYMENT_ENABLED	never inspected by config at all

src/config/deployment-mode.ts replaces this with an allowlist: only development and test relax. staging, prod, Production, a typo, and unset all resolve to hardened, and every gate above now consumes that one function.

I want to flag the JWT one specifically because it is a scope extension: JWT_SECRET is now required whenever NODE_ENV is not development/test, not only in production. My reasoning is that the entire fix rests on the token being unforgeable, so leaving staging signing with a secret that is committed to the repo would make criterion 1 cosmetic there. Say the word and I will narrow it back to production-only.

Related: docker-compose.yml was doing JWT_SECRET: ${JWT_SECRET:-dev-secret} while defaulting NODE_ENV to production. I removed the fallback — the stack now refuses to start without an explicit secret.

2. How each acceptance criterion stands

#	Criterion	Status
1	One user cannot read or mutate another wallet by changing request parameters	Met. The user parameter and its three anon-placeholder fallbacks are deleted. No route, query or body parameter anywhere in src/wallet names a wallet, so cross-wallet access is unrepresentable rather than checked — there is no 403 case, only 401.
2	Unauthenticated balance/history/purchase return 401	Met. Covered for absent, malformed, wrong-key and expired tokens, using the real JwtStrategy.
3	Staging/production cannot boot with simulated payment success enabled	Met for anything that is not development/test. Residual: an operator who sets NODE_ENV=development on a production box still gets simulation. Code cannot distinguish that from a real dev box; the allowlist is the strongest in-process signal available. Enforcing the environment name belongs to the deployment pipeline.
4	No fabricated XLM/USD value or transaction ID presented as real money	Met on the API surface. Residual: wallets whose credits were inflated by the old simulated purchase keep that number. The old code recorded no provenance, so nothing can tell which credits were simulated — reconciling or zeroing them is your call, not something a PR should do silently.
5	UI can detect that credit packages are unsupported and hide the action safely	Met on the backend. GET /wallet/packages returns purchase.supported: false with a stable reason code, and each package carries purchasable: false. Needs Stellar-AgentVerse/UI to actually read it — I can't verify that from this repo, which is why the PR says Refs and not Closes. If you read this criterion as satisfied by the backend contract alone, it's a one-word edit.
6	Authorization and environment fail-closed behavior have integration tests	Met, with the CI caveat in §5 below.

3. On the design choices, in case you'd have made them differently

Balance shape. Once xlmBalance can't be presented as real, there are three options and they are not equivalent:

• Delete the fields → a client doing balance.xlmBalance.toFixed(2) throws, and templates render undefined, with no way to say why.
• Return 0 → that is itself a fabricated claim about someone's money, and indistinguishable from a genuinely empty account. This is precisely what criterion 4 forbids.
• Chosen: keep the names, nest them under onChain, type them number | null, pair them with a status discriminator and a stable reason. A typed client gets a compile error at the moved field rather than silently rendering a stale number.

Transaction ids. wallet_transactions.txid is varchar(100) with no format constraint, and held both seeded 0x82f...e31 strings and minted tx-<epoch>-<rand> ids — while a genuine hash lives elsewhere as purchase.transactionHash varchar(64). Rather than add a provenance column, ledgerReference is a format check: non-null only for a real 64-lowercase-hex Stellar hash. Both fabricated shapes fail it today, and it starts working by itself the day a real settlement path writes a real hash — no second migration, no flag to remember.

501, not 403/503/410. 403 means "you specifically may not"; 503 invites a retry, and this is permanent until a settlement rail exists; 410 is a 4xx that generic client handlers report as a bad request. 501 is exactly "the server does not implement this".

One constant, two consumers. The capability advertised by GET /packages and the message on the 501 both come from a single frozen object in wallet.capabilities.ts, and an e2e test reads the reason code off the packages route and asserts the 501 body matches it — so "these cannot drift apart" is enforced, not just claimed in a comment.

No migration, no dropped column. wallets.xlmBalance still exists; nothing reads or writes it any more. Dropping it would be an irreversible schema change inside a security fix, and the down-migration could not restore the values. Happy to add it as a follow-up if you want it gone.

4. Bugs I introduced and then caught in self-review

Listing these because they show what the tests are actually pinning down:

1. ?limit=abc → 500. @Query('limit') is declared number but arrives as a string; the ValidationPipe coerces with Number(...), so abc reached the service as NaN, and TypeORM's take() throws a non-HttpException — a 500 for a client typo. ?skip=Infinity would have produced OFFSET Infinity. Both are now sanitised before the query builder, with table-driven tests.
2. Silent behaviour change on first read. Removing the write-on-read initially dropped monthlyAllocation from the column default of 100 to 0 for a caller with no wallet row. Now it returns the same default a created row would have carried.
3. Three isProduction denylists survived my first pass (DB_SYNCHRONIZE, CORS_ORIGINS, swagger.ts) while my own commit message claimed they were all allowlists. Fixed, and the commit message rewritten.
4. Circular tests. The first version of the wallet e2e mocked WalletService and then asserted the mock's own return value — it proved the fixture, not the fix. It now wires the real WalletService to mocked repositories, feeds in a row carrying the old fabricated values (xlmBalance: '1240.45', txid: '0x82f...e31'), and asserts that 1240.45, its 138.93 USD derivation, and both txids are absent from the serialised response.

5. ⚠️ CI has been red on main for at least a month, and no test has ever run there

Not caused by this PR, but it changes what "green CI" can mean for you here.

npm run lint exits non-zero on a clean checkout of main — 317 errors. Because Lint ran first, every run stopped there with Test and Build reported as skipped: run 30476632558 is one of many.

Two related facts worth knowing:

• npm test uses jest rootDir: "src", so nothing under test/ has ever run in CI even when the job got that far. The PR adds npm run test:e2e as its own step.
• npm run lint runs with --fix, so simply running it rewrites ~70 files. I reverted that collateral rather than ship it; that is why files I only touch lightly (payments.controller.ts, seed.ts, payments.service.ts) keep their pre-existing prettier errors.

I moved Lint to run last. It still fails the job — the difference is that test and build results become visible instead of skipped. I did not attempt to fix the lint debt itself: it is a repo-wide reformat that would bury a P0 under file churn. Happy to send it as its own PR whenever you want it.

6. Other things I found in the code and did not touch

1. DashboardController has the same bug as this issue. GET /api/dashboard/metrics?creator=<any public key> is unauthenticated and returns that creator's totalRevenue and totalExecutions; top-assets and activity-logs take the same parameter. Identical identity-via-query-parameter pattern, different module. Out of scope for a wallet issue and it would roughly double this diff — tell me whether you want a separate issue or a PR straight away.
2. POST /api/payments returns 201 for a failed payment, with success: false in the body. Pre-existing; changing the status code is an API contract decision, not a bug fix.
3. MockPaymentAdapter is a registered provider but is absent from PaymentsService's adapter registry, so no route can reach it. MOCK_PAYMENT_ENABLED / MOCK_PAYMENT_FAIL are documented as if it were live. I gated the flags at boot anyway and made the README say plainly that no route reaches it — but you may simply want the adapter deleted.
4. src/payments/stripe/stripe.service.ts and src/payments/paypal/paypal.service.ts are injected into no module and reachable from nothing.
5. .env.example documents S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY and PROMPT_CONTENT_ENCRYPTION_KEY, none of which any file under src/ reads. They belong to the prompt-delivery work, so I left them rather than guess. .env.example also had PAYPAL_MODE while the adapter reads PAYPAL_ENV — that one I did fix, since it sits in the module this issue covers.
6. Nothing writes wallet_transactions any more. The simulated purchase was its only writer, and I removed the seed fixtures, so GET /wallet/transactions returns an empty list on a fresh database. That is the honest state — there is no real money activity to report — but it does mean the endpoint looks inert until a settlement path exists.
7. No test boots the real AppModule. Every e2e spec hand-assembles a TestingModule, so nothing exercises guard + global filter + envelope interceptor + validateEnv together against the Postgres service CI already provisions but no test uses. test/config-fail-closed.e2e-spec.ts closes half of this by driving ConfigModule.forRoot({ validate }) rather than calling validateEnv directly — so it fails if the wiring is removed, not just if the rule changes — but a full AppModule e2e is still missing.

7. Breaking changes for Stellar-AgentVerse/UI

Deliberate, and a typed client gets a compile error rather than silently rendering stale data — but somebody has to update the frontend:

1. GET /wallet/packages returns an object { purchase, packages }, not a bare array.
2. WalletBalanceDto loses top-level xlmBalance / xlmUsdEstimate; they move into onChain as nullable.
3. WalletTransactionDto.txid becomes ledgerReference: string | null.
4. POST /wallet/purchase returns 501 instead of 201.
5. All three private wallet routes now require a bearer token.

8. Verification

npm test          ✅ 36 suites, 225 tests   (was 35 / 186)
npm run test:e2e  ✅ 10 suites,  67 tests   (was  8 /  27)
npm run build     ✅
npx tsc --noEmit -p tsconfig.build.json     ✅

Diff is 1,107 production lines (741 added / 366 deleted) against CONTRIBUTING's 400-line guideline. The issue spans wallet, payments and config, and about a third of the production diff is deletion. If you would rather review it in pieces, the natural split is (a) wallet identity + response shapes, (b) deployment-mode.ts + validateEnv, (c) payment adapters — say so and I will restack it.

9. What I need from you

1. Approve and run the fork CI workflow — first-time contributor gate. It uses no secrets.
2. Set JWT_SECRET wherever this deploys. Boot now fails without it outside development/test, which is the point, but it will surface as a failed deploy if it is currently unset.
3. Decide on historic credits (criterion 4 residual): leave the inflated balances, or zero them.
4. Closes vs Refs — your call on criterion 5.
5. The DashboardController leak — separate issue, or a PR now?

[Joaco2603]

Implemented and verified in merged Backend PRs #22 and #23 plus UI PR #10. Wallet identity is JWT-bound, simulated money is removed/quarantined, unsupported purchase capability is explicit, and unit/e2e/build checks pass. Closing this issue as complete; the remaining real Testnet deployment work belongs to #17 and its documented dependencies.

[dostertags]

⚠️ The wallet fix never reached main — the P0 in this issue is still live on the default branch.

No objection to closing #19 as a duplicate. But #23 merged into the wrong base, so nothing from it is on main.

What happened

#22	chore/marketplace-staging-hardening → main, merged 06:48:37Z
#23	fix/marketplace-merge-hardening → chore/marketplace-staging-hardening, merged 06:59:30Z

#23 was stacked on #22, but #22 had already landed on main eleven minutes earlier. So #23 merged into a base branch that was, by then, a dead end — and it was never retargeted to main.

chore/marketplace-staging-hardening is now 10 commits ahead of main, and every wallet hardening commit is in those 10.

Verification

gh api "repos/Stellar-AgentVerse/Backend/compare/main...3ee2dd0" \
  --jq '{status, ahead_by, behind_by}'
# {"status":"diverged","ahead_by":10,"behind_by":1}

src/wallet/wallet.controller.ts on main right now:

gh api "repos/Stellar-AgentVerse/Backend/contents/src/wallet/wallet.controller.ts?ref=main" \
  --jq .content | base64 -d | grep -n "anon-placeholder"
# 34:    const publicKey = user || 'anon-placeholder';
# 56:    const publicKey = user || 'anon-placeholder';
# 69:    const publicKey = user || 'anon-placeholder';

All three routes on main still take @Query('user'), still fall back to anon-placeholder, and still carry no @UseGuards. purchasePackage still mints credits against the simulated xlmBalance. Reproducible against a deployment built from main:

GET /api/wallet/balance?user=<any wallet>       → 200, that wallet's data
POST /api/wallet/purchase?user=<any wallet>     → 201, credits minted

The 10 commits waiting on the branch:

3ee2dd0 fix(wallet): secure authenticated balances and payment capabilities
c45e0a7 chore(release): sync wallet branch with staging CI gate
76971d4 test(auth): cover strict signature format
770b47f fix(release): verify staging dependencies
29471cf fix(payments): reject unavailable providers
b926e27 fix(wallet): quarantine unverified credit balances
452e995 fix(config): fail closed outside simulation environments
0df293f fix(auth): harden wallet signature verification
a26e24d chore(release): add migration-owned staging smoke
1d451b8 fix(wallet): derive wallet identity from JWT and remove simulated money

Suggested fix

Open chore/marketplace-staging-hardening → main and merge it. behind_by is only 1, so it should be a clean fast merge. I do not have push access on this repo, so I cannot open that PR myself — say the word and I will do whatever part of it I can from a fork.

Until that lands I would suggest reopening this issue, since the acceptance criteria are not satisfied on the default branch.

---

Two smaller notes while this is open:

1. DashboardController still has the identical bug and is untouched on main and on the branch. GET /api/dashboard/metrics?creator=<any public key> is unauthenticated and returns that creator's totalRevenue; top-assets and activity-logs take the same parameter. Same identity-via-query-parameter pattern this issue was opened for, different module. I raised it in my earlier comment and it is still open — separate issue, or a PR?

2. CI is green on main again — thanks for picking up the test:e2e step and the lint reordering in d7a67e6. Worth noting that main's green tick currently certifies the unfixed code, which is part of why this slipped past.

For the record on #19: its commit 1d451b8 is the base of that 10-commit series with my authorship intact, so the work is not lost — it just needs the branch to reach main.