Learn AWS IAM by Solving 12 Policy Puzzles in the Browser

Laith Rachwani — Thu, 21 May 2026 17:07:02 +0000

AWS IAM is hard to learn from docs alone. The evaluation logic only really clicks after enough trial and error, identity policies, resource policies, SCPs, permissions boundaries, explicit deny precedence, all interacting in non-obvious ways.

I built Learn AWS IAM to make that process more hands-on. It's 12 interactive levels that run entirely in the browser. No AWS account, no signup, free, open source. Inspired by Learn Git Branching.

Each level gives you a scenario: a user needs to read from one S3 bucket but not another, an EC2 role needs to assume a role in a different account, an SCP is blocking something it shouldn't. You read the existing policies, figure out what's wrong, and edit JSON until the request evaluates the way it should.

Topics covered across the 12 levels:

Identity-based and resource-based policies
Cross-account access
ABAC with tags
Service Control Policies
Permissions boundaries

The rest of this post is about how it's built.

One state machine per level

Each level has its own XState machine. The machine owns everything: which nodes and edges exist on the canvas, which objectives are active, which UI elements are currently restricted, what popup or popover is showing. Every user action becomes an event sent to the current level's machine, whether it's submitting a policy, drawing a connection between two nodes, or clicking "next" on a tutorial popup.

State machines fit because each level is a mostly linear flow with branches. Each tutorial step is a state, user actions drive transitions, and guards make sure the user can't skip ahead or reach an invalid step.

The alternative I considered was a set of useEffects reacting to state changes and triggering other state changes. Ordering becomes implicit there. Each effect reacts to state, state changes trigger other effects, and you end up reasoning about which effect fires first in a given render cycle rather than reading a transition table.

Machines also need to be serializable so the user's progress can be saved as checkpoints. This means runtime-dependent logic (validators, guard predicates) can't live in the machine context directly. Instead, it lives in a separate registry keyed by level number and a string name. The machine stores the name; when an action runs, it looks up the real function. Snapshot restoration works transparently because the snapshot only ever contained names.

The canvas is a separate layer

The canvas renders IAM entities as draggable nodes with edges representing relationships between them. It's built on ReactFlow. The state machine is the source of truth for which nodes and edges exist; a lighter @xstate/store instance handles UI-level state (positions, hover, selection).

The machine emits events the canvas subscribes to: NODES_ADDED, NODES_DELETED, EDGES_ADDED, NODE_UPDATED. The canvas translates them into store actions.

This indirection exists specifically because of animations. Without it, nodes deleted by the machine would vanish from the DOM immediately, before any exit animation could run. The event gives the canvas a window to animate first.

The deletion flow has three steps:

Machine emits NODES_DELETED with IDs
Canvas store marks those nodes as "deleting", triggering Framer Motion exit animations
On animation completion, the nodes are removed from the canvas store for good. Skipping the indirection and diffing prev/next node arrays in a useEffect would technically work, but you'd lose the IDs of what was deleted the moment the machine context updates.

Policy editing with CodeMirror + AJV

Most objectives in each level revolve around writing a policy, which is a JSON document following a specific schema. The editor is built on CodeMirror 6 with AJV validating the JSON on every keystroke.

Validation runs at two levels. First, the base AWS IAM policy schema covers statement structure, Action, Principal, Resource, and condition operators. On top of that, individual objectives attach their own validation rules. Level 5's EC2 role objective, for example, requires the trust policy to include ec2.amazonaws.com as the service principal.

AJV compiles all the validators once when the level loads and reuses them for the lifetime of that level.

The editor also has a custom CodeMirror extension that renders small help badges inline next to specific lines, attaching contextual hints to the relevant parts of the policy while the user edits it.

Project layout

The codebase is organized as a stack of layers with dependencies flowing downward:

lib / types / hooks / config / stores   <- foundation
domain                                  <- IAM entities, ARNs, base schemas
levels                                  <- per-level machines, objectives, tutorial copy
runtime                                 <- loads the right level, persistence, providers
features                                <- canvas, editor, dialogs (rendering only)
app_shell / app                         <- root

Upper layers import from lower layers. Lower layers never import from upper ones. There is one exception: a typed pub/sub bus lets levels/ fire side effects handled by runtime/ (like saving a checkpoint) without creating an import cycle.

features/ and levels/ are also peers and can't import from each other, even though levels/ sits above features/ in the chain. Level logic and UI rendering are isolated concerns; they interact only through runtime/, which acts as the bridge. The canvas component doesn't know what level it's rendering. It subscribes to whatever machine actor runtime/ hands it.

Stack

React with TypeScript, bundled with Vite
XState for level orchestration, @xstate/store for lighter state - ReactFlow for the canvas
CodeMirror 6 and AJV for the editor
Chakra UI for components
Framer Motion for animations
Vitest for unit and integration tests
Playwright for E2E across all 12 levels

Each level's state machine is a separate dynamic import, so only the current level's code is downloaded when the user navigates to it. The code editor is also lazy-loaded.