DEV Community: Tharindu Karunanayaka

HTTP Finally Has a QUERY Method — and It Fixes a 30-Year-Old Compromise

Tharindu Karunanayaka — Sun, 05 Jul 2026 03:41:57 +0000

For as long as most of us have been building web APIs, there's been an awkward gap in HTTP's method vocabulary. You want to ask a server a question — run a search, filter a dataset, evaluate a complex query — and get an answer back without changing anything. HTTP has never had a clean way to do that. As of RFC 10008, published in June 2026, it finally does: the QUERY method.

This post explains the problem QUERY solves, what makes it different from GET and POST, and the one genuinely tricky part — caching.

The problem: GET and POST both fit badly

When you need to send a query to a server, you've historically had two bad options.

Use GET. GET is the natural fit semantically: it's safe (it doesn't change server state) and idempotent (making the same request twice has the same effect as making it once), and its responses are cacheable. The problem is that GET carries its parameters in the URL. That's fine for ?page=2&sort=name, but it falls apart the moment your query is large or structured. URLs have length limits (proxies, servers, and browsers all impose their own), you have to URL-encode everything, and expressing a nested JSON filter or a GraphQL-style query as query-string parameters ranges from ugly to impossible. Sending a request body with GET is technically undefined and widely ignored, so that door is closed.

Use POST. POST lets you put a rich, structured query in the request body with whatever media type you like — JSON, GraphQL, SQL-ish DSLs, protobuf, anything. That's why virtually every search and GraphQL endpoint uses POST today. But POST is semantically wrong for a read. POST is neither safe nor idempotent: to HTTP, caches, and intermediaries, a POST looks like it might create or change something. So responses generally aren't cached, clients won't automatically retry a failed POST (it might have side effects), and you lose all the machinery that makes reads on the web fast and resilient.

So for decades we've been picking between "correct semantics but can't send real data" (GET) and "can send real data but wrong semantics" (POST). QUERY exists to end that compromise.

What QUERY actually is

QUERY is, in the words of the spec, a method that requests the target process the enclosed content and respond with the result of that processing. In plainer terms: it's a request that carries a body like POST, but is declared safe and idempotent like GET.

Three properties define it:

It is safe — a QUERY does not alter the state of the resource it targets. It's a read, and clients, servers, and intermediaries can treat it as one.

It is idempotent — repeating the same QUERY has the same effect as sending it once. Because there's no partial state change to worry about, a QUERY can be safely retried or restarted automatically, for example after a dropped connection. This is the key thing POST can never offer.

It is cacheable — responses can be stored and reused, which brings the performance benefits of GET to requests that were previously stuck as uncacheable POSTs.

The request body carries the query itself, and its media type describes what kind of query it is. The server processes that content and returns the result. This is exactly the shape that search endpoints, GraphQL, analytics APIs, and complex filtering have always wanted: a real body, plus honest read semantics.

QUERY vs GET vs POST at a glance

Property	GET	POST	QUERY
Carries a request body	No (undefined)	Yes	Yes
Safe (no state change)	Yes	No	Yes
Idempotent (safe to retry)	Yes	No	Yes
Cacheable	Yes	Rarely	Yes
Good for large/structured queries	No	Yes	Yes

QUERY is essentially the cell that was always missing: the safe, idempotent, cacheable method that can still carry a body.

The catch: caching is harder than it looks

The headline feature — cacheable queries with a body — is also where the real engineering complexity lives, and it's worth being honest about it.

With GET, the cache key is basically the URL. It's short, it's right there in the request line, and a cache can decide what to do before reading anything else. QUERY breaks that convenience. Because the meaningful part of the request now lives in the body, a cache has to read the entire request content to compute the cache key. That's fundamentally more work than keying on a URL.

Worse, bodies aren't naturally canonical. Two JSON queries that are semantically identical — same fields, different whitespace or key ordering — are different byte sequences, and a naïve cache would treat them as different keys, tanking the hit rate. So effective QUERY caching depends on normalizing the request body before keying on it, which pushes real complexity into caches and intermediaries. The spec also provides mechanisms for a server to point at a cacheable representation of the results (so that follow-up reads can behave more like ordinary GETs), but the underlying reality remains: caching a QUERY is materially more involved than caching a GET.

None of this makes QUERY worse than the POST-based status quo — POST responses usually weren't cached at all. It just means the caching win isn't free; it arrives with new requirements for the infrastructure in the middle.

Should you use it yet?

QUERY is now a published standard (RFC 10008), which is the milestone that lets client libraries, servers, frameworks, proxies, and CDNs begin implementing it with confidence. But "standardized" and "universally deployed" are not the same thing. Real-world adoption depends on the whole chain — HTTP clients, server frameworks, load balancers, API gateways, and caches — understanding the method. Until that support is broad, a QUERY request may be rejected or mishandled by some intermediary that's never heard of it, and you'll still see POST used as the pragmatic fallback for a while.

The sensible read for now: QUERY is the correct answer to a problem the industry has worked around for thirty years, and it's finally a real standard rather than a proposal. If you build APIs where reads carry heavy or structured payloads — search, GraphQL, analytics, complex filtering — it's worth understanding now and adopting as your stack's support catches up. It won't replace GET for simple reads or POST for genuine writes; it fills the specific, long-standing gap between them.

Sources: RFC 10008: The HTTP QUERY Method (RFC Editor), RFC 10008 (IETF Datatracker), draft-ietf-httpbis-safe-method-w-body (IETF Datatracker), RFC 10008: The New HTTP QUERY Method Explained (Developers Digest)

AI-DLC: Giving Structure to AI-Assisted Development

Tharindu Karunanayaka — Sun, 05 Jul 2026 03:30:12 +0000

AI coding assistants are great at writing code and terrible at knowing when to write it. Ask one to build a feature and it will happily jump straight to implementation, skipping the questions a good engineer asks first: what exactly are we building, why, what are the risks, and how should it be broken down? The result is fast output that often solves the wrong problem.

AWS's AI-DLC (AI-Driven Development Life Cycle) is an attempt to fix that gap. It's an open-source set of workflow rules — released by awslabs — that steer AI coding agents through a disciplined software development process instead of letting them freewheel. Importantly, it isn't a tool you install or a service you pay for. It's a methodology delivered as a bundle of markdown rules that your existing coding agent reads and follows.

The core idea: methodology over tooling

One of AI-DLC's stated tenets is "methodology first." The whole thing ships as plain markdown rule files that you drop into whatever your agent already uses for project instructions — CLAUDE.md for Claude Code, .cursor/rules/ for Cursor, .github/copilot-instructions.md for GitHub Copilot, .amazonq/rules/ for Amazon Q, steering files for Kiro, and so on. There's nothing to run. The agent loads the rules and its behavior changes.

This makes AI-DLC deliberately agnostic. It doesn't tie you to a specific IDE, model, or vendor — any coding agent that supports project-level rules can use it. The philosophy is that a good development methodology should outlive any particular tool.

A three-phase adaptive workflow

At its heart, AI-DLC organizes work into three phases that mirror how thoughtful software actually gets built.

The Inception phase answers what to build and why. This is where the agent does requirements analysis, creates user stories when they're warranted, sketches the application design, breaks work into units that can be built in parallel, and assesses risk and complexity before a line of code is written.

The Construction phase answers how to build it: detailed component design, actual code generation, build configuration, testing strategy, and quality validation.

The Operations phase covers deployment and monitoring — infrastructure automation, observability, and production-readiness checks. This phase is still marked as future/in-progress in the project, so it's more of a roadmap than a finished capability today.

The word that matters most here is adaptive. AI-DLC doesn't force every request through the full ceremony. It analyzes the complexity of what you're asking and only runs the stages that add value. A trivial change stays lightweight; a complex feature gets the full treatment with requirements analysis, design, and risk assessment. That's a sensible answer to the usual complaint about process — that it slows down simple work.

What does this mean for the traditional SDLC?

The name is not an accident. AI-DLC is a deliberate play on the SDLC — the Software Development Life Cycle that has organized how teams build software for decades: requirements, design, implementation, testing, deployment, maintenance. Those phases were written for human-only teams, where a person did the thinking at every stage and process existed mostly to coordinate people.

AI-DLC's bet is that this assumption no longer holds. When an AI agent can generate design and code in minutes, the bottleneck shifts from producing work to deciding what to produce and validating it. So AI-DLC re-centers the life cycle around that new reality. Its three phases still map onto the old SDLC stages, but the roles are inverted: the agent does the heavy lifting of analysis, design, and implementation, while the human's job becomes steering and approving at each gate. The process isn't there to coordinate people anymore — it's there to keep humans in control of a machine that moves fast.

Does that mean AI-DLC "replaces" the SDLC? In spirit, yes — it's positioning itself as the successor: the software life cycle rebuilt for the age of AI coding agents rather than bolted onto it. But it's worth being honest about the scope today. The Operations phase is still marked as future, the methodology explicitly keeps humans approving every critical decision, and AWS itself warns that generative AI still makes mistakes. So this is less "the SDLC is dead" and more "the SDLC is being rewritten" — the same fundamental stages, reorganized around who (or what) actually does the work. Teams that cling to a purely human, hand-offs-between-phases model will likely find it increasingly out of step with how software gets built.

Keeping the human in the loop

A recurring theme in AI-DLC is that the human approves and the agent proposes, never the other way around. The workflow is built around explicit checkpoints: you review each execution plan, approve each phase before it proceeds, and validate the artifacts the agent generates along the way. All of those artifacts land in an aidlc-docs/ directory so there's a paper trail of what was decided and why.

Interestingly, AI-DLC pushes its structured questions into files rather than chat. Instead of a back-and-forth conversation, the agent presents multiple-choice questions as documents you answer, which keeps decisions durable and reviewable rather than buried in a scrolling transcript. To start, you simply phrase your request beginning with "Using AI-DLC, ..." and the workflow activates.

Extensions: layering in your own rules

Out of the box, the core workflow is general-purpose, but AI-DLC supports an extension system for layering additional constraints on top. Extensions are grouped by category — the project ships with a security/ baseline and a property-based testing/ extension as examples.

Each extension is a pair of files: a rules file and an opt-in prompt. When a workflow starts, AI-DLC scans for these opt-in prompts and asks you, during requirements analysis, whether to enable each one. Opt in, and those rules become blocking constraints — at every stage the model must verify compliance before it's allowed to proceed. Extensions without an opt-in file are always enforced. This is how an organization can bake in security, compliance, or org-specific standards so the AI can't quietly skip them.

Worth noting: AWS explicitly frames the bundled security extension as a directional reference, not production-ready policy. You're expected to build, customize, and test your own rules before relying on them.

The tenets that hold it together

AI-DLC's design is anchored by a short set of principles: no duplication (one source of truth, other formats generated from it), methodology first (nothing to install), reproducibility (rules explicit enough that different models produce similar results), tool-agnosticism, and human-in-the-loop control. Taken together, they explain most of the design choices — why it's markdown instead of an app, why it works across agents, and why approval gates are everywhere.

Is it worth trying?

If you already lean on an AI coding agent and find yourself frustrated that it rushes to code, over-engineers simple asks, or skips the thinking, AI-DLC is a low-commitment experiment. It's free, it's just files, it works with the tools you already have, and you can pull it back out just as easily. The honest caveats are that the operations phase isn't finished, the security extension is a starting point rather than a finished control, and — as AWS itself notes — generative AI still makes mistakes, so the review gates aren't optional theater. They're the point.

For teams trying to get consistent, reviewable behavior out of AI assistants rather than one-off bursts of code, that's a genuinely useful framing.

Learn more

The project is open source under the MIT-0 license and available on GitHub: awslabs/aidlc-workflows. The repository includes setup instructions for Kiro, Amazon Q, Cursor, Cline, Claude Code, and GitHub Copilot, along with links to AWS's AI-DLC methodology blog and method definition paper.

Sources: awslabs/aidlc-workflows on GitHub

How Do You Log Someone Out of a Stateless System? JWT Invalidation on Logout

Tharindu Karunanayaka — Sat, 04 Jul 2026 09:37:35 +0000

JWTs are one of those technologies that feel wonderful right up until you hit your first "log me out" requirement. Then you discover the awkward truth: the very property that makes JWTs attractive — statelessness — is also what makes logout hard.

This post walks through what JWTs actually are, why "invalidating" one is a design problem rather than a one-liner, and the practical methods available to revoke an access token on logout, along with the bottleneck each one introduces.

A quick refresher on JWTs

A JSON Web Token (JWT) is a signed, self-contained token. It carries a JSON payload of claims — who the user is, when the token was issued, when it expires, and often a unique token id (jti) — and a cryptographic signature over that payload. Because the token is signed with a secret (or a private key), any server holding the corresponding key can verify it is authentic and untampered without calling a database.

That last part is the entire point. When a request arrives with a JWT, the server checks the signature and the expiry, reads the claims, and proceeds. No lookup, no shared session store, no round trip. This is what people mean when they call JWT auth stateless: the server keeps no per-user session record. The token itself is the session, and it's valid until it expires.

Access tokens and refresh tokens

In practice you rarely use a single token. The common pattern splits responsibility across two:

The access token is the short-lived workhorse. It's sent on every API request and typically expires in minutes (5–15 is common). Because it's checked statelessly on every call, you want its lifetime short — if it leaks, the damage window is small.

The refresh token is long-lived (days or weeks) and does one job: obtain new access tokens when the current one expires. It is not sent on every request — only to a dedicated token endpoint. This lets the access token stay short and stateless while the user avoids logging in every ten minutes.

The refresh token is easy — the access token is the problem

Here's the key insight that shapes everything below: the refresh token is not the hard part of logout.

Refresh tokens are few, long-lived, and hit a single endpoint. Whoever issues them — your auth provider, or your own token endpoint — already stores them server-side. On logout you simply tell the provider to invalidate that refresh token, and it's done. The user can no longer mint new access tokens. One database write, one endpoint, no impact on your request hot path.

The access token is where the difficulty actually lives. It's stateless by design: no server stored a copy, and its signature stays valid until the exp claim passes. So even after you've killed the refresh token, the user's current access token keeps working until it naturally expires. If you do nothing, a "logged out" user still has a working access token for its remaining lifetime.

So the real question this post answers is narrow: how do we stop an already-issued access token from being accepted, without giving up too much of the statelessness we adopted JWTs for? Every method below is a point on that tradeoff curve.

Method 1: Short expiry and just wait it out

The simplest approach is to not revoke the access token at all. Keep it very short-lived and accept that logout means "invalidate the refresh token, delete the tokens client-side, and let the access token expire on its own."

Because the refresh token is already dead, the user can't get a new access token — so the only exposure is the current one finishing out its few remaining minutes.

Bottleneck: it doesn't actually revoke anything. A leaked or stolen access token works until it expires, and there is no way to kill it early. This is perfectly fine for low-risk apps with genuinely short tokens, but unacceptable when you need immediate, guaranteed revocation of a specific token.

Method 2: Token blocklist (denylist)

Keep a list of access tokens that have been explicitly revoked, identified by their jti. On logout, add the token's jti to the blocklist. On every request, look up the incoming token's jti before honoring it — if it's on the list, reject it even though the signature is valid.

The natural home for this is a cache with a TTL, such as Redis. The crucial detail: you set each blocklist entry's TTL to match the token's own remaining validity. Once the token would have expired anyway, the entry evaporates on its own, so the blocklist never grows unbounded — it only ever holds tokens that are both revoked and not yet naturally expired. Every request does a quick jti lookup against that cache.

Bottleneck: you've reintroduced a lookup on every request, which is exactly the statelessness you were trying to avoid. In practice it's a cheap in-memory hit, but it's now a hard dependency on the auth path — if the cache is down or slow, your authentication is down or slow. At scale it becomes shared infrastructure you must replicate, secure, and keep highly available. You've traded some statelessness for the ability to revoke instantly.

Method 3: Token versioning / "valid-after" timestamp

Store a single small value per user — a token version number or a tokensValidAfter timestamp. Embed the version (or the token's issue time) in the JWT. On each request, compare the token against the user's current value; if the token predates it, reject it. Logging out is just bumping the version, which instantly invalidates every access token issued before the bump.

Bottleneck: you still need a lookup for the user's current version, so it isn't free — but it's a tiny per-user value rather than a per-token list, which makes it far cheaper to store and trivial to cache. The tradeoff is coarser granularity: bumping the version invalidates all of that user's access tokens at once. That's exactly what you want for "log out everywhere," but if you need to revoke a single device while leaving others alive, you'd need per-device versioning, which grows the state again.

Choosing between them: combine Method 1 and Method 2

For most real systems, the best answer is not to pick one method but to combine short expiry (Method 1) with a jti blocklist (Method 2) — on top of invalidating the refresh token at the provider.

Here's why the combination works so well. Method 1 alone can't revoke a specific token early; Method 2 alone would force you to keep a huge, long-lived blocklist if tokens lived for hours. Together they cancel out each other's weaknesses:

Short expiry keeps the blocklist tiny and self-cleaning. Because access tokens only live a few minutes, any blocklist entry's TTL is also only a few minutes. The cache stays small, cheap, and fast no matter how many logouts happen — entries are added on logout and disappear moments later when the token would have expired anyway.
The blocklist closes the gap that short expiry leaves open. Method 1 alone means a logged-out or stolen token keeps working for its full remaining lifetime. Adding the jti blocklist lets you kill that specific token immediately, so you get instant, guaranteed revocation when you need it.
The cost stays bounded. be clear about what you're paying. Every single authenticated request now makes a network call to the cache to check the jti. That adds latency to each request — typically a small amount (often sub-millisecond to a few milliseconds on a Cache), but it's real, it's on the critical path, and it scales with your request volume. You're also now depending on the cache being available: if Cache is slow, every request slows down; if it's unreachable, you have to decide whether to fail open (accept tokens you can't verify against the blocklist) or fail closed (reject everyone), and neither is comfortable. And it's another piece of stateful infrastructure to run, replicate, monitor, and secure. The blocklist staying small thanks to short TTLs is genuinely helpful, but it doesn't remove these costs — it only keeps the memory footprint modest.

Put together, a typical logout flow looks like this: invalidate the refresh token at the provider (so no new access tokens can be minted), add the current access token's jti to the Cache blocklist with a TTL equal to its remaining lifetime (so the existing token dies immediately), and clear the tokens on the client. Every incoming request then verifies the signature and expiry statelessly, plus one fast jti lookup — and short token lifetimes guarantee that lookup table stays small.

The recurring theme is unavoidable: every method that gives you real revocation power reintroduces some state. JWTs let you choose how much state and where it sits. Combining short expiry with a small, TTL-bounded jti blocklist is the sweet spot for most applications — it keeps the request path almost fully stateless while still letting you revoke an access token the instant a user logs out.

Social signing: log in, sign, never touch the key with AWS Nitro Enclaves

Tharindu Karunanayaka — Sat, 04 Jul 2026 08:59:19 +0000

Picture a product where users sign up with a normal social login, get a blockchain wallet without knowing it, and send transactions by clicking a button. No seed phrase, no browser extension, no scary "write down these 12 words or your money is gone forever" screen. To them it feels like any other app. Behind it sits a real on-chain account with a real private key.

The whole thing lives or dies on one question: if a backend is creating and holding private keys for every user, what happens when someone breaks in? A database full of user private keys is about the worst thing you can leak. So the bar is simple to state and annoying to actually meet: even the people running the service shouldn't be able to read the keys. Not the developers, not the on-call engineer at 2am, not an attacker who's popped a shell on the box, not whoever ends up with a copy of the database.

The usual way teams get this experience is to buy it. You integrate a Wallet-as-a-Service provider — Privy, Magic, Web3Auth, Turnkey, etc abd let them handle key creation, custody, and signing behind their SDK. That's a perfectly reasonable choice, and for a lot of teams it's the right one. But it comes with trade-offs: a third party now holds (or co-controls) your users' keys, you're tied to their pricing and uptime, your security story is only as good as their black box, and there's usually a per-wallet or per-signature bill that grows with you. This post is about the other path — building the whole thing yourself, in your own AWS account, so no outside vendor ever touches a private key and the trust boundary is entirely yours.

Doing that used to mean standing up and babysitting your own HSMs, which is exactly why most people reach for a WaaS in the first place. The shortcut is AWS Nitro Enclaves doing the sensitive work, with KMS acting as a bouncer that will only unlock a key for one specific, provable piece of code. You get HSM-grade key protection without running an HSM, on infrastructure you already have. I'll follow the user's journey — sign up, key gets made, log in, send funds — and bring in the security machinery at the points where it actually matters, rather than dumping it all up front.

If you're comfortable with OAuth, EC2, IAM and a bit of Python you'll be fine. The examples are deliberately chain-agnostic: wherever you'd otherwise load a raw private key (ed25519, secp256k1, whatever your chain uses) into memory to sign a transaction, the same pattern applies. Slot in your chain's SDK where the placeholders are.

Here's the shape of it before get into the weeds:

The one thing to hold onto: a plaintext private key only ever exists for a few milliseconds, and only ever in two places — inside a sealed enclave and inside a KMS hardware module. It never lands on the app servers, the database, the logs, or the wire. Not even when it's first created.

Signing up, and letting the enclave make the key

The front door is boring on purpose. User taps "sign up," an OpenID Connect flow runs through the identity provider (Cognito in front of the social providers works well here, but Auth0 or Google directly are the same idea), and back comes a JWT with the usual claims — sub, email, aud, iss, exp.

The sub claim is the important one. It's a stable unique ID for the user, and it becomes the handle everything else hangs off of.

Now, where do you generate the key? The obvious answer is a Lambda, and it works. But it has a nagging problem: for a few milliseconds the raw key sits in ordinary Lambda memory. Nobody's supposed to be able to read it, but "supposed to" is doing a lot of work in that sentence. The stronger option is to generate the key inside the enclave too. Then the raw key is born inside the sealed box and gets encrypted before anything ever leaves. There's no window, however tiny, where it exists somewhere it could theoretically be read.

The parent server just asks the enclave (over the local vsock channel — more on that soon) to make a wallet, and passes along some temporary AWS credentials so the enclave can reach KMS. This code runs inside the enclave:

import boto3
from botocore.config import Config

KMS_KEY_ID = "arn:aws:kms:us-east-1:123456789012:key/abcd-…"

def kms_client(creds: dict):
    # The enclave has no network of its own; it reaches KMS through the
    # local vsock proxy the parent runs (same path used for decryption).
    return boto3.client(
        "kms",
        region_name="us-east-1",
        aws_access_key_id=creds["access_key_id"],
        aws_secret_access_key=creds["secret_access_key"],
        aws_session_token=creds["token"],
        config=Config(proxies={"https": "127.0.0.1:8000"}),
    )

def create_wallet(creds: dict) -> dict:
    """Runs INSIDE the enclave. The plaintext private key never leaves this function."""
    private_key, address = generate_keypair()      # your chain's keygen (ed25519, secp256k1, …)
    ciphertext = kms_client(creds).encrypt(
        KeyId=KMS_KEY_ID,
        Plaintext=private_key,                      # the raw private key material
    )["CiphertextBlob"]
    return {
        "address": address,                         # public address, fine to hand back
        "encrypted_key": ciphertext.hex(),          # only ciphertext leaves the enclave
    }

Once the enclave hands back the public address and the ciphertext, the parent's job is trivial: drop that ciphertext into Secrets Manager under the user's sub.

import json, socket, boto3

secrets = boto3.client("secretsmanager")

def create_account(token: str, aws_creds: dict) -> str:
    claims = verify_jwt(token)                                  # who is this user?
    result = call_enclave({"op": "create", "credential": aws_creds})

    secrets.create_secret(
        Name=f"wallet/user/{claims['sub']}",
        SecretString=json.dumps(result),           # { address, encrypted_key }
    )
    return result["address"]                        # show the user their shiny new address

Where the key actually lives

The encrypted key goes into AWS Secrets Manager, one secret per user, named wallet/user/<sub>. What's stored there is already useless on its own — it's envelope ciphertext that can't be unwrapped without both KMS and the enclave, which is the whole point of the next section. So even if someone dumped every secret in the account, they'd have a pile of garbage.

Secrets Manager is a good fit here for a few reasons beyond just holding bytes. It re-encrypts everything at rest with its own KMS key, so the key ends up wrapped twice: once by the master key inside the enclave, then again by Secrets Manager. It gives you per-secret IAM, CloudTrail on every read, and versioning, all of which are nice to have when the thing you're storing is somebody's wallet. Scope the parent's role so it can only touch wallet/user/* and nothing else in the account.

One detail on cost and key management, since it comes up: use a single KMS master key to encrypt every user's private key. A private key is nowhere near KMS's 4 KB encryption limit, so there's no reason to mint a KMS key per user, and KMS bills per master key, so per-user keys would be financially silly. The per-user isolation that matters doesn't come from having millions of master keys anyway — it comes from each ciphertext being distinct and from the decrypt being gated. Which, finally, brings us to the interesting part.

Sending a transaction by logging in

This is the payoff and also where all the security machinery earns its keep. A returning user logs in, gets a fresh JWT, asks to send some funds, and the system signs the transaction with their key — without that key ever being visible to the servers. To believe that last clause you need to understand three things, so here they are roughly in the order you'd hit them.

The sealed box

A Nitro Enclave is a stripped-down virtual machine carved out of a normal EC2 instance. No disk, no network card, no SSH, and — this is the part that matters — no way for anyone to read its memory, including root on the parent instance. The only channel in or out is a local socket called vsock, addressed by a context ID (think of it like an IP) and a port. Only the key-handling code runs in there: creating wallets and signing. Everything else — the web server, JWT checks, Secrets Manager calls — runs on the parent, outside the box, which you should assume could get compromised.

PCR0, or how KMS knows it's really your code

For KMS to hand a key only to your signing code, it needs some way to recognize that code. That mechanism is PCR0.

PCR is short for Platform Configuration Register. When an enclave boots, the Nitro hypervisor measures the image as it loads it — hashing the contents into a set of registers that the enclave itself can't write to. If you've ever poked at a TPM and secure boot, it's the same idea. Only the hypervisor sets these values, at boot, which is exactly why you can trust them. There are a few of them:

PCR0 is a SHA-384 hash of the entire enclave image, kernel and app and all. That's the one you'll usually use. PCR1 covers just the kernel and bootstrap, PCR2 just the app without the kernel, and PCR8 is the certificate you signed the image with, if you signed it (handy if you'd rather pin "anything the build pipeline signed" than one exact hash).

The thing to internalize about PCR0 is that it's a content hash, so it's completely deterministic and completely unforgiving. Rebuild the exact same image and you get the exact same PCR0. Change one line, bump a dependency, nudge the base image, and it's a totally different value. You see it printed when you build:

nitro-cli build-enclave --docker-uri signing-server:latest --output-file signing_server.eif
# Measurements:
#   "PCR0": "abacc679…cacd9fc0373ecd78c34c3e4cbf78ea9b5b0452a18"

That string is the fingerprint of your exact code, and it's what KMS checks before it will decrypt anything. Two things trip people up here, so consider yourself warned. First, because PCR0 changes on every code change, shipping a new enclave build means updating the KMS policy — allow both the old and new value during a rollout so you don't lock yourself out mid-deploy (signing images and pinning PCR8 is the cleaner long-term answer). Second, if you run with --debug-mode to see console output, attestation is disabled and all the PCRs go to zero. Great for local testing, a disaster if you point it at real keys.

Attestation, and the part everyone gets wrong

When the enclave asks KMS to decrypt, it doesn't send a plain API call. The Nitro SDK wraps the request in a signed attestation document that carries the PCR values and a one-time public key the enclave just generated. KMS checks that the document genuinely came from Nitro hardware and that PCR0 matches the condition in the key policy.

(Worth noting the asymmetry with sign-up: encrypting the key back during account creation needed no attestation at all — anyone with the right IAM can encrypt. Decrypting is the dangerous direction, so that's the one that's locked down.)

Here's the bit that's easy to get wrong, and almost everyone does at first: the decryption happens in two places, not one.

The real decryption happens inside KMS, not in the enclave. The master key never leaves the hardware module; KMS unwraps the ciphertext into the raw key on its side. But it obviously can't just send that plaintext back over the wire, since the reply travels through the untrusted parent to get to the enclave. So instead KMS re-encrypts the plaintext using that one-time public key from the attestation document and returns that (the CiphertextForRecipient field). Then a second decryption happens locally, inside the enclave, using the matching one-time private key that never left it.

You don't hand-roll any of this. The kmstool_enclave_cli binary that AWS ships does both halves — it builds the attested request (that's decryption #1, in KMS) and does the local unseal (decryption #2, in the enclave), and just hands you the plaintext.

The policy condition doing the enforcing is one line, kms:RecipientAttestation:ImageSha384, which reads as "only an enclave whose PCR0 equals this may decrypt":

{
  "Sid": "Allow decrypt only from our enclave",
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::<ACCOUNT_ID>:role/ec2-instance-role" },
  "Action": "kms:Decrypt",
  "Resource": "*",
  "Condition": {
    "StringEqualsIgnoreCase": {
      "kms:RecipientAttestation:ImageSha384": "<YOUR_PCR0_VALUE>"
    }
  }
}

So stealing the instance credentials gets you nowhere. Dumping every secret gets you nowhere. To decrypt a key you'd have to be the exact code, running inside a genuine enclave — and even that wouldn't help you, for reasons I'll come back to at the end.

Wiring it together

The full send path: verify the login JWT, pull the user's ciphertext out of Secrets Manager by sub, fill in the public chain data the transaction needs (nonce, fee, gas, chain ID — whatever your chain uses), then push the ciphertext and the unsigned transaction into the enclave to sign.

Verifying the login token on the parent is a few lines of PyJWT:

import jwt
from jwt import PyJWKClient

jwks_client = PyJWKClient("https://YOUR_IDP_DOMAIN/.well-known/jwks.json")

def verify_jwt(token: str) -> dict:
    signing_key = jwks_client.get_signing_key_from_jwt(token)
    return jwt.decode(
        token,
        signing_key.key,
        algorithms=["RS256"],
        audience="your-api-identifier",
        issuer="https://YOUR_IDP_DOMAIN/",
    )                                  # ["sub"] == the user's Secrets Manager key

A note on stepping up to MFA for bigger transfers. The login JWT tells you who the user is, but for a large payment you want fresh proof that the actual human is behind this particular transaction, not just that they logged in an hour ago. The pattern for that is step-up authentication. The parent runs some business logic first — over some value threshold, say, or past a daily cumulative limit, or a destination the account has never sent to — and if the transaction trips that rule it refuses to sign and sends back a challenge instead. The app then prompts for MFA (a TOTP code, a passkey, a push), and on success the IdP mints a second JWT that's scoped to this one transaction: bound to the exact amount and destination, with an expiry measured in a minute or two so it can't be replayed on a different or later transfer. The parent checks both tokens — the session one for identity, the step-up one for this specific transaction — before anything reaches the enclave.
def require_step_up_if_needed(session_claims, amount, to, step_up_token):
    if amount <= LIMIT:                           # small tx: session JWT is enough
        return
    if not step_up_token:
        raise StepUpRequired()                    # tell the app to prompt for MFA
    mfa = verify_jwt(step_up_token)               # same signature/claims checks
    if (mfa["sub"] != session_claims["sub"]       # bind it to THIS user + THIS transfer
            or mfa.get("amount") != amount
            or mfa.get("destination") != to
            or "mfa" not in mfa.get("amr", [])):   # amr = auth methods actually used
        raise Unauthorized()
The nice thing is that it's a completely separate lock that slots in before the key machinery, and it doesn't touch any of it. The enclave, the attestation, the KMS policy — all unchanged. You've just made the "should this transfer happen at all" decision stricter for the transactions that deserve the extra friction.

The parent side, then, authenticates, loads the ciphertext, fills in the public chain data, and relays. It never touches a plaintext key:

import json, socket, boto3

secrets = boto3.client("secretsmanager")
chain = ChainClient("https://your-node.example:PORT")   # your chain's RPC client
ENCLAVE_CID, ENCLAVE_PORT = 16, 5000

def call_enclave(payload: dict) -> dict:
    s = socket.socket(socket.AF_VSOCK, socket.SOCK_STREAM)
    s.connect((ENCLAVE_CID, ENCLAVE_PORT))
    s.send(json.dumps(payload).encode())
    result = json.loads(s.recv(8192).decode()); s.close()
    return result

def send(token: str, to: str, amount, aws_creds: dict) -> str:
    claims = verify_jwt(token)                                   # 401 if invalid
    record = json.loads(
        secrets.get_secret_value(SecretId=f"wallet/user/{claims['sub']}")["SecretString"]
    )

    # Build the unsigned tx and fill in public chain data (nonce, fee, gas, chain id…).
    unsigned_tx = build_tx(from_addr=record["address"], to=to, amount=amount)
    unsigned_tx = fill_chain_params(unsigned_tx, chain)          # public data, no key needed

    signed = call_enclave({
        "op": "sign",
        "transaction": unsigned_tx,
        "encrypted_key": record["encrypted_key"],
        "credential": aws_creds,                                # temp instance creds
    })
    return chain.broadcast(signed["signed_tx"])                 # submit; needs no key

Why does the enclave need AWS credentials handed to it? Because it has no network of its own. It borrows the parent's temporary instance credentials, tunneled through the same vsock proxy, to reach KMS. On their own those credentials are useless for this — without a valid attestation document, KMS just refuses to decrypt.

And the enclave itself, which is a single small server handling both the create from sign-up and the sign here:

import base64, json, socket, subprocess

VSOCK_PORT = 5000

def kms_decrypt(ciphertext_hex: str, creds: dict) -> bytes:
    """kmstool_enclave_cli does decryption #1 (KMS) and #2 (local unseal)."""
    out = subprocess.run(
        ["/app/kmstool_enclave_cli",
         "--region", "us-east-1", "--proxy-port", "8000",
         "--aws-access-key-id", creds["access_key_id"],
         "--aws-secret-access-key", creds["secret_access_key"],
         "--aws-session-token", creds["token"],
         "--ciphertext", ciphertext_hex],
        capture_output=True, check=True,
    ).stdout.decode()
    b64 = out.strip().split(":")[-1].strip()     # "PLAINTEXT: <base64>"
    return base64.b64decode(b64)                 # the raw private key

def handle(req: dict) -> dict:
    if req["op"] == "create":
        return create_wallet(req["credential"])          # from sign-up
    if req["op"] == "sign":
        private_key = kms_decrypt(req["encrypted_key"], req["credential"])
        try:
            signed_tx = sign_transaction(req["transaction"], private_key)  # your chain's signer
            return {"signed_tx": signed_tx}
        finally:
            del private_key                              # don't let plaintext outlive the request
    return {"error": "unknown op"}

def serve():
    s = socket.socket(socket.AF_VSOCK, socket.SOCK_STREAM)
    s.bind((socket.VMADDR_CID_ANY, VSOCK_PORT)); s.listen()
    while True:
        conn, _ = s.accept()
        req = json.loads(conn.recv(8192).decode())
        conn.send(json.dumps(handle(req)).encode())
        conn.close()

if __name__ == "__main__":
    serve()

That's the entire trust boundary, and it's small enough to read in one sitting. The same sealed box both mints keys and signs with them, and in either case the plaintext key only exists inside the enclave — created in create_wallet or briefly revived in kms_decrypt, used once, and dropped before any reply crosses back over vsock. (generate_keypair and sign_transaction are the only two chain-specific pieces; everything else is identical no matter which blockchain you're on.)

Building and running it

The enclave app is a Docker image that you convert into an enclave image file:

FROM amazonlinux:2
RUN yum install -y python3 gcc python3-devel && pip3 install boto3 <your-chain-sdk>
COPY kmstool_enclave_cli /app/kmstool_enclave_cli
COPY libnsm.so /app/libnsm.so
COPY server.py /app/server.py
CMD ["python3", "/app/server.py"]

nitro-cli build-enclave --docker-uri signing-server:latest --output-file signing_server.eif
# ^ prints PCR0 → paste it into the KMS key policy
nitro-cli run-enclave --cpu-count 2 --memory 3806 \
                      --eif-path signing_server.eif --enclave-cid 16

One gotcha: enclaves aren't managed by Docker or systemd, so nothing restarts them for you if they die. A tiny watchdog under systemd that polls nitro-cli describe-enclaves and relaunches the enclave when it's gone covers this.

Wrapping up

Back at the start, the choice looked like "buy a Wallet-as-a-Service and hand off custody" or "run your own HSMs and hate your life." This is the third door. You get HSM-grade key protection out of infrastructure you already run, you own the entire trust boundary end to end, and the only two pieces that are chain-specific are generate_keypair and sign_transaction — everything else is the same whether you're on Ethereum, Solana, Bitcoin, or something that doesn't exist yet.

It's not a small amount of moving parts, and the attestation flow takes a beat to click. But once it does, the mental model is clean: social login decides who can act, the JWT and step-up MFA decide what they can do, PCR0 decides which code is allowed to touch a key, and the enclave plus KMS make sure the plaintext only ever exists somewhere nobody — including you — can reach into. That's a wallet you can put in front of ordinary users and still describe honestly: we made your key, we help you spend it, and we can't read it.

If you take one thing away, let it be that "non-custodial-ish, self-hosted, no vendor holding the keys" is not a moonshot anymore. It's a weekend spike on top of a reference implementation. So go build it.

More info — the full working reference implementation (VPC, KMS policy, enclave build, CDK) is open source: aws-samples/aws-nitro-enclave-blockchain-wallet. Clone it, deploy it, and read the parts this post glossed over.

Next steps — two directions worth exploring once the single-enclave version is working:

Remove the single point of trust with MPC. Right now one enclave can reconstruct a whole key. Split it so no single enclave (or single AWS account) ever holds the complete key, and a signature needs several parties to cooperate: Build secure multi-party computation (MPC) wallets using AWS Nitro Enclaves.
Make it production-grade. Add key backup and recovery (what happens if a user loses access?), multi-AZ high availability for the enclave and monitoring/alerting on failed attestations.