🛡️ Investec Developer Quest

A local-first CLI game for learning Investec API patterns, Programmable Banking card logic, and secure fintech engineering.

This is a community playground, not an official Investec product.

What you'll learn in 10 minutes

• Find the bug: see how a string merchant-category code bypasses a card rule in the offline induction mission.
• Prove the fix: normalize the input, then pass behavior tests and block the Red Team attack.
• Keep the lesson: unlock the reference, debrief, and case file before your next mission.

Start with pnpm game, edit the mission's solution.js, then run pnpm game test. Get set up in 5 minutes.

Current content: 23 playable levels across Seasons 1 to 4 (v2.0.0).

✨ What's new in v2

• Faster start: pnpm game briefs you and loads an offline induction mission. You can also play in GitHub Codespaces with zero install.
• Season 3 expanded from 1 to 5 missions: replay protection, SSRF-safe callbacks, tamper-evident audit logs, and a season boss.
• Never stuck for long: a stuck-escape ladder (explain → walkthrough → community), plus progress deltas on every failing run.
• Rewards along the way: graduated XP, ranks, path and season badges, daily streaks, and time estimates.
• Social and community: one-time share prompts at big moments, and "Share your approach" discussions after each reference.
• Take it to the real API: every debrief ends with a "Try it for real" section linking the matching Investec API docs, sandbox, card IDE guide, or community resources.

See CHANGELOG.md for details.

🏆 See who has completed the quest so far in the Community Completion Leaderboard. Completed the game? Submit your completion through the swag claim process below.

🚀 Start Here (5 minutes)

☁️ Zero-install option: GitHub Codespaces

Click Open in GitHub Codespaces above. The dev container installs Node 20, pnpm 9, all dependencies, and .env for you. When the terminal is ready, run:

pnpm game

Prefer to play locally? Follow the steps below.

🧰 1) Prerequisites

• Node.js 20+
• pnpm 9 (the repository pins 9.12.3)

Install the matching pnpm version:

npm install -g pnpm@9.12.3

Quick check:

node -v
pnpm -v

Windows players should read Windows Setup first (PowerShell policy can block scripts).

📦 2) Install and start the Quickstart Path

git clone https://github.com/Investec-Developer-Community/investec-dev-quest.git
cd investec-dev-quest
pnpm install
cp .env.example .env
pnpm game

pnpm game (or pnpm game start) is the front door. On a fresh profile it briefs you and loads your induction mission. After that, it resumes your active mission or loads the next one.

The Quickstart Path is the recommended first route:

1. Season 2 Level 1: Merchant Mirage, the induction mission. It runs offline with one card rule to fix.
2. Season 1 Level 1: First Contact, your first mission against the mock Investec API.
3. Season 4 Level 1: Tool Gatekeeper

After the Quickstart Path, the win banner and pnpm game route you through the Grandmaster Run in campaign order.

To claim swag, you still need the Grandmaster Run: all 23 levels.

🧪 3) Run once, then edit once

pnpm game test

Edit this file:

seasons/season-2/level-1/solution.js

🔁 4) Tight feedback loop

pnpm game test
# or
pnpm game watch

• Stuck? Use pnpm game hint
• Failures unclear? Use pnpm game explain
• Journal and case files become richer after solved levels record evidence: pnpm game journal

Each failing run also shows how far you've moved since your last run, for example Behavior 3/5 → 4/5 ▲.

🪜 Stuck-escape ladder

If you're stuck, work up the ladder:

1. pnpm game hint unlocks the two written hints, one at a time.
2. pnpm game explain gives free, non-spoiler coaching for every failing test.
3. pnpm game hint --walkthrough becomes available after both written hints. It points at the first failing assertion, what it saw, its intent, and the test source. It counts as a third hint, and re-running it is free.
4. Ask the community. The CLI prints a pre-filled GitHub Discussions link for your level. Share your approach, not a full solution.

After 5 attempts on the same mission, pnpm game test shows this ladder automatically.

✅ 5) Confirm you are on track

pnpm game status

Behavior tests prove the feature works. Attack tests prove the exploit is blocked. A level is complete only when both pass. XP is a bragging-rights score derived from how cleanly you solve completed levels; swag eligibility still requires 23/23 levels complete.

⭐ XP, ranks, badges and streaks

XP per level = 100 base + hint bonus + attempt bonus (+100 for boss levels). The win banner shows the breakdown.

• Hint bonus: 0 hints +50 · 1 hint +25 · 2 hints +10 · walkthrough (hint 3) +0
• Attempt bonus: 1–2 attempts +25 · 3–4 attempts +10 · 5+ attempts +0

watch re-runs don't count as attempts. XP is derived from your progress, so existing profiles are re-scored automatically.

Ranks grow as you complete missions: Recruit (0), Analyst (3), Responder (6), Specialist (12). When every mission is complete, you get a final title based on how cleanly you solved.

Badges are earned for each completed path (Quickstart Graduate, API Foundations Engineer, Card Code Operator, Security Specialist, Grandmaster) and each season (API Desk Lead, Card Desk Lead, Workflow Sentinel, AI Guardian). The win banner announces new badges and promotions. When you finish a path, it also suggests something to build next with real Investec APIs. pnpm game badge lists your badges, with share text for each.

Share moments: the first time you block an exploit, beat a season boss, finish a path, or complete the campaign, the CLI shows one share prompt: a GitHub star link, an X post link, and a LinkedIn link. Each moment appears once per profile. Turn them off with GAME_QUIET_SOCIAL=1 in .env, or pass --quiet-social to test or watch.

Share your approach: after pnpm game reference, the CLI shows five debrief questions and a pre-filled Show and tell discussion link. Compare approaches without posting full solutions.

Daily streaks count consecutive days on which you ran at least one test. pnpm game welcomes you back with when you last played, your streak, and the badge closest to completion. Everything is stored locally. There is no telemetry.

Time estimates appear in level, status, and map (remaining time per path), so you can plan a session.

🧭 Player Paths

These are suggested learning tracks. To claim swag, you must complete all 23 levels.

Path	Recommended levels	Best for
Quickstart path	Season 2 Level 1, Season 1 Level 1, Season 4 Level 1	First-time players learning the edit-test-hint loop
API foundations path	Season 1 Levels 1-6	OAuth2, pagination, token reuse/refresh, beneficiaries, idempotent payments
Card code path	Season 2 Levels 1-6	beforeTransaction rules, MCCs, budgets, velocity limits
Security path	Season 2 Level 1, Season 3 Levels 1-3, Season 4 Levels 1, 4, 5	Validation, HMAC verification, replay windows, SSRF-safe callbacks, exact allowlists, injection defense
Grandmaster Run	All 23 levels	Swag eligibility

Run pnpm game map to see path progress and the next incomplete mission.

⌨️ Commands

Most-used commands

pnpm game                    # start or continue the campaign
pnpm game test
pnpm game watch
pnpm game hint
pnpm game explain
pnpm game status
pnpm game map

More command examples

pnpm game start                     # same as bare `pnpm game`
pnpm game level <n> --season <n>   # load a specific level
pnpm game test --verbose            # full failure traces
pnpm game hint --topic auth         # topic-focused hint mode
pnpm game hint --walkthrough        # after both hints: pinpoint the first failing assertion
pnpm game badge                     # earned badges and share text
pnpm game claim                     # after all missions: save a bundle and open the swag issue
pnpm game claim --no-open           # save the bundle and print the pre-filled URL only
pnpm game reference --season 2 --level 1
pnpm game reset --yes
pnpm game journal --all-evidence

For complete CLI options, run:

pnpm game --help
pnpm game <command> --help

The CLI header auto-reflects mission count and CLI version from current repo state.

Progress is stored at ~/.investec-game/progress.json.

Reset all progress:

rm ~/.investec-game/progress.json

🧠 How the Game Works

Level structure

Each level lives in seasons/season-N/level-N/.

File	Purpose
story.md	Scenario and context
starter/solution.js	Starter template copied to working file
solution.js	Your working solution
tests/behavior.test.js	Behavior checks
attack/exploit.test.js	Exploit checks
hints/hint-1.md	First hint
hints/hint-2.md	Second hint
reference/solution.js	Reference implementation after completion
debrief.md	Required post-solve explanation, ending with a "Try it for real" section linking real Investec resources

🏁 Win condition

Both suites must pass:

1. Behavior tests
2. Attack script

This enforces dual validation: no over-restricting and no under-fixing.

📓 Carry-forward consequences

Quality of earlier fixes carries into later narrative and debrief output.

On completion, each level writes a case file entry with:

• adversary blocked
• production habit learned
• downstream consequence change

Case files and consequence context are surfaced via status, journal, and reference.

Carry-forward context only reports decisions you have actually made. If you reach a later mission before the Season 1 mission that sets a posture (for example, starting with the Quickstart induction in Season 2), that context shows not assessed yet.

For architecture and consequence internals, see docs/architecture-overview.md.

📚 Seasons

Season	Theme
1	API Foundations: OAuth2, accounts, transactions, pagination
2	Card Code and Rules Engine
3	Secure Fintech Workflows: webhook signatures, replay protection, SSRF-safe callbacks, tamper-evident audit logs
4	Intelligent Banking Automation

🔌 Mock API

The local mock API is auto-started by the CLI for API-required levels.

• Base URL: http://localhost:3001
• Credentials from .env: game_client_id, game_client_secret, game_api_key

Troubleshooting and health-check steps are in docs/troubleshooting.md.

🎁 Claim Your Prize

Swag eligibility requires 23/23 levels complete.

Upgrading from v1? Your progress carries over. v2 adds four Season 3 missions, so a v1 19/19 profile shows 19/23. Run pnpm game to go straight to the first new mission.

Claim flow:

1. Run pnpm game status and confirm 23/23 levels complete.
2. Run pnpm game claim. It saves a JSON bundle under ~/.investec-game/claims/ and opens the swag claim issue with the bundle pre-filled. No screenshot is needed.
3. Review the form, enter your GitHub handle and honest total play time (HH:MM:SS, excluding breaks and time away), confirm your own completion, and submit. Feedback is optional.
4. A maintainer reviews the claim and shares the claim form link directly.

No browser available? Run pnpm game claim --no-open and open the printed URL manually. If the URL cannot be opened, use the issue template above and paste the JSON from the saved file. pnpm game certificate still prints a shareable certificate.

The bundle contains mission IDs, attempts, hints, timestamps, per-level and total XP, CLI version, and a SHA-256 content hash. It does not include your code, credentials, or personal details.

Time is self-reported, not measured or verified, and is not covered by the bundle hash. Add the time spent playing across sessions and exclude breaks: 20 minutes on Monday plus 15 minutes on Friday is 00:35:00, not four days. The CLI leaves the time field blank and does not calculate a duration from mission timestamps. Those timestamps are metadata only; missing legacy timestamps do not prevent a completed player from claiming.

The hash checks bundle integrity, not independent solving: local progress can be edited and references are public. Maintainer review is still required; automated verification and leaderboard updates are not implemented yet.

🏆 Community Completion Leaderboard

Publicly submitted completion claims, ordered by self-reported time. v1 has 19 missions; v2 has 23.

Rank	Player	Version	Reported time	Feedback	Submission
1	limanindou	v1	2 hours	—	Issue #15
2	Irfaan-28	v2	5 hours 45 minutes	—	Issue #90
3	sean-gordon	v1	8 hours	“That was a fun challenge! Thanks!”	Issue #67
4	lungilemooketsi	v1	~30 hours	“This was quite the learning experience for me, great fun and an even better challenge.”	Issue #66
—	EstherSewlall	v1	Not provided	—	Issue #9
—	Kimmicorn-glitch	v1	Not provided	—	Issue #29

🤝 Contributing a Level

See docs/authoring-guide.md.

Architecture guide: docs/architecture-overview.md.

README demo assets and regeneration instructions: docs/media/README.md.

Quick checklist:

1. Scaffold a level:

pnpm create-level -- --season <n> --level <n> --name "<Level Name>" --difficulty beginner --attackName "Exploit Name" --minutes 15

2. Write scenario in story.md.
3. Implement buggy/incomplete starter/solution.js.
4. Add behavior tests and attack script.
5. Add two hints and a debrief.md (including a ## Try it for real section).
6. Verify starter fails and reference passes.
7. Open a PR.

For full validation parity (including API-required levels), run:

node scripts/validate-levels.mjs --strict

🗂️ Project Structure

investec-developer-game/
├── packages/
│   ├── cli/
│   ├── mock-api/
│   ├── webhook-emitter/
│   └── shared/
├── seasons/
│   ├── season-1/
│   ├── season-2/
│   ├── season-3/
│   └── season-4/
├── templates/
│   └── level-template/
└── docs/
    ├── authoring-guide.md
    └── architecture-overview.md

🙌 Inspired by

Inspired by GitHub Secure Code Game: https://securitylab.github.com/secure-code-game/